Version: 8.2

Customize fields (Freedom UI)

Level: beginner

Set up the field display condition

Detailed example: Set up the display condition of a page field.

To set up the field display condition:

Add a field to set the display condition if needed. Instructions: Fields and inputs (user documentation).

Add an attribute.

Go to the viewModelConfigDiff schema section → values configuration object.
Add an attribute that stores data.

View an example that adds the SomeAttribute attribute to the Freedom UI page schema below.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/[
    {
        "operation": "merge",
        "path": [
            "attributes"
        ],
        "values": {
            ...,
            /* An attribute that stores data. */
            "SomeAttribute": {}
        }
    },
    ...
]/**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/,

Bind an attribute to the field.
1. Go to the viewConfigDiff schema section → corresponding page element.
2. Bind the model attribute to the visible property. The value of this attribute controls whether the page displays or hides the field. Describe the business logic that changes the attribute value in the handlers schema section. The visible property is responsible for the visibility of the field.
View an example that binds the visible property to the $SomeAttribute attribute below.
viewConfigDiff schema section
```
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    ...,
    {
        ...,
        "values": {
            ...,
            /* The property that flags the field as visible. Bound to the "SomeAttribute" attribute. */
            "visible": "$SomeAttribute"
        },
        ...
    }
]/**SCHEMA_VIEW_CONFIG_DIFF*/,
```

Implement the base request handler.

Go to the handlers schema section.
Add a custom implementation of the crt.HandleViewModelAttributeChangeRequest base request handler.

Run the handler when the value of any attribute changes, including changes made after loading the attribute values from the data source. Depending on the attribute value (true or false), the handler executes different business logic.

View an example of a crt.HandleViewModelAttributeChangeRequest request handler, whose logic depends on the SomeAttribute attribute, below.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "crt.HandleViewModelAttributeChangeRequest",
        /* Custom implementation of a system request handler. */
        handler: async (request, next) => {
            /* Check the attribute value. */
            if (request.attributeName === 'SomeAttribute') {
                /* Implement the business logic. */
                ...,
                /* If the condition is met, set the "SomeAttribute" attribute to "true." */
                request.$context.SomeAttribute = someCondition;
            }
            /* Call the next handler if it exists and return its result. */
            return next?.handle(request);
        }
    }
]/**SCHEMA_HANDLERS*/,

Set up a condition that locks the field

Creatio lets you set up a condition that locks the field in the back-end. Instructions: Access management (user documentation).

Detailed example: Set up the condition that locks the field on a page.

To set up a condition that locks the field in the front-end:

Add a field to set the display condition if needed. Instructions: Fields and inputs (user documentation).
Add an attribute. Instructions: Set up the field display condition (step 2).
Bind an attribute to the label. Instructions: Set up the field display condition (similarly to step 3). Instead of the visible property, use the readonly property that locks the field from editing.
Implement the base request handler. Instructions: Set up the field display condition (step 3).

Set up a field population condition

Detailed example: Set up the condition that populates a page field.

To set up a field population condition:

Add a field to set the population condition if needed. Instructions: Fields and inputs (user documentation).
Implement the base request handler. Instructions: Set up the field display condition (step 3).

Set up a field requirement condition

Detailed example: Set up the requirement condition of a page field.

To set up the field requirement condition:

Add a field to set the requirement condition if needed. Instructions: Fields and inputs (user documentation).

Bind a validator to the attribute.

Go to the viewModelConfigDiff schema section → values configuration object → corresponding page element.
Bind the crt.Required type validator that checks the attribute value to the required property.

View an example that binds the crt.Required type validator to the SomeAttribute attribute below.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/[
    {
        ...,
        "values": {
            ...,
            "SomeAttribute": {
                ...,
                /* The property that contains the list of attribute validators. */
                "validators": {
                    /* Flag the field as required. */
                    "required": {
                        "type": "crt.Required"
                    }
                }
            },
            ...,
        }
    },
    ...,
]/**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/,

Implement the base request handler. Instructions: Set up the field display condition (step 3).

Implement field value validation

Detailed example: Implement the validation of a field value on a page.

Creatio applies validators to the attributes rather than visual elements, but validators can get the validity status data by using CrtControl. Learn more: validators schema section.

To implement field value validation:

Add a field whose value to validate if needed. Instructions: Fields and inputs (user documentation).

Implement a validator type.

Go to the validators schema section.
Implement a custom validator type. It must start with a vendor prefix. Format the validator type in PascalCase.

The validators schema section lets you implement:
- validator
- validator function (function (config))
- validator parameters ("params")
- whether the validator is asynchronous (async flag)

View an example that implements a custom usr.SomeValidator validator type below.

validators schema section
validators: /**SCHEMA_VALIDATORS*/{
    /* Implement a custom validator type. */
    "usr.SomeValidator": {
        /* Business logic of the validator. */
        "validator": function (config) {
            return function (control) {
                return control.value !== config.invalidName ? null: {
                    "usr.SomeValidator": { message: "Some message." }
                };
            };
        },
        /* Validator parameters. */
        "params": [
            {
                "name": "parameter1"
            },
            {
                "name": "message"
            }
        ],
        "async": false
    }
}/**SCHEMA_VALIDATORS*/

Bind a validator to the attribute. Creatio lets you bind the validator to a dedicated attribute or multiple attributes by setting different parameters for each of the attributes.

Go to the viewModelConfigDiff schema section → values configuration object → corresponding page element.
Bind the custom validator of the dedicated type.
Set the parameter1 property to the field value that triggers the custom validator.
Set the message property to the tooltip that Creatio displays when field contains the value specified in the parameter1 property. The priority of the message parameter of the attribute configuration object is higher than the priority of the corresponding validator parameter. I. e., for attributes that have a message parameter set, Creatio generates the error message from the parameter, not from the validator body.

View an example that binds the usr.SomeValidator validator to the SomeAttribute1 and SomeAttribute2 attributes below.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/[
    {
        "operation": "merge",
        "path": [
            "attributes"
        ],
        "values": {
            ...,
            "SomeField": {
                ...,
                /* The property that contains the list of attribute validators. */
                "validators": {
                    /* Bind a custom validator to an attribute. */
                    "SomeAttribute1": {
                        /* Validator type. */
                        "type": "usr.SomeValidator",
                        "params": {
                            /* The field value that triggers the custom validator. */
                            "parameter1": "Some parameter value 1",
                            /* The tooltip that Creatio displays when the field contains the value specified in the "parameter1" property. */
                            "message": "#ResourceString(SomeText)#"
                        }
                    },
                    /* Bind a custom validator to an attribute. */
                    "SomeAttribute2": {
                        "type": "usr.SomeValidator",
                        "params": {
                            "parameter1": "Some error message"
                        }
                    }
                }
            },
            ...,
        }
    },
    ...,
]/**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/,

If an error occurs, the SomeText localized string specified in the SomeAttribute1 attribute is displayed for the SomeAttribute1 attribute, and the Some error message value specified in the validator body is displayed for the SomeAttribute2 attribute.

To disable a validator, set the disabled property of the corresponding validator to true (disabled: true).

Implement field value conversion

Detailed example: Implement the conversion of a field value on a page.

Learn more: converters schema section.

Converters have the following special features:

applicable only in the RunTime mode
not applicable to constants
only work in one direction, cannot be used with CrtControl

To implement field value conversion:

Add a field whose value to convert if needed. Instructions: Fields and inputs (user documentation).
Implement a converter.
1. Go to the converters schema section.
2. Implement a custom converter. It must start with a vendor prefix. Format the converter type in PascalCase.
View an example that implements a custom usr.SomeConverter converter below.
converters schema section
```
converters: /**SCHEMA_CONVERTERS*/{
    /* Implement a custom converter. */
    "usr.SomeConverter": function(value) {
        ...;
    }
}/**SCHEMA_CONVERTERS*/,
```
Bind a converter to the attribute.
1. Go to the viewConfigDiff schema section → corresponding page element.
2. Bind the converter to the attribute. Use the pipe character to set the converter.
View an example that binds the usr.SomeConverter converter to the $SomeAttribute attribute below.
viewConfigDiff schema section
```
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    {
        "values": {
            /* Bind the "usr.SomeConverter" converter to the "$SomeAttribute" attribute. */
            "caption": "$SomeAttribute | usr.SomeConverter",
        }
    }
]/**SCHEMA_VIEW_CONFIG_DIFF*/,
```
Besides simple converters, Creatio provides chains of converters. A converter chain includes multiple converters that are applied to an attribute in a single property.

View an example that binds a chain of converters (crt.ToBoolean and crt.InvertBooleanValue) to the $SomeAttribute attribute below.
viewConfigDiff schema section
```
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    {
        /* Bind the "crt.ToBoolean" and "crt.InvertBooleanValue" converters to the "$SomeAttribute" attribute. */
        "visible": "$SomeAttribute | crt.ToBoolean | crt.InvertBooleanValue",
    },
]/**SCHEMA_VIEW_CONFIG_DIFF*/,
```
Creatio lets you set converter parameters. You can use the same converter multiple times by setting different parameter values. To set the converter parameters, specify the parameter value with the : prefix after the converter type. Place the colon character in front of each converter parameter value.

Available values of converter parameters:
- String. Enclose a string value in single quotes.
- Number.
- true or false.
- A binding to another attribute.
View an example that binds the exmpl.Concat converter that has a SomeParameter string parameter to the $SomeAttribute attribute below. Note that exmpl.Concat is an example converter and is not available for solving actual business problems.
viewConfigDiff schema section
```
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    {
        /* Bind the "exmpl.Concat" converter with the "SomeParameter" parameter to the "$SomeAttribute" attribute. */
        "visible": "$SomeAttribute | exmpl.Concat:' ':$SomeParameter",
    },
]/**SCHEMA_VIEW_CONFIG_DIFF*/,
```

Converters are not available for the following binding types:

binding to resource attribute
function binding
binding an event to a model method

Update form page fields automatically

Creatio updates fields on an open form page automatically without the need to refresh the page.

View the field types that support the functionality in the table below.

Field type	Setup instructions	Usage example
Fields of directly linked records	The functionality is enabled by default	You open the contact page that has the Account and No. of employees fields. If you fill out the Account field, Creatio populates the No. of employees field automatically.
Record fields	Update record fields automatically	You have Assign to me button on a request page. The button runs a business process that sets the current user as the request owner. If you click the Assign to me button, Creatio populates the Owner field on the page using your contact, and the result is visible immediately.

Set up the field display condition​

Set up a condition that locks the field​

Set up a field population condition​

Set up a field requirement condition​

Implement field value validation​

Implement field value conversion​

Update form page fields automatically​

See also​