validationRules

running validationRules at the client is considered in beta.

Validation rules can be used to perform checks on the values of the fields, automatically update values to conform to certain restrictions, and prevent submit of a form with invalid values.

The validation rules allow expressing certain conditions the fields should adhere to. The syntax is similar to the validationRules syntax used by Limecraft API.

Example

Say we have a compound form field representing a numeric range. It has an in and an out field.

{
    compoundDefinition: {
        "fields": {
            "in": {
                label: 'In',
                multiValued: false,
                type: 'INTEGER',
                handle: 'mediaAssetIn',
            },
            "out": {
                label: 'Out',
                multiValued: false,
                type: 'INTEGER',
                handle: 'mediaAssetOut',
            }
        },
        "validationRules": {}
    },
    "hidden": false,
    "label": "Range",
    "multiValued": false,
    "type": "COMPOUND"
}

Now we want to ensure that the value of out is always greater than that of in. The compoundDefinition can have a validationRules property, which we will fill in as follows:

{
    fields: { ... },
    validationRules: {
        "rules": [
            {
                "description": "Not a valid range",
                "evaluateClientSide": "Blur",
                "handle": "out-gt-in",
                "operator": "AND",
                "rules": [
                    {
                        "leftSide": {
                            "select": "out/value",
                            "undefined": false
                        },
                        "op": "gt",
                        "rightSide": {
                            "select": "in/value",
                            "undefined": false
                        },
                        "type": "LIMECRAFT_RULE"
                    }
                ],
                "showClientSide": false,
                "validateAt": [
                    "Runtime",
                    "DeliveryRequestSubmissionSubmit"
                ]
            },
        ],
        "version": 1
    }
}

The syntax is the same as rules evaluated on the server. However, some restrictions apply.

Limitations of client-evaluated rules

The following limitations apply if you want the rule to evaluate on the client.

  • only AND operator is supported

  • when using select, it should be of the form fieldName/value or handle:/value. All other selects are not supported.

  • type should be "LIMECRAFT_RULE"

  • only the field mentioned in leftSide (not rightSide) will be changed automatically to conform to the rules

  • no hierarchical rules: validationRules.rules[i].rules[j] should be a basic rule.

  • op should be one of arrayContains, stringContains, eq, gt, gte, lt, lte

op

op Description

gte

This rule ensures that the leftSide field has a value greater than, or equal to the value referenced by the rightSide.

{
    // out's value should be greater than, or equal to, the value 250
    "leftSide": {
        "select": "out/value"
    },
    "op": "gte",
    "rightSide": {
        "value": 250
    },
    "type": "LIMECRAFT_RULE"
}

It is possible to reference the value of another field as the rightSide.

{
    // out's value should be greater than, or equal to, in's value
    "leftSide": {
        "select": "out/value"
    },
    "op": "gte",
    "rightSide": {
        "select": "in/value"
    },
    "type": "LIMECRAFT_RULE"
}

This rule is supported on numeric (* ish *) field types:

  • INTEGER

  • LONG

  • DOUBLE

  • DATE

  • FRAME

lte

This rule ensures that the leftSide field has a value less than, or equal to the value referenced by the rightSide.

See also gte rule which works similar.

lt

This rule ensures that the leftSide field has a value less than the value referenced by the rightSide.

See also lte and gte rules which works similar.

gt

This rule ensures that the leftSide field has a value greater than the value referenced by the rightSide.

See also gte rule which works similar.

eq

This rule ensures that the leftSide field has a value equal to the value referenced by the rightSide.

See also gte rule which works similar.

arrayContains

This rule ensures that the leftSide field has a value which entirely contains the value referenced by the rightSide.

The field value has to be an array. The other field’s value can be an array (of which all the elements have to be contained by our field) or a simple value (which has to be contained by our field value).

stringContains

This rule ensures that the leftSide field has a String value which entirely contains the value referenced by the rightSide. Both have to be string values.

evaluateClientSide

The evaluateClientSide of the rule determines what triggers evaluating the rule.

evaluateClientSide Description

PreSave

The rule is supposed to not be evaluated "live" when the user is changing things, but only when a submit button on the form is pressed.

Blur

The rule is supposed to be evaluated at every "blur" (loosing focus) of a field. This is usually preferred over Runtime, as the latter can easily reduce the user experience and even make it impossible to enter certain values.

The rule will also run at PreSave phase.

handle

The handle property of a form field (or user input field fieldConfig) can be set to a unique value (within the form). The validation rules can reference this field using the handle by appending it with a colon in the select.

{
    "leftSide": {
        "select": "myHandle:/value"
    }
}

Using the form field name only works when the other field is at the same level. With handle you can reference fields which are further away in the tree of fields (e.g. a part of another COMPOUND field).

Automatically changing values

When possible, the form will try to adhere to the rules automatically, by changing the value of a field.

When a rule is defined, only the field referenced in leftField will be modified automatically. This is usually done when the field referenced in leftField or rightField looses focus ("on blur").

The following op values support automatically changing the value: eq, gt, gte, lt, lte.