How to use a section rule to prompt for report criteria
Many reports provide a user interface in which the application can request, and the user can provide, values the report needs: “get me the invoices created within a certain time period”, or “show me this information for users with this last name.”
You can easily offer such an interface using the report's default format. With the addition of a section rule, you can provide a custom form that offers user-friendly fields and makes use of your application's style sheet. The process is the same for list view and summary view reports.
- Create an appropriate list view or summary view report, or save a copy of an existing report. This example uses a copy of a report that finds all the work objects created in the current application during the past X days. The report in its original format offers a default of 30 days for X.
To create the report used in this example, follow the steps in How to use parameters as selection criteria in a list view rule.
Run the report to see the default experience. The report runs without any user input, relying on the default value of 30 days, and returns a list of work objects created during that period.
To change the default number of days, the user must click the Customize list criteria link. A system-designed screen then appears where the user can specify two DateTime values as the start and end times for the data in the report.
The following steps prepare and deploy a section rule that will offer more attractive prompts.
- Create two property rules to hold the start and end dates and times the user will submit. Set the Property Type for each to DateTime.
- Specify a page on the clipboard where the fields will appear:
- In the List View rule form, select the Pages & Classes tab, and add a row.
- Give the new page a descriptive name, and specify as its class the same work class as the first key part of the report rule.
- Save the rule.
- Create a section rule that the list view rule will use to display the parameter prompts. Give the new section rule a descriptive name in the Purpose field:
- In the Layout tab of the new section, provide instructions and appropriate data fields. This example uses two Calendar controls to simplify user data entry.
- Set the property for each Calendar control to one of the properties you created in step 3, and verify that the Display As field is set to DateTime-Calendar.
- Select the list view rule for this report and bring the Content tab to the front. In the Criteria section create two rows labeled A and B, if they do not already exist. Set the first one to check whether the creation date for each order is newer than the date the user has specified as the start date for the report. The second row checks whether each creation date is older than the date the user has provided as the end date. In the Value column, enter one of the two properties you created in step 3.
- Set the value of the Logic field to "A AND B". That is, for each order that the report checks, if the result is true for both rows, then the order is included in the report data.
- Under Prompt Settings, click Configure. The Configure Prompt Settings dialog appears.
- Change the selection in the drop down menu at the top left from Default to Custom.
- In the Prompt Page Name field that appears, select the page you created for this report's parameters.
- Check the Prompt user... check box and, in the field that appears, select the section you created to display the customized parameter fields for this report.
- You can also change the label on the report's search button by changing the text in the Search Button Label field.
- Click Apply.
- In the List View rule for this report, bring the Organize tab to the front. Deselect the Customize View button and Customize Criteria link check boxes if they are selected, as these options are not available when you use a section-based prompt page.
- Save and run the List View rule again. The screen displays the section you created, formatted according to the style sheet for your application.
- Click Run and the report displays.
- For added user convenience, display the search criteria above the results. This allows the user to modify the criteria and run the report again.
- In the list view rule you created, bring the Content tab to the front and click Configure, as in step 8.
- In the Criteria Prompt Settings dialog, select the Display Criteria... check box and, in the the drop down menu that appears, select the section you created, as in step 9.
- Save the rule.
- Run the report again, entering values for the start and end dates. The resulting display will include, at the top of the screen, the report criteria you used.
Published December 9, 2008 — Updated July 20, 2009