Providing the user with a list of values
List boxes, combo boxes, and radio buttons are ideal mechanisms for providing a list of values to a user. The differences between these user interface elements are as follows:
*Radio buttons occupy as many lines in the Enter Parameters dialog as there are values. For ease of use, a set of radio buttons should contain fewer than 10 entries.
*The list box and combo box appear similar to the user. Both save space in the Enter Parameters dialog. The list box takes up only one line, and the combo box takes up two lines in Enter Parameters. For ease of use, a list box or combo box should contain fewer than 100 values.
*In addition to presenting a list of values, the combo box also supports the user typing a value. This feature is useful for supplying a string pattern. For example, instead of selecting a specific name for a customer name parameter, the user can type M% to get all customers whose names start with M. This technique assumes that the user is familiar with SQL pattern-matching syntax.
*The list box supports the selection of multiple values. The combo box and radio buttons support the selection of only one value.
Figure 13‑17 shows an example of an Enter Parameters dialog that displays a list box, combo box, and radio buttons.
Figure 16-13 Three types of selection elements in Enter ParametersFigure 16-13 Three types of selection elements in Enter Parameters
Figure 13‑17 Three types of selection elements in Enter Parameters
You can create two kinds of lists: static and dynamic.
*In a static list of values, you specify the values to display to the report user during report design. Creating a static list provides more control over the list of values. For example, you might want to present only certain values to the user, or localize the values. If you create a static list of values, however, you have to update the list manually to match the values in the data source.
*In a dynamic list of values, BIRT retrieves the values from the data source when the report runs. Create a dynamic list for values that are frequently updated in the data source, such as new customer names, product names, or order numbers.
For a list box or a combo box, you can create either a static or a dynamic list of values. For a set of radio buttons, you can only create a static list.
Creating a static list of values
To create a static list of values for a list box, combo box, or a set of radio buttons, use one or both of the following techniques:
*Import values from a data set field.
*Type each value to display.
To display all the unique values in a data set field, which is the typical case, import the values from the data set field. You can type the values, but this task would be tedious. Type a value only to display a value that is not in the data set field, such as ranges of values (0–100, 101–200, and so on).
To import all values from a data set field, first create a data set that retrieves the values. The query in the following example retrieves the unique values from the country field in the Customers table. You would specify this simple query to populate a parameter list with all the country names.
SELECT DISTINCT country
FROM Customers
Sometimes the values in a data set field are not in a suitable form or descriptive enough for report users. For example, the values in a territory field might use abbreviations, such as NA, EMEA, or APAC. For such cases, it is preferable to display the full names to the user. You do so by providing alternate values in the Display Text property.
If you are creating a report to be viewed in multiple locales, you can localize each parameter value by providing a resource key in the Display Text Key property. A resource key is a text string in an external source that is translated, or localized, into different languages. For more information about resource keys and localization, see Localizing text.
How to specify static report parameter values
This procedure assumes that you already created a report parameter.
1 In Data Explorer, expand Report Parameters, then double-click the report parameter to edit.
Edit Parameter displays the property settings for the report parameter.
2 For Display type, choose Combo Box, List Box, or Radio Button.
Edit Parameter displays the Selection list values table and the Import Values button, as shown in Figure 13‑18. The Selection list values table is where you specify the values to display in the list box, combo box, or radio buttons.
Figure 16-14 Selection values field and Import Values button in Edit ParameterFigure 16-14 Selection values field and Import Values button in Edit Parameter
Figure 13‑18 Selection list values table and Import Values button in Edit Parameter
3 In Selection list values, use the default value, Static.
4 To import values from a data set field, perform the following tasks:
1 Choose Import Values. Import Values displays the first data set in the report and the values of the first field in the data set, as shown in Figure 13‑19.
Figure 16-15 Import ValuesFigure 16-15 Import Values
Figure 13‑19 Import Values
2 In Select Data Set, choose the data set that returns the field values to display in the list box, combo box, or radio buttons. Typically, this data set is one that you create specifically to populate the parameter’s list of values.
3 In Select Column, choose the field that contains the values to use.
4 Select the values to import.
*To import all values, choose the double right arrow (>>) button.
*To import a particular value, select the value, and choose the right arrow (>) button.
Choose OK. Edit Parameter displays the imported values in the Selection list values table, as shown in Figure 13‑20.
Figure 16-16 Imported values in Edit ParameterFigure 16-16 Imported values in Edit Parameter
Figure 13‑20 Imported values in Edit Parameter
5 To provide descriptive labels for users to choose, other than the value in Value, perform the following steps:
1 Double-click the item in the Selection list values table.
2 In Edit Selection Choice, in Display Text, type the text that you want to display to the user. Figure 13‑21 shows an example of displaying United Kingdom for the value, UK.
Figure 13‑21 Specifying the text to display
3 Choose OK to save the change. The Selection values table displays the updated value.
6 To add values manually, complete the following steps for each value:
1 Next to the Selection list values table, choose New.
2 In New Selection Choice:
1 In Display Text, type the text prompt to display to the user.
2 In Value, type the value to pass to the SQL query or the filter condition. Figure 13‑22 shows an example of a user-defined value that appears as All Customers on the Enter Parameter dialog when the user runs the report. When the user selects this value, % is passed to the SQL query.
Figure 13‑22 Creating a new value
3 Choose OK. The new value is added to the Selection list values table.
7 To designate a value as the default value, select the value, then choose Set as Default.
8 To specify how the values should be sorted when presented to the user:
1 Under Sort, in Sort by, select one of the following values:
*Select None, the default, to display the values in natural order, which is the order of items in the Value column of the Selection list values table.
*Select Display Text to display in ascending or descending order the values in the Display Text column.
*Select Value Column to display in ascending or descending order the values in the Value column.
2 In Sort direction, select either Ascending or Descending.
9 Choose OK to save your changes to the report parameter.
Creating a dynamic list of values
You can create a dynamic list of values for a list box or a combo box. First, create a data set that retrieves the values with which to populate the list. The query in the following example retrieves all the unique values from the customername field in the Customers table. Specify this simple query in a data set to populate a parameter list with all the customer names.
SELECT DISTINCT customername
FROM Customers
For a report design using dynamic lists, BIRTretrieves values from the data source when the report runs. You cannot predict during the design process how many values the list box or combo box displays when the user runs the report. If you are concerned about the list getting too long, specify a maximum number of values to display. This solution, however, is not practical because the list displays the first value up to the specified maximum number, and omits the rest of the values.
You can display alternate values if you do not want to display the actual field values. You cannot, however, specify an alternate display value for each individual value because you do not know at design time the precise list of values. Instead, you specify an expression that applies to all the values. For example, you can prepend values with static text by using an expression, such as:
"Order " + dataSetRow["Ordernumber"]
How to specify dynamic report parameter values
This procedure assumes that you already created a report parameter.
1 In Data Explorer, expand Report Parameters, then choose the report parameter to edit. Edit Parameter displays the property settings for the report parameter.
2 In Display type, choose Combo Box or List Box.
3 In Selection list values, choose Dynamic. Edit Parameter displays additional fields, as shown in Figure 13‑23.
Figure 16-18 Dynamic parameter options in Edit ParameterFigure 16-18 Dynamic parameter options in Edit Parameter
Figure 13‑23 Dynamic parameter options in Edit Parameter
4 In Data set, choose the data set that returns the field values to display in the list box or combo box.
5 In Select value column, select the field that contains the values to pass to the SQL query or filter condition at run time.
6 Optionally, in Select display text, select a field that contains the values that you want to display to the user. For example, the values to pass to the SQL query or filter condition are from the customernumber field, but you want to display values from the customername field to the user. You can also use the expression builder to specify an expression to display custom values. The following example shows how to use an expression to combine values from two fields:
dataSetRow["ORDERNUMBER"] + "--" + dataSetRow["CUSTOMERNAME"]
From this expression, BIRT provides meaningful values to the user, such as:
10100--Online Diecast Creations, Co.
10101--Blauer See Auto, Co.
7 Optionally, in Default value, select a value to use as the default.
8 Optionally, in List Limit, specify the maximum number of values to display.
9 Choose OK to save your changes to the report parameter.
Enabling the user to select multiple values
You can provide the user with the option of selecting one value, multiple values, or all the values in a list. To provide this option, you must select the list box as the parameter display type and create a BIRT filter that uses the report parameter values.
How to enable the selection of multiple values
This procedure assumes that you already created a report parameter.
1 In Data Explorer, expand Report Parameters, then choose the parameter to edit.
2 In Edit Parameter, in Display type, choose List Box.
3 Create a static or dynamic list of values, using the steps provided in the previous sections.
4 Select Allow Multiple Values.
5 Choose OK to save your changes to the report parameter.
6 Create a filter at the data set, table, or list level. To define the filter condition:
*Select the field to filter.
*Select the In operator.
*Specify the report parameter as the filter value.
Figure 13‑24 shows an example of a filter condition that returns data rows where the PRODUCTVENDOR field contains the value or values in the RP_productvendor report parameter.
Figure 13‑24 A filter condition that uses report parameter values