Displaying BIRT parameters
Parameters in a BIRT document prompt users to type or select values to pass into the BIRT document. These values are used to add, change or filter data in the BIRT document. You can set default parameter values in the gadget configuration, display the parameters in the gadget for the user to select values, or use a data selection or parameter gadget that is already on the dashboard to send parameter values to the BIRT document.
For example, a BIRT design file displays order history for each customer and uses parameters to prompt the user for a customer name before generating the document. Other possible uses of parameters include requesting a report in a specific language or adding comments into a final report.
When you display a BIRT document in a report or Reportlet gadget you can set default values for any parameters in the BIRT document. To enable users to change parameter values and update the BIRT document, display the parameters on the dashboard.
When using a report or Reportlet gadget you can display parameters in the following ways:
*Do not display parameter.
The parameter is not displayed on the dashboard. A default value is selected when creating or editing the gadget. Users cannot change this value.
*Display parameter as part of the gadget.
The parameter is displayed as part of the report or Reportlet gadget. A user selects a value for the parameter, then chooses Run to update the BIRT document. Figure 16‑5 shows a report gadget with parameters displayed in the gadget.
Figure 16‑5 Displaying parameters as part of a gadget
*Display parameter as a new selector.
Create a new data selection gadget that displays the parameter. Other report and Reportlet gadgets can use this gadget. Figure 16‑6 shows a report gadget with a parameter displayed as a new selector gadget. When a user changes the value, the linked document updates.
Figure 16‑6 Displaying parameters as a separate gadget
*Link to this selector.
Use an existing parameter or data selection gadget to send parameter values to the BIRT document.
How to set default parameter values
This procedure requires a dashboard you can edit and a BIRT document that uses parameter values. Create a new dashboard if one does not already exist.
To set default parameter values in a gadget, complete the following steps:
1 In the dashboard editor, choose InsertReportReport.
2 Choose Browse to display available reports.
3 Select a BIRT report document or report design file to display and choose OK.
4 In Parameter, set default values for the report’s parameters and choose OK. Figure 16‑7 shows default values set for a sample report.
Figure 16‑7 Setting default parameter values in a report gadget
5 In New Report Gadget, choose OK to add the new gadget to the dashboard.
Displaying parameters in a data selector gadget
Use data selector gadgets to display parameters when you want to use the user’s selected value in other gadgets, such as a chart. You can display parameters from BIRT design and BIRT data object files.
When you choose to display a parameter as a new data selector, the Data Selector Gadget Wizard launches. Use this wizard to build a data selection gadget using the parameter choices in the BIRT file as a data source. You can choose the selector type, such as list or check box, you can choose the formatting options, such as formatting the displayed values, and you can link other gadgets to the user selections.
Once the data selection gadget appears on the dashboard, you can edit it like other data selection gadgets except that you cannot change the data source or filter settings.
You can also link a report gadget with parameters to data selection gadgets from other data sources. For example, a BIRT document displays customer invoices and uses a parameter named Customer to generate the invoice of specific customers. The dashboard includes a list for users to select customer names. You create a report gadget to display the BIRT document. In the gadget’s Parameter Display Settings, select the list of customer names in the section Link to this selector. Now, each user selection from the list updates the BIRT document.
How to create a new selector for a parameter
This procedure requires a dashboard you can edit and a BIRT document that uses parameter values. Create a new dashboard if one does not already exist.
To display parameter values in a separate gadget, complete the following steps:
1 In the dashboard editor, choose InsertReportReport.
2 Choose Browse to display available reports.
3 Select a BIRT report document or report design file to display, and choose OK.
4 In New Report Gadget—Parameter Display Settings, select Display parameter as a new selector. Figure 16‑8 shows the parameter display settings for an example report.
Figure 16‑8 Configuring parameter display settings for a report gadget
Data Selector Gadget Wizard appears.
5 In Data Selector Gadget Wizard—Type, select a gadget type. The example in Figure 16‑9 shows a radio data selector.
Figure 16‑9 Selecting a radio gadget
6 Choose OK. New Report Gadget—Parameter Display Setting appears.
7 Choose OK. The data selection gadget and report gadget appear, displaying the default value for the parameter, as shown in Figure 16‑10. Other gadgets can now link to the new data selection gadget.
Figure 16‑10 Displaying a parameter for a report in a data selection gadget
Displaying parameters in a parameter gadget
Use parameter gadgets to display cascading or dynamic filter parameters from a BIRT document on a dashboard. There are two types of parameters, values and conditions (sometimes called dynamic filters). Values are used when the BIRT report requires only a single value. When conditions are also used, as in the case of dynamic filter parameters, the user can select a condition like less than, greater than, equal to in addition to a value.
Parameter gadgets enable users to send values to BIRT documents displayed in one or more report or Reportlet gadgets. These gadgets display all or selected parameter choices in a BIRT document file. You can also assign default parameter values and if the parameter includes filter conditions, such as a dynamic filter parameter you can also assign default conditions, such as greater than. User selections in the parameter gadget update the linked BIRT document when the user chooses Apply Changes.
For example, two report gadgets contain a parameter to select a credit limit for potential clients. The parameter gadget displays the filter condition and value of the credit limit. The user selects less than for the filter condition and enters a value of 80,000. When the user chooses Apply Changes, both report gadgets update and use the credit limit parameter of less than 80,000.
Parameter gadgets are also used to create data selection gadgets on a dashboard using a BIRT file as the data source instead of a BIRT data object. Other dashboard visualization gadgets that do not use conditions, such as a chart, can link to the parameter gadgets but require additional scripting when conditions and values appear in the parameter. Data visualization gadgets expect only values, not conditions. For more information about data selection gadgets see Visualizing data on a dashboard.
How to create a parameter gadget
This procedure requires a dashboard you can edit and a BIRT document that uses parameter values. Create a new dashboard if one does not already exist.
To create a parameter gadget, complete the following steps:
1 In the dashboard editor, choose InsertReportParameter.
2 Choose Browse to display available reports.
3 Select a BIRT report document or report design file to display and choose OK.
4 Select which report parameters to display in the parameter gadget and choose OK. Figure 16‑11 shows three selected parameters to display from an example report.
Figure 16‑11 Configuring parameter display settings for a report gadget
5 Select default values for any parameters in New Parameter Gadget—Parameter. Figure 16‑12 shows three selected parameters to display from the example report.
Figure 16‑12 Configuring default values for a parameter gadget
6 Choose OK to create the new parameter gadget on the dashboard. Figure 16‑13 shows the new parameter gadget created from the example report.
Figure 16‑13 Configuring default values for a parameter gadget