Entering Parameters
Creating parameters and using them within a report’s selection filter and its formulas is just one aspect of parameters. The second aspect is when the user runs the report and enters the data into the parameter fields. Although this is a pretty simple process, it helps to review it to make sure you are familiar with each aspect of it.
When a report opens the first time, it presents you with the Enter Values dialog box. This dialog box lists all the parameters used in the report. Each parameter is listed in the order that they appear in the Field Explorer window and each parameter is enclosed within its own grey box. Within each box is the prompt text that tells the user what to enter and an input area for entering the values. At the bottom of the dialog box are the OK and Cancel buttons for accepting or canceling the input. An example is shown in Figure 4-14.
Figure 4-14. The Enter Values dialog box for entering parameters.
If you don’t see the OK and Cancel buttons or you notice that some of the parameters are missing from the dialog box, it is because there are too many parameters to display within the dialog box’s default size. You have to scroll down to the bottom of the dialog box to see the remaining parameters as well as the buttons.
When you refresh the report data by pressing the F5 key or clicking the Refresh Data button on the toolbar, you are asked whether you want to use the existing parameter values or enter new values. If you select the option to enter new values, then the Enter Values dialog box is presented again and you can override the existing parameter values. If you select the option to keep the existing values, then the report opens without prompting you for the parameters.
Crystal Reports presents different prompts for each data type and option. This creates numerous possible combinations for entering values. Fortunately, they are presented in such a way that it’s pretty obvious how to use each one. We’ll cover the basics here so that you are familiar with them.
The most basic type of parameter prompt is for the single value parameter type. It simply presents you with an input box for entering the value. If the data type is Boolean, then you are shown a dropdown list that lets you choose True or False.
If the data type is Date, you have to enter the date in the format of “yyyy-mm-dd”. There is a button listed next to the input box that you can click on to display a pop-up calendar (see Figure 4-5 at the beginning of the chapter). The calendar is useful if you need to enter a date at a particular time (the last Friday of the month) and you need to see an overview of the entire month to figure out which date it is. Clicking on a day in the calendar automatically causes the pop-up window to close and it fills in the date for you.
Question: Is there a way to override the default input format for dates? I want to let the user enter a date in the format of MM/DD/YYYY but Crystal Reports doesn’t let me.
Answer: There are two ways to change the default input format for dates. The first way is to change your browser locale settings. Crystal Reports uses the current locale for setting the date format. If you want to manually set the date format, there is a trick you can use. Change the parameter to a String data type and set the edit mask to “00/00/0000” (or the local date format you use). This requires the user to enter the date in the proper format. To filter on the parameter value use the Date() function to convert the string to a date. The drawback to using this technique is that since the parameter is now a string data type, there isn’t a pop-up calendar for selecting the date.
The next parameter type that effects how the user is prompted is a parameter with default values. This was already discussed in detail in an earlier section. To summarize, a parameter with default values presents you with a dropdown list showing all the possible default values. Click on the one you wish to use. When using default values, you can set the option that allows the user to enter a custom value. When this is selected, an input box is shown below the dropdown list and the user can enter a value not shown in the default value list. This was shown in Figure 4-14 as the Selected Country parameter.
Entering range parameters presents you with more options than the simplistic discrete parameter does. Range parameters let you select a start range and end range. In addition to that, you can specify whether these values should be inclusive or exclusive. You can also specify if there should be no start or end range at all. Figure 4-15 shows an example of entering a range parameter and the options that can be selected.
Figure 4-15. Range parameter dialog box.
Entering the start and end values is done via the two input boxes located adjacent to each other. Below each input box are the two options that specify how the value should be used. The first option is Include This Value and it is checked by default. It specifies that the value you entered should be included as part of the range. For example, let’s say that you are entering values for a date range parameter. If you enter the values 10/1/2005 and 10/31/2005, then by default the range is inclusive and the first valid date is 10/1/2005 and the last valid date is 10/31/2005. However, if you uncheck the Include This Value option then the date you entered won’t be included in the range. If you did this for the start range, then the first valid date would be 10/2/2005 because 10/1/2005 would be excluded. If you did this for the end of range, then the last valid date would be 10/30/2005.
Excluding one of the range values is useful when the beginning or end of a range is always changing. For example, let’s say that you want to print the entire month of February but you can’t remember when there is a leap year. In this case, you would enter an ending range of 03/01/2005 and uncheck the Include This Value option. That way you know that the valid date range will always go to the day before the first day of March, but not include March 1st. This lets Crystal Reports determine what the last day of the month is and whether February is in a leap year or not. Another example is printing an employee directory of everyone with a last name that starts with the letter B. You would enter the start range of “B” and an end range of “C”. For the end range, you would uncheck the Include This Value option. This will include every possible last name that starts with the letter “B” without you having to actually know what the last one is.
The second option is No Lower Value/No Upper Value. This means that you don’t want to specify a value for the start or end of the range. By checking the option No Lower Value, there is no minimum value in the range. For example, if you have a date range with No Lower Value checked and an end range of 10/31/2005 then the report will print every record with a date prior to, and including, 10/31/2005. It doesn’t matter if the first date in the table is from last year or ten years ago, it’s going to be included. The option No Upper Value means that there is no maximum value. Any date greater than the start range is treated as a valid date.
Of course, all these range related options can be combined to let you select any possible date range you need. The one thing to be aware of is that when you select one of the options No Lower Value or No Upper Value, then you can’t enter a value for that part of the range. This makes sense because if you specify that there is “No Lower Value” then why would you try to specify a lower value? You wouldn’t, and consequently Crystal Reports disables the input box.
The last parameter type to consider is the multi-value parameter. This parameter lets you build a list of acceptable values. It is also the most complex because it lets you combine both discrete and range parameters within this list of acceptable values. Figure 4-16 shows an example of a parameter that lets you specify a list of countries to print. This list can consist of a range of values or the names of individual countries.
Figure 4-16. Enter multiple values for the Country parameter.
The top of the dialog box is where you enter the range values. Enter the start and end values and click the Add Range button. It gets added to the list in the bottom right corner. You can see in the figure that it lists both the start and end range with “…” between them showing that it is a range value. The input box below the range values lets you enter discrete values. Click the arrow button to add it to the list to the right. If you accidentally add an incorrect item to the list, you can select it and click on the Remove button. You can also remove all the items in the list and start over from scratch by clicking on the Remove All button.
As of this edition of Crystal Reports, all prompts are displayed as simple input boxes or lists. You can’t use prompts such as check boxes or radio buttons. Hopefully, this will be a feature we see in a future edition!
Question: Is it possible to use a formula field to set the default value of a parameter?
Answer: The normal behavior of parameters is that the user has to enter a value for each one. But you can get around this by making the report a subreport of a blank report and in the blank report create a formula which is linked to the parameter field. By linking the formula in the main report to the parameter in the subreport, you are giving the parameter a default value. When you link the formula in the main report to the existing parameter in the subreport, ignore the default parameter that Crystal Reports shows by default. Linking subreports are discussed in more detail in Chapter 9.
