Constraint settings

Constraint settings control the text that the user is allowed to input. For example, you can limit input to a range of numbers, to a particular length, or to a specific pattern, such as the common ###-####.

Constraint settings follow this syntax:

   <format>
      <constraints>
         <settingname₁>setting</settingname₁>
         ...
         <settingname_n>setting</settingname_n>
      </constraints>
   </format>

Note: You can define any number of settings.

The following list defines that valid settings:

applyifinvisible

Sets whether invisible or inactive items are included in the format validation check.

on – Items that are not displayed, visible, or active are included in format validation check.
off – Items that are not displayed, visible, or active are NOT included in format validation check.

casesensitive

Sets whether the data entered must match the case of the defined constraints. Valid settings are:

on – The data entered must match the case of the defined template.
off – The data entered does not need to match the case of any defined template.

Default: off.

Note: casesensitive is only available for the string data type.

checks

Allows you to force the format check to fail, or to ignore all constraints settings. Valid settings are:

fail – Forces the format check to fail.
ignore – Ignores all constraint settings. Note that the data type and the presentation settings are still respected.
none – Has no effect.

Default: none.

decimalseparators

Defines one or more symbols that are allowed to indicate the decimal place. This is often a period, as shown:

   100.00

List each separator in its own separator tag, as shown:

   <decimalseparators>
      <decimalseparator₁
         >separator</decimalseparator₁>
      ...
      <decimalseparator_n
         >separator</decimalseparator_n>
   </decimalseparators>

You can use any string, such as a comma or a comma followed by a space. This setting is only valid for integer, float, and currency data types.

Note:

The user must use the same separator in a given string. For example, if you define both comma and space as valid separators, the user must type either 1,000,000 or 1 000 000. Mixing the separators, as in 1,000 000, is not allowed.
If this setting is empty, it inherits the decimalseparator defined in the presentation settings.

Default: a comma.

groupingseparators

Defines one or more symbols that are allowed to separate groups of numbers (such as thousands in North America) during input. This is often a comma, as shown:

   1,000,000

List each separator in its own separator tag, as shown:

   <groupingseparators>
      <groupingseparator₁
         >separator</groupingseparator₁>
      ...
      <groupingseparator_n
         >separator</groupingseparator_n>
   </groupingseparators>

You can use any string, such as a comma or a comma followed by a space, with the keyword none representing no separator at all. This setting is only valid for integer, float, and currency data types.

Usage details

The user must use the same separator in a given string. For example, if you define both comma and space as valid separators, the user must type either 1,000,000 or 1 000 000. Mixing the separators, as in 1,000 000, is not allowed.
If this setting is empty, it inherits the groupingseparator defined in the presentation settings.

Default: a comma.

length

Sets a range of lengths that the data entered must fall within. To do this, you must include the <min> and <max> tags in your definition, as shown:

   <length>
      <min>shortest length allowed</min>
      <max>longest length allowed</max>
   </length>

For example, if you wanted all values to be between 4 and 7 characters in length, you would set the min to 4 and the max to 7. This allows the user to enter a value that is either 4 characters or 7 characters in length, as well as all lengths in between.

The length is calculated after all formatting has been applied, and will include all formatting characters such as the negative sign, currency symbols, and so on.

If you add a length setting to a field, the field is treated as mandatory.

Default: the maximum range of lengths allowed for the data type.

mandatory

Sets whether the user must enter a value. Valid settings are:

on – The user must enter a value.
off – The user need not enter a value.

This value works in conjunction with the required property for the linked element in the XForms model. If either setting indicates that input is mandatory, then it is mandatory.

Default: the required property of the linked XForms data element, or off.

message

Sets the message that is displayed when the input is invalid. This can be any text.

Default: none.

patterns

Allows you to set one or more patterns for strings, date, or numbers that are valid as input. For example, you might want to constrain dates to the following format: YYYY-MM-DD.

You must define each pattern in its own <pattern> tag, as shown:

   <patterns>
      <pattern₁>pattern</pattern₁>
      ...
      <pattern_n>pattern</pattern_n>
   </patterns>

If you define more than one patternref in the presentation settings, you must define an equal number of patterns in the constraints. Each patternref is then matched to the corresponding constraint pattern. For example, the first patternref is matched to the first constraint pattern, the second patternref is matched to the second constraint pattern, and so on. This allows you to define a different pattern for each constraint.

Note that unlike the template setting, the pattern setting does not show users any of the text you include in your patterns, since there is no way to tell which pattern the user will follow.

range

Sets a numerical range that the data entered must fall within. To do this, you must include the <low> and <high> tags in your definition, as shown:

   <range>
      <min>smallest number allowed</min>
      <max>highest number allowed</max>
   </range>

The low and high values are inclusive. For example, if you wanted to create a range from 1 to 100, you would set the low value to 1 and the high value to 100. This allows the user to enter either 1 or 100, as well as all values in between.

If you set a range for a string, the data is evaluated on a character by character basis. For example, you might set your low value to “fg” and your high value to “jk”. In this case, the first character entered would have to be in the f-j range, and the second character would have to be in the g-k range. This check ignores case.

Default: the maximum range allowed for the data type.

template

Allows you to display symbols in the input area before the user enters their data. This is useful if you want to show formatting placeholders, such as parentheses for the area code in a phone number.

To create a template, use a wild card to represent any 1 character that the user types in. All other characters are shown to the user as typed.

For example, if you create the following template:

   (...)...-....

The user will see the following:

   (   )   -

Setting a template in limits user input to the format set by the template. If the user attempts to enter incorrect data, it is rejected either by a warning message or by predictive input checking in the Viewer (if enabled).

Usage details:

For string data types, the following wild card characters are supported:
- Single wild cards: ., ?, #, and @.
  - . and ?: match any one Unicode character
  - #: matches any one Unicode digit character
  - @: matches any one Unicode letter character
  Note: When preceded by a back slash, the wild card characters become static.
- When preceded by a back slash, the following are static characters: *, %, !, and \.

yearwindow

Sets how to interpret two digit dates. This provides two options for interpreting dates:

Fixed Date – You can specify a specific year, such as 70. All numbers from that year and up are assumed to be in the 20th century (for example, 1975). All numbers before that are assumed to be in the 21st century (for example, 2004).
To set a fixed date, you must include the <fixedyear> tag as shown:
```
    <yearwindow>
      <fixedyear>the year</fixedyear>
    </yearwindow>
```

Sliding Date – You can specify a range rather than a fixed date. This means that the date on which the decision is based changes as time passes. The date is calculated by taking the current date and subtracting a number you specify. For example, if you set your range to 30 years and it is 2004, your decision date would be 2004 - 30 = 1974. In this case, all numbers from 74 and up would be in the 20th century, and all numbers under 74 would be in the 21st century.
To set a sliding date, you must include the <factor> tag as shown:
```
   <yearwindow>
      <factor>range</factor>
   </yearwindow>
```

You can set either a fixed date or a sliding date, but not both. If you do set both, the sliding date will override the fixed date.

Default: a sliding date with a factor of 30.