Filtering

Easily enable filtering on your grid by setting the filter attribute on your <zing-grid> tag.

Default Filter Settings

Once you add the filter attribute, filter fields will appear under each head cell to make each column filterable.

Top

Filter Type

Defining <zg-column> types will adjust the filter to the corresponding input type. For example, setting [type="select"] will create a dropdown list with filtering options:

<zg-colgroup>
  <!-- default type is text -->
  <zg-column index="title"></zg-column>
  <!-- define a select dropdown as a filter -->
  <zg-column
    index="genre"
    type="select"
    type-select-options="Crime, Drama, Romance, Sci-Fi, Western, Mystery Thriller">
  </zg-column>
</zg-colgroup>
Top

Remove Column Filter

You can remove a column filter by defining the [filter="disabled"] attribute on specific columns, like so:

<zg-column filter="disabled"></zg-column>
Top

Built-in Filter Options

By default, the filter is set depending on the type of the column. To set to a different built-in filter, set filterer to of the available options:

  • boolean
  • number
  • select
  • text (default)
<zing-grid filter>
  <zg-colgroup>
    <zg-column index="inStock" filterer="boolean"></zg-column>
    <zg-column index="item" filterer="select"></zg-column>
    <zg-column index="color"></zg-column>
    <zg-column index="size" ></zg-column>
    <zg-column index="price" filterer="number" type="currency" type-currency="USD"></zg-column>
  </zg-colgroup>
  ...
</zing-grid>
Top

Specifying Filter Index

When index is set to multiple fields, use filter-index to specify which field (or index) to filter by.

By default, the column is filtered by the first listed index.

<zing-grid id="htmlGrid" caption="filterIndex demo" filter>
  <zg-colgroup>
    <zg-column index="last,first" _filter-index="last">
      [[index.first]] - [[index.last]]
    </zg-column>
    <zg-column index="last"></zg-column>
    <zg-column index="number"></zg-column>
  </zg-colgroup>
  ...
</zing-grid>
Top

Specifying Filter Key

When filter is done in the server-side, the filter key is set to the index value by default.

For example, filtering in the "name" column results in the filter request to https://www.your_domain.com?name=filterTerm.

The filter-key attribute can be used to specify the key for server-side filtering: https://www.your_domain.com?filterKey=filterTerm

Therefore in the example below, the "species" column sends a filter request to https://www.your_domain.com?excludeMain=filterTerm.

<zing-grid filter sort pager>
  <zg-colgroup>
    <zg-column index="name"></zg-column>
    <zg-column index="species" filter-key="excludeMain"></zg-column>
  </zg-colgroup>
  <zg-data>
    <zg-param name="src" value="https://zgdemo-filter.glitch.me/api"></zg-param>
    <zg-param name="loadByPage" value="true"></zg-param>
    <zg-param name="recordPath" value="data"></zg-param>
    <zg-param name="serverFilter" value="true"></zg-param>
  </zg-data>
</zing-grid>
Top

Filterer Object

The filterer object is used to override the default filter behavior. Set filterer to the name of your filterer object, which can set all or part of the properties.

The full custom filterer object to only allow letters in filter term:

let customFilter = {
  init(oDOMFilter) {
    let oDOMInput = document.createElement('input');
    oDOMInput.type = 'text';
    oDOMInput.autoComplete = 'off';
    oDOMInput.ariaInvalid = false;
    oDOMInput.style.width = '1px';
oDOMFilter.appendChild(oDOMInput);
return oDOMInput;

}, afterInit(oDOMFilter) { let oDOMInput = oDOMFilter.querySelector('input'); oDOMInput.addEventListener('keypress', (e) => { let char = e.key; if (!/^[a-z]$/i.test(char)) { e.preventDefault(); }; }); }, value(oDOMFilter) { let oDOMInput = oDOMFilter.querySelector('input'); return oDOMInput.value; }, setValue(sValue, oDOMFilter) { let oDOMInput = oDOMFilter.querySelector('input'); oDOMInput.value = sValue; }, triggerEvent: 'keyup', };

Going into detail for each of the filterer object properties:

  • init: Initializes by creating the filter input element, setting the input's properties, and appending it to the current column's ZGFilter element.
  • afterInit: After initializing, the filter input is updated to only allow letters in filter term.
  • value: Returns the filter term. By default, the filter term is found in the current column's ZGFilter input element.
  • setValue: Specifies which input to set the value of. By default, it is the current column's ZGFilter input element.
  • triggerEvent: Event that triggers the filter. Default default, the "keyup" event triggers filtering.

Because the custom filterer object is very similar to the default filterer, the object can be simplified to only override the "afterInit" property:

let customFilter = { 
  afterInit(oDOMFilter) {
    let oDOMInput = oDOMFilter.querySelector('input');
    oDOMInput.addEventListener('keypress', (e) => {
      let char = e.key;
      if (!/^[a-z]$/i.test(char)) {
        e.preventDefault();
      };
    });
  }
};
Top

External Input

You can use an external input and our API method filterColumn('...') (see below) to dynamically search the grid from an external input.

const zgRef = document.querySelector('zing-grid');
zgRef.filterColumn('columnIndex', 'columnFilterValue');

The following API methods can dynamically get or set filter on the grid:

  • getFilter()
  • setFilter()
Top

Related Resources

Here are some extra resources related to this feature to help with creating your grid:

[features: filtering]