Skip to main content
Version: 8.0

Manage the system setting values on a page

Level: intermediate

To implement the example:

  1. Set up the page UI. Read more >>>
  2. Set up how to manage the system setting values. Read more >>>
Example

Display the following system setting values on the custom request page:

  • The number of the last created request increased by 1. Increase the number when creating a new request or copying an existing request.
  • The city of the current user.
Increasing the number when creating a new request
Increasing the number when creating a new request
Increasing the number when copying an existing request
Increasing the number when copying an existing request

1. Set up page UI​

  1. Create an app based on the Records & business processes template. Instructions: Create an app manually (user documentation).

    For this example, create a Requests app.

  2. Add system settings.

    For this example, add the following system settings:

    • system setting that stores the request number
    • system setting that stores the city name

    To do this:

    1. Open the System settings section. To do this, click in the top right → System setup → System settings.

    2. Click Add setting and fill out the system setting properties.

      Element

      Property

      Property value

      System setting that stores the request number

      Name

      Request number

      Code

      UsrLastRequestNumber

      Type

      Integer

      Default value

      0

      System setting that stores the city name

      Name

      City

      Code

      UsrDefaultCity

      Type

      Lookup

      Lookup

      City

      Default value

      New York

  3. Open the form page in the Freedom UI Designer.

    For this example, open the Requests form page.

  4. Add labels.

    For this example, add the following labels:

    • label of the request number
    • label that contains the value of the request number from the system setting
    • label of the current user city
    • label that contains the value of the current user city from the system setting

    To do this:

    1. Add a label to the working area of the Freedom UI Designer.

    2. Click and fill out the label properties.

      Element

      Property

      Property value

      Label of the request number

      Text

      Request number

      Style

      Caption

      Text color

      #757575

      Label that contains the value of the request number from the system setting

      Text

      Request number (value)

      Style

      Body

      Label of the current user city

      Text

      City

      Style

      Caption

      Text color

      #757575

      Label that contains the value of the current user city from the system setting

      Text

      City (value)

      Style

      Body

  5. Save the changes.

2. Set up how to manage the system setting values​

Configure the business logic in the Client Module Designer. For this example, set up how to manage the system setting values.

  1. Open the source code of the Freedom UI page. To do this, click .

  2. Add the dependencies. To do this, add @creatio-devkit/common library as a dependency. The library includes the sdk.SysSettingsService service to manage system settings.

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

  3. Add an attribute.

    1. Go to the viewModelConfig schema section → attributes configuration object.
    2. Add a LastRequestNumber attribute that stores data of the "Request number" ("UsrLastRequestNumber" code) system setting.
    3. Add a DefaultCity attribute that stores data of the "City" ("UsrDefaultCity" code) system setting.
    viewModelConfig schema section
    viewModelConfig: /**SCHEMA_VIEW_MODEL_CONFIG*/{
        "attributes": {
            ...,
            /* The attribute that stores data of the "Request number" ("UsrLastRequestNumber" code) system setting. */
            "LastRequestNumber": {},
            /* The attribute that stores data of the "City" ("UsrDefaultCity" code) system setting. */
            "DefaultCity": {},
        },
        ...
    }/**SCHEMA_VIEW_MODEL_CONFIG*/,

  4. Bind an attribute to the label.

    1. Go to the viewConfigDiff schema section → UsrRequestNumberValue element.
    2. Bind the $LastRequestNumber attribute to the caption property.
    3. Go to the UsrCityValue element.
    4. Bind the $DefaultCity attribute to the caption property.
    viewConfigDiff schema section
    viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
        ...,
        /* Label that contains the value of the request number from the system setting. */
        {
            "operation": "insert",
            "name": "UsrRequestNumberValue",
            "values": {
                ...,
                /* The property that handles the text contained in the element. Bound to the "LastRequestNumber" attribute. */
                "caption": "$LastRequestNumber",
            },
            ...
        },
        ...,
        /* Label that contains the value of the current user city from the system setting. */
        {
            "operation": "insert",
            "name": "UsrCityValue",
            "values": {
                ...,
                /* The property that handles the text contained in the element. Bound to the "DefaultCity" attribute. */
                "caption": "$DefaultCity",
            },
            ...
        },
        ...,
    ]/**SCHEMA_VIEW_CONFIG_DIFF*/,

  5. Implement the base request handler.

    For Creatio versions 8.0.6-8.0.10

    1. Go to the handlers schema section.

    2. Add a custom implementation of the crt.HandleViewModelResumeRequest base request handler.

      1. Create an instance of the system setting service from @creatio-devkit/common.
      2. Retrieve the value of the "City" ("UsrDefaultCity" code) system setting and specify the value in the DefaultCity attribute.
      3. Retrieve the page state.
      4. Check the page state. If the page is new or copies an existing page, retrieve the value of the "Request number" ("UsrLastRequestNumber" code) system setting, increase the value of the system setting, specify the new value in the LastRequestNumber attribute.
    handlers schema section
    handlers: /**SCHEMA_HANDLERS*/[
        {
            request: "crt.HandleViewModelResumeRequest",
            /* The custom implementation of the system request handler. */
            handler: async (request, next) => {
                /* Wait for the rest of the initialization handlers to finish. */
                await next?.handle(request);
                /* Create an instance of the system setting service from "@creatio-devkit/common." */
                const sysSettingsService = new sdk.SysSettingsService();
                /* Retrieve the value of the "City" ("UsrDefaultCity" code) system setting. */
                const defaultCity = await sysSettingsService.getByCode('UsrDefaultCity');
                /* Specify the value of the "City" ("UsrDefaultCity" code) system setting in the "DefaultCity" attribute. */
                request.$context.DefaultCity = defaultCity.displayValue;
                /* Retrieve the page state. */
                const cardState = await request.$context.CardState;
                /* Check the page state. If the page is new or copies an existing page, increase the value of the "Request number" ("UsrLastRequestNumber" code) system setting. */
                if (cardState === 'add' || cardState === 'copy') {
                    /* Retrieve the value of the "Request number" ("UsrLastRequestNumber" code) system setting. */
                    const lastNumber = await sysSettingsService.getByCode('UsrLastRequestNumber');
                    /* Send a request to update the value of the "Request number" ("UsrLastRequestNumber" code) system setting. */
                    await sysSettingsService.update({
                        code: 'UsrLastRequestNumber',
                            /* The new value is higher than the previous one by 1. */
                            value: ++lastNumber.value
                    });
                    /* Specify the new value of the "Request number" ("UsrLastRequestNumber" code) system setting in the "LastRequestNumber" attribute. */
                    request.$context.LastRequestNumber = lastNumber.value;
                    /* Call the next handler if it exists and return its result. */
                    return next?.handle(request);
                }
            },
        },
    ] /**SCHEMA_HANDLERS*/,
    For Creatio versions 8.0-8.0.5

    1. Go to the handlers schema section.

    2. Add a custom implementation of the crt.HandlerViewModelInitRequest base request handler.

      1. Create an instance of the system setting service from @creatio-devkit/common.
      2. Retrieve the value of the "City" ("UsrDefaultCity" code) system setting and specify the value in the DefaultCity attribute.
      3. Retrieve the page state.
      4. Check the page state. If the page is new or copies an existing page, retrieve the value of the "Request number" ("UsrLastRequestNumber" code) system setting, increase the value of the system setting, specify the new value in the LastRequestNumber attribute.
    handlers schema section
    handlers: /**SCHEMA_HANDLERS*/[
        {
            request: "crt.HandlerViewModelInitRequest",
            /* The custom implementation of the system request handler. */
            handler: async (request, next) => {
                /* Wait for the rest of the initialization handlers to finish. */
                await next?.handle(request);
                /* Create an instance of the system setting service from "@creatio-devkit/common." */
                const sysSettingsService = new sdk.SysSettingsService();
                /* Retrieve the value of the "City" ("UsrDefaultCity" code) system setting. */
                const defaultCity = await sysSettingsService.getByCode('UsrDefaultCity');
                /* Specify the value of the "City" ("UsrDefaultCity" code) system setting in the "DefaultCity" attribute. */
                request.$context.DefaultCity = defaultCity.displayValue;
                /* Retrieve the page state. */
                const cardState = await request.$context.CardState;
                /* Check the page state. If the page is new or copies an existing page, increase the value of the "Request number" ("UsrLastRequestNumber" code) system setting. */
                if (cardState === 'add' || cardState === 'copy') {
                    /* Retrieve the value of the "Request number" ("UsrLastRequestNumber" code) system setting. */
                    const lastNumber = await sysSettingsService.getByCode('UsrLastRequestNumber');
                    /* Send a request to update the value of the "Request number" ("UsrLastRequestNumber" code) system setting. */
                    await sysSettingsService.update({
                        code: 'UsrLastRequestNumber',
                            /* The new value is higher than the previous one by 1. */
                            value: ++lastNumber.value
                    });
                    /* Specify the new value of the "Request number" ("UsrLastRequestNumber" code) system setting in the "LastRequestNumber" attribute. */
                    request.$context.LastRequestNumber = lastNumber.value;
                    /* Call the next handler if it exists and return its result. */
                    return next?.handle(request);
                }
            },
        },
    ] /**SCHEMA_HANDLERS*/,

  6. Save the changes.

View the result​

To view the result when creating a new request:

  1. Open the Requests section.
  2. Create a request.

As a result, Creatio will display the number of the last created request, increased by 1, and the city of the current user on the page of a new request. The values will be retrieved from the corresponding system settings. View the result >>>

To view the result when copying an existing request:

  1. Create a request that has an arbitrary name. For example, "Request’s name."
  2. Copy an existing request. For example, "Request’s name." To do this, click → Copy.
  3. Set an arbitrary request name. For example, "Sick leave."

As a result, Creatio will display the number of the last created request, increased by 1, and the city of the current user on the page of a copied request. The values will be retrieved from the corresponding system settings. View the result >>>

Source code​

/* Declare the AMD module. */
define("UsrAppRequests_FormPage", /**SCHEMA_DEPS*/["@creatio/sdk" ]/**SCHEMA_DEPS*/, function/**SCHEMA_ARGS*/(sdk)/**SCHEMA_ARGS*/ {
    return {
        viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
            /* Label of the request number. */
            {
                "operation": "insert",
                "name": "UsrRequestNumber",
                "values": {
                    "layoutConfig": {
                        "column": 1,
                        "row": 2,
                        "colSpan": 1,
                        "rowSpan": 1
                    },
                    "type": "crt.Label",
                    "caption": "#ResourceString(UsrRequestNumber_caption)#",
                    "labelType": "caption",
                    "labelThickness": "normal",
                    "labelEllipsis": false,
                    "labelColor": "#757575",
                    "labelBackgroundColor": "transparent",
                    "labelTextAlign": "start"
                },
                "parentName": "LeftAreaProfileContainer",
                "propertyName": "items",
                "index": 0
            },
            /* Label that contains the value of the request number from the system setting. */
            {
                "operation": "insert",
                "name": "UsrRequestNumberValue",
                "values": {
                    "layoutConfig": {
                        "column": 1,
                        "row": 3,
                        "colSpan": 1,
                        "rowSpan": 1
                    },
                    "type": "crt.Label",
                    /* The property that handles the text contained in the element. Bound to the "LastRequestNumber" attribute. */
                    "caption": "$LastRequestNumber",
                    "labelType": "body",
                    "labelThickness": "normal",
                    "labelEllipsis": false,
                    "labelColor": "#181818",
                    "labelBackgroundColor": "transparent",
                    "labelTextAlign": "start"
                },
                "parentName": "LeftAreaProfileContainer",
                "propertyName": "items",
                "index": 1
            },
            /* Label of the current user city. */
            {
                "operation": "insert",
                "name": "UsrCity",
                "values": {
                    "layoutConfig": {
                        "column": 1,
                        "row": 4,
                        "colSpan": 1,
                        "rowSpan": 1
                    },
                    "type": "crt.Label",
                    "caption": "#ResourceString(UsrCity_caption)#",
                    "labelType": "caption",
                    "labelThickness": "normal",
                    "labelEllipsis": false,
                    "labelColor": "#757575",
                    "labelBackgroundColor": "transparent",
                    "labelTextAlign": "start"
                },
                "parentName": "LeftAreaProfileContainer",
                "propertyName": "items",
                "index": 2
            },
            /* Label that contains the value of the current user city from the system setting. */
            {
                "operation": "insert",
                "name": "UsrCityValue",
                "values": {
                    "layoutConfig": {
                        "column": 1,
                        "row": 5,
                        "colSpan": 1,
                        "rowSpan": 1
                    },
                    "type": "crt.Label",
                    /* The property that handles the text contained in the element. Bound to the "DefaultCity" attribute. */
                    "caption": "$DefaultCity",
                    "labelType": "body",
                    "labelThickness": "normal",
                    "labelEllipsis": false,
                    "labelColor": "#181818",
                    "labelBackgroundColor": "transparent",
                    "labelTextAlign": "start"
                },
                "parentName": "LeftAreaProfileContainer",
                "propertyName": "items",
                "index": 3
            },
            {
                "operation": "insert",
                "name": "UsrName",
                "values": {
                    "layoutConfig": {
                        "column": 1,
                        "row": 1,
                        "colSpan": 1,
                        "rowSpan": 1
                    },
                    "type": "crt.Input",
                    "multiline": false,
                    "control": "$UsrName",
                    "label": "$Resources.Strings.UsrName",
                    "labelPosition": "auto"
                },
                "parentName": "LeftAreaProfileContainer",
                "propertyName": "items",
                "index": 4
            }
        ]/**SCHEMA_VIEW_CONFIG_DIFF*/,
        viewModelConfig: /**SCHEMA_VIEW_MODEL_CONFIG*/{
            "attributes": {
                "UsrName": {
                    "modelConfig": {
                        "path": "PDS.UsrName"
                    }
                },
                "Id": {
                    "modelConfig": {
                        "path": "PDS.Id"
                    }
                },
                /* The attribute that stores data of the "Request number" ("UsrLastRequestNumber" code) system setting. */
                "LastRequestNumber": {},
                /* The attribute that stores data of the "City" ("UsrDefaultCity" code) system setting. */
                "DefaultCity": {},
            }
        }/**SCHEMA_VIEW_MODEL_CONFIG*/,
        modelConfig: /**SCHEMA_MODEL_CONFIG*/{
            "dataSources": {
                "PDS": {
                    "type": "crt.EntityDataSource",
                    "config": {
                        "entitySchemaName": "UsrAppRequests"
                    },
                    "scope": "page"
                }
            },
            "primaryDataSourceName": "PDS"
        }/**SCHEMA_MODEL_CONFIG*/,
        handlers: /**SCHEMA_HANDLERS*/[
            {
                request: "crt.HandleViewModelResumeRequest",
                /* The custom implementation of the system request handler. */
                handler: async (request, next) => {
                    /* Wait for the rest of the initialization handlers to finish. */
                    await next?.handle(request);
                    /* Create an instance of the system setting service from "@creatio-devkit/common." */
                    const sysSettingsService = new sdk.SysSettingsService();
                    /* Retrieve the value of the "City" ("UsrDefaultCity" code) system setting. */
                    const defaultCity = await sysSettingsService.getByCode('UsrDefaultCity');
                    /* Specify the value of the "City" ("UsrDefaultCity" code) system setting in the "DefaultCity" attribute. */
                    request.$context.DefaultCity = defaultCity.displayValue;
                    /* Retrieve the page state. */
                    const cardState = await request.$context.CardState;
                    /* Check the page state. If the page is new or copies an existing page, increase the value of the "Request number" ("UsrLastRequestNumber" code) system setting. */
                    if (cardState === 'add' || cardState === 'copy') {
                        /* Retrieve the value of the "Request number" ("UsrLastRequestNumber" code) system setting. */
                        const lastNumber = await sysSettingsService.getByCode('UsrLastRequestNumber');
                        /* Send a request to update the value of the "Request number" ("UsrLastRequestNumber" code) system setting. */
                        await sysSettingsService.update({
                            code: 'UsrLastRequestNumber',
                                /* The new value is larger than the previous one by 1. */
                                value: ++lastNumber.value
                        });
                        /* Specify the new value of the "Request number" ("UsrLastRequestNumber" code) system setting in the "LastRequestNumber" attribute. */
                        request.$context.LastRequestNumber = lastNumber.value;
                        /* Call the next handler if it exists and return its result. */
                        return next?.handle(request);
                    }
                },
            },
        ]/**SCHEMA_HANDLERS*/,
        converters: /**SCHEMA_CONVERTERS*/{}/**SCHEMA_CONVERTERS*/,
        validators: /**SCHEMA_VALIDATORS*/{}/**SCHEMA_VALIDATORS*/
    };
});

Resources​

Package with example implementation