Setting Parameter Options

At the bottom of the Edit Parameters dialog box is an Options area that lists the available options that can be set for a parameter. It has options that let you do more with parameters than just display a list of default values for the user to pick from. Some of the advanced features are the ability to enter single or multiple values, set a range of valid entries, and control data entry using an edit mask. Each of the options on the Edit Parameters dialog box is listed below with a description of how to use it.

Prompt Text

The prompt text is the question that prompts the user to enter a value. You can type in any text that describes to the user what type of information they need to enter. It can also be helpful if you tell the user how the parameter is going to be used. For example, rather than just saying, “Enter the country”, the prompt could say, “Enter the country you want to print the sales for”. This tells the user what data is needed and why.

Prompt with Description Only

We already talked about this option in an earlier section. It gives you the option of showing the value and its description or of just showing the description. Only showing the description is useful when the value wouldn’t make sense to the user (e.g. a cryptic Inventory ID).

Even though you have the option of showing the description to the user instead of the actual value, behind the scenes Crystal Reports is storing the value field in the parameter. The user will never see this, but you need to make sure that any formulas you write with that parameter are done so with the expectation of using the value field. The description is strictly used for display purposes and nothing else.

Default Value

Even though some parameters have a large list of values to choose from, there are times when one value is used the majority of the time. When this is the case, you can have Crystal Reports display a default value. Rather than typing in the value, the user can just click the OK button. Of course, if the user doesn’t want to use the default value, he can override it with a new value.

Allow Custom Values

So far, everything we discussed in reference to the list of values assumes that the user always wants to pick a value from the list that you created. But this isn’t always the case. For example, the list of values might be out of date and you haven’t had time to add the new entries. Thus, the user needs to enter a value not in the list. You could also have a list of values that just show the user the most commonly used values, but it doesn’t show every single value because there are too many to view. In this case, the user can enter a new value if the value he needs isn’t in the list.

When the Allow Custom Values option is set to True, the user is presented with a second text area directly below the dropdown list. The text area allows you to enter a new value for the parameter. This is illustrated in Figure 4-8.

Figure 4-8. Letting the user enter a custom value.

Since there are two input areas now, you might be confused about which one Crystal Reports will use. Crystal Reports always uses the value in the text box. If the user enters a custom value, it is entered in the text box at the bottom and Crystal Reports knows to use it. If the user picks an item from the drop-down list, then when they select that item Crystal Reports will automatically enter it in the bottom text box as well. This ensures that the text box has the correct value even when the user picks an item from the drop-down list.

Min/Max Length

When a parameter’s data type is String, you can set the minimum and maximum number of characters that the user can enter. Crystal Reports will only accept a parameter if its length falls within the specified range. This helps enforce data integrity. For example, if a parameter filters on the state’s abbreviation (KY, CA, etc.), then the Min Length is 2 and the Max Length is also 2.

When setting restrictions on the length, you aren’t required to enter a value for both the Min Length and Max Length properties. You can set just one of the properties or neither. For example, most passwords have a minimum length requirement but no limit on the maximum number of characters you can enter.

The Min Length and Max Length properties are not available for Numbers, Dates or Boolean data types. However, both Numbers and Dates do let you specify a minimum and maximum range of values (described next).

Min/Max Value

Numbers and dates can have valid ranges assigned to them. You can specify what the minimum and maximum values are. This prevents the user from entering a parameter value that is outside the acceptable range.

For dates, the range properties are called Start and End. Although they are named differently than the number properties, they mean the same thing.