A Validation Rule allows a configurator to identify and communicate problems with a configuration to a user. If a user has entered data into a field which exceeds a threshold or limit, a validation rule can...
- Show the error.
Add a visual indicator highlighting that field as invalid - Explain the error.
Add messaging to that field or any other field describing the problem, and - Offer to fix the error.
Add a "fix this" button that contains one or more pre-designed solutions to the problem.
This differs from Value Rules, where you can automatically correct or set a field to a value with no interaction from the user. Validation rules invite user interaction.
Validation rules are part of the rule cycle. They run each time a change is made to the configuration, and are performed after the value rules are run. The validation state of all fields is reset before the start of each run.
Two types of validations exist, warnings and errors.
- A warning will display an orange caution triangle. The user will still be able to submit their configuration.
- An error will display with a red exclamation point next to the field. The user will not be able to submit their configuration. (This can be overridden by adjusting a Configurator Property.)
Arguments
Arguments are variables passed in to the rule. You can find them by using the Get/Set variable snap blocks. In this rule type, the Get block exposes these arguments:
| Name | Type | Description |
|---|---|---|
| clientLanguage | text | the two-character code representing the current user's preferred language. |
| configurator | Configurator | the current running configurator. |
| environment | string | "dev" if you are in the development environment, "test" if you are in the test environment, and "prod" if you are in the production environment. |
| isMobile | boolean | true, if the viewport seems to have the size of a mobile device. Use this flag to show something differently on screen if required by a smaller device. |
| user | User | the current user. |
| parameters | map | a map of GET or POST parameters passed into the configurator when it was launched. |
Examples
Take a vehicle configurator, which could have three different values for the type of vehicle: A motorcycle, passenger car, or truck. The limit on the number of wheels depends on the type:
This sets the minimum and maximum values.
Next, we can apply this to the field validation:
If isValid is equal to false, then the field will be marked invalid and labeled with the specified message.
In practice, it's usually better to specify minimum and maximum values for the field itself, assuming it is a number type. However, in some cases, you may still want to validate number fields in this manner, as it invites interaction. Instead of overwriting the user's previous selection, you may want to simply warn the user that their setting exceeds recommended values.
"Fix This" functionality
Validation Rules can also provide preset options to correct a validation error. The validate field block has a "+" mutation button which can add this function to your validation rule.
Example
Given a hypothetical car configurator, you may want to validate that a V8 engine has at least 2.1 liter displacement. The validation rule below will offer two options to correct this error if it is invalid. Either the user can reduce the number of cylinders to 6 or the displacement can be increased to 2.1 L.
When a user inputs the incorrect parameters, the validation rule will have a "Fix This" button next to the associated error, providing the two options as defined above. The example below shows the dropdown after the "Fix This" button has been clicked.
Localizing your Validation Rule
The base logic of your validation rule doesn't change from one language to the next. But the message you show and the text of your "fix this" choices do. Here's how to make that validation rule text appear in the correct language. The basic idea: rather than embedding hard-coded text throughout your rules, you use a function to gather the correct string from a lookup table that has been localized.
- Understand the fundamentals.
You should already know how to localize tables, and have experience in some of our more powerful text manipulations.
- Create a lookup table of message strings, and a function to retrieve a message from the table.
This is generally a good idea in any application. Rather than embedding hard-coded text throughout your rules, you would call a function that, given a message code, returns a message string. - Replace your hard-coded text with a call to the function.
The function then retrieves the appropriate message from the table, and shows that in your message rule.
Snap rules run in a specific order, and in response to specific events. Learn more about rule execution order.