Properties Methods Events Config Options Direct Link

    Observable
      GridFilters

# Class Ext.ux.grid.GridFilters

Package: | Ext.ux.grid
Defined In: | GridFilters.js
Class: | GridFilters
Extends: | Observable

GridFilter is a plugin (`ptype='gridfilters'`) for grids that allow for a slightly more robust representation of filtering than what is provided by the default store.

Filtering is adjusted by the user using the grid's column header menu (this menu can be disabled through configuration). Through this menu users can configure, enable, and disable filters for each column.

Features:

- Filtering implementations :
  Default filtering for Strings, Numeric Ranges, Date Ranges, Lists (which can be backed by a Ext.data.Store), and Boolean. Additional custom filter types and menus are easily created by extending Ext.ux.grid.filter.Filter.
- Graphical indicators :
  Columns that are filtered have a configurable css class applied to the column headers.
- Paging :
  If specified as a plugin to the grid's configured PagingToolbar, the current page will be reset to page 1 whenever you update the filters.
- Automatic Reconfiguration :
  Filters automatically reconfigure when the grid 'reconfigure' event fires.
- Stateful : Filter information will be persisted across page loads by specifying a `stateId` in the Grid configuration.
  The filter collection binds to the `beforestaterestore` and `beforestatesave` events in order to be stateful.
- Grid Changes :
  - A `filters` property is added to the grid pointing to this plugin.
  - A `filterupdate` event is added to the grid and is fired upon onStateChange completion.
- Server side code examples :
  - PHP - (Thanks VinylFox)
  - Ruby on Rails - (Thanks Zyclops)
  - Ruby on Rails - (Thanks Rotomaul)
  - Python - (Thanks Matt)
  - Grails - (Thanks Mike)

Example usage:

    var store = new Ext.data.GroupingStore({
        ...
    });

    var filters = new Ext.ux.grid.GridFilters({
        autoReload: false, //don't reload automatically

        local: true, //only filter locally

        // filters may be configured through the plugin,

        // or in the column definition within the column model configuration

        filters: [{
            type: 'numeric',
            dataIndex: 'id'
        }, {
            type: 'string',
            dataIndex: 'name'
        }, {
            type: 'numeric',
            dataIndex: 'price'
        }, {
            type: 'date',
            dataIndex: 'dateAdded'
        }, {
            type: 'list',
            dataIndex: 'size',
            options: ['extra small', 'small', 'medium', 'large', 'extra large'],
            phpMode: true
        }, {
            type: 'boolean',
            dataIndex: 'visible'
        }]
    });
    var cm = new Ext.grid.ColumnModel([{
        ...
    }]);

    var grid = new Ext.grid.GridPanel({
         ds: store,
         cm: cm,
         view: new Ext.grid.GroupingView(),
         plugins: [filters],
         height: 400,
         width: 700,
         bbar: new Ext.PagingToolbar({
             store: store,
             pageSize: 15,
             plugins: [filters] //reset page to page 1 if filters change

         })
     });

    store.load({params: {start: 0, limit: 15}});

    // a filters property is added to the grid

    grid.filters

## Config Options

Config Options | Defined By
--- | ---
| autoReload : Boolean Defaults to true, reloading the datasource when a filter change happens. Set this to false to prevent the datastore ... Defaults to true, reloading the datasource when a filter change happens. Set this to false to prevent the datastore from being reloaded if there are changes to the filters. See `updateBuffer`. | GridFilters
| encode : Boolean Specify true for buildQuery to use Ext.util.JSON.encode to encode the filter query parameter sent with a remote requ... Specify true for buildQuery to use Ext.util.JSON.encode to encode the filter query parameter sent with a remote request. Defaults to false. | GridFilters
| filterCls : String The css class to be applied to column headers with active filters. Defaults to `'ux-filterd-column'`. | GridFilters
| filters : Array An Array of filters config objects. Refer to each filter type class for configuration details specific to each filte... An Array of filters config objects. Refer to each filter type class for configuration details specific to each filter type. Filters for Strings, Numeric Ranges, Date Ranges, Lists, and Boolean are the standard filters available. | GridFilters
| listeners : Object A config object containing one or more event handlers to be added to this object during initialization. This should ... A config object containing one or more event handlers to be added to this object during initialization. This should be a valid listeners config object as specified in the addListener example for attaching multiple handlers at once. DOM events from ExtJs Components While some ExtJs Component classes export selected DOM events (e.g. "click", "mouseover" etc), this is usually only done when extra value can be added. For example the DataView's `click` event passing the node clicked on. To access DOM events directly from a Component's HTMLElement, listeners must be added to the Element after the Component has been rendered. A plugin can simplify this step:
    // Plugin is configured with a listeners config object.
    // The Component is appended to the argument list of all handler functions.
    Ext.DomObserver = Ext.extend(Object, {
        constructor: function(config) {
            this.listeners = config.listeners ? config.listeners : config;
        },

        // Component passes itself into plugin's init method
        init: function(c) {
            var p, l = this.listeners;
            for (p in l) {
                if (Ext.isFunction(l[p])) {
                    l[p] = this.createHandler(l[p], c);
                } else {
                    l[p].fn = this.createHandler(l[p].fn, c);
                }
            }

            // Add the listeners to the Element immediately following the render call
            c.render = c.render.createSequence(function() {
                var e = c.getEl();
                if (e) {
                    e.on(l);
                }
            });
        },

        createHandler: function(fn, c) {
            return function(e) {
                fn.call(this, e, c);
            };
        }
    });

    var combo = new Ext.form.ComboBox({

        // Collapse combo when its element is clicked on
        plugins: [ new Ext.DomObserver({
            click: function(evt, comp) {
                comp.collapse();
            }
        })],
        store: myStore,
        typeAhead: true,
        mode: 'local',
        triggerAction: 'all'
    });
| Observable
| local : Boolean `true` to use Ext.data.Store filter functions (local filtering) instead of the default (`false`) server side filtering. | GridFilters
| menuFilterText : String defaults to `'Filters'`. | GridFilters
| paramPrefix : String The url parameter prefix for the filters. Defaults to `'filter'`. | GridFilters
| showMenu : Boolean Defaults to true, including a filter submenu in the default header menu. | GridFilters
| stateId : String Name of the value to be used to store state information. | GridFilters
| updateBuffer : Integer Number of milliseconds to defer store updates since the last filter change. | GridFilters

## Public Properties

This class has no public properties.

## Public Methods

Method | Defined By
--- | ---
- | addEvents( `Object|String o`, `string Optional.` ) : void Adds the specified events to the list of events which this Observable may fire. Adds the specified events to the list of events which this Observable may fire. Parameters: `o` : Object|String Either an object with event names as properties with a value of `true` or the first event name string if multiple event names are being passed as separate parameters. `Optional.` : string Event name if multiple event names are being passed as separate parameters. Usage:
      this.addEvents('storeloaded', 'storecleared');
Returns: void | Observable
| addFilter( `Object/Ext.ux.grid.filter.Filter config` ) : Ext.ux.grid.filter.Filter Adds a filter to the collection and observes it for state change. Adds a filter to the collection and observes it for state change. Parameters: `config` : Object/Ext.ux.grid.filter.Filter A filter configuration or a filter object. Returns: `Ext.ux.grid.filter.Filter` The existing or newly created filter object. | GridFilters
| addFilters( `Array/Ext.grid.ColumnModel filters` ) : void Adds filters to the collection. Adds filters to the collection. Parameters: `filters` : Array/Ext.grid.ColumnModel Either an Array of filter configuration objects or an Ext.grid.ColumnModel. The columns of a passed Ext.grid.ColumnModel will be examined for a `filter` property and, if present, will be used as the filter configuration object. Returns: void | GridFilters
- | addListener( `String eventName`, `Function handler`, [`Object scope`], [`Object options`] ) : void Appends an event handler to this object. Appends an event handler to this object. Parameters: `eventName` : String The name of the event to listen for. `handler` : Function The method the event invokes. `scope` : Object (optional) The scope (`this` reference) in which the handler function is executed. If omitted, defaults to the object which fired the event. `options` : Object (optional) An object containing handler configuration. properties. This may contain any of the following properties: scope : Object The scope (`this` reference) in which the handler function is executed. If omitted, defaults to the object which fired the event. delay : Number The number of milliseconds to delay the invocation of the handler after the event fires. single : Boolean True to add a handler to handle just the next firing of the event, and then remove itself. buffer : Number Causes the handler to be scheduled to run in an Ext.util.DelayedTask delayed by the specified number of milliseconds. If the event fires again within that time, the original handler is not invoked, but the new handler is scheduled in its place. target : Observable Only call the handler if the event was fired on the target Observable, not if the event was bubbled up from a child Observable. Combining Options Using the options argument, it is possible to combine different types of listeners: A delayed, one-time listener.
      myDataView.on('click', this.onClick, this, {
      single: true,
      delay: 100
      });
  Attaching multiple handlers in 1 call The method also allows for a single argument to be passed which is a config object containing properties which specify multiple handlers.
      myGridPanel.on({
      'click' : {
          fn: this.onClick,
          scope: this,
          delay: 100
      },
      'mouseover' : {
          fn: this.onMouseOver,
          scope: this
      },
      'mouseout' : {
          fn: this.onMouseOut,
          scope: this
      }
      });
  Or a shorthand syntax:
      myGridPanel.on({
      'click' : this.onClick,
      'mouseover' : this.onMouseOver,
      'mouseout' : this.onMouseOut,
       scope: this
      });
Returns: void | Observable
| bindStore( `Store store` ) : void Changes the data store bound to this view and refreshes it. Changes the data store bound to this view and refreshes it. Parameters: `store` : Store The store to bind to this view Returns: void | GridFilters
- | buildQuery( `Array filters` ) : Object Function to take the active filters data and build it into a query. The format of the query depends on the encode c... Function to take the active filters data and build it into a query. The format of the query depends on the `encode` configuration: `false` : Default Flatten into query string of the form (assuming `paramPrefix='filters'`:
      filters[0][field]="someDataIndex"&
      filters[0][data][comparison]="someValue1"&
      filters[0][data][type]="someValue2"&
      filters[0][data][value]="someValue3"&
- `true` : JSON encode the filter data
      filters[0][field]="someDataIndex"&
      filters[0][data][comparison]="someValue1"&
      filters[0][data][type]="someValue2"&
      filters[0][data][value]="someValue3"&
Override this method to customize the format of the filter query for remote requests. Parameters: `filters` : Array A collection of objects representing active filters and their configuration. Each element will take the form of {field: dataIndex, data: filterConf}. dataIndex is not assured to be unique as any one filter may be a composite of more basic filters for the same dataIndex. Returns: `Object` Query keys and values | GridFilters
| cleanParams( `Object p` ) : void Removes filter related query parameters from the provided object. Removes filter related query parameters from the provided object. Parameters: `p` : Object Query parameters that may contain filter related fields. Returns: void | GridFilters
| clearFilters() : void Turns all filters off. This does not clear the configuration information (see removeAll). Turns all filters off. This does not clear the configuration information (see removeAll). Parameters: None. Returns: void | GridFilters
| enableBubble( `Object events` ) : void Enables events fired by this Observable to bubble up an owner hierarchy by calling this.getBubbleTarget() if present... Enables events fired by this Observable to bubble up an owner hierarchy by calling `this.getBubbleTarget()` if present. There is no implementation in the Observable base class. This is commonly used by Ext.Components to bubble events to owner Containers. See Ext.Component.getBubbleTarget. The default implementation in Ext.Component returns the Component's immediate owner. But if a known target is required, this can be overridden to access the required target more quickly. Example:
    Ext.override(Ext.form.Field, {
    //  Add functionality to Field's initComponent to enable the change event to bubble

        initComponent: Ext.form.Field.prototype.initComponent.createSequence(function() {
            this.enableBubble('change');
        }),

    //  We know that we want Field's events to bubble directly to the FormPanel.

        getBubbleTarget: function() {
            if (!this.formPanel) {
                this.formPanel = this.findParentByType('form');
            }
            return this.formPanel;
        }
    });

    var myForm = new Ext.formPanel({
        title: 'User Details',
        items: [{
            ...
        }],
        listeners: {
            change: function() {
    //          Title goes red if form has been modified.

                myForm.header.setStyle("color", "red");
            }
        }
    });
Parameters: `events` : Object The event name to bubble, or an Array of event names. Returns: void | Observable
| fireEvent( `String eventName`, `Object... args` ) : Boolean Fires the specified event with the passed parameters (minus the event name). An event may be set to bubble up an Obse... Fires the specified event with the passed parameters (minus the event name). An event may be set to bubble up an Observable parent hierarchy (See Ext.Component.getBubbleTarget) by calling enableBubble. Parameters: `eventName` : String The name of the event to fire. `args` : Object... Variable number of parameters are passed to handlers. Returns: `Boolean` returns false if any of the handlers return false otherwise it returns true. | Observable
| getFilter( `String dataIndex` ) : Ext.ux.grid.filter.Filter Returns a filter for the given dataIndex, if one exists. Returns a filter for the given dataIndex, if one exists. Parameters: `dataIndex` : String The dataIndex of the desired filter object. Returns: `Ext.ux.grid.filter.Filter` | GridFilters
| getFilterClass( `String type` ) : Class Function for locating filter classes, overwrite this with your favorite loader to provide dynamic filter loading. Function for locating filter classes, overwrite this with your favorite loader to provide dynamic filter loading. Parameters: `type` : String The type of filter to load ('Filter' is automatically appended to the passed type; eg, 'string' becomes 'StringFilter'). Returns: `Class` The Ext.ux.grid.filter.Class | GridFilters
| getFilterData() : Array Returns an Array of the currently active filters. Returns an Array of the currently active filters. Parameters: None. Returns: `Array` filters Array of the currently active filters. | GridFilters
| hasListener( `String eventName` ) : Boolean Checks to see if this object has any listeners for a specified event Checks to see if this object has any listeners for a specified event Parameters: `eventName` : String The name of the event to check for Returns: `Boolean` True if the event is being listened for, else false | Observable
| on( `String eventName`, `Function handler`, [`Object scope`], [`Object options`] ) : void Appends an event handler to this object (shorthand for addListener.) Appends an event handler to this object (shorthand for addListener.) Parameters: `eventName` : String The type of event to listen for `handler` : Function The method the event invokes `scope` : Object (optional) The scope (`this` reference) in which the handler function is executed. If omitted, defaults to the object which fired the event. `options` : Object (optional) An object containing handler configuration. Returns: void | Observable
| purgeListeners() : void Removes all listeners for this object Removes all listeners for this object Parameters: None. Returns: void | Observable
| relayEvents( `Object o`, `Array events` ) : void Relays selected events from the specified Observable as if the events were fired by this. Relays selected events from the specified Observable as if the events were fired by `this`. Parameters: `o` : Object The Observable whose events this object is to relay. `events` : Array Array of event names to relay. Returns: void | Observable
| removeAll() : void Remove all filters, permanently destroying them. Remove all filters, permanently destroying them. Parameters: None. Returns: void | GridFilters
| removeListener( `String eventName`, `Function handler`, [`Object scope`] ) : void Removes an event handler. Removes an event handler. Parameters: `eventName` : String The type of event the handler was associated with. `handler` : Function The handler to remove. This must be a reference to the function passed into the addListener call. `scope` : Object (optional) The scope originally specified for the handler. Returns: void | Observable
| resumeEvents() : void Resume firing events. (see suspendEvents) If events were suspended using the queueSuspended parameter, then all event... Resume firing events. (see suspendEvents) If events were suspended using the `queueSuspended` parameter, then all events fired during event suspension will be sent to any listeners now. Parameters: None. Returns: void | Observable
| saveState( `Object grid`, `Object state` ) : Boolean Saves the state of all active filters Saves the state of all active filters Parameters: `grid` : Object `state` : Object Returns: `Boolean` | GridFilters
| suspendEvents( `Boolean queueSuspended` ) : void Suspend the firing of all events. (see resumeEvents) Suspend the firing of all events. (see resumeEvents) Parameters: `queueSuspended` : Boolean Pass as true to queue up suspended events to be fired after the resumeEvents call instead of discarding all suspended events; Returns: void | Observable
| un( `String eventName`, `Function handler`, [`Object scope`] ) : void Removes an event handler (shorthand for removeListener.) Removes an event handler (shorthand for removeListener.) Parameters: `eventName` : String The type of event the handler was associated with. `handler` : Function The handler to remove. This must be a reference to the function passed into the addListener call. `scope` : Object (optional) The scope originally specified for the handler. Returns: void | Observable
| updateColumnHeadings() : void Update the styles for the header row based on the active filters Update the styles for the header row based on the active filters Parameters: None. Returns: void | GridFilters

## Public Events

This class has no public events.