Enabling the User to Filter Data 

When you create a report, you build a data set and typically specify filter criteria to display specific data in the report. When a user views the report, the user sees the information that you selected. As users become familiar with the report and recognize its potential as an analytical tool, they may want to view the data in different ways. For example, in a sales report, a user may want to view only sales in California, or sales over a certain amount, or sales that closed in the last 30 days.

The solution for this type of ad hoc reporting requirement is for the report to prompt the user to provide information that determines what data to display. Report developers make this solution available by using report parameters.

To enable users to filter database data, you complete the following tasks in the recommended order. For detailed information about these tasks, see the corresponding topics later in this section.

n	Create report parameters to prompt the user to specify values that determine what rows to retrieve.

n	Insert parameter markers in the SQL query.

n	Create a data set parameter to supply a value for each parameter marker in the SQL query.

n	Bind the data set parameter to the report parameter, so that the data set parameter gets the user-specified value from the report parameter and passes it to the SQL query.

n	Determine how to present the report parameters to a user.

n	Test the report parameters.

How to create a basic report parameter

1	In Data Explorer, right-click Report Parameters, and choose New Parameter.

New Parameter appears, as shown in Figure 12‑1.

Figure 12‑1

New Parameter

2	Specify the following basic properties:

1

In Name, type a name for the parameter. It is good practice to use a prefix, such as RP, in the name to help distinguish report parameters from other parameter types, such as data set parameters. For example, a report parameter used to filter on a quantityinstock field might be named RP_quantityinstock. The value you specify in Name appears as the prompt to the report user if you do not specify a value for the next property, Prompt text. Rather than specify only a Name value for the parameter, you should use a technically descriptive value in Name, and provide a user-friendly value in Prompt text.

2	In Data type, select a data type for the parameter.

The data type that you select does not have to match the data type of the field in the data source. Values in an orderID field, for example, can be stored as integers in the database, but the report parameter that is associated with this field can be of decimal or string type. The data type that you select for the report parameter determines the formatting options that are available if you choose to provide a default value or a list of values for the report parameter.

3	Choose OK.

The parameter appears under Report Parameters in Data Explorer.

How to insert a parameter marker in the SQL query

This procedure assumes that you already created a data set.

1	In Data Explorer, right-click the data set whose query you want to edit, then choose Edit. Edit Data Set displays the query.

2	Add a WHERE clause with one or more parameters, as shown in the following examples:

WHERE quantityinstock < ?

WHERE quantityinstock <= ? AND productvendor = ?

WHERE quantityinstock <= ? OR productline LIKE ?

Figure 12‑2 shows an example of a query with two parameter markers.

Figure 12‑2

Query with two parameter markers

At this point, you are ready to define a data set parameter for each ? parameter marker. The next section describes this task.

How to define a data set parameter

This procedure assumes that you already inserted a parameter marker in the SQL query. If you use multiple data set parameters, create them in the order in which their corresponding parameter markers appear in the WHERE clause.

1	In Data Explorer, choose the data set for which you want to create parameters. Edit Data Set displays the query for the data set.

2	Choose Parameters. Edit Data Set displays the Parameters page. This page displays placeholder data set parameters, which BIRT Report Designer creates for each ? parameter marker you specify in the WHERE clause of the query

3	Edit each data set parameter. Select a parameter and choose Edit.

4	On Edit Parameter, specify the following information:

1	In Name, type a name for the data set parameter. It is good practice to use a prefix, such as DSP, to differentiate the parameter from other parameter types, such as report parameters.

2	In Data type, select a data type for the parameter.

3	In Direction, choose Input. This value means that the parameter is an input parameter.

4	In Linked To Report Parameter, select the report parameter to bind to this data set parameter.

Figure 12‑3 shows an example of a data set parameter definition where the data set parameter, DSP_quantityinstock, is linked to a report parameter, RP_quantityinstock.

Figure 12‑3

Data set parameter definition

5	Choose OK.

5	Repeat steps 3 and 4 to define additional data set parameters for any other parameter markers that you inserted in your SQL query.

6	To save the changes to the data set, choose OK.

7	Test the parameters to verify that the query is updated with user-specified values and that the report shows the results you expect.

1	Choose Preview.

2	If Enter Parameters does not appear, choose Show Report Parameters.

Enter Parameters displays all the report parameters that you created. Figure 12‑4 shows example report parameters, RP_quantityinstock and RP_productvendor. The parameter names are displayed because values were not supplied for the Prompt text property.

Figure 12‑4

Enter Parameters

3	Specify a value for each parameter, then choose OK.

If you completed all the tasks that were described earlier in this section, the WHERE clause of your query incorporates the specified values, and the report displays the rows that match the WHERE clause.