Adding Custom Visualization Components to TIBCO Jaspersoft® Studio 6.2

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. Possible values for this property are: Male, Female, Custom
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: https://github.com/mbostock/d3/wiki/Formatting#d3_format
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.

http://community-static.jaspersoft.com/sites/default/files/wiki_attachments/sparkline.png?_ga=1.248779716.2115103839.1448308340

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

misterjaaay 0

Posted April 11, 2019

- Share this comment

Path must be an SVG path(https://www.w3.org/TR/SVG/paths.html) and should look like below:

<cvc:itemProperty name="figure" value="Custom"/>
<cvc:itemProperty name="customPath" value="M50 123 c29 -54 56 -101 59 -106 8 -8 111 171 111 192 0 7 -35 11 -111 11 l-111 0 52 -97z"/>

Sign In

Adding Custom Visualization Components to TIBCO Jaspersoft® Studio 6.2

Custom Visualization Component Descriptor

JSON File Format

Adding Properties to the UI

Property description format:

Adding a CVC to Jaspersoft Studio

Requirements for Using CVCs

Specifying a CVC Location

Using a CVC in a Report

Pre-installed CVCs

The Figures component

Configuration settings

The Radial Progress component

Configuration settings

The Sparkline component (added in 6.2.2)

Configuration settings

Data settings

See Also

Table of contents

User Feedback

Recommended Comments

misterjaaay 0

Link to comment

Share on other sites

Create an account or sign in to comment

Create an account

Sign in

Activity

Products

Explore