In version 6.2, the Custom Visualization Component is a community-only feature, it is not yet supported in the professional software.
In Jaspersoft Studio 6.2, we added a JSON descriptor format that allows you to register your custom visualization components (CVCs) with Jaspersoft Studio and create a specialised UI for the component. Two pre-installed sample CVCs, Figures and Radial Progress, implement the descriptor format.
For more information, see the following:
http://community.jaspersoft.com/wiki/new-features-jaspersoft-62
Custom Visualization Component Descriptor
The JSON descriptor for a CVC is composed of a JSON file and additional resources:
- JSON file - Describes the CVC resource, references required assets (such as a JavaScript file), and optionally defines a UI.
- Preview image (optional) - Image used for the component in Jaspersoft Studio. This image appears in the component chooser dialog when a user creates a CVC and is also used as the image for a your component in Design view.
- Component-specific assets, such as a JavaScript file and a css file. All resources are referenced inside the JSON descriptor.
JSON File Format
To set up a JSON file for a CVC, use the following members:
Property Name | Default | Mandatory | Description |
---|---|---|---|
label | - | Mandatory | Name of the component shown in dialog boxes (for example, Cool Circle). |
description | - | Optional | A short description of the component; shown as a tooltip in the component chooser dialog when a user creates a CVC. |
module | - | Mandatory | (Read only) Name of the requirejs module implemented by the minified JavaScript. Must be unique across your installed CVCs. |
thumbnail | - | Optional | A PNG used in the component chooser dialog; you can optionally configure your component to use this for the preview of the component in design view. |
ui | - | Optional | A nested descriptor of the properties and dataset required by this component |
css | - | Optional | Optional css file reference (it will be copied inside the report directory when the component is created with a wizard). |
script | - | Mandatory | JavaScript reference (it will be copied inside the report directory when the component is created with a wizard). |
Adding Properties to the UI
The Javascript, CSS, and module properties are shown on Data tab of the Properties view for your component in Jaspersoft Studio. You can use additional properties in the JSON file to define additional UI, in the form of a set of input fields (text, numbers, combobox, etc...), and an optional list of datasets that can be used by the component implementation. The values entered by the user in the UI are passed to the JavaScript file specified in the script member.
Property name | Default | Mandatory | Description |
---|---|---|---|
sections | - | Optional | List of available sections which collects properties, in addition to js, css, and module properties, which are always present and, if we manage the custom ui, presented as read only. |
dataset | - | Optional | Set of dataset definitions. A dataset describes the fields of the item in the set. |
Property description format:
{ "label": "Figures", "description": "Display a list of figures", "module": "figures", "thumbnail": "Figures.png", "sections": [ { "name" : <string>, "expandable" : <true | false>, // optional, default is true. If true, the name is shown as label and the section can also collapse "properties" : [ { "name": <string>, "label": <string>, "description": <string>, "mandatory": <true | false>, "defaultValue": <string>, "type": <type>, // Possible types are: "Path", "Text", "Float", "Integer", "Double", "Combo", "Color" "min" : <number>, // Valid for number types "min" : <number>, // Valid for number types "options" : [{ "label": <string>, "value": <val>}, {"label": <string>, "value": <val>}, ... ] // List of possible options, valid for combobox only "readOnly" : <true | false>, // optional, default is false. }, ... ] }, ... ], "datasets": [ { "label": <string>, // Used only in UI "cardinality" : <int>, // -1 = no limit, otherwise a specific number, i.e 1. "sections": [ { "name" : <string>, "properties" : [ { // same as in sections }, ... ] }, ... ] }, ... ] }
Adding a CVC to Jaspersoft Studio
Requirements for Using CVCs
- PhantomJS
You must install PhantomJS before you can use a custom visualization component in Jaspersoft Studio. PhantomJS is available for all the major OSs here: http://phantomjs.org/
Once you have installed PhantomJS, add it to your classpath. As of Jaspersoft Studio 6.2, there is no additional configuration needed to use PhantomJS.
The PhantomJS license is BSD, but third-party licenses prevent us from including it in our software.
Specifying a CVC Location
Once you have created a JSON descriptor for your CVC, you can add the descriptor location to your Jaspersoft Studio configuration as follows:
- Select Window > Preferences > Jaspersoft Studio > Resource Folder Locations > Custom Visualisation Component to open the Preferences dialog box.
- Click New, select the location for your JSON descriptor, and click OK.
- Click OK to close the Preferences dialog.
Using a CVC in a Report
Drag the Custom Visualization element from the Palette to your report. If the JSON descriptor is correctly configured, you should see the component in the component chooser dialog box.
Select the component you want to add to the report. The component assets (javascript and css) are copied into the report directory
Pre-installed CVCs
Jaspersoft Studio 6.2 includes two CVC (stored inside the CVC plugin), available out of the box: Figures and Radial Progress. These components are sample implementations of the JSON descriptor format.
To add one of these components, drag the Custom Visualization element http://community-static.jaspersoft.com/sites/default/files/images/cvc-icon.png from the Palette to your report and select the component in the component chooser dialog box. The component assets (javascript and css) are copied into the report directory. The first time you add a pre-installed CVC to a report, you are prompted to give access permission to the location where these components are stored. You only have to do this once.
The Figures component
The Figures component is often used in dashboards and infographics:
It is used to show a set of figures and color them. The number of figures shown is based on two numbers: items value and items count. The items count is the number of figures shown. The items value is the number of figures to color with the primary color (black by default). The items value don't have to be an integer number, but partial figures can be also coloured (like in the image).
Configuration settings
Name | Property | Default | Mandatory | Description |
---|---|---|---|---|
Items Value | itemsValue | 1 | true | The number of selected values. |
Items Count | itemsCount | 1 | false | The number of phantom figures. Phantom figures are figures which are not selected, the ones painted in gray in the figure. If not set, or 0, the first integer bigger or equal than itemsValues will be used |
figure | Figure | Male | true | The figure to show. The Figures component has two built-in figures: Male and Female, but it is possible to use any figure in form of SVG path. In this case the type should be set to Custom and the path should be set in the customPath property. |
customPath | Custom Path | false | This property is used only if the figure is set to Custom. The value must represent a valid SVG path data (http://www.w3.org/TR/SVG/paths.html#PathData). The image shows the use o a very complex path, taken from this SVG picture: http://www.clipartsfree.net/clipart/88-albert-einstein-silhouette-clipart.html | |
fgColor | Foreground Colour | #000000 (black) | false | The default colour used to plot the figures |
fgOpacity | Foreground Colour opacity | 1.0 | false | Opacity of the figures. Opacity spans from 0 (transparent) to 1 (fully visible) |
bgColor | Background Colour | #000000 (black) | false | The background colour used for the not selected figures. |
bgOpacity | Background Colour Opacity | 0.2 | false | Opacity of the not background color. Opacity spans from 0 (transparent) to 1 (fully visible) |
showBackground | Show Background | true | false | Show or hide the background figures |
rows | Rows | 0 | false | If different than 0, this property allows to pre-set the number of rows that should be used to layout the figures. |
columns | Columns | 0 | false | If different than 0, this property allows to pre-set the number of columns that should be used to layout the figures. |
maximizeColumnNumber | Maximize cols number | true | false | Allows to maximize the number of columns number. This option only takes effect when the user set a specific number of rows to be used. In that case, if the number of figures is close to the number of rows, the figures could be either displayed filling the available area row by row, or column by column. If true, the chart will try to render as many figure as possible in each row, otherwise the priority will given to the rows. In these two images, the number of rows is set to 9, and the number of items is 30. |
vAlign | Vertical Alignment | top | false | How to align the whole figure (vertically). |
hAlign | Horizontal Alignment | left | false | Horizontal Alignment of the overall set of figures |
hPadding | Horizontal Padding | 10 | false | The horizontal space between figures |
vPadding | Vertical Padding | 10 | false | The vertical space between figures |
The Radial Progress component
The Radial Progress component is often used in dashboards and infographics:
It is used to show a percentage. If the percentage is over 100%, other rings are shown until the full percentage is represented (or the number of maximum rings is reached).
The percentage is calculated based on two numbers: value and target. In particular the percentage is value/target. If target is not specified, or it is 0, it set to 1.
Each grey (background) ring represents 100% of the target.
Configuration settings
Name | Property | Default | Mandatory | Description |
---|---|---|---|---|
value | Value | 90 | true | The value to represent. It is set to 90 mostly to present to the user how the component works. |
target | Target | 100 | false | The target representing 100%. It is set to 100 by default mostly to present to the user how the component works. |
valueFormat | Value Format | .1% | false | The format used to format the value when printed in the centre of the rings. This format follows the D3 format specifications available here: |
autoFit | Auto fit | true | false | If true, the font size of the label is automatically calculated. |
fgColor | Foreground Color | #000000 (black) | false | The colour used to plot the value ring(s) |
fgOpacity | Foreground Opacity | 1.0 | false | Opacity of the foreground colour. Opacity spans from 0 (transparent) to 1 (fully visible) |
bgColor | Background Color | #000000 (black) | false | The colour used to plot the background ring(s) |
bgOpacity | Background Opacity | 0.2 | false | Opacity of the background colour. Opacity spans from 0 (transparent) to 1 (fully visible) |
showBackground | Show Background | true | false | Allows to hide the background ring(s) |
ringThickness | Ring Thickness | 4.0 | false | The thickness of the rings |
ringPadding | Ring Padding | 4.0 | false | Distance between rings |
maxRings | Max number of rings | 0 | false | The maximum number of rings displayed (by default rings are shown until there is space). |
hPadding | Horizontal Padding | 10 | false | Horizontal Padding (left and right) |
vPadding | Vertical Padding | 10 | false | Vertical Padding (top and bottom) |
animation | Use Animation | true | false | Use an animation when displaying the component. (This property is automatically set to false when the report is not exported in HTML) |
The Sparkline component (added in 6.2.2)
The Sparkline component is a minimalistic line chart, without axes or coordinates, that shows variation over time. It follows the guidelines of Edward Tufte here: http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0001OR to represent a series of values.
Configuration settings
Name | Property | Default | Mandatory | Description |
---|---|---|---|---|
Line Color | lineColor | #000000 | false | The color used to plot the line |
Line Opacity | lineOpacity | 1 | false | The opacity of the line color (from 0 to 1) |
Line Width | lineStroke | 0.1 | false | Line width (in pixels) |
Interpolation type | interpolation | basis | false | The type of interpolation used to plot the line. Interpolation types: linear http://community-static.jaspersoft.com/sites/default/files/wiki_attachments/sparkline-linear.png?_ga=1.15776629.2115103839.1448308340 step-before http://community-static.jaspersoft.com/sites/default/files/wiki_attachments/sparkline-step-before.png?_ga=1.15776629.2115103839.1448308340 step-after http://community-static.jaspersoft.com/sites/default/files/wiki_attachments/sparkline-step-before.png?_ga=1.15776629.2115103839.1448308340 basis http://community-static.jaspersoft.com/sites/default/files/wiki_attachments/sparkline-basis.png?_ga=1.240300864.2115103839.1448308340 cardinal http://community-static.jaspersoft.com/sites/default/files/wiki_attachments/sparkline-cardinal.png?_ga=1.182064868.2115103839.1448308340
monotone http://community-static.jaspersoft.com/sites/default/files/wiki_attachments/sparkline-monotone.png?_ga=1.182064868.2115103839.1448308340 |
Fill Color | fillColor | #0000FF | false | The color used to fill the line area |
Fill Opacity | fillOpacity | 0.5 | false | The opacity of the line area (from 0 to 1) |
Circe Color | circleColor | #FF0000 | false | The color used to plot the circle on the last point |
Circle Opacity | circleOpacity | 1 | false | The opacity of the circle on the last point (from 0 to 1) |
Circle Radius | circleRadius | 2 | false | The radius (in pixels) of the circle on the last point. |
Data settings
The component requires a data item to provide a set of values that will be plotted. Series items must have the following properties:
Item property name | Type |
---|---|
value | numeric |
Recommended Comments
Create an account or sign in to comment
You need to be a member in order to leave a comment
Create an account
Sign up for a new account in our community. It's easy!
Register a new accountSign in
Already have an account? Sign in here.
Sign In Now