Version: 8.2

Customize selection windows

Level: intermediate

Creatio lets you display previously handled data in custom selection window. Compared to a full-scale selection window of a Dropdown field type, custom selection window provides more options for selecting records. For example:

Work with a large amount of data from multiple resources.
Work with flexible search.
Display pre-filtered data.
Use groups.
Customize the order of displaying columns.
Enable or disable the addition of records.

1. Create a selection window

Create a new Freedom UI app or open an existing app. Instructions: Create an app manually (user documentation).
Create a Freedom UI page schema that implements the selection window. To do this, click New page → Blank page → Select.
Open the source code of the Freedom UI page. To do this, click .
Change the schema properties. To do this, click in the properties area and fill out the schema properties.

Property
Property value
Parent object
BaseLookupPageTemplate

Fill out other properties based on your business goals.
Save the changes.

Property	Property value
Parent object	BaseLookupPageTemplate

2. Set up the selection window UI

Open the selection page in the Freedom UI Designer.
If needed, add one or more Freedom UI elements whose data to display in the selection window. Instructions: Element setup examples (user documentation).
Set up additional filtering if needed. Instructions: Set up List components (user documentation).
Save the changes.

3. Set up the page UI

Set up the page UI based on your business goals. Instructions: Element setup examples (user documentation).

4. Set up how to open the selection window

Add the dependencies. To do this, add @creatio-devkit/common library as a dependency. The library includes the HandlerChainService service that opens pages.

View an example that adds the @creatio-devkit/common library as a dependency to the SomeApp_FormPage Freedom UI page schema below.
AMD module dependencies
```
/* Declare the AMD module. */
define("SomeApp_FormPage", /**SCHEMA_DEPS*/["@creatio-devkit/common"]/**SCHEMA_DEPS*/, function/**SCHEMA_ARGS*/(sdk)/**SCHEMA_ARGS*/ {
    return {
        ...
    }
});
```
Add an attribute. Instructions: Set up the field display condition (step 2).
Bind an attribute to the label. Instructions: Set up the field display condition (similarly to step 3). Instead of the visible property, use the caption property that handles the text displayed in the element.
Set up how to handle the selection window open on button click. Instructions: Optimize the execution of a custom business logic (step 4).

Implement the custom request handler.

Go to the handlers schema section.
Add a custom implementation of the custom usr.SomeCustomRequest request handler.
1. Send the crt.OpenSelectionWindowRequest system request that opens the selection window.
2. Implement other business logic based on your business goals.

View an example of a custom usr.SomeCustomRequest request handler that opens the UsrSomeSelectionWindow selection window, below.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "usr.SomeCustomRequest",
        /* Implement the custom request handler. */
        handler: async (request, next) => {
            /* Send the system request to open the "UsrSomeSelectionWindow" selection window. */
            sdk.HandlerChainService.instance.process({
                type: 'crt.OpenSelectionWindowRequest',
                scopes: [...request.scopes],
                $context: request.$context,
                /* Entity schema whose data is displayed in the selection window. Optional. If you omit the "entitySchemaName" property, Creatio uses the value from the attribute specified in the "itemsAttributeName" property.*/
                entitySchemaName: 'SomeSchema',
                /* Title of the selection window. */
                caption: 'SomeString',
                /* Schema code of the selection window. Optional. If you omit the "schemaName" property, Creatio uses the "BaseLookupPageTemplate" schema. */
                schemaName: 'UsrSomeSelectionWindow',
                /* Attribute that stores data of the selection window title and the selection result in the window. Generally, it is the attribute associated with the "Combobox" control. Optional. If you use some attribute as an "itemAttributeName" property value, Creatio sets the result to the attribute value. */
                itemAttributeName: 'SomeAttribute1',
                /* Attribute that stores data of the data source. Optional. If you specify the "itemsAttributeName" property, Creatio uses the value to get entity. */
                itemsAttributeName: 'SomeAttribute2',
                /* Callback function that handles the records selected in the selection window. */
                afterClosed: async (result) => {

                    const canceled = result.canceled;
                    if (canceled) {
                        /* If the selection window does not include any record selected and a user closes the selection window, execute the following business logic. */
                        ...;
                    }
                    if (!result.canceled) {
                        /* If the selection window includes selected records, execute the following business logic. */
                        const lookupValues = await result.getLookupValues();
                        const value = lookupValues[0];
                        if (value) {
                            /* If the selection window includes selected records, execute the following business logic. */
                            ...;
                        }
                    }
                },
                /* Filter data. Optional. If you specify the "filtersConfig" property, Creatio filters data. */
                filtersConfig: {
                    filterAttributes: [
                        {
                            name: 'SomeFilter',
                            loadOnChange: false
                        }
                    ],
                    attributesConfig: {
                        SomeFilter: {
                            value: {
                                /* Implement the business logic that filters data to display in the selection window. */
                                ...,
                            }
                        }
                    }
                }
            });
            /* Call the next handler if it exists and return its result. */
            return next?.handle(request);
        }
    }
]/**SCHEMA_HANDLERS*/,

The implementation of a custom request handler has the following special features:

If you omit the entitySchemaName property, Creatio uses the value from the attribute specified in the itemsAttributeName property to get entity.
If you omit the schemaName property, Creatio uses the BaseLookupPageTemplate schema.
If you omit the caption property, Creatio uses the value from the attribute specified in the itemAttributeName property. If you also omit the itemAttributeName property, Creatio uses the value specified in the entitySchemaName property.
If you use some attribute as an itemAttributeName property value, Creatio sets the result to the attribute value.
If you specify the filtersConfig property, Creatio filters data.

Set up additional functionality of the selection window if needed.

Add New button (Freedom UI only)

To use the selection window in Classic UI, exclude the button that opens new record, i. e., whose Action property is "Open new record," from the window. Otherwise, Creatio will close the selection window, create a new record, but not populate the created record with the values selected in the selection window.

View an example that adds New button below.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "usr.SomeCustomRequest",
        /* Implement the custom request handler. */
        handler: async (request, next) => {
            /* Send the system request to open the "UsrSomeSelectionWindow" selection window. */
            sdk.HandlerChainService.instance.process({
                ...,
                /* Set up additional functionality. */
                "features": {
                    /* Add "New" button. */
                    "create": {
                        "enabled": true;
                    }
                },
                ...,
            });
            /* Call the next handler if it exists and return its result. */
            return next?.handle(request);
        }
    }
]/**SCHEMA_HANDLERS*/,

Enable multiple selection

View an example that enables multiple selection below.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "usr.SomeCustomRequest",
        /* Implement the custom request handler. */
        handler: async (request, next) => {
            /* Send the system request to open the "UsrSomeSelectionWindow" selection window. */
            sdk.HandlerChainService.instance.process({
                ...,
                /* Set up additional functionality. */
                "features": {
                    "select": {
                        /* Enable multiple selection. */
                        "multiple": true
                    }
                },
                /* Callback function that handles the records selected in the selection window. */
                afterClosed: async (result) => {

                    const lookupValues = await result.getLookupValues();
                    /* If the selection window includes multiple selected records, execute the following business logic. */
                    ...;

                    const canceled = result.canceled;
                    if (canceled) {
                        /* If the selection window does not include any record selected and a user closes the selection window, execute the following business logic. */
                        ...;
                    }
                },
                ...,
            });
            /* Call the next handler if it exists and return its result. */
            return next?.handle(request);
        }
    }
]/**SCHEMA_HANDLERS*/,

Add Select all checkbox

View an example that adds Select all checkbox, below.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "usr.SomeCustomRequest",
        /* Implement the custom request handler. */
        handler: async (request, next) => {
            /* Send the system request to open the "UsrSomeSelectionWindow" selection window. */
            sdk.HandlerChainService.instance.process({
                ...,
                /* Set up additional functionality. */
                "features": {
                    "select": {
                        "multiple": true,
                        /* Add "Select all" checkbox. */
                        "selectAll": true
                    }
                },
                ...,
            });
            /* Call the next handler if it exists and return its result. */
            return next?.handle(request);
        }
    }
]/**SCHEMA_HANDLERS*/,

Set up the condition to select lookup values

View an example that receives 2 lookup values with step 2, below.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "usr.SomeCustomRequest",
        /* Implement the custom request handler. */
        handler: async (request, next) => {
            /* Send the system request to open the "UsrSomeSelectionWindow" selection window. */
            sdk.HandlerChainService.instance.process({
                ...,
                /* Set up additional functionality. */
                "features": {
                    "select": {
                        "multiple": true
                    }
                },
                /* Callback function that handles the records selected in the selection window. */
                afterClosed: async (result) => {

                    let rowsOffset = 0;
                    const rowCount = 2;
                    const pagingConfig = { rowsOffset, rowCount };

                    /* Set up the condition to select lookup values. */
                    let lookupValues = await result.getLookupValues({ pagingConfig });
                    while (lookupValues.length) {
                        /* Execute the following business logic with received lookup values. */
                        ...,
                        rowsOffset += 2;
                        lookupValues = await result.getLookupValues({ pagingConfig: { rowsOffset, rowCount }});
                    }

                    if (!lookupValues.length) {
                        /* Execute the following business logic when all the received lookup values are handled. */
                        ...,
                    },

                    /* If the selection window includes multiple selected records, execute the following business logic. */
                    ...;

                },
                ...,
            });
            /* Call the next handler if it exists and return its result. */
            return next?.handle(request);
        }
    }
]/**SCHEMA_HANDLERS*/,

Set up a list of pre-selected lookup values

View an example that sets up a list of pre-selected lookup values, below.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "usr.SomeCustomRequest",
        /* Implement the custom request handler. */
        handler: async (request, next) => {
            /* Send the system request to open the "UsrSomeSelectionWindow" selection window. */
            sdk.HandlerChainService.instance.process({
                ...,
                /* Set up a list of pre-selected lookup values. */
                selectionState: {
                    type: 'specific',
                    selected: [
                        /* List of pre-selected lookup values. */
                        'Some-Record1-ID',
                        'Some-Record2-ID',
                        ...,
                    ],
                },
                ...,
            });
            /* Call the next handler if it exists and return its result. */
            return next?.handle(request);
        }
    }
]/**SCHEMA_HANDLERS*/,

Enable displaying of deactivated object records

Learn more: Deactivate object records.

View an example that enables displaying of deactivated object records, below.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "usr.SomeCustomRequest",
        /* Implement the custom request handler. */
        handler: async (request, next) => {
            /* Send the system request to open the "UsrSomeSelectionWindow" selection window. */
            sdk.HandlerChainService.instance.process({
                ...,
                /* Set up additional functionality. */
                "features": {
                    /* Enable displaying of deactivated object records. */
                    showDeactivatedRecords: true,
                },
                ...,
            });
            /* Call the next handler if it exists and return its result. */
            return next?.handle(request);
        }
    }
]/**SCHEMA_HANDLERS*/,

Save the changes.

1. Create a selection window​

2. Set up the selection window UI​

3. Set up the page UI​

4. Set up how to open the selection window​

See also​

1. Create a selection window

2. Set up the selection window UI

3. Set up the page UI

4. Set up how to open the selection window

See also