Edit Mask

Some string parameters have a format where special characters appear within the string at particular locations. For example, a phone number has the format of (999) 999-9999. No matter what the phone number is, it has to be formatted the same every time. Crystal Reports gives you the ability to specify an edit mask for string parameters that forces the user to enter a string in a very precise way. If there are special characters such as a dash or colon, it forces the user to type in the field exactly and it guarantees that the data they entered is formatted properly.

Creating edit masks can be a little confusing if this is the first time you’ve ever used them. Each edit mask consists of a bunch of characters and each character has a rule that specifies what the user can and can’t type in that position. But edit masks aren’t hard to use once you understand the rules. You just have to practice a few times to get the hang of them. Let’s start by looking at a few examples and then we’ll look at what the rules are.

Social Security Number: 000-00-0000

This edit mask requires the user to enter a social security number in the precise format. The “0” in the edit mask says that the user must enter a digit from 0-9. The first three characters will be numbers. The dash is a literal character that can’t be replaced with another character. Thus, this edit mask requires the user to enter a certain quantity of numbers with dashes in between.

Phone Number: (000)000-0000

This phone number edit mask is similar to the social security edit mask. The only difference being that it uses two parentheses. These are also literal characters and must be typed in exactly.

State Abbreviation: >AA

A state abbreviation is always two characters long. This edit mask uses the A character to force the user to enter a letter. What makes this edit mask interesting is that is also uses the greater-than sign at the beginning. This requires all letters to be entered as upper-case. This is useful when doing text searches that are case-sensitive.

One thing to be aware of is that by using an edit mask you are indirectly specifying what the Min Length and Max Length properties are. Since the edit mask specifies how many characters must be typed in, the user can enter no more and no less. Thus, when using an edit mask, it isn’t necessary to also specify the Min Length and Max Length properties because this is already implied.

Table 4-2. Edit mask characters and the rules for usage.

When the user enters a parameter value that doesn’t match the edit mask, the error messages aren’t always very helpful. First of all, if there are multiple errors in the value, the user is only told about them one at a time. After she corrects one error and clicks the OK button, she is then presented with the next error message. It would be helpful if a bullet-point list of all the errors were shown at once. Secondly, the dialog box always displays the edit mask to the user so that they know what type of data entry is expected. This is certainly helpful for the person who designed the report, but most users are not going to have any idea what all these funny characters mean. For some users, seeing the edit mask can do more harm than good. The best way to keep this from hindering your reports is by using preventive medicine. Within the prompt text, you should indicate to the user what the edit mask rules are so that the user knows in advance the proper way to enter the data. For example, if you want them to enter a two digit state abbreviation and have each letter upper case, then just say so. Make the prompt text say something like, “What state do you want to filter on? Please enter the two letter abbreviation using uppercase letters (e.g. KY).”