Version: 8.1

Customize fields (Freedom UI)

Level: beginner

Creatio 8 Atlas provides the following page customization actions:

Set up a 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.

Customize the field display condition

Add a page field to set the display condition at step 1 of the Freedom UI page customization procedure if needed.

Set up the display condition of the field on the page at step 2 of the Freedom UI page customization procedure.

Add an attribute that stores data to the viewModelConfigDiff schema section.

Example that adds the SomeAttributeName attribute to the client module schema of the Freedom UI page.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG*/{
    "attributes": {
        /* An attribute that stores data. */
        "SomeAttributeName": {}
    }
}/**SCHEMA_VIEW_MODEL_CONFIG*/,

Bind the visible property to the corresponding model attribute in the viewConfigDiff schema section. The value of this attribute controls whether the page displays or hides the field. Describe the business logic that changes an 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 $SomeAttributeName attribute below.
viewConfigDiff schema section
```
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    {
        "values": {
            /* Property that controls the visibility of the field. Bound to the SomeAttributeName attribute. */
            "visible": "$SomeAttributeName"
        },
    }
]/**SCHEMA_VIEW_CONFIG_DIFF*/,
```

Add a custom implementation of the crt.HandleViewModelAttributeChangeRequest system query handler to the handlers schema section. The handler runs when the value of any attribute changes, including when loading attribute values from a data source. Depending on the attribute value (true or false), the handler executes different business logic.

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

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

View a detailed example that sets up the field display condition in a separate article: Set up the display condition of a field on a page.

Set up a condition that locks the field

This section covers the procedure for setting up a condition that locks the page field in the app’s front-end. To set up a condition that locks the field in the back-end, follow the procedure in the user documentation: Access management.

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

Add a page field to set up a condition that locks it at step 1 of the Freedom UI page customization procedure if needed.
Set up the condition that locks the field on the page at step 2 of the Freedom UI page customization procedure.
1. Add an attribute that stores data to the viewModelConfigDiff schema section. Add the attribute the same way as in the setup procedure for the field display condition.
2. Bind the readonly property to the appropriate model attribute in the viewConfigDiff schema section. Property binding is similar to that described in the setup procedure for the field display condition. Instead of the visible property, use the readonly property that locks the field from editing.
3. Add a custom implementation of the crt.HandleViewModelAttributeChangeRequest system query handler to the handlers schema section. The implementation of the handler is similar to that described in the setup procedure for the field display condition.

View a detailed example that sets up a condition that locks the field in a separate article: Set up the condition that locks the field on a page.

Set up a field population condition

Add a page field to configure the population condition at step 1 of the Freedom UI page customization procedure if needed.
Set up the field population condition at step 2 of the Freedom UI page customization procedure. To do this, add a custom implementation of the crt.HandleViewModelAttributeChangeRequest system query handler to the handlers schema section. The implementation of the handler is similar to that described in the setup procedure for the field display condition.

View a detailed example that sets up a field population condition in a separate article: Set up the condition that populates a field on a page.

Set up a field requirement condition

Add a page field to set the requirement condition at step 1 of the Freedom UI page customization procedure if needed.

Set up the field requirement condition on the page at step 2 of the Freedom UI page customization procedure.

Bind the crt.Required type validator to the model attribute in the viewModelConfigDiff schema section. The validator checks that the attribute value is populated.

View an example that binds a crt.Required type validator to a model attribute below.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG*/{
    "attributes": {
        /* UI element attribute. */
        "SomeAttributeOfElement": {
            /* Property that enables validators in the attribute. */
            "validators": {
                /* Flag the field as required. */
                "required": {
                    "type": "crt.Required"
                }
            }
        }
    }
}/**SCHEMA_VIEW_MODEL_CONFIG*/,

Add a custom implementation of the crt.HandleViewModelAttributeChangeRequest system query handler to the handlers schema section. The handler runs when the value of any attribute changes, including when loading attribute values from a data source. Depending on the value of the attribute (true or false), the handler executes different business logic.

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

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "crt.HandleViewModelAttributeChangeRequest",
        /* Custom implementation of a system query handler. */
        handler: async (request, next) => {
            if (request.someAttributeName === 'SomeAttributeValue') {
                /* Check the attribute value. */
                if (SomeAttributeValue1) {
                    /* If the attribute value is equal to the value of SomeAttributeValue1, apply the required validator to the SomeAttributeName attribute. */
                    request.$context.enableAttributeValidator('SomeAttributeName', 'required');
                } else {
                    /* Otherwise, do not apply the required validator to the SomeAttributeName attribute. */
                    request.$context.disableAttributeValidator('SomeAttributeName', 'required');
                }
                /* Call the next handler if it exists and return its result. */
                return next?.handle(request);
            }
        }
    }
]/**SCHEMA_HANDLERS*/,

View a detailed example that sets up a field requirement condition on a page in a separate article: Set up a field requirement condition on a page.

Implement field value validation

Validators are functions that check whether the value of the ViewModel attribute is correct. For example, they can check the value of a record field for compliance with specified conditions. To implement a validator, use the validators section of the Freedom UI page schema. Learn more about creating a Freedom UI page in a separate article: Client module.

Creatio applies validators to the ViewModel attributes rather than visual elements, but validators can get the validity status data by using CrtControl. Validator examples: MaxLengthValidator, MinLengthValidator, RequiredValidator.

To implement field value validation on the page:

Add a page field whose value to validate at step 1 of the Freedom UI page customization procedure if needed.

Implement field value validation on the page at step 2 of the Freedom UI page customization procedure.

Implement a custom validator in the validators schema section.

The validators schema section lets you declare:

validator
validator function (function (config))
validator parameters ("params")
whether the validator is asynchronous (async flag)

View an example that declares a custom usr.SomeValidatorName validator below.

validators schema section
validators: /**SCHEMA_VALIDATORS*/{
    /* The validator type must have a vendor prefix.
    Specify the validator type in PascalCase. */
    "usr.SomeValidatorName": {
        "validator": function (config) {
            return function (control) {
                return control.value !== config.invalidName ? null: {
                    "usr.SomeValidatorName": { message: "Some message." }
                };
            };
        },
        "params": [
            {
                "name": "parameterName"
            },
            {
                "name": "message"
            }
        ],
        "async": false
    }
}/**SCHEMA_VALIDATORS*/

message is a property that lets you set a custom error message.

Bind the validator to an attribute or multiple model attributes by setting different parameters for each of the attributes in the viewModelConfigDiff schema section. To do this, specify the validators key with the validator’s name and its parameters in the corresponding attribute of the viewModelConfigDiff schema section.

View an example that binds the usr.SomeValidatorName validator to the SomeAttributeName1 and SomeAttributeName2 attributes of the model below.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG*/{
    "attributes": {
        "SomeField": {
            "validators": {
                /* Bind a custom validator to an attribute. */
                "SomeAttributeName1": {
                    "type": "usr.SomeValidatorName",
                    "params": {
                        "parameterName": "someParameterNameValue1",
                        "message": "#ResourceString(SomeAttributeName1String)#"
                    }
                },
                "SomeAttributeName2": {
                    "type": "usr.SomeValidatorName",
                    "params": {
                        "parameterName": "someParameterNameValue2",
                    }
                },
            }
        },
    }
}/**SCHEMA_VIEW_MODEL_CONFIG*/,

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 with a message parameter set, Creatio generates the error message from the parameter, not from the validator body.

If an error is caught, the value of the SomeAttributeName1String localized string specified in the SomeAttributeName1 attribute is displayed for the attribute, and the Some message. value specified in the validator body is displayed for the SomeAttributeName2 attribute.

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

View a detailed example that uses a validator in a separate article: Implement the field value validation on a page.

Implement field value conversion

A converter is a function that converts the value of the ViewModel attribute bound to the property of the visual component to another value. Converters provided by Creatio 8 Atlas work similarly to Angular filters. Read more in the official Angular documentation. To implement converters, use the converters section of the Freedom UI page schema. Learn more about creating a Freedom UI page in a separate article: Client module. Converter examples: crt.invertBooleanValue, crt.toBoolean.

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 on the page:

Add a page field whose value to convert at step 1 of the Freedom UI page customization procedure if needed.
Implement field value conversion on the page at step 2 of the Freedom UI page customization procedure.
1. Implement a custom converter in the converters schema section.
  
  View an example that declares the usr.SomeConverterName converter below.
  converters schema section
```
converters: /**SCHEMA_CONVERTERS*/{
    /* Custom converter. */
    "usr.SomeConverterName": function(value) {
        ...;
    }
}/**SCHEMA_CONVERTERS*/,
```
2. Append the pipe character and the converter type to the name of the attribute to apply the converter in the viewConfigDiff schema section.
  
  View an example that applies the usr.SomeConverterName converter to the $SomeAttributeName attribute below.
  viewConfigDiff schema section
```
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    {
        "values": {
            /* Bind the usr.SomeConverterName converter to the $SomeAttributeName attribute. */
            "caption": "$SomeAttributeName | usr.SomeConverterName",
        }
    }
]/**SCHEMA_VIEW_CONFIG_DIFF*/,
```
  Besides simple converters, Creatio 8 Atlas provides chains of converters. A converter chain comprises multiple converters that are applied to an attribute in a single property.
  
  View an example that applies a chain of converters (crt.ToBoolean and crt.InvertBooleanValue) to the $SomeAttributeName attribute below.
  viewConfigDiff schema section
```
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    {
        /* Bind the crt.ToBoolean and crt.InvertBooleanValue converters to the $SomeAttributeName attribute. */
        "visible": "$SomeAttributeName | crt.ToBoolean | crt.InvertBooleanValue",
    },
]/**SCHEMA_VIEW_CONFIG_DIFF*/,
```
  Creatio lets you set converter parameters. You can use the same converter several 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 applies the exmpl.Concat converter with a SomeParameter string parameter to the SomeAttributeName 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 $SomeAttributeName attribute. */
        "visible": "$SomeAttributeName | 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

View a detailed example that uses a converter in a separate article: Implement field value conversion on a page.

Update form page fields automatically

Creatio updates fields on an open form page automatically without the need to refresh the page. This functionality is available for the following field types:

Fields of directly linked records. The functionality is enabled by default.

For example, 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. To enable the functionality, follow the instructions in a separate article: Update record fields automatically.

For example, 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 with your contact, and the result is visible immediately.

Resources

Access management Creatio documentation

Official Angular documentation (pipe concept)

Customize 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​

Resources​