Freedom UI page customization basics

Guide
PDF
Beginner

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: Freedom UI 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.

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
See also
Overview of Freedom UI Designer and its elements
Client module
Freedom UI page
Set up the app UI
Client schema
Manage the system setting values on a page
Medium

Example. Display the following on the record page of the Requests custom section:

  • User’s city.
  • The number of the last created record in the Requests section, increased by 1. Increase the number when creating a new request or copying an existing one.

Use the values ​​of custom system settings.

1. Set up page UI 

  1. Create a custom Requests app based on the Records & business processes template. To do this, follow the procedure in the user documentation: Create a custom app.

  2. Add a system setting that stores the request number.

    1. Click Run app on the Requests app page.
    2. Click to open the System Designer. Click System settings in the System setup block.
    3. Click Add setting on the section toolbar.

    4. Fill out the system setting properties:

      • Set Name to "Request number."
      • Set Code to "UsrRequestLastNumber."
      • Select "Integer" in the Type property.
      • Set Default value to "0."

  3. Add a system setting that stores the city name.

    1. Click Add setting on the section toolbar.

    2. Fill out the system setting properties:

      • Set Name to "City."
      • Set Code to "UsrDefaultCity."
      • Select "Lookup" in the Type property.
      • Select "City" in the Lookup property.
      • Select "New York" in the Default value property.

  4. Go to the Requests app page and open the Requests form page page in the workspace.

    The Requests form page page includes the Name field by default.

  5. Add a request number label.

    1. Add a Label component to the Freedom UI Designer’s workspace.

    2. Click the button on the Freedom UI Designer’s action panel and fill out the title’s properties in the setup area:

      • Set Text to "Request number."
      • Select "Caption" in the Style property.
      • Select the grey color in the Text color property.

  6. Add the following labels the same way:

    • The value of the system setting that stores the request number.
    • Cities.
    • The value of the city system setting.

    View the label properties to add in the table below.

    Label property values
    Element
    Property
    Property value
    A label that contains the value of the system setting that stores the request number.
    Text
    "Request number (value)"
    Style
    Select "Body text"
    City label
    Text
    "City"
    Style
    Select "Caption"
    Text color
    Select the grey color
    A label that contains the value of the city system setting.
    Text
    "City (value)"
    Style
    Select "Body text"
  7. Click the button on the Freedom UI Designer’s action bar. The source code of the Freedom UI page opens after you save the page settings.

2. Manage system setting values 

Configure the business logic in the Client Module Designer. In this example, configure how to manage system settings values.

  1. Enable the sdk.SysSettingsService system setting service. To do this, add the @creatio-devkit/common dependency to the AMD module.

    AMD module dependencies
    /* AMD module declaration. */
define("UsrAppRequests_FormPage", /**SCHEMA_DEPS*/["@creatio-devkit/common"] /**SCHEMA_DEPS*/, function/**SCHEMA_ARGS*/(sdk)/**SCHEMA_ARGS*/ {
    return {
        ...
    };
});

  2. Add the following attributes to the viewModelConfig schema section:

    • UsrDefaultCity. Stores data about the value of the UsrDefaultCity system setting.
    • UsrRequestLastNumber. Stores data about the value of the UsrRequestLastNumber system setting.
    viewModelConfig schema section
    viewModelConfig: /**SCHEMA_VIEW_MODEL_CONFIG*/{
    "attributes": {
        ...,
        /* The attribute that stores the value of the UsrDefaultCity system setting. */
        "UsrDefaultCity": {},
        /* The attribute that stores the value of the UsrRequestLastNumber system setting. */
        "UsrRequestLastNumber": {}
    }
}/**SCHEMA_VIEW_MODEL_CONFIG*/,

  3. Change the following property values in the viewConfigDiff schema section:

    • caption property for the RequestNumberValue element. Bind the property to the value of the $UsrRequestLastNumber attribute. The caption property is responsible for the text that the element contains.
    • caption property for the CityValue element. Bind the property to the value of the $UsrDefaultCity attribute.
    viewConfigDiff schema section
    viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    ...,
    {
        "operation": "insert",
        "name": "RequestNumberValue",
        "values": {
            ...,
            /* The property responsible for the text that the element contains. Bound to the UsrRequestLastNumber attribute. */
            "caption": "$UsrRequestLastNumber",
            ...
        },
        ...
    },
    ...,
    {
        "operation": "insert",
        "name": "CityValue",
        "values": {
            ...,
            /* The property responsible for the text that the element contains. Bound to the UsrDefaultCity attribute. */
            "caption": "$UsrDefaultCity",
            ...
        },
        ...
    }
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

  4. Add a custom implementation of the system query handler to the handlers schema section. Execute the handler when the View model is initialized.

    1. Instantiate the system value service from @creatio-devkit/common.
    2. Retrieve the value of the UsrDefaultCity system setting and write it to the UsrDefaultCity attribute.
    3. Retrieve the page state.
    4. Retrieve the value of the UsrRequestLastNumber system setting.
    5. When creating a new record or copying an existing record, send a query to update the value of the UsrRequestLastNumber system setting (increase it by 1).
    6. Update the value of the UsrRequestLastNumber attribute.
    For Creatio version 8.0.6 and later
    For Creatio version 8.0-8.0.5
  5. Click Save on the Client Module Designer’s toolbar.

Outcome of the example 

To view the outcome of the example when creating a new request:

  1. Go to the Requests app page and click Run app.
  2. Click New on the Requests app toolbar.

As a result, the record page of the Requests custom section will display:

  • User’s city. The default value of the City (UsrDefaultCity code) system setting is used.
  • The number of the last created record in the Requests section, increased by 1. The value of the Request number (UsrRequestLastNumber code) system setting is used. It is increased by 1 when a new request is created.

To view the outcome of the example when copying an existing request:

  1. Add a Request’s name request first.
  2. Click → Copy in the Request’s name request’s row in the record list.

As a result, the page of the copied record of the Requests custom section will display:

  • User’s city. The default value of the City (UsrDefaultCity code) system setting is used.
  • The number of the last created record in the Requests section, increased by 1. The value of the Request number (UsrRequestLastNumber code) system setting is used. It is increased by 1 when an existing request is copied.
Resources
Package with example implementation
Change where the query handler is invoked on the page
Medium

Example. Display the number of the newest section record on the record page of the Requests custom section. Set the number to the custom system setting. Increment the number by 1 after saving the request page.

1. Set up page UI 

  1. Create a custom Requests app based on the Records & business processes template. To do this, follow the procedure in the user documentation: Create a custom app.

  2. Add a system setting that stores the request number.

    1. Click to open the System Designer. Click System settings in the System setup block.
    2. Click Add setting on the section toolbar.

    3. Fill out the system setting properties:

      • Set Name to "Request number."
      • Set Code to "UsrRequestLastNumber."
      • Select "Integer" in the Type property.
      • Set Default value to "1."

  3. Open the Requests form page page in the workspace of the Requests app page.

    The Requests form page page includes the Name field by default.

  4. Add a 2 columns component to the Freedom UI Designer workspace.

  5. Add a request number label.

    1. Add a component of the Label type to the first column of the 2 columns component of the Freedom UI Designer.

    2. Click the button on the Freedom UI Designer’s action panel and fill in the label’s properties in the setup area:

      • Set Title to "Create request."
      • Select "Caption" in the Style property.
      • Select the gray color in the Text color property.

  6. Add a title that contains the value of the system setting with the request number.

    1. Add a component of the Label type to the second column of the 2 columns component of the Freedom UI Designer.

    2. Click the button on the Freedom UI Designer’s action panel and fill in the title’s properties in the setup area:

      • Set Title to "Request number (value)."
      • Select "Body text" in the Style property.
  7. Click the button on the Freedom UI Designer’s action bar. The source code of the Freedom UI page opens after you save the page settings.

2. Change the origin of the query handler call 

Configure the business logic in the Client Module Designer. In this example, change the origin of the query handler call.

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

    AMD module dependencies
    /* AMD module declaration. */
define("UsrAppRequests_FormPage", /**SCHEMA_DEPS*/["@creatio-devkit/common"] /**SCHEMA_DEPS*/, function/**SCHEMA_ARGS*/(sdk)/**SCHEMA_ARGS*/ {
    return {
        ...
    };
});

  2. Add the UsrRequestLastNumber attribute to the viewModelConfig schema section. The attribute stores the value of the UsrRequestLastNumber system setting.

    viewModelConfig schema section
    viewModelConfig: /**SCHEMA_VIEW_MODEL_CONFIG*/{
    "attributes": {
        ...,
        /* The attribute that stores the value of the UsrRequestLastNumber system setting. */
        "UsrRequestLastNumber": {}
    }
}/**SCHEMA_VIEW_MODEL_CONFIG*/,

  3. Bind the caption property of the RequestNumberValue element to the $UsrRequestLastNumber model attribute in the viewConfigDiff schema section. The caption property is responsible for the text that the element contains.

    viewConfigDiff schema section
    viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    ...,
    {
        "operation": "insert",
        "name": "RequestNumberValue",
        "values": {
            ...,
            /* The property responsible for the text that the element contains. Bound to the UsrRequestLastNumber attribute. */
            "caption": "$UsrRequestLastNumber",
            ...
        },
        ...
    }
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

  4. Add a custom implementation of the crt.SaveRecordRequest system query handler to the handlers schema section. The handler is called by clicking the Save button on the request page toolbar.

    • Implement waiting for the execution of the next handler. In this example, it is the handler that saves the record.
    • Instantiate the system value service from @creatio-devkit/common after saving the record.
    • Get the value of the UsrRequestLastNumber system setting.
    • Send a query to update the value of the UsrRequestLastNumber system setting (increases it by 1).
    • Update the value of the UsrRequestLastNumber attribute.
    • Return the result of the saving.
    handlers schema section
    handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "crt.SaveRecordRequest",
        /* Implement the custom query handler. */
        handler: async (request, next) => {
            /* Wait for the next handler (in this case, the handler that saves the record) to execute. */
            const saveResult = await next.handle(request);
            /* Instantiate the system value service from @creatio-devkit/common after saving the record. */
            const sysSettingsService = new sdk.SysSettingsService();
            /* Retrieve the value of the UsrRequestLastNumber system setting. */
            const requestLastNumber = await sysSettingsService.getByCode('UsrRequestLastNumber');
            /* Send a query to update the value of the UsrRequestLastNumber system setting. */
            await sysSettingsService.update({
                code: 'UsrRequestLastNumber',
                /* The new value is larger than the previous one by 1. */
                value: ++requestLastNumber.value
            });
            /* Update the value of the UsrRequestLastNumber attribute. */
            request.$context.UsrRequestLastNumber = requestLastNumber.value;
            /* Return the result of the saving. */
            return saveResult;
        }
    }
] /**SCHEMA_HANDLERS*/,
    Complete source code of the page schema
  5. Click Save on the Client Module Designer’s toolbar.

Outcome of the example 

To view the outcome of the example:

  1. Go to the Requests app page and click Run app
  2. Click New on the Requests app toolbar.

As a result, when you click the Save button on the request page toolbar, Creatio will display the number of the last record created in the Requests section, increased by 1. The value is taken from the Request number (UsrRequestLastNumber code) system setting.

Resources
Package with example implementation