Skip to main content
Version: 8.1

Manage the system setting values on a page

Level: intermediate
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 viewModelConfigDiff schema section:

    • UsrDefaultCity. Stores data about the value of the UsrDefaultCity system setting.
    • UsrRequestLastNumber. Stores data about the value of the UsrRequestLastNumber system setting.
    viewModelConfigDiff schema section
    viewModelConfigDiff: /**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.

    Add a custom implementation of the crt.HandleViewModelResumeRequest system query handler to the handlers schema section.

    Freedom UI cannot destroy a View model and loads the last page state when you re-open a previously loaded module. Use the crt.HandleViewModelResumeRequest handler called every time you open a previously loaded page. The crt.HandleViewModelInitRequest and crt.HandleViewModelResumeRequest handlers use the same data.

    handlers schema section
    handlers: /**SCHEMA_HANDLERS*/[
    {
    request: "crt.HandleViewModelResumeRequest",
    /* Custom implementation of a system query handler. */
    handler: async (request, next) => {
    /* Wait for the rest of the initialization handlers to finish. */
    await next?.handle(request);
    /* Instantiate a system value service from @creatio-devkit/common. */
    const sysSettingsService = new sdk.SysSettingsService();
    /* Retrieve the value of the UsrDefaultCity system setting and write it to the UsrDefaultCity attribute. */
    const defaultCity = await sysSettingsService.getByCode('UsrDefaultCity');
    request.$context.UsrDefaultCity = defaultCity.displayValue;
    /* Retrieve the page state. */
    const cardState = await request.$context.CardState;
    /* When creating a new record or copying an existing record, increase the value of the UsrRequestLastNumber system setting. */
    if (cardState === 'add' || cardState === 'copy') {
    /* Retrieve the value of the UsrRequestLastNumber system setting and write it to the UsrRequestLastNumber attribute. */
    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 higher than the previous one by 1. */
    value: ++requestLastNumber.value
    });
    /* Update the value of the UsrRequestLastNumber attribute. */
    request.$context.UsrRequestLastNumber = requestLastNumber.value;
    }
    },
    }
    ]/**SCHEMA_HANDLERS*/,
  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.

Source codes

Complete source code of the page schema
/* AMD module declaration. */
define("UsrAppRequests_FormPage", /**SCHEMA_DEPS*/["@creatio-devkit/common"] /**SCHEMA_DEPS*/, function/**SCHEMA_ARGS*/(sdk)/**SCHEMA_ARGS*/ {
return {
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
{
"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": 0
},
{
"operation": "insert",
"name": "RequestNumber",
"values": {
"layoutConfig": {
"column": 1,
"row": 2,
"colSpan": 1,
"rowSpan": 1
},
"type": "crt.Label",
"caption": "#ResourceString(RequestNumber_caption)#",
"labelType": "caption",
"labelThickness": "normal",
"labelEllipsis": false,
"labelColor": "#757575",
"labelBackgroundColor": "transparent",
"labelTextAlign": "start"
},
"parentName": "LeftAreaProfileContainer",
"propertyName": "items",
"index": 0
},
{
"operation": "insert",
"name": "RequestNumberValue",
"values": {
"layoutConfig": {
"column": 1,
"row": 3,
"colSpan": 1,
"rowSpan": 1
},
"type": "crt.Label",
/* The property responsible for the text that the element contains. Bound to the UsrRequestLastNumber attribute. */
"caption": "$UsrRequestLastNumber",
"labelType": "body-1",
"labelThickness": "normal",
"labelEllipsis": false,
"labelColor": "#181818",
"labelBackgroundColor": "transparent",
"labelTextAlign": "start"
},
"parentName": "LeftAreaProfileContainer",
"propertyName": "items",
"index": 1
},
{
"operation": "insert",
"name": "City",
"values": {
"layoutConfig": {
"column": 1,
"row": 4,
"colSpan": 1,
"rowSpan": 1
},
"type": "crt.Label",
"caption": "#ResourceString(City_caption)#",
"labelType": "caption",
"labelThickness": "normal",
"labelEllipsis": false,
"labelColor": "#757575",
"labelBackgroundColor": "transparent",
"labelTextAlign": "start"
},
"parentName": "LeftAreaProfileContainer",
"propertyName": "items",
"index": 2
},
{
"operation": "insert",
"name": "CityValue",
"values": {
"layoutConfig": {
"column": 1,
"row": 5,
"colSpan": 1,
"rowSpan": 1
},
"type": "crt.Label",
/* The property responsible for the text that the element contains. Bound to the UsrDefaultCity attribute. */
"caption": "$UsrDefaultCity",
"labelType": "body-1",
"labelThickness": "normal",
"labelEllipsis": false,
"labelColor": "#181818",
"labelBackgroundColor": "transparent",
"labelTextAlign": "start"
},
"parentName": "LeftAreaProfileContainer",
"propertyName": "items",
"index": 3
}
]**SCHEMA_VIEW_CONFIG_DIFF*/,
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG*/{
"attributes": {
"UsrName": {
"modelConfigDiff": {
"path": "PDS.UsrName"
}
},
"Id": {
"modelConfigDiff": {
"path": "PDS.Id"
}
},
/* 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*/,
modelConfigDiff: /**SCHEMA_MODEL_CONFIG*/{
"dataSources": {
"PDS": {
"type": "crt.EntityDataSource",
"config": {
"entitySchemaName": "UsrAppRequests"
},
"scope": "page"
}
},
"primaryDataSourceName": "PDS"
}/**SCHEMA_MODEL_CONFIG*/,
handlers: /**SCHEMA_HANDLERS*/[
{
request: "crt.HandleViewModelResumeRequest",
/* Custom implementation of a system query handler. */
handler: async (request, next) => {
/* Wait for the rest of the initialization handlers to finish. */
await next?.handle(request);
/* Instantiate a system value service from @creatio-devkit/common. */
const sysSettingsService = new sdk.SysSettingsService();
/* Retrieve the value of the UsrDefaultCity system setting and write it to the UsrDefaultCity attribute. */
const defaultCity = await sysSettingsService.getByCode('UsrDefaultCity');
request.$context.UsrDefaultCity = defaultCity.displayValue;
/* Retrieve the page state. */
const cardState = await request.$context.CardState;
/* When creating a new record or copying an existing one, increase the value of the UsrRequestLastNumber system setting. */
if (cardState === 'add' || cardState === 'copy') {
/* Retrieve the value of the UsrRequestLastNumber system setting and write it to the UsrRequestLastNumber attribute. */
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 higher than the previous one by 1. */
value: ++requestLastNumber.value
});
/* Update the value of the UsrRequestLastNumber attribute. */
request.$context.UsrRequestLastNumber = requestLastNumber.value;
}
},
}
]/**SCHEMA_HANDLERS*/,
converters: /**SCHEMA_CONVERTERS*/{}/**SCHEMA_CONVERTERS*/,
validators: /**SCHEMA_VALIDATORS*/{}/**SCHEMA_VALIDATORS*/
};
});

Resources

Package with example implementation