diff --git a/docs/grid/api/gridcolumn_properties/gridcolumn_header_property.md b/docs/grid/api/gridcolumn_properties/gridcolumn_header_property.md index e92ecca8..8a02841d 100644 --- a/docs/grid/api/gridcolumn_properties/gridcolumn_header_property.md +++ b/docs/grid/api/gridcolumn_properties/gridcolumn_header_property.md @@ -11,6 +11,9 @@ description: You can explore the header config of Grid column in the documentati ### Usage ~~~jsx +type TOption = { id: Id, value: string } | string; +type IOption = { id: Id, value: string }; + header: [ { text?: @@ -35,6 +38,10 @@ header: [ filterConfig?: { placeholder?: string, // sets an input placeholder for `inputFilter`, `comboFilter` and `dateFilter` icon?: string, // sets CSS class for the filter icon in `inputFilter` and the calendar icon in `dateFilter` + /* the property of `selectFilter` and `comboFilter` configuration */ + options?: + TOption[] | + ((uniqueData: IOption[], col: ICol) => TOption[]), /* properties of `comboFilter` configuration */ filter?: (item, input: string) => boolean, multiselection?: boolean, // false by default @@ -100,7 +107,7 @@ Each header object may include: filterConfig - (optional) a configuration object for setting the behavior and appearance of the filter. The set of properties depends on the filter type specified in the `content` property:

- a configuration object for "inputFilter" can contain the following properties:
- a configuration object for "comboFilter" can contain a set of properties: - a configuration object for "dateFilter" (PRO version) can contain a set of properties:
Main properties:Calendar API configuration properties: + (optional) a configuration object for setting the behavior and appearance of the filter. The set of properties depends on the filter type specified in the `content` property:

- a configuration object for "inputFilter" can contain the following properties:
- a configuration object for "selectFilter" can contain the following property:
- a configuration object for "comboFilter" can contain a set of properties: - a configuration object for "dateFilter" (PRO version) can contain a set of properties:
Main properties:Calendar API configuration properties: customFilter (optional) a callback function that allows defining custom filtering logic. It takes two parameters:and returns *true*, if the row matches the filtering criteria, otherwise *false* diff --git a/docs/grid/configuration.md b/docs/grid/configuration.md index 59a04076..73878467 100644 --- a/docs/grid/configuration.md +++ b/docs/grid/configuration.md @@ -1418,6 +1418,12 @@ Allows end users to filter data of a column by choosing an option from a present } ~~~ +If you specify **selectFilter** as the header or footer content of a column, you can set a configuration object for it via the `filterConfig` property. + +#### The list of configuration properties for `selectFilter` + +- `options` - (*array | function*) - optional, sets the list of the filter options manually instead of building it from the column data, see [Custom options of header/footer filters](#custom-options-of-headerfooter-filters) + **Related sample**: [Grid. Header filters (dateFilter, comboFilter, inputFilter, selectFilter)](https://snippet.dhtmlx.com/4qz8ng3c) :::note @@ -1449,6 +1455,7 @@ If you specify **comboFilter** as the header or footer content of a column, you - **placeholder** - (*string*) sets a placeholder in the input of ComboBox - **virtual** - (*boolean*) enables dynamic loading of data on scrolling the list of options, *true* by default - **template** - (*function*) a function which returns a template with content for the filter options. Takes an option item as a parameter +- **options** - (*array | function*) sets the list of the filter options manually instead of building it from the column data, see [Custom options of header/footer filters](#custom-options-of-headerfooter-filters) ~~~jsx { id: "category", @@ -1533,6 +1540,133 @@ Calendar API configuration properties: **Related sample**: [Grid. Header filters (dateFilter, comboFilter, inputFilter, selectFilter)](https://snippet.dhtmlx.com/4qz8ng3c) +### Custom options of header/footer filters + +:::info +The ability to manage the options of a filter manually is available starting from v9.4. +::: + +By default, **selectFilter** and **comboFilter** build their list of options from the data of the column, and offer only the values that actually occur in the loaded rows. If a column holds *"KG"* in every row, the dropdown offers *"KG"* and nothing else, even when the valid values for the column come from a fixed reference list. + +The `options` property of the `filterConfig` object lets you define that list yourself. It takes either a static array of options or a function that transforms the data-driven list: + +~~~jsx +type TOption = { id: Id, value: string } | string; +type IOption = { id: Id, value: string }; + +options?: TOption[] | ((uniqueData: IOption[], col: ICol) => TOption[]); +~~~ + +| Form | Behavior | +| ---- | -------- | +| `TOption[]` | a static list. It fully replaces the data-driven one, and Grid does not scan the dataset for this column | +| `(uniqueData, col) => TOption[]` | a callback function. It receives the data-driven list, already normalized to `{ id, value }` pairs, and returns the list to show | +| *omitted* | the default. Grid builds the list from the column data | + +#### Option format + +An option is either an `{ id, value }` pair or a plain string. Grid converts both `id` and `value` to strings, because a header filter always reports its value as a string. + +- `id` - the value stored in the cell. This is what the filter compares against, and what the [`customFilter`](#customizing-headerfooter-filters) function receives as its `match` parameter +- `value` - the label shown in the dropdown + +:::note +The `id` of an option must match the value stored in the cell, not the formatted one. For example, in a column with `type: "number"` and a [`numberMask`](#numbermask), the cell holds *1000* while Grid displays *1,000*, so the option `id` must be *1000*. +::: + +#### A static list of options + +Use a static list when the column's valid values come from a fixed reference list that must always be offered in full: + +~~~jsx {10-14} +const grid = new dhx.Grid("grid_container", { + columns: [ + { + id: "unitMeasure", + header: [ + { text: "Unit Measure" }, + { + content: "selectFilter", + filterConfig: { + options: [ + { id: "KG", value: "Kilogram" }, + { id: "L", value: "Liters" }, + { id: "PCS", value: "Pieces" } + ] + } + } + ] + } + ], + data: [ + { id: 1, unitMeasure: "KG" }, + { id: 2, unitMeasure: "KG" } + ] +}); +~~~ + +The dropdown shows *Kilogram*, *Liters* and *Pieces* regardless of what the dataset contains. Selecting *Liters* leaves Grid empty, which is the expected outcome: the option exists, while the matching rows do not. + +The property also accepts a list of plain strings. In this case each string becomes both the id and the label of an option: + +~~~jsx +filterConfig: { options: ["KG", "L", "PCS"] } +~~~ + +#### A function for adjusting options + +Use a function when you want to keep the data-driven list and adjust it: add the options that the data does not contain yet, hide the ones users must never filter by, or reorder the list. + +~~~jsx +// always offers "Liters" on top of whatever the data holds +filterConfig: { + options: uniqueData => uniqueData.concat([{ id: "L", value: "Liters" }]) +} +~~~ + +~~~jsx +// hides the technical "draft" status from the filter +filterConfig: { + options: uniqueData => uniqueData.filter(option => option.id !== "draft") +} +~~~ + +Grid normalizes the list to `{ id, value }` pairs before it calls the function, so `option.id` is always defined and safe to compare. The second argument is the configuration object of the column. + +The function runs whenever Grid recalculates the filter lists: + +- when Grid initializes +- when a data event fires (`load`, `parse`, `add`, `remove`, `update`, `filter`) +- when you call the [`setColumns()`](grid/api/grid_setcolumns_method.md) method +- when you show or hide a column + +A plain [`paint()`](grid/api/grid_paint_method.md) call does not re-evaluate it. + +**Related sample**: [Grid. Custom options of the header filter](https://snippet.dhtmlx.com/pcrjqux0) + +#### Behavior notes + +- **The selected value is never dropped.** An option that no row matches stays selected, and Grid stays empty. A filter does not reset itself when its selected value is absent from the column data. + +- **Cross-filtering.** When several columns are filtered at once, Grid normally narrows the filter lists of the other columns to the values that are still reachable. The two forms of the `options` property differ here: + + - Grid never narrows a static list, since it is a reference list and not a view of the data + - a callback function receives the narrowed list, so its result can reflect what is currently reachable + +- **The full list stays in the dropdown.** When the `options` property is defined, **selectFilter** renders its whole `