X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/25ef3491bd9ae007ff1fc2b0d7943e6eaaccf775..6746dc89c47ed01b165cc1152533605f97eb8e8d:/docs/source/Filter.html diff --git a/docs/source/Filter.html b/docs/source/Filter.html index 302a1b44..a10c3a2d 100644 --- a/docs/source/Filter.html +++ b/docs/source/Filter.html @@ -1,188 +1,168 @@ +
+Ext.namespace('Ext.ux.grid.filter'); - -/** - * @class Ext.ux.grid.filter.Filter - * @extends Ext.util.Observable - * Abstract base class for filter implementations. - */ -Ext.ux.grid.filter.Filter = Ext.extend(Ext.util.Observable, { - /** - * @cfg {Boolean} active - * Indicates the initial status of the filter (defaults to false). - */ - active : false, - /** - * True if this filter is active. Use setActive() to alter after configuration. - * @type Boolean - * @property active - */ - /** - * @cfg {String} dataIndex - * The {@link Ext.data.Store} dataIndex of the field this filter represents. - * The dataIndex does not actually have to exist in the store. - */ - dataIndex : null, - /** - * The filter configuration menu that will be installed into the filter submenu of a column menu. - * @type Ext.menu.Menu - * @property - */ - menu : null, - /** - * @cfg {Number} updateBuffer - * Number of milliseconds to wait after user interaction to fire an update. Only supported - * by filters: 'list', 'numeric', and 'string'. Defaults to 500. - */ - updateBuffer : 500, - - constructor : function (config) { - Ext.apply(this, config); - - this.addEvents( - /** - * @event activate - * Fires when an inactive filter becomes active - * @param {Ext.ux.grid.filter.Filter} this - */ - 'activate', - /** - * @event deactivate - * Fires when an active filter becomes inactive - * @param {Ext.ux.grid.filter.Filter} this - */ - 'deactivate', - /** - * @event serialize - * Fires after the serialization process. Use this to attach additional parameters to serialization - * data before it is encoded and sent to the server. - * @param {Array/Object} data A map or collection of maps representing the current filter configuration. - * @param {Ext.ux.grid.filter.Filter} filter The filter being serialized. - */ - 'serialize', - /** - * @event update - * Fires when a filter configuration has changed - * @param {Ext.ux.grid.filter.Filter} this The filter object. - */ - 'update' - ); - Ext.ux.grid.filter.Filter.superclass.constructor.call(this); - - this.menu = new Ext.menu.Menu(); - this.init(config); - if(config && config.value){ - this.setValue(config.value); - this.setActive(config.active !== false, true); - delete config.value; - } - }, - - /** - * Destroys this filter by purging any event listeners, and removing any menus. - */ - destroy : function(){ - if (this.menu){ - this.menu.destroy(); - } - this.purgeListeners(); - }, - - /** - * Template method to be implemented by all subclasses that is to - * initialize the filter and install required menu items. - * Defaults to Ext.emptyFn. - */ - init : Ext.emptyFn, - - /** - * Template method to be implemented by all subclasses that is to - * get and return the value of the filter. - * Defaults to Ext.emptyFn. - * @return {Object} The 'serialized' form of this filter - * @methodOf Ext.ux.grid.filter.Filter - */ - getValue : Ext.emptyFn, - - /** - * Template method to be implemented by all subclasses that is to - * set the value of the filter and fire the 'update' event. - * Defaults to Ext.emptyFn. - * @param {Object} data The value to set the filter - * @methodOf Ext.ux.grid.filter.Filter - */ - setValue : Ext.emptyFn, - - /** - * Template method to be implemented by all subclasses that is to - * return true if the filter has enough configuration information to be activated. - * Defaults to return true. - * @return {Boolean} - */ - isActivatable : function(){ - return true; - }, - - /** - * Template method to be implemented by all subclasses that is to - * get and return serialized filter data for transmission to the server. - * Defaults to Ext.emptyFn. - */ - getSerialArgs : Ext.emptyFn, - - /** - * Template method to be implemented by all subclasses that is to - * validates the provided Ext.data.Record against the filters configuration. - * Defaults to return true. - * @param {Ext.data.Record} record The record to validate - * @return {Boolean} true if the record is valid within the bounds - * of the filter, false otherwise. - */ - validateRecord : function(){ - return true; - }, - - /** - * Returns the serialized filter data for transmission to the server - * and fires the 'serialize' event. - * @return {Object/Array} An object or collection of objects containing - * key value pairs representing the current configuration of the filter. - * @methodOf Ext.ux.grid.filter.Filter - */ - serialize : function(){ - var args = this.getSerialArgs(); - this.fireEvent('serialize', args, this); - return args; - }, - - /** @private */ - fireUpdate : function(){ - if (this.active) { - this.fireEvent('update', this); - } - this.setActive(this.isActivatable()); - }, - - /** - * Sets the status of the filter and fires the appropriate events. - * @param {Boolean} active The new filter state. - * @param {Boolean} suppressEvent True to prevent events from being fired. - * @methodOf Ext.ux.grid.filter.Filter - */ - setActive : function(active, suppressEvent){ - if(this.active != active){ - this.active = active; - if (suppressEvent !== true) { - this.fireEvent(active ? 'activate' : 'deactivate', this); - } - } - } + +/** + * @class Ext.util.Filter + * @extends Object + * <p>Represents a filter that can be applied to a {@link Ext.util.MixedCollection MixedCollection}. Can either simply + * filter on a property/value pair or pass in a filter function with custom logic. Filters are always used in the context + * of MixedCollections, though {@link Ext.data.Store Store}s frequently create them when filtering and searching on their + * records. Example usage:</p> +<pre><code> +//set up a fictional MixedCollection containing a few people to filter on +var allNames = new Ext.util.MixedCollection(); +allNames.addAll([ + {id: 1, name: 'Ed', age: 25}, + {id: 2, name: 'Jamie', age: 37}, + {id: 3, name: 'Abe', age: 32}, + {id: 4, name: 'Aaron', age: 26}, + {id: 5, name: 'David', age: 32} +]); + +var ageFilter = new Ext.util.Filter({ + property: 'age', + value : 32 +}); + +var longNameFilter = new Ext.util.Filter({ + filterFn: function(item) { + return item.name.length > 4; + } +}); + +//a new MixedCollection with the 3 names longer than 4 characters +var longNames = allNames.filter(longNameFilter); + +//a new MixedCollection with the 2 people of age 24: +var youngFolk = allNames.filter(ageFilter); +</code></pre> + */ +Ext.define('Ext.util.Filter', { + + /* Begin Definitions */ + + /* End Definitions */ + /** + * @cfg {String} property The property to filter on. Required unless a {@link #filterFn} is passed + */ + + /** + * @cfg {Function} filterFn A custom filter function which is passed each item in the {@link Ext.util.MixedCollection} + * in turn. Should return true to accept each item or false to reject it + */ + + /** + * @cfg {Boolean} anyMatch True to allow any match - no regex start/end line anchors will be added. Defaults to false + */ + anyMatch: false, + + /** + * @cfg {Boolean} exactMatch True to force exact match (^ and $ characters added to the regex). Defaults to false. + * Ignored if anyMatch is true. + */ + exactMatch: false, + + /** + * @cfg {Boolean} caseSensitive True to make the regex case sensitive (adds 'i' switch to regex). Defaults to false. + */ + caseSensitive: false, + + /** + * @cfg {String} root Optional root property. This is mostly useful when filtering a Store, in which case we set the + * root to 'data' to make the filter pull the {@link #property} out of the data object of each item + */ + + /** + * Creates new Filter. + * @param {Object} config (optional) Config object + */ + constructor: function(config) { + Ext.apply(this, config); + + //we're aliasing filter to filterFn mostly for API cleanliness reasons, despite the fact it dirties the code here. + //Ext.util.Sorter takes a sorterFn property but allows .sort to be called - we do the same here + this.filter = this.filter || this.filterFn; + + if (this.filter == undefined) { + if (this.property == undefined || this.value == undefined) { + // Commented this out temporarily because it stops us using string ids in models. TODO: Remove this once + // Model has been updated to allow string ids + + // Ext.Error.raise("A Filter requires either a property or a filterFn to be set"); + } else { + this.filter = this.createFilterFn(); + } + + this.filterFn = this.filter; + } + }, + + /** + * @private + * Creates a filter function for the configured property/value/anyMatch/caseSensitive options for this Filter + */ + createFilterFn: function() { + var me = this, + matcher = me.createValueMatcher(), + property = me.property; + + return function(item) { + return matcher.test(me.getRoot.call(me, item)[property]); + }; + }, + + /** + * @private + * Returns the root property of the given item, based on the configured {@link #root} property + * @param {Object} item The item + * @return {Object} The root property of the object + */ + getRoot: function(item) { + return this.root == undefined ? item : item[this.root]; + }, + + /** + * @private + * Returns a regular expression based on the given value and matching options + */ + createValueMatcher : function() { + var me = this, + value = me.value, + anyMatch = me.anyMatch, + exactMatch = me.exactMatch, + caseSensitive = me.caseSensitive, + escapeRe = Ext.String.escapeRegex; + + if (!value.exec) { // not a regex + value = String(value); + + if (anyMatch === true) { + value = escapeRe(value); + } else { + value = '^' + escapeRe(value); + if (exactMatch === true) { + value += '$'; + } + } + value = new RegExp(value, caseSensitive ? '' : 'i'); + } + + return value; + } });- \ No newline at end of file +