A Value Rule allows a configurator to programmatically manipulate field values based on algorithms, formulas, and other business logic. In addition, value rules can be used to add and delete nested configurators, set select field options, and set field, group, and page labels. Common uses for value rules include:
- Pre-populating field values with defaults based on previously entered data.
- Relabeling a label field with hard-coded data (e.g. if someone enters a width, height, and depth for a box, you may want to change a label field to display the volume)
- Adding nested configurators
Like all rules in configurators, the Value Rule uses Snap.
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 |
|---|---|---|
| changedField | Field | Which field had changed. Note that this variable may be null, since sometimes value rules are executed independent of whether a field value has changed. |
| 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. |
| parameters | map | a map of GET or POST parameters passed into the configurator when it was launched. |
| user | User | The logged in user, in case your value rule's logic depends on who is using the configurator. |
Examples
1. Setting a Label
A common use of a value rule is to display informative information in label fields based on entered data. The following informs the user of the volume of a cube based on the entered height, width, and depth.
2. Applying a Default Value to a Field
Another common use is to apply a default value to a field based on prior entered content.
Value rules can apply business logic (set a value you don't want the user to edit), or can help you set default values (a value you offer to your user, but want them to be able to change). In this example, we're setting a default. Since value rules are run every time a change is made, you should make sure of two things if you're setting a default value:
- If you are setting a default value of a field, it is best practice to set its default based on fields that are displayed prior to this field (fields above this field in the design tree). If you change the values of a field that had already been entered by the user, you may cause confusion after the user scrolls back up and notices the changed value. It's best to adjust a field the user will go to, not one they have already set. In the UI for the example here, we should place the Width field above the Height field. In this way, the user will first have selected a width and then the height field will be populated with the default we calculate. So, by the time the user focuses on the height field, it's set for them.
- Value rules are run every time a change is made to a field. For this reason, if you are setting a default value, you should make sure it is only set under the condition that it is currently unset (in the above example, we are first checking if the height is zero before we set it). If you fail to do this, then no matter what value your user overrides the default with, the field will always be set back to the default.
3. Running a Value Rule only when necessary
Since all value rules are run each time a change is made to any field, you may want to ensure that a specific, time-consuming value rule is run only when necessary. For example, imagine a configurator that allows your user to choose the type of metal. If they choose gold as the metal, you want to perform a web service call-out to gather today's price of gold, to ensure you are charging the customer an appropriate price. This web-service call-out, like all web services, takes a few seconds to run. If you call this web service in a value rule, you are adding significant delay to the user's experience with every click.
Here's a value rule which calls the slow safe function (which contains the web service call-out) every time:
A better design would be to call that slow or expensive operation only if the user has edited the "material" field, and that field has the value "gold":
The first three conditional clauses were written separately here for easier understanding. Since they are all booleans, you can "and" them together:
Don't Repeat Yourself: store common value and event logic in a global event rule.
When writing a value rule, you have access to code stored in Global Event rules. Global Event Rules are libraries of shared code, functionally the same as global rules. However, the types, functions, and subroutines that are defined within a Global Event rule are only accessible from value rules and event rules.
Snap rules run in a specific order, and in response to specific events. Learn more about rule execution order.