Filtering Advanced
ZingGrid's built-in filter menu has many capabilities that can be customized.
First, easily enable filtering on your grid by setting the filter attribute on your <zing-grid> tag and filter buttons will appear on each head cell to make each column filterable.
For more information about the filtering feature, check out the Filtering Docs.
Otherwise, continue below to learn how to customize the filter menu capabilities.
Filter Menu Buttons
When clicking the filter buttons, a filter menu appears. The default buttons displayed are "reset" and "apply".
To change which buttons are displayed or in what ordering, set filter-buttons to a comma separated list of buttons.
The buttons options are:
- close: Closes the filter menu
- reset: Resets filter applied through the menu (this includes filtering through conditions and selectbox options, but excludes inline)
- apply: Applies the filters applied through the menu (conditions and selectbox options)
For example, the code below will yield a filter menu with buttons in the exact order: reset, close, apply.
<zing-grid filter filter-buttons="reset, close, apply"> ... </zing-grid>
Customizing List of Conditions
The filter menu provides a dropdown of conditions to apply to the column. Each column type has its own default list of conditions.
The filter-conditions attribute accepts a comma separated list of conditions to customize which conditions to display.
Depending on which tag the attribute is defined, the conditions can be set at the grid or column level.
Below are the list of options accepted by filter-conditions.
The table below lists which column types supports the condition and a description of what the condition does.
| Condition | Type | Description |
|---|---|---|
| default | * | Includes a set of built-in conditions which varies depending on the column type |
| break | * | Displays a horizontal separator |
| none | * | Does not apply any conditions |
| empty | * | Filters for empty / null values |
| nonEmpty | * | Filters out empty /null values |
| equals | date, iframe, number, select, text | Filters for exact term |
| notEquals | date, iframe, number, select, text | Filters for values that is not the exact term |
| beginsWith | iframe, select, text | Filters for values that begins with term |
| endsWith | iframe, select, text | Filters for values ending with term |
| contains | date, iframe, number, select, text | Filters for values containing the term |
| notContains | date, iframe, number, select, text | Filters for values not containing the term |
| between | number | Filters for values between the two terms |
| notBetween | number | Filters for values not between the two terms |
| greaterThan | number | Filters for values greater than the term |
| greaterEqualThan | number | Filters for values greater than or equal to term |
| lessThan | number | Filters for values less than the term |
| lessEqualThan | number | Filters for values less than or equal to term |
| before | date | Filters for values before term |
| after | date | Filters for values after term |
| betweenDate | date | Filters values between the terms |
| today | date | Filters for values matching today's date |
| yesterday | date | Filters for values matching yesterday's date |
| tomorrow | date | Filters for values matching tomorrow's date |
| trueVal | boolean | Filters for true values |
| falseVal | boolean | Filters for false values |
| custom filter name | * | Filters by your custom condition (Example below) |
Below is an example that customizes which conditions to display, including a custom condition.
<zing-grid filter filter-conditions="none, contains, break, custom"> ... </zing-grid>
// Define custom condition let conditionObj = { // Condition label title: "Is Shirt", // Number between 0 and 2 of text fields to display fieldCount: 0, /** * Method that is called when filter is applied * @param {object} obj - Data being filtered * @param {*} obj.dataVal - Value of grid's data * @param {*} [obj.val1] - Value in first text field, if present * @param {*} [obj.val2] - Value in second text field, if present * @returns {boolean} True to display data in results */ filterMethod: (obj) => { return obj && obj.dataVal && obj.dataVal === 'shirt'; }, }; // Register condition to use in grid ZingGrid.registerCustomFilterMethod('custom', conditionObj);
Max Conditions
The maximum default number of conditions that can be applied to the column is one.
This can be easily changed through the filter-conditions-max attribute.
Initially, one condition is displayed. After the latest condition is changed, the next condition displays. To change the number of conditions to initially display, go on to the next section.
In the example below, the maximum number of conditions is increased to five.
<zing-grid filter filter-conditions-max=5> ... </zing-grid>
Number of Conditions to Display
The default behavior of the filter menu is to display a single condition.
The filter menu can be customized to display a specified number of conditions through the filter-conditions-display attribute.
The number specified in filter-conditions-display should be less than or equal to filter-conditions-max.
The filter-conditions-max attribute defines the maximum number of conditions that can be applied to the column.
<zing-grid filter filter-conditions-max=3 filter-conditions-display=2> ... </zing-grid>
Default Condition
When filtering through conditions, the default condition displayed is either "contains" or "none" (depending on column type).
You can change the default condition with filter-default-condition.
For a list of conditions to set the attribute, refer to the table in the "Customizing List of Conditions" section
<zing-grid filter filter-default-condition="equals"> ... </zing-grid>
Menu Filter Options
Filtering by conditions is not the only option. By default, the filter menu only displays a "conditions" area.
You can filter by selectbox options, which creates a checkbox option for each unqiue value in the column.
Enable this by setting filter-menu-areas="selectbox".
The filter menu is not limited to one filtering option.
You can have both by updating filter-menu-areas to "both".
<zing-grid filter filter-menu-areas="both"> ... </zing-grid>
Filter On
When filtering, the filter comparison can be applied to the column's raw or rendered values. The default behavior varies depending on the column type.
If the default behavior does not meet your needs, use filter-on to specify which filter comparison to apply ("raw" or "rendered").
Column type restrictions:
- iframe filters only by raw values
- aggregate filters only by rendered values
<zing-grid filter filter-on="rendered"> <zg-colgroup> <zg-column index="item,color,size" header="Rendered item names" renderer="renderItemName"></zg-column> ... </zg-colgroup> ... </zing-grid>
Selectbox Labels
Instead of filtering by conditions, the filter menu can also filter through selectbox options.
Display selectbox options by setting filter-menu-areas="selectbox" | "both".
Depending on the column situation, either the raw or rendered values are displayed as the selectbox labels.
In the example below, a renderer is applied to the column.
For the selectbox options to match the cell values displayed, filter-selectbox-display is set to "rendered".
<zing-grid filter filter-menu-areas="both" filter-selectbox-display="rendered"> <zg-colgroup> <zg-column index="item,color,size" header="Rendered item names" renderer="renderItemName"></zg-column> ... </zg-colgroup> ... </zing-grid>
Filter Trigger
The default behavior is to apply the filters from the menu when the "Apply" button is clicked.
This can be altered by setting the filter-trigger attribute.
The menu filter can be triggered either by "button" or "change".
When filter is triggered by "change", filter menu buttons are removed. Filter will apply under the two conditions:
- condition text fields changes
- selecbox options changes
<zing-grid filter filter-trigger="change"> ... </zing-grid>
Related Resources
Here are some extra resources related to this feature to help with creating your grid:
[features: filtering advanced]