Grid header filter custom options: DHX-5218

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:
         </tr>
         <tr>
             <td><a href="../../../configuration/#headerfooter-filters"><b>filterConfig</b></a></td>
-            <td>(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: <br><br> - a configuration object for <b>"inputFilter"</b> can contain the following properties: <ul><li><b>placeholder</b> - (optional) the placeholder text in the input field</li><li><b> icon</b> - (optional) the CSS class for the filter icon</li></ul> <br> - a configuration object for <b>"comboFilter"</b> can contain a set of properties:<ul><li><b>filter</b> - (optional) sets a custom function for filtering Combo Box options</li><li><b>multiselection</b> - (optional) enables selection of multiple options, *false* by default</li><li><b>readonly</b> - (optional) makes ComboBox readonly (it is only possible to select options from the list, without entering words in the input). The default value of the <b>readonly</b> property depends on the following conditions:<ul><li>the `readonly:true` is set as a default value, if `htmlEnable:true` is set for a column and there is no template specified for a column</li><li>in all other cases, `readonly:false` is set by default</li></ul></li><li><b>placeholder</b> - (optional) sets a placeholder in the input of ComboBox</li><li><b>virtual</b> - (optional) enables dynamic loading of data on scrolling the list of options, <i>true</i> by default</li><li><b>template</b> - (optional) a function which returns a template with content for the filter options. Takes an option item as a parameter:<ul><li><b>item</b> - (object) an option item</li></ul></li></ul> - a configuration object for <b>"dateFilter" (PRO version)</b> can contain a set of properties:<br>Main properties:<ul><li><b>icon</b> - (optional) the CSS class for the calendar icon</li><li><b>placeholder</b> - (optional) the placeholder text in the input field when no date is selected</li><li><b>asDateObject</b> - (optional) determines how the filter processes data for `customFilter` and the `beforeFilter` and `filterChange` events. If *true*, the comparison is performed using Date objects, *false* by default</li><li><b>range</b> - (optional) enables the date range selection mode (from and to), *false* by default</li><li><b>dateFormat</b> - (optional) the date display format (e.g., *"%d/%m/%Y"*). By default, applies the `dateFormat` used for the column</li></ul>Calendar API configuration properties:<ul><li><b>date</b> - (optional) - the initial date opened in the calendar</li><li><b>mark</b> - (optional) - a function for adding custom CSS classes to specific dates </li><li><b>disabledDates</b> - (optional) - a function for disabling the selection of specific dates </li><li><b>weekStart</b> - (optional) - the start day of the week (*"saturday"*, *"sunday"* (default), *"monday"*).</li><li><b>weekNumbers</b> - (optional) - shows week numbers if *true*, *false* by default</li><li><b>mode</b> - (optional) - the calendar display mode (*"calendar"* (default), *"year"*, *"month"*, *"timepicker"*)</li><li><b>timePicker</b> - (optional) - adds the ability to select time, *false* by default</li><li><b>timeFormat</b> - (optional) - the time format (*12* or *24* (default) hours)</li><li><b>thisMonthOnly</b> - (optional) - if *true*, allows selecting dates only within the current month, *false* by default</li><li><b>width</b> - (optional) - the width of the dropdown calendar, *"250px"* by default</li></ul></td>
+            <td>(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: <br><br> - a configuration object for <b>"inputFilter"</b> can contain the following properties: <ul><li><b>placeholder</b> - (optional) the placeholder text in the input field</li><li><b> icon</b> - (optional) the CSS class for the filter icon</li></ul> <br> - a configuration object for <b>"selectFilter"</b> can contain the following property:<ul><li><a href="../../../configuration/#custom-options-of-headerfooter-filters"><b>options</b></a> - (optional) sets the list of the filter options manually instead of building it from the column data. Can be set in one of the following ways:<ul><li>as an array of options, either <code>&#123; id, value &#125;</code> objects or plain strings (a string becomes both the id and the label of an option). Such a list fully replaces the data-driven one, and Grid does not scan the dataset for this column</li><li>as a callback function which receives the data-driven list, already normalized to <code>&#123; id, value &#125;</code> pairs, and the configuration object of the column, and returns the list of options to show</li></ul>An option object has two properties:<ul><li><b>id</b> - the value stored in the cell. This is what the filter compares against, and what <b>customFilter</b> receives as its <b>match</b> parameter. It must match the stored value, not the formatted one: in a column with <i>type: "number"</i> and a <b>numberMask</b>, the cell holds <i>1000</i> while Grid displays <i>1,000</i>, so the option <b>id</b> must be <i>1000</i></li><li><b>value</b> - the label shown in the dropdown</li></ul>If the property is omitted, Grid builds the list from the column data</li></ul> <br> - a configuration object for <b>"comboFilter"</b> can contain a set of properties:<ul><li><b>filter</b> - (optional) sets a custom function for filtering Combo Box options</li><li><b>multiselection</b> - (optional) enables selection of multiple options, *false* by default</li><li><b>readonly</b> - (optional) makes ComboBox readonly (it is only possible to select options from the list, without entering words in the input). The default value of the <b>readonly</b> property depends on the following conditions:<ul><li>the `readonly:true` is set as a default value, if `htmlEnable:true` is set for a column and there is no template specified for a column</li><li>in all other cases, `readonly:false` is set by default</li></ul></li><li><b>placeholder</b> - (optional) sets a placeholder in the input of ComboBox</li><li><b>virtual</b> - (optional) enables dynamic loading of data on scrolling the list of options, <i>true</i> by default</li><li><b>template</b> - (optional) a function which returns a template with content for the filter options. Takes an option item as a parameter:<ul><li><b>item</b> - (object) an option item</li></ul></li><li><a href="../../../configuration/#custom-options-of-headerfooter-filters"><b>options</b></a> - (optional) sets the list of the filter options manually instead of building it from the column data, the same as the <b>options</b> property of the <b>"selectFilter"</b> configuration described above</li></ul> - a configuration object for <b>"dateFilter" (PRO version)</b> can contain a set of properties:<br>Main properties:<ul><li><b>icon</b> - (optional) the CSS class for the calendar icon</li><li><b>placeholder</b> - (optional) the placeholder text in the input field when no date is selected</li><li><b>asDateObject</b> - (optional) determines how the filter processes data for `customFilter` and the `beforeFilter` and `filterChange` events. If *true*, the comparison is performed using Date objects, *false* by default</li><li><b>range</b> - (optional) enables the date range selection mode (from and to), *false* by default</li><li><b>dateFormat</b> - (optional) the date display format (e.g., *"%d/%m/%Y"*). By default, applies the `dateFormat` used for the column</li></ul>Calendar API configuration properties:<ul><li><b>date</b> - (optional) - the initial date opened in the calendar</li><li><b>mark</b> - (optional) - a function for adding custom CSS classes to specific dates </li><li><b>disabledDates</b> - (optional) - a function for disabling the selection of specific dates </li><li><b>weekStart</b> - (optional) - the start day of the week (*"saturday"*, *"sunday"* (default), *"monday"*).</li><li><b>weekNumbers</b> - (optional) - shows week numbers if *true*, *false* by default</li><li><b>mode</b> - (optional) - the calendar display mode (*"calendar"* (default), *"year"*, *"month"*, *"timepicker"*)</li><li><b>timePicker</b> - (optional) - adds the ability to select time, *false* by default</li><li><b>timeFormat</b> - (optional) - the time format (*12* or *24* (default) hours)</li><li><b>thisMonthOnly</b> - (optional) - if *true*, allows selecting dates only within the current month, *false* by default</li><li><b>width</b> - (optional) - the width of the dropdown calendar, *"250px"* by default</li></ul></td>
         </tr>
         <tr>
             <td><a href="../../../configuration/#customizing-headerfooter-filters"><b>customFilter</b></a> </td><td>(optional) a callback function that allows defining custom filtering logic. It takes two parameters:<ul><li><b>value</b> - (required) the cell value in the row</li><li> <b>match</b> - (required) the value selected in the filter</li></ul>and returns *true*, if the row matches the filtering criteria, otherwise *false*</td>

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 `<select>` list even while a value is selected, so users can switch straight to another option.
+
+- **Interaction with `customFilter`.** The [`customFilter`](#customizing-headerfooter-filters) function takes precedence over the built-in matching and receives `option.id` as its `match` argument:
+
+    ~~~jsx
+    {
+        content: "selectFilter",
+        filterConfig: { options: [{ id: "L", value: "Liters" }] },
+        customFilter: (cellValue, match) => cellValue === match // match === "L"
+    }
+    ~~~
+
+- **Columns without `options`.** A column that does not define the `options` property builds its filter list from the data, narrows it on cross-filtering, and reports the displayed text as the filter value.
+
 ### Customizing header/footer filters
 
 To add a custom function with your you own logic for the filter of a Grid column, you need to set the `customFilter` attribute when configuring the header/footer content of the [column](grid/api/api_gridcolumn_properties.md).