Organizing multiple user selections
Gadgets can combine multiple user selections on a dashboard in the following ways:
*Apply button
The current selections gadget from the dashboard menu can display or clear all data selections on the dashboard at the same time or clear selected values, as shown in Figure 17‑48.
Figure 17‑48 Displaying a current selections gadget
Building cascade selections
You can link data selection gadgets together so that choices in one gadget filter the available choices in another gadget. Each user selection is published to all linked gadgets, and users can make selections in any order. Selection gadgets update the dashboard after each user selection in the gadget.
For example, if you have three lists, one for country, city, and customer name on a dashboard with a chart, selecting a country updates the chart. Selecting a city updates the chart, and selecting a customer name also updates the chart. The following solutions avoids unnecessary updates to the dashboard:
*Remove the links in the country list to the city and customer names. Selections in the other gadgets do not update the country list.
*Remove the links in the chart to the country and city gadget. Leave only the link to the customer name. The chart only updates when a customer name is chosen.
You can also use a selector group or apply gadget to send multiple values at the same time and avoid unnecessary dashboard updates.
Building group selections
Use the selector group gadget to display related user selections and enable users to finish all selections before updating linked gadgets. Users must make their selections in a fixed order. When the user chooses Apply, the dashboard updates to display data related to the user selection. This gadget displays values from a single BIRT data object.
Figure 17‑49 shows a finished selector group gadget on the dashboard.
Figure 17‑49 Displaying a selector group gadget on the dashboard
Using a selector group gadget
Selector group gadgets display multiple values as cascading choices for users. A user picks from related values, one after the other in the order displayed, and publishes those values to linked gadgets when all selections are finished. When the user chooses Apply, gadgets that are linked to the selector group update to display data related to the user selection. This avoids unnecessary updates to the dashboard. Other data selection gadgets apply the changes each time a user makes a selection.
Selecting fields to display
All data displayed in a selector group gadget comes from a single BIRT data object. After selecting the data object, you can select one or more data fields to display together. You can sort and format each data field differently. Each data field filters the values displayed from the next field.
For example, if the first data field is country and the second is city, the gadget displays countries for a user to select. Each selected country displays city names from the selected countries.
Figure 17‑50 shows the selection of data to display in a selector group gadget.
Figure 17‑50 Selecting data to display in a selector group gadget
Choosing a selector type
You can display selector group gadgets in combo box or list types using Data Selector Gadget Wizard. Choose Type to select how the selector group gadget is displayed.
Formatting a selector group gadget
Use Format from Data Selector Gadget Wizard to change the selector group orientation, set a limit to the quantity of displayed values, and change the format of each displayed field. A list type also supports multi-value selections and searching for values in the gadget, as shown in Figure 17‑51.
Figure 17‑51 Formatting a selector group gadget using the list type
Each displayed field also supports formatting, depending on the content of the field. For example, country names can display in capital letters and phone numbers can display using the regional phone number format.
Using an apply button gadget
Data selection gadgets update all linked gadgets after each user selection. Use the apply button gadget to collect and hold user selections from multiple data selection gadgets. When the user makes selections, the selections are held by the apply button gadget until the user chooses the apply button. Other gadgets link to the apply button and receive the user selections only when the user chooses to apply their selected values.
After adding data selection gadgets and one or more apply button gadgets to a dashboard, you use Link from the gadget menu to choose which apply button to forward user selections. Figure 17‑52 shows a chart using an apply button with the name Send.
Figure 17‑52 Setting a gadget to use an apply button
Figure 17‑53 shows an apply button gadget holding user selections until the user chooses the apply button. The chart updates only after the user chooses the apply button.
Figure 17‑53 Using an apply button gadget with multiple data selection gadgets
You can set the button name and change the general options of the apply button gadget to display it with or without a gadget header and border.
For more information about linking gadgets together, see Linking and scripting gadgets.
Using parameter selections
Link to a parameter gadget to receive user‑selected parameter values. Parameter gadgets display parameters from BIRT design files. If the parameter includes filter conditions such as from a dynamic filter parameter, then you must process the selected condition using JavaScript. The BIRT document that contains this parameter can already process the selected condition but a visualization gadget, such as a chart, requires additional JavaScript to handle the selected condition.
For example, a user selects the following values from a parameter gadget: the filter condition greater than, and the value 300. A chart is linked to this parameter gadget and receives the selected condition and value, but chart gadgets require only a value, not a filter condition. Figure 17‑54 shows a parameter gadget displaying parameters from a BIRT design file.
Figure 17‑54 Displaying report parameters in a parameter gadget
Add JavaScript to the chart gadget to extract the value from the user selection and to optionally process or remove the selected filter condition. For more information about parameter gadgets, see Displaying a file on a dashboard.