Docs

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 buttons will appear on each head cell to make each column filterable.

Click the button to open up a menu to specify filter conditions to apply to the grid.

Top

Additional Filter Settings

The default filter is set up to apply a filter condition through the menu. For more menu filtering options, check our the Filtering Advanced Docs.

Additionally, the grid supports inline filtering. Enable this by setting filter to "inline". This will include filter fields under each head cell.

Or enable both menu and inline filter by setting filter to "both".

Top

Filter Type

Defining <zg-column> types will adjust the filter to the corresponding input type. Usually, the default column type is text.

For example, setting [type="select"] on the "Genre" column updates the inline filter with a dropdown list of filtering options.

Another example is setting [type="number"] on the "Year" column. The filter menu will now include filter conditions specifically for number types:

  • Greater Than
  • Greater Than or Equal To
  • Less Than
  • Less Than or Equal To
  • Between
  • Not Between
<zg-colgroup>
  <!-- default type is text -->
  <zg-column index="title"></zg-column>
  <!-- define number type to display number-related filter conditions -->
  <zg-column index="year" type="number" type-number-formatting="disabled"></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

Define Column Filter

Filters can be set at the column level. An additional filter option supported is "disabled" ([filter="menu" | "inline" | "both" | "disabled"]).

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, filter is set depending on the type of the column. To set to a different built-in filter, set filterer to one of the supported options:

  • boolean
  • number
  • select
  • text (default)
<zing-grid filter="both">
  <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 and you want to only filter by one of these indices, use filter-index to specify which index to filter by.

By default, the column is filtered by the rendered cell value. Below, the example is set to filter by the "last" 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 Inline Filter Key

When inline filtering 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="inline" 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

Specifying Menu Filter Key

When server-side filtering through the menu, the filter key is also set to the index value by default.

For example, filtering in the "name" column results in the filter object to be:

{
  name: {
    "conditionals": [ ... ]
  }
}

The filter-key attribute can be used to specify the keys of the filter object:

{
  'name-key': {
    "conditionals": [ ... ]
  }
}

Below is an example of server-side filtering through the menu when setting filter-key.

<zing-grid filter="both" filter-menu-areas="both">
    <zg-colgroup>
      <zg-column index="id" filter-key="id-key"></zg-column>
      <zg-column index="name" filter-key="name-key"></zg-column>
      <zg-column index="job" filter-key="name-job"></zg-column>
    </zg-colgroup>
    <zg-data>
      <zg-param name="src" value="https://zingsoft-filter-function.glitch.me//api"/zg-param>
      <zg-param name="loadByPage" value="true"></zg-param>
      <zg-param name="serverFilter" value="true"></zg-param>
      <zg-param name="filterFunction" value="createFilterURL"></zg-param>
    </zg-data>
  </zing-grid>
function createFilterURL(oFilter) {
  console.log(oFilter);
  return `?filter=${encodeURIComponent(JSON.stringify(oFilter))}`;
};
Top

Inline Filterer Object

The inline filterer object is used to override the default inline 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 inline 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. By default, the "keyup" event triggers filtering.

Because the custom inline filterer object is very similar to the default inline 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 apply inline filtering to the grid from an external input.

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

Additionally, the same can be done through filterMenuColumn() to dynamically apply filter conditionals or selectbox options to the grid.

const zgRef = document.querySelector('zing-grid');
zgRef.filterMenuColumn('columnIndex', {
  // By conditions
  conditionals: [{
    condition: 'contains',
    val1: 'Bender'
    // val2: n/a (only applies for conditions that accepts two values)
  }],

  // By selectbox options
  // selectItems: ['Bender Bending Rodriguez'],

  // Indicate to match case
  // matchCase: true,
  
  // Indicate how to filter multiple conditions (default is 'and')
  // boolean: 'or',
});

To reset filter, use the resetFilter method. This method could also be applied to a specified column.

const zgRef = document.querySelector('zing-grid');
zgRef.resetFilter('fieldIndex');  // Specify column by field index, or reset all column by leaving blank

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]