d3ComponentLibrary

About

The d3 component gallery is a Sparkl plugin that bundles specific visualizations as ctools components to be used in dashboards.

Please help us extending this gallery

Installing

In order to install the D3 Component Library, either get it from the Pentaho Marketplace or clone this project directly into your pentaho-solutions/system and do an ant resolve.

Pentaho 5.x required.

Adding new visualizations.

If your favorite visualization is not part of the gallery, follow this instructions to add it:

Pick your visualization

Choose one from the d3 gallery, from somewhere else, or create your own.

Install Sparkl

Make sure you have Sparkl installed. Everyone should have it :)

Create a dashboard for your new visualization

In the directory d3ComponentLibrary/dashboards you'll see the available dashboards. Pick the one you want. Currently you may need to manually copy the source files (.wcdf and .cdfde). In what I hope to be a recent future we'll be able to simply do a save as from within CDE, but that's currently not allowed. Refresh the sparkl application through the UI or through the url:

http://127.0.0.1:8080/pentaho/plugin/d3ComponentLibrary/api/refresh

The name of the dashboard will be the id of the visualization you're creating. This is where you'll supply an example and the documentation for the visualization.

Create the directory for the CDE component

The code for the visualizations are in d3ComponentLibrary/resources/components. Create a directory there with the name of your visualization.

Create component.xml

Every component needs to have a component.xml that acts as a descriptor for CDE to know how to use it. My suggestion is for you to look into one of the existing ones and use it as a template.

The important bits in there are:

• Header - put the component information there
• Contents/Model - The specific options of the component. Most of them are plain CDF, so leave them there, and add the ones you want
• Implementation - Point to your code. You'll need a Styles tag if you want to also supply a CSS code
• Dependencies - The dependencies for the component code. d3 is already in the plugin, and some helper functions are provided in d3ComponentBase.js, so most likely you won't need anything here

Implement your code

This is a standard CDF component, that extends D3ComponentBase. Note that the name of the component always starts with an uppercase letter, and the variable name is the same as specified in the Header/IName node in component.xml appended with "Component".

You'll mostly need to implement the render function, and use the original d3 code as an example. Then you'll need to hook in the data that comes from Pentaho and parametrize any arguments you wish. Take a look at the bundled visualizations.

The arguments added to the visualization should be added to the component.xml file, in //Contents/Model/.

Test it

When you make changes to the component.xml file, you need to refresh CDE. Use the following url:

http://127.0.0.1:8080/pentaho/plugin/pentaho-cdf-dd/api/renderer/refresh

If everything worked correctly, you Then you should be able to see the new component in CDE, under the D3 Components group and use it in a dashboard.

To test your code, simply execute the dashboard, eg with:

127.0.0.1:8080/pentaho/plugin/d3ComponentLibrary/api/calendarview?debug=true&bypassCache=true

. Adding debug=true&bypassCache=true is only useful for bypassing the minification step, allowing to use a javascript browser debugger like firebug or developer tools.

Add an image

Add an image to static/custom/img with your visualization - it will be picked and shown in the index.

Submit it back

Send it to us! Do a pull request or through email

Questions?

Find us at ##pentaho irc channel in irc.freenode.net, through the Pentaho Community mailing list or through the Pentaho Forums