Specifying Parameters in Dashlets

This documentation is an older version of JasperReports Server User Guide. View the latest documentation.

Specifying Parameters in Dashlets

You can add parameters to dashlet names, text dashlets, web page dashlets, and hyperlinks in chart dashlets. When you add a parameter, you must map a filter in the dashboard to the parameter. See Mapping parameters in the filter manager for more information.

Simple parameters:

For text dashlets, web links, and dashboard names, use the syntax $P{parameter_name} to directly pass the parameter value to the web page. Examples:

•

In a text dashlet, enter the parameter in the Text box:

Product Family: $P{Product Family}

•

In a web page dashlet or a web link in a chart dashlet hyperlink, enter the parameter in the Web Page Address (URL) text box:

http://en.wikipedia.org/wiki/$P{Customer Country}

•

Dashlet name: Enter the parameter in the Dashlet Name box:

Unit Sales for $P{Product Family}

For repository hyperlinks in a chart dashlet, use the syntax ?filter_in_target=$P{dashlet_param}. For example, the following link sets the c_country_1 input control in the 05. Unit Sales Trend report to the value of a Store Country parameter in the dashlet.

repo:/public/Samples/Reports/05._Unit_Sales_Trend?c_country_1=$P{Store Country}

To find the correct name for a filter in a target resource, open the Dashboard Designer in a new window, and add the resource to the canvas. Then expand the resource's folder in the Filters panel and hover over the filter whose name you want to see.

Parameters in multi-valued input controls:

For multi-valued input controls, you can define a separator for the input control values:

•

For text dashlets, web links, and dashboard names, use the syntax $P{parameter_name ? "separator"}. The following example in a text box displays results like Product Family: Drink + Food:

Product Family: $P{Product Family ? " + "}

•

For repository links in a chart dashlet, use the syntax ?$P{"filter_in_target=", dashlet_param, ? "&"}. For example, the following link allows multi-select with the c_country_1 input control in the 05. Unit Sales Trend report:

repo:/public/Samples/Reports/05._Unit_Sales_Trend?$P{"c_country_1=", Store Country, "&"}

When Mexico and USA are selected, this expands to the following link:

repo:/public/Samples/Reports/05._Unit_Sales_Trend?c_country_1=Mexico&c_country_1=USA

Mapping parameters in the filter manager

After you have created a parameter, create a mapping for it as follows:

Mapping parameters in dashboard names and text or web page dashlets:

In the Dashboard Designer, click

In the filter row where you want to add the new filter, click

Using these new line-items, select the dashlet where you added a parameter, then select the parameter.

Click OK to apply and save or Cancel to discard your changes.

Mapping parameters in chart hyperlinks:

To have JasperReports Server create a parameter mapping automatically:

In the Dashlet Properties dialog box for your chart, use one of the names in the Available parameters list as the name of your parameter.

Click OK to close the dialog box and create the mapping.

To create a mapping in the filter manager:

In the Dashlet Properties dialog box for your chart, click Create Links in Filter Manager... to open the filter manager.

In the filter row where you want to add the new filter, click

Using these new line-items, select the dashlet where you added a parameter, then select the parameter.

Click OK to apply and save or Cancel to discard your changes.

Creating a Web Page Dashlet

When working with Web Page dashlets in the Dashboard Designer, you can include a parameter reference in the dashlet's URL. The parameter references an existing filter in another dashlet, and uses that filter to display a specific web page relevant to the filtered information.

The following example takes you through the steps for creating a simple dashboard in the Dashboard Designer, adding a sample chart with geographic filters, and creating a Web Page dashlet that displays a Wikipedia page for the country the sample chart is filtered on.

First, create the simple dashboard:

1. Log in to JasperReports Server as superuser.

Click Create > Dashboard.

The Dashboard Designer appears, displaying the list of available content and the canvas.

In the Existing Content section of the Available Content panel, find report 06. Sales Mix by Gender.

Click and drag the report onto the Dashboard Canvas. Note that the Filters section now includes the Sales Mix by Gender chart.

Next, add the filter input control to the dashboard:

In the Filters section, expand the 06. Sales Mix by Gender folder.

The input controls associated with the Sales Mix by Gender Report appear.

Drag the Customer Country input control onto the canvas.

Now, add the Web Page dashlet with the parameter reference and add it to the filter:

In the New Content section of the Available Content panel, click and drag the Web Page item onto your dashboard.

The Dashlet URL window opens.

Enter the following URL:

http://en.wikipedia.org/wiki/$P{Customer Country}

Click OK.

Right-click the dashlet and select Properties.

Change the Dashlet Name to Wiki.

Click

In the Customer Country filter, click

A row containing the new affected dashlet and filter/parameter dropdown menus appears.

In the Dashlet Affected column, select wiki from the new Select dashlet... dropdown menu.

In the Filter/Parameter Affected column, select Customer Country from the new Select parameter... dropdown menu.

10.

Click OK.

Finally, preview the new dashboard functionality:

Click

Click in the Customer Country text box to display the available countries.

Select Mexico from the values list, and click Apply at the bottom of the dashlet. The data in the Sales Mix by Gender report is updated to display only information about Mexico, and the wiki dashlet displays the Wikipedia page for Mexico.

In “Dashboard with web page parameters” you can see how the dashboard canvas looks at this point: