Filter crt.OpenLookupPageRequest

Hello,

Here is an example of OpenLookupPageRequest with a filtersConfig.

handlers: /**SCHEMA_HANDLERS*/[
			{
				request: "usr.OpenLookupRequest",
				handler: async (request, next) => {
					devkit.HandlerChainService.instance.process({
						type: "crt.OpenLookupPageRequest",
						scopes: [...request.scopes],
						$context: request.$context,
						entitySchemaName: "Contact",
						// caption: 'Responsible',
						schemaName: 'CustomLookupPage',
						itemAttributeName: 'LookupAttribute_2mnilrq',
						// itemsAttributeName: 'Contact_List',
						afterClosed: (result) => {
							alert(result?.displayValue ?? '');
						},
						filtersConfig: {
							filterAttributes: [
								{
									name: 'MyFilter',
									loadOnChange: false
								}
							],
							attributesConfig: {
								MyFilter: {
									value: {
										"items": {
											"29e16d42-36f1-4e04-9029-4321cbb2494d": {
												"filterType": 1,
												"comparisonType": 11,
												"isEnabled": true,
												"trimDateTimeParameterToDate": false,
												"leftExpression": {
													"expressionType": 0,
													"columnPath": "Name"
												},
												"isAggregative": false,
												"dataValueType": 1,
												"rightExpression": {
													"expressionType": 2,
													"parameter": {
														"dataValueType": 1,
														"value": "Super"
													}
												}
											}
										},
										"logicalOperation": 0,
										"isEnabled": true,
										"filterType": 6,
										"rootSchemaName": "Contact"
									}
								}
							}
						}
					});
					return next?.handle(request);
				}
			}
		]/**SCHEMA_HANDLERS*/,

If you don't know how to build a proper filter here is a small tip. On a Freedom UI page add a list with the object you want to filter. In this list add a static filter with a condition you want to apply to a OpenLookupPageRequest and save it. As a result, in the code of this page, you can find the full filter code, all you need to do is to replace "MyFilter" with it.

Question on OpenLookupPageRequest. In an edit scenario, could you pass the already selected options so that they appear already selected in the lookup list?

You can use the option selectionState to predefine selected rows, which will be pre-selected

type: "crt.OpenLookupPageRequest",
	...
	selectionState: {
		type: 'specific',
		selected: [
			'9d06bf9f-eb7a-4849-b83d-cbba994f185d',
			'49ba9a9e-2e28-48cb-b1bc-81b7871acb9d',
		],
	},

Dmytro Vovchenko,

Those are really useful, are there any other parameters that can be passed to the newly opened lookup page? I'm currently looking for a way to automatically set the initial search value of the lookup window, but I'm sure there are many other undocumented useful parameters like the selectionState that can be passed to a lookup page when opening it. A generic way to pass data into the page would be great!

I looked into passing a defaultSearchValue parameter into the request, but it didn't seem to affect the modal lookup.

Harvey Adcock,

Hello,

Here is all the available documentation we have:

Lookup window example:

In order to open the lookup window, you have to use crt.OpenSelectionWindowRequest

/**
 * @publicApi
 */
@CrtRequest({
    type: 'crt.OpenSelectionWindowRequest',
})
export class OpenSelectionWindowRequest extends BaseRequest {
    public itemAttributeName?: string;
    public itemsAttributeName?: string;
    /**
     * @publicApi
     */
    public entitySchemaName?: string;
    /**
     * @publicApi
     */
    public schemaName?: string;
    /**
     * @publicApi
     */
    public filtersConfig?: FiltersConfig;
    /**
     * @publicApi
     */
    public features?: PageLookupFeatures;
    /**
     * @publicApi
     */
    public selectionState?: SelectionState;
    /**
     * @publicApi
     */
    public afterClosed?: (result: SelectionWindowResult) => void;
    /**
     * @publicApi
     */
    public caption?: LocalizableString;
}

Add the following code to your custom handler:

handlers: /**SCHEMA_HANDLERS*/[
			{
				request: "usr.OpenLookupRequest",
				handler: async (request, next) => {
					devkit.HandlerChainService.instance.process({
						type: "crt.OpenSelectionWindowRequest",
						scopes: [...request.scopes],
						$context: request.$context,
						entitySchemaName: "Contact",
						// caption: 'Responsible',
						schemaName: 'CustomLookupPage',
						itemAttributeName: 'LookupAttribute_2mnilrq',
						// itemsAttributeName: 'Contact_List',
						afterClosed: async (result) => {
							if (!result.canceled) {
								const lookupValues = await result.getLookupValues();
								const value = lookupValues[0];
								if (value) {
									alert(value?.displayValue ?? '');
								}
							}
						},
						filtersConfig: {
							filterAttributes: [
								{
									name: 'MyFilter',
									loadOnChange: false
								}
							],
							attributesConfig: {
								MyFilter: {
									value: {
										"items": {
											"29e16d42-36f1-4e04-9029-4321cbb2494d": {
												"filterType": 1,
												"comparisonType": 11,
												"isEnabled": true,
												"trimDateTimeParameterToDate": false,
												"leftExpression": {
													"expressionType": 0,
													"columnPath": "Name"
												},
												"isAggregative": false,
												"dataValueType": 1,
												"rightExpression": {
													"expressionType": 2,
													"parameter": {
														"dataValueType": 1,
														"value": "Super"
													}
												}
											}
										},
										"logicalOperation": 0,
										"isEnabled": true,
										"filterType": 6,
										"rootSchemaName": "Contact"
									}
								}
							}
						}
					});
					return next?.handle(request);
				}
			}
		]/**SCHEMA_HANDLERS*/,

where

entitySchemaName - the name of the entity schema whose data is displayed in the lookup window. Optional parameter. If not specified, the data source is taken from the attribute specified in itemAttributeName

caption - optional parameter, displayed in the window title. If caption is not specified, the caption is taken from the attribute specified in the itemAttributeName parameter. If itemAttributeName is not specified, then from the entity schema.

schemaName - the name of the schema that is displayed in the lookup window. Optional parameter. Default is BaseLookupPageTemplate

itemAttributeName - the name of the attribute from which the title is taken, the name of the entity schema and in which the result of the selection in the window will be written. Optional parameter. As a rule, this is the attribute with which the Combobox control is associated.

itemsAttributeName - the name of the attribute from which the data source name is taken. Optional parameter.

afterClosed - callback function returning the result of the selection in the window. Optional parameter.

filtersConfig-  describes the filter to be applied to the data. Optional parameter

PageLookupFeatures

Additionally, the user can specify additional features for the selection window.

export interface PageLookupFeatures {
    create?: {
        enabled: boolean;                         // false by default
    };
    select: {
        multiple: boolean;                        // false by default
        selectAll: boolean;                       // false by default
    };
    showDeactivatedRecords?: boolean;
}

The user should provide the Create option as enabled to display the New button in the selection window (only for the FreedomUI host).

devkit.HandlerChainService.instance.process({
	type: "crt.OpenSelectionWindowRequest",
	scopes: [...request.scopes],
	$context: request.$context,
	....
	"features": {
		"create": {
            "enabled": true;
        }
	}
});

The New button in this window works best only in the Freedom UI shell. In the Classic UI, new record will be created, but the selection window will close after saving it without passing the created record selected value. If you want to use this window in the Classic UI, please consider it, or don’t show this button there.

SelectionWindowResult  type

export class SelectionWindowResult {
    canceled: boolean; // indicates whether selection window was canceled by user
    filter: FilterMetadata; // Filter 
    async getLookupValues(options?: { pagingConfig: DataSourcePagingConfig }): Promise<LookupValue[]>; // method to get lookup values
}

where DataSourcePagingConfig is 

interface DataSourcePagingConfig {
    rowsOffset: number;
    rowCount: number;
}

example

devkit.HandlerChainService.instance.process({
	type: "crt.OpenSelectionWindowRequest",
	scopes: [...request.scopes],
	$context: request.$context,
	....
	"features": {
		"select": {
            "multiple": true;
        }
	},
	afterClosed: async (selectionWindowResult) => {
		const filter = selectionWindowResult.filter // getting filter
		// or 
		const lookupValues = await selectionWindowResult.getLookupValues(); // getting lookupValues
	}
});

Multiselection mode

To enable multiselection mode user should add next feature to OpenPageLookupRequest

devkit.HandlerChainService.instance.process({
	type: "crt.OpenSelectionWindowRequest",
	scopes: [...request.scopes],
	$context: request.$context,
	....
	features: {
		select: {
            "multiple": true
        }
	}
});

So afterClosed will look like this 

devkit.HandlerChainService.instance.process({
	type: "crt.OpenSelectionWindowRequest",
	scopes: [...request.scopes],
	$context: request.$context,
	....
	features: {
		select: {
			multiple: true
		}
	},
	afterClosed: async (selectionWindowResult) => {
		const lookupValues = await selectionWindowResult.getLookupValues();
		// do something with lookup values
	}
});

Select all

To enable the ability to select all records, you should add the next features to OpenPageLookupRequest.

devkit.HandlerChainService.instance.process({
	type: "crt.OpenSelectionWindowRequest",
	scopes: [...request.scopes],
	$context: request.$context,
	....
	features: {
		select: {
            multiple: true,
            selectAll: true
        }
	}
});

Canceled
 

Handling cases when the user presses the cancels Selection window

devkit.HandlerChainService.instance.process({
	type: "crt.OpenSelectionWindowRequest",
	scopes: [...request.scopes],
	$context: request.$context,
	....
	features: {
		select: {
			multiple: true
		}
	},
	afterClosed: (selectionWindowResult) => {
		const canceled = selectionWindowResult.canceled;
		if (canceled) {
			// do some logic when user canceled selection window
		}
	}
});

Selecting a special set of values

getLookupValues could be called with paging config where user can specify rowsOffset and rowCount to get a specific list of values

devkit.HandlerChainService.instance.process({
	type: "crt.OpenSelectionWindowRequest",
	scopes: [...request.scopes],
	$context: request.$context,
	....
	features: {
		select: {
			multiple: true
		}
	},
	afterClosed: async (selectionWindowResult) => {
		const pagingConfig = {
			rowsOffset: 2,
			rowCount: 2
		}
		const lookupValues = await selectionWindowResult.getLookupValues({ pagingConfig });
		// do something with received lookup values
	}
});

Example of iterating through lookupValues. Getting pair of 2 lookupValues with step of 2

devkit.HandlerChainService.instance.process({
	type: "crt.OpenSelectionWindowRequest",
	scopes: [...request.scopes],
	$context: request.$context,
	....
	features: {
		select: {
			multiple: true
		}
	},
	afterClosed: async (selectionWindowResult) => {
		let rowsOffset = 0;
        const rowCount = 2;
        const pagingConfig = { rowsOffset, rowCount };
        let lookupValues = await selectionWindowResult.getLookupValues({ pagingConfig });
        while (lookupValues.length) {
            /*
              fn(lookupValues); // do something with received lookupValues pair
            */
            rowsOffset += 2;
            lookupValues = await selectionWindowResult.getLookupValues({ pagingConfig: { rowsOffset, rowCount }});
        }
        if (!lookupValues.length) {
            /*
              Do some logic here on end of list - when there are no more lookupValues
            */
        }
	}
});

Selection state

and SelectionState is:

{
    type: 'specific';
    selected: unknown[]; // array of id's
}

So user can predefine selected rows, which will be pre-selected

devkit.HandlerChainService.instance.process({
	type: "crt.OpenSelectionWindowRequest",
	...
	selectionState: {
		type: 'specific',
		selected: [
			'9d06bf9f-eb7a-4849-b83d-cbba994f185d',
			'49ba9a9e-2e28-48cb-b1bc-81b7871acb9d',
		],
	},
});

showDeactivatedRecords

When set to true, deactivated entries of the object are shown.

This is all the information that we have on the lookup page handling cases, I hope it helps.