Page customization

Beginner
PDF

Configure the business logic of Freedom UI pages in the validators, converters, and handlers sections of the client schemas. We recommend using no-code tools to set up business logic. Learn more in the user documentation: Freedom UI Designer. If no-code tools are not sufficient to implement your customization, we recommend setting up business logic in the source code of the Freedom UI page schema. Learn more about creating a Freedom UI page in a separate article: Client module.

For example, you can use a Freedom UI page to implement the following business logic:

  • element visibility
  • element locking
  • element requirement
  • element filtering
  • field population
  • Creatio data querying
  • HTTP request sending
  • page navigation

Learn more about pages in a separate article: Page.

Page customization procedure 

  1. Set up an app page.

    1. Create a custom app. To do this, follow the procedure in the user documentation: Create a custom app.
    2. Add one or more elements whose business logic to set up. To do this, follow the procedure in the user documentation: Set up the app UI.
  2. Set up the business logic of a page item.

    Configure the business logic in the client schema of the Freedom UI page. To open the client module schema, click the button on the action panel of the Freedom UI Designer on the corresponding page. The source code of the Freedom UI page opens after you save the page settings. Perform the setup in the corresponding client schema sections of the Freedom UI page Learn more in a separate article: Client schema.

Query handlers are the preferred way to customize the page. Query handlers are items of the HandlerChain mechanism that lets you describe business logic as an action request and chain of handlers. You can manage data sources using the handlers schema section. Query examples: page readiness, data load and save, business process launch.

Creatio 8 Atlas lets you organize query handlers in event chains. For example, trigger the base Creatio save handler first and execute the custom page logic later upon the page saver query.

To limit the scope of a query handler, fill out the scopes property of the client module with the names of the client schemas for which the handler must work.

View detailed examples of handler invocation in a separate block: Examples.

Customize page fields 

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 

  1. Add a page field to set the display condition at step 1 of the page customization procedure if needed.
  2. Set up the display condition of the field on the page at step 2 of the page customization procedure.

    1. Add an attribute that stores data to the viewModelConfig schema section.

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

      viewModelConfig schema section
    2. 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
    3. 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

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:

  1. Add a page field to set up a condition that locks it at step 1 of the page customization procedure if needed.
  2. Set up the condition that locks the field on the page at step 2 of the page customization procedure.

    1. Add an attribute that stores data to the viewModelConfig 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 

  1. Add a page field to configure the population condition at step 1 of the page customization procedure if needed.
  2. Set up the field population condition at step 2 of the 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 

  1. Add a page field to set the requirement condition at step 1 of the page customization procedure if needed.
  2. Set up the field requirement condition on the page at step 2 of the page customization procedure.

    1. Bind the crt.Required type validator to the model attribute in the viewModelConfig 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.

      viewModelConfig schema section
    2. 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

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:

  1. Add a page field whose value to validate at step 1 of the page customization procedure if needed.
  2. Implement field value validation on the page at step 2 of the page customization procedure.

    1. 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

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

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

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

      viewModelConfig schema section

      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:

  1. Add a page field whose value to convert at step 1 of the page customization procedure if needed.
  2. Implement field value conversion on the page at step 2 of the 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
    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

      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

      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

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.

Display the value of a system variable 

Creatio 8 Atlas uses the sdk.SysValuesService service to manage system variables.

In Creatio 8 Atlas, accessing system variables is different from the previous versions. In this version, write the system variable name in lowercase without _ delimiters and the CURRENT prefix (for example, maintainer, primaryLanguage, etc.).

To display the value of a system variable on a page:

  1. Add a page inscription to display the values ​​of system variables at step 1 of the page customization procedure if needed.
  2. Set up how to display the value of a system variable on the page at step 2 of the page customization procedure.

    1. Enable the sdk.SysValuesService system variable service. To do this, add the @creatio/sdk dependency to the AMD module.

      View an example that adds a dependency to the UsrAppClientSchemaName AMD module below.

      AMD module dependencies
    2. Add an attribute that stores data to the viewModelConfig schema section. Add the attribute similarly to the procedure for setting up the field display condition.
    3. Bind the caption property to the corresponding 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 caption property responsible for the text displayed in the element.
    4. Add a custom implementation of the crt.HandlerViewModelInitRequest system query handler to the handlers schema section. The handler is executed when the View model is initialized. Depending on the value of the attribute (true or false), the handler executes different business logic.

      1. Instantiate the system value service from @creatio/sdk.
      2. Load system values.
      3. Calculate the value and write the calculation result to the corresponding attribute if needed.

      View an example of a crt.HandlerViewModelInitRequest query handler with someVariable calculation result written in the SomeAttributeName attribute below.

      handlers schema section

View a detailed example that configures how to display the value of a system variable in a separate article: Display the values of system variables on a page.

Send a web service request and handle the response 

Creatio 8 Atlas uses the sdk.HttpClientService service to send web service requests.

To send a web service request and handle the response on the page:

  1. Add a page inscription to display the handled result of a web service request at step 1 of the page customization procedure if needed.
  2. Set up how to send a web service request and handle the response on the page at step 2 of the page customization procedure.

    1. Enable the sdk.HttpClientService service that sends HTTP requests. Enable the service similarly to the display procedure for the value of system variables.
    2. Add an attribute that stores data to the viewModelConfig schema section. Add the attribute similarly to the setup procedure for the field display condition.
    3. Bind the caption property to the corresponding 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 caption property responsible for the text displayed in the element.
    4. Add a custom implementation of the crt.HandlerViewModelInitRequest system query handler to the handlers schema section. The handler is executed when the View model is initialized.

      1. Instantiate the HTTP client from @creatio/sdk.
      2. Specify the URL to get the required information. If a web service request is sent using a non-absolute path (without https:// or http:// prefixes), this is a request to an internal Creatio web service. In that case, Creatio automatically adds the address of the current app to the link.
      3. Send a GET request.
      4. Retrieve the required values from the response and write them to the corresponding attributes.

      View an example of the crt.HandlerViewModelInitRequest request handler that sends a request to the https://SomeUrlValue web service, receives the someValue parameter from the response body, and writes the parameter to the SomeAttributeName attribute, below.

      handlers schema section

View a detailed example that sets up a web service request and handles the response in a separate article: Send a request to an external web service and handle its result on a page.

Hide functionality on a page 

Creatio 8 Atlas lets you execute the following actions that hide functionality on a page:

  • Hide functionality during development.
  • Hide functionality due to insufficient access permissions.

Hide functionality during development 

Creatio 8 Atlas uses the sdk.FeatureService service to check functionality status.

To hide functionality during development on a page :

  1. Add a page component that contains the functionality during development at step 1 of the page customization procedure if needed.
  2. Set up how to hide the functionality on the page at step 2 of the page customization procedure.

    1. Enable the sdk.FeatureService service that checks the functionality status. Enable the service similarly to the display procedure for the value of system variables.
    2. Add an attribute that stores data to the viewModelConfig schema section. Add the attribute similarly to the setup procedure for the field display condition.
    3. Bind the visible property to the corresponding model attribute in the viewConfigDiff schema section. Property binding is similar to that described in the setup procedure for the field display condition.
    4. Add a custom implementation of the crt.HandlerViewModelInitRequest system query handler to the handlers schema section. The handler is executed when the View model is initialized.

      1. Instantiate the service that checks the functionality status from @creatio/sdk.
      2. Get the status of the functionality by its code and write it to the corresponding attribute.

      View an example of a crt.HandlerViewModelInitRequest query handler that receives a feature status with the SomeFeatureCode code and writes it to the SomeAttributeName attribute below.

      handlers schema section

View a detailed example that hides functionality during development in a separate article: Hide a feature at the development stage on a page.

Hide functionality due to insufficient access permissions 

Creatio 8 Atlas uses the sdk.RightsService service to check access permissions.

To hide functionality due to insufficient access permissions:

  1. Add a page component with the functionality for which access permissions are configured at step 1 of the page customization procedure if needed.
  2. Set up how to hide functionality on the page due to insufficient access permissions at step 2 of the page customization procedure.

    1. Enable the sdk.RightsService service that checks access permissions. Enable the service similarly to the display procedure for the value of system variables.
    2. Add an attribute that stores data to the viewModelConfig schema section. Add the attribute similarly to the setup procedure for the field display condition.
    3. Bind the visible property to the corresponding model attribute in the viewConfigDiff schema section. Property binding is similar to that described in the setup procedure for the field display condition.
    4. Add a custom implementation of the crt.HandlerViewModelInitRequest system query handler to the handlers schema section. The handler is executed when the View model is initialized.

      1. Instantiate the service that checks access permissions from @creatio/sdk.
      2. Get information about the user’s permissions to perform the corresponding action.
      3. Write the result of the checkup to the corresponding attribute.

      View an example of the crt.HandlerViewModelInitRequest request handler that checks for permissions to perform a system operation with the SomeOperationCode code and writes the result to the SomeAttributeName attribute below.

      handlers schema section

View a detailed example that hides functionality due to insufficient access permissions in a separate article: Hide the feature on a page due to insufficient access permissions.

Open a page from a custom handler 

Creatio 8 Atlas uses the sdk.HandlerChainService service to open pages. Creatio 7.X and Creatio 8 Atlas use the same method to open record pages. You can pass the needed default column values when Creatio adds a record.

Creatio 8 Atlas provides the following actions to open pages from a custom handler:

  • Open a record page from a custom handler.
  • Open a Freedom UI page from a custom handler.

Open a record page from a custom handler 

  1. Add a page button that opens the record page on click at step 1 of the page customization procedure if needed.
  2. Set up how to open the record page from a custom handler at step 2 of the page customization procedure.

    1. Enable the sdk.HandlerChainService service that opens pages. Enable the service similarly to the display procedure for the value of system variables.
    2. Bind the clicked property to the corresponding query in the viewConfigDiff schema section. Describe the business logic that opens the page in the handlers schema section. The clicked property is responsible for the action performed on button click.

      View an example that binds the clicked property to the usr.SomeRequest custom query below.

      viewConfigDiff schema section
    3. Add the implementation of a custom query to the handlers schema section.

      To open a page:

      1. Get an instance of the sdk.HandlerChainService singleton service that opens pages.
      2. Send a crt.UpdateRecordRequest system query that opens the page by the specified ID.

      View an example of the usr.SomeRequest query handler that sends the crt.UpdateRecordRequest system query below. The crt.UpdateRecordRequest query opens the page of the SomeSchemaName record with the SomeRecordId ID.

      handlers schema section

      To open the page and populate the fields with the specified values:

      1. Get an instance of the sdk.HandlerChainService singleton service that opens pages.
      2. Send the crt.CreateRecordRequest system query that creates a page with fields populated with the specified values.

      View an example of the usr.SomeRequest query handler that sends the crt.CreateRecordRequest system query below. The crt.CreateRecordRequest query opens the SomeSchemaName record page and populates the SomeField field with the "SomeRecordId" value.

      handlers schema section

View a detailed example that opens a record page in a separate article: Open a record page from a custom handler.

Open a Freedom UI page from a custom handler 

  1. Take steps 1-2 from the procedure to open the record page from a custom handler.
  2. Set up how to open a Freedom UI page from a custom handler at step 2 of the procedure for opening the record page from a custom handler. To do this, add the implementation of a custom query to the handlers schema section.

    1. Get an instance of the sdk.HandlerChainService singleton service that opens pages.
    2. Send a crt.OpenPageRequest system query that opens the Freedom UI page with the specified name.

    View an example usr.SomeRequest query handler that sends the crt.OpenPageRequest system query below. The crt.OpenPageRequest query opens the SomePageName page.

    handlers schema section

View a detailed example that opens a Freedom UI page in a separate article: Open a Freedom UI page from a custom handler.

Close the WebSocket when destroying the View of the model 

To close the WebSocket when destroying the View of the model, add a custom implementation of the crt.HandleViewModelDestroyRequest system query handler to the handlers schema section. The handler is executed when the View of the model is destroyed (for example, when you open another page). Designed to destroy resources. We do not recommend writing asynchronous code in the handler (server calls, timeouts, etc.) except for reading the value of attributes.

View an example of the crt.HandleViewModelDestroyRequest query handler that closes the custom SomeWebSocket WebSocket below.

handlers schema section