Filtering Report Data with Parameters

Objective

After completing this lesson, you will be able to filter data in a report using single or multiple parameter values.

Overview of Parameters

See the following scenario to learn restricting data using a parameter.

In a sunlit modern meeting area with large arched windows and minimalist chairs, two colleagues sit facing each other, leaning in over open folders and gesturing as they engage in a focused, collaborative discussion about reporting parameters (an overlaid speech bubble asks What is a parameter used for in Crystal Reports and why is it important? and another bubble explains how parameters prompt users for input and enable one report to serve multiple users), while a stylized calendar icon to the right suggests scheduling or planning.

Here is an example of parameter and how it is referenced by the Select Expert before covering the details in this lesson.

The following screenshot shows how to create a new parameter.

A screenshot of a Windows-style Create New Parameter dialog in a reporting/design application showing the Name field populated with My Parameter, Type set to String and List of Values set to Static, an empty Value/Description grid in the center, a Value Options table below listing settings such as Show on (Viewer) Panel: Editable, Prompt Text: Enter My Parameter, and Allow custom values: True, an OK/Cancel/Help button row at the bottom, and a right-hand Field Explorer pane listing Database, Formula, SQL Expression and Parameter fields (including Country Selected).

The following screenshot shows how to edit a parameter.

Screenshot of a Windows report-design dialog titled Edit Parameter: Country Selected displaying a parameter named Country Selected (Type: String, List of Values: Static) with an editable table listing the values USA, China, and Germany (plus a placeholder row Click here to add item), a Description/Value Field area and a Value Options panel showing settings such as Prompt Text Enter Country Selected: and Editable, and a right-hand Field Explorer pane listing Database Fields, Formula Fields, SQL Expression Fields and Parameter Fields with Country Selected highlighted.

The following screenshot shows how a parameter is referenced by the Select Expert.

A screenshot of a report-design Select Expert -- Record dialog in a Windows-style GUI shows a focused configuration task in which the left pane displays a filter criterion set to Customer.Country is equal to the parameter Country Selected (rendered in the formula box as {Customer.Country} = {?Country Selected}) with buttons for OK, Cancel, Help and Formula Editor, while the right Field Explorer pane lists Database Fields, Formula Fields, SQL Expression Fields and Parameter Fields (highlighting Country Selected), plus Running Total, Group Name and Special Fields.

Parameters are Crystal Reports fields that you can use in a Crystal Reports formula. As a formula component, a parameter must have a value before the program can process the report. By using parameters in formulas, selection formulas, and in the report itself, you can create a single report that changes its behavior depending on the values entered. Parameter fields can also be used in subreports.

Prompts are elements that help users set a value for report parameters. Prompts are different from parameters in the following ways:

  • Prompts aren't used directly by a Crystal Reports formula.

  • Prompts include user-interface settings that help you determine the appearance of the prompting dialog box that your users see.

  • Prompts include an optional list of values that your users can choose from. This list of values can be a static list that is stored in each report, or a dynamic list that is retrieved from a database (this type of prompt includes multi-level cascading lists that are also retrieved from a database).

  • Prompts can be set so that the parameter itself is optional.

When your users select values in the prompting dialog box, they're setting values for prompts. The Crystal Reports prompting engine then assigns that value to the corresponding parameter, which is finally used by the report. When you create and edit a parameter field, you work with one parameter and one or more prompts.

Once you've created a parameter field, you can use it (or reference it) in your report in place of a fixed value. Many of your reports may be similar to existing reports, but with modifications to the record or group selection. Perhaps the report must be modified to allow for a specific part code, date range, or other value in the record selection. Create a parameter field and use it in your record selection to allow for flexible reporting. When running the report you can choose the part code, date range, or other value you want for this occurrence of the report.

One of the most common uses of a parameter is in record selection (Select Expert).

For example, to easily modify a report for various regions, use a parameter field in place of a specific region value. {Customer.Region} = {?Region} where {?Region} is a parameter field you've created. The value you select for the region parameter field is used for the record selection in that occurrence of the report.

Typical Use Cases for Parameters

Parameters prompt the user of a report to enter information. Think of a parameter as a question that the user must answer before the report is generated. The information users enter, or the way they respond, determines what appears in the report. For example, in a report used by sales people, there may be a parameter that asks the user to choose a region. The report returns the results for the specific region, instead of returning the results for all of the regions.

Two Windows-style modal dialog boxes on a white background show a small Refresh Report Data prompt in the top-left with radio buttons offering Use current parameter values or (selected) Prompt for new parameter values and OK/Cancel/Help buttons, and a larger Enter Values window displaying a Country Selected dropdown set to USA and a matching Enter a Value text field with OK and Cancel buttons, presenting a neutral, functional user prompt to supply parameters for refreshing a report.

By using parameter fields in formulas, selection formulas, and in the report itself, you can create a single report that you can modify whenever your needs change.

A parameter field can be identified by braces and a question mark before the parameter name, for example:

{?parameter_name}

Create and Use a Parameter to Filter a Report

In this exercise, you will create and use a parameter to filter a report.

Summary

  • Parameters create dynamic reports by adjusting to user-provided values.
  • Prompts facilitate the setting of parameter values, enhancing user interaction.
  • Parameters enable flexible data filtering in record selection for varied report scenarios.