As Crystal Reports has become increasingly advanced over the years, the number of ways to customize reports has also increased. However, passing data to a report hasn’t changed much. Parameters are still the preferred method of passing data to a report. This chapter explores how to create parameters, query the user for input, and use parameters to customize a report.
Inputting Parameters
A parameter is like any other field on the report: it can be displayed on the report, used in filters, and used to change the formatting of report objects. Crystal Reports considers parameters to be the programming language equivalent of a constant data type. The parameter is assigned a value when the report loads and that value never changes.
In their simplest form, parameters are used as an easy way to let the user enter a value. At another level, they can be thought of as a way of creating advanced input boxes. Parameters can have default values defined in such a way that the user is able to enter the value by selecting it from a predefined list in the combobox. The programmer controls how many options a user has in the combobox. The section on default values details the setting up of parameters in this way.
When a report loads, parameters get their values by displaying a dialog box to the user. This dialog box prompts the user for information and it has input fields for the user to enter one or more values. Once the user closes the dialog box, the report uses the user input to generate the report. An example of this is a report that prints records between a valid data range. Parameters confine the beginning and ending date ranges.
Adding Parameters
Parameters are another type of report object. The steps to add and modify them are similar to what you’ve already been doing. Add a parameter by clicking on the Field Explorer tab (on the left side of the IDE by default) and right-clicking on Parameter Fields. Then, select the New menu option. Clicking on an existing item allows the option to edit, delete or rename the item. Figure 5-1 shows this menu.
Figure 5-1. Menu option for adding a new parameter.
Once you select New, the Create Parameter Field dialog box appears, shown in Figure 5-2.
Figure 5-2. The Create Parameter Field dialog box.
This dialog box has two textboxes and one dropdown box at the top. This is for entering the necessary properties: the parameter’s name, the prompting text, and the value type. The Name property is how the parameter is referenced in the report. Running the report triggers the display of the Prompting Text, which should describe what the user is asked to enter. The Value Type property selects the data type for the parameter field. All the available data types are listed in this dropdown box.
The lower half of the dialog box lets you set the options for the data that the parameter can store. Table 5-1 describes four options.
Table 5-1. Options for parameter fields
| Option | Description |
|---|---|
| Discrete value(s) | The user must enter a single value. |
| Range value(s) | The user enters two values that are the beginning and ending points of a range. The range includes the values entered. For example, if you entered a range of 1,000 and 1,999, it would include all numbers from 1,000 up to and including 1,999. |
| Discrete and Range values | The user can enter both discrete and range values. |
| Allow multiple values | Allow a parameter to accept more than one value. |
The option to allow multiple values is used with discrete values and range values. For discrete values, the user can enter multiple single values and they are each treated individually. For range values, the user can enter multiple sets of ranges and each range is treated separately from the other ranges entered. A parameter can also have a collection of both discrete values and range values.
The Create Parameter Field dialog box for Boolean data types has different options. When you change the Value Type property to Boolean, the lower half of the dialog box changes to reflect the new options (see Figure 5-3).
Figure 5-3. The Create Parameter Field dialog box for Boolean data.
Boolean parameters can be thought of as being similar to checkboxes or option buttons. With checkboxes, each value is independent of the other. That is, selecting or changing one checkbox has no effect on other checkboxes. This is the default behavior of Boolean parameters. Option buttons are used in groups and each is mutually exclusive of the other. Selecting one will automatically turn off all others in the same group. The Place in Parameter Group option lets you place a Boolean parameter in a parameter group. Give it a group number and set whether the parameters in that group are mutually exclusive to each other. If the parameters are mutually exclusive, only one Boolean parameter can be assigned to True at a time. If the user sets two or more parameters to True, only the most recent will keep its value; the others are reset to False.
