list.render.before

About 1532 wordsAbout 5 min

2025-12-16

This hook is called before rendering the object table.

Purpose

It performs additional actions before list rendering, including:

Customizing object table field presentation
Customizing filters

Parameters

Parameter	Description	Type	Allowed Values	Default
Common parameters	See details	Object	--	--

Hook Callback Parameters

functional registers the hook callback. The host passes the following parameters when executing the hook:

Parameter	Description	Type	Default
context	List plugin context containing common and event-specific parameters	Object	--
plugin	Current plugin runtime information; business logic normally does not need it	Object	--
context.recordType	Current record type API name; it may be an empty string when no record type is specified	String	--

Return Value

The hook may return the following configuration object. An async hook may return Promise<Object>.

Parameter	Description	Type	Default
columnsExtendConfig	Column extension configuration	Object	--
filterExtendConfig	Filter extension configuration	Object	--
termExtendConfig	Scenario extension configuration	Object	--
imageExtendConfig	Image field extension configuration	Object	--
viewInfoExtendConfig	View extension configuration	Object	--
actionExtendConfig	Button execution behavior extension	Object	--
formatListDataAsync	Processes list data after default formatting	Function	--
formatRequestParam	Extends list query request parameters	Function	--
forceTrWrap	Whether list cells forcibly wrap	Boolean	--
allSummaryFields	Per-scenario summary fields across all pages	Object	--
summaryFields	Per-scenario summary fields for the current page	Object	--
enableLiveFiltering	Whether list filtering uses live search	Boolean	--
buttons	List toolbar button configuration	Object	--
operateBtns	Row action button extension functions	Function[]	--
disableFeatures	Features disabled for the table	Object	--

All top-level properties are optional. Return only the properties that need to change.

Cross-object filtering mode does not support filterExtendConfig, termExtendConfig, viewInfoExtendConfig, disableFeatures, or formatRequestParam; the host removes these properties.

columnsExtendConfig

Parameter	Description	Type	Default
filterColumns	Fields hidden from the table, table settings, and filters	Array	--
render	Custom cell render configuration	Object	--
attrs	Cell attribute extension configuration	Object	--

columnsExtendConfig.render

Parameter	Description	Type	Default
[fieldApiName]	Field render function	Function	--

The render function signature is render(value, type, data, index). The host uses this function directly as the table column render function.

Parameter	Description	Type
value	Raw field value before default formatting	Any
type	Render type; normally `column` during initial rendering, but some partial updates pass the current column configuration object	String \| Object
data	Complete current row data	Object
index	Row index within the current page	Number

The return value is inserted as cell content and should normally be a String. HTML in the string is rendered as cell content. Escape raw strings before including them in returned HTML to prevent XSS.

columnsExtendConfig.attrs

An attrs key may be a field API name, returnType, or dataType. A field API name takes precedence.

Parameter	Description	Type	Default
showLookupText	Shows lookup text without a clickable link	Boolean	--
isEdit	Enables cell editing	Boolean	--
noSupportBatchEdit	Disables batch editing	Boolean	--
disabledDel	Disables clearing the field value	Boolean	--
fixed	Fixes the column to the left side of the table	Boolean	--

filterExtendConfig

Parameter	Description	Type	Default
[fieldApiName]	Filter configuration for the field	Object	--

filterExtendConfig.

Parameter	Description	Type	Default
disabled	Disables filtering for the field	Boolean	--
onlyOr	Operators retained for the field	Array	--
components	Filter components keyed by operator number	Object	--
filterOptions	Filters options for single-select and multi-select fields	Function	--
defaultCompare	Default operator	Number	--
selectType	Uses `select` to force a select control for single-select or multi-select fields	String	--
groupIncludeChildrenStatus	Department filter behavior: `2` includes child departments and `1` excludes them	Number	--

Common operator numbers:

Number	Operator	Description
1	EQ	Equal
2	N	Not equal
3	GT	Greater than
4	GTE	Greater than or equal
5	LT	Less than
6	LTE	Less than or equal
7	LIKE	Contains
8	NLIKE	Does not contain
9	IS	Is empty
10	ISN	Is not empty
11	STARTWITH	Starts with
12	ENDWITH	Ends with
13	HASANYOF	Is any of
14	NHASANYOF	Is not any of
17	BETWEEN	Time range
22	IN	Text is any of
23	NIN	Text is not any of

filterOptions(options) receives the original option array and must return the filtered Object[]. Each option normally contains value and label.

The host creates a configured filter component with new components[comparison](options). A condition-filter component must implement render(), getValue(), and destroy(). An external filter component must also implement setValue() and clean().

Method	Description	Return Value
render(container: HTMLElement)	Mounts the component in the provided native DOM container	void
getValue()	Returns the current filter value	Any
destroy()	Destroys the component and cleans up DOM and events	void
setValue(value)	Sets the value for an external filter	void
clean()	Clears an external filter	void

Constructor options may include fieldAttr, filterValue, model, search, $el, zIndex, keyEnterFn, and el. Condition filters receive $el, zIndex, and keyEnterFn; external filters receive el.

termExtendConfig

Parameter	Description	Type	Default
default	Default scenario API name	String	--
retain	Scenario API names or IDs to retain	Array	--

imageExtendConfig

Parameter	Description	Type	Default
[imageFieldApiName]	Image field configuration	Object	--

imageExtendConfig.

Parameter	Description	Type	Default
previewWidth	Hover-preview width	Number	--
previewHeight	Hover-preview height	Number	--

actionExtendConfig

Keys in actionExtendConfig are case-sensitive runtime actions. They are not always identical to layout action or api_name values. For example, the built-in Add button uses layout action Add but runtime action add, so its extension is actionExtendConfig.add.

Parameter	Description	Type	Default
[action]	Execution parameters or row-action pre-hook for an action	Object	--
beforeRowAction	Shared row-action pre-hook used when the action has no specific hook	(params: Object) => Promise	--

actionExtendConfig.

Parameter	Description	Type	Default
parseParam	Extends button execution parameters	(params: Object) => Object	--
beforeRowAction	Runs before a row action and must return a Promise	(params: Object) => Promise	--

parseParam(params) returns properties that are shallow-merged into the execution parameters. Toolbar parameters commonly include source, apiname, pageApiname, dataList, queryParam, recordType, displayName, describe, field_list, _show_field_list, objectDescribeExt, and success.

A row-action beforeRowAction(params) continues the default action after the Promise resolves and stops it when the Promise rejects. Common parameters include data, dataId, fields, title, apiname, button_apiname, button_action, button_type, redirect_type, buttonInfo, objectDescribe, objectDescribeExt, shouldFetchDetail, _from, and success.

formatListDataAsync

formatListDataAsync(listData) receives { totalCount, data } after standard list formatting and must preserve that structure. It may return the object directly or return Promise<Object>.

formatRequestParam

formatRequestParam(params) receives the complete list request parameters. Relevant properties include object_describe_api_name, search_template_id, and the JSON string search_query_info. Return an Object to shallow-merge changes, return nothing after mutating params, or preferably return an explicit change object.

disableFeatures

Set an optional property to true to disable the corresponding feature:

Property	Feature	Property	Feature
term	Scenario switching	allowTerm	Scenario data
filter	Filtering	sort	Field sorting
multiSort	Multi-field sorting	search	Search
quickFilter	Quick filter	button	General buttons
batchButtons	Batch action buttons	operate	Row action buttons
multiple	Multiple selection	termBatch	Scenario batch area
recordType	Record type	view	View switching
refresh	Refresh	setting	Settings
summary	Summary information	pagination	Pagination
tag	Tag button	guide	List guide
detail	Detail navigation

allSummaryFields

allSummaryFields is keyed by scenario ID or scenario API name. Each value is an array of items with type: 'sum', field_name, and an api_name such as sum_amount__c.

summaryFields

summaryFields is keyed by scenario ID or scenario API name. Each value is an array of items with type: 'sum' and field_name.

buttons and operateBtns

buttons configures list toolbar buttons:

Parameter	Description	Type	Default
add	Custom buttons to add	Object[]	--
del	Layout button actions or API names to remove	String[]	--
reset	Existing buttons to rename or override	Object[]	--

An add item requires action and label; use callback(params) for click handling, exposed for direct visibility, and placement: { base, relative } for placement. Toolbar callbacks receive recordType and objectApiName.

operateBtns is an array of (rowData) => ({ add, del, reset, retain }) functions. Custom row buttons require action, label, and callback(params). Their callback receives the complete row-action parameters.

Basic Examples

Extend List Query Parameters

export default class Plugin {
    apply() {
        return [{
            event: 'list.render.before',
            functional: this.renderBefore.bind(this)
        }];
    }
    renderBefore() {
        return {
            formatRequestParam(params) {
                const searchQueryInfo = JSON.parse(params.search_query_info);
                searchQueryInfo.filters = searchQueryInfo.filters || [];
                searchQueryInfo.filters.push({
                    field_name: 'name',
                    field_values: ['value'],
                    operator: 'LIKE'
                });
                return {
                    search_query_info: JSON.stringify(searchQueryInfo)
                };
            }
        };
    }
}

Hide a Column

return {
    columnsExtendConfig: {
        filterColumns: ['name']
    }
};

Customize Cell Content

return {
    columnsExtendConfig: {
        render: {
            owner: (value, type, data, index) => `${index + 1}. Custom Owner`
        }
    }
};

Disable Filtering for a Field

return {
    filterExtendConfig: {
        owner: { disabled: true }
    }
};

Retain Selected Filter Operators

return {
    filterExtendConfig: {
        name: { onlyOr: [7, 8] }
    }
};

Filter Select Options

return {
    filterExtendConfig: {
        status: {
            filterOptions(options) {
                return options.filter(option => option.value !== 'disabled');
            }
        }
    }
};

Set the Default Scenario

return {
    termExtendConfig: {
        default: 'All',
        retain: ['All', 'InCharge']
    }
};

Configure Summary Fields

return {
    summaryFields: {
        All: [{ type: 'sum', field_name: 'amount__c' }]
    },
    allSummaryFields: {
        All: [{
            type: 'sum',
            field_name: 'amount__c',
            api_name: 'sum_amount__c'
        }]
    }
};

Set Image Preview Size

return {
    imageExtendConfig: {
        field_0N8Yi__c: {
            previewWidth: 500,
            previewHeight: 500
        }
    }
};

return {
    buttons: {
        add: [{
            action: 'customButton',
            label: 'Custom Object Button',
            exposed: true,
            placement: { base: 'Add' },
            callback({ recordType, objectApiName }) {
                console.log(recordType, objectApiName);
            }
        }]
    }
};

Add a Row Action Button

return {
    operateBtns: [
        rowData => ({
            add: [{
                action: 'customRowButton',
                label: 'Show Record ID',
                callback(params) {
                    console.log(rowData, params.dataId);
                }
            }]
        })
    ]
};

FAQ

Q: Why is the data incorrect after paging when formatListDataAsync modifies list data?

A: The function receives the current page's { totalCount, data } each time. Always derive and return the same structure from that input; do not cache or reuse a previous page's data. Use formatRequestParam to change list request parameters.

bizApi

dataGetter

dataUpdater

bizApi

dataGetter

bizApi

dataGetter

list.render.before