src/util/Filter.js

   1 /**
   2  * @class Ext.util.Filter
   3  * @extends Object
   4  * <p>Represents a filter that can be applied to a {@link Ext.util.MixedCollection MixedCollection}. Can either simply
   5  * filter on a property/value pair or pass in a filter function with custom logic. Filters are always used in the context
   6  * of MixedCollections, though {@link Ext.data.Store Store}s frequently create them when filtering and searching on their
   7  * records. Example usage:</p>
   8 <pre><code>
   9 //set up a fictional MixedCollection containing a few people to filter on
  10 var allNames = new Ext.util.MixedCollection();
  11 allNames.addAll([
  12     {id: 1, name: 'Ed',    age: 25},
  13     {id: 2, name: 'Jamie', age: 37},
  14     {id: 3, name: 'Abe',   age: 32},
  15     {id: 4, name: 'Aaron', age: 26},
  16     {id: 5, name: 'David', age: 32}
  17 ]);
  18
  19 var ageFilter = new Ext.util.Filter({
  20     property: 'age',
  21     value   : 32
  22 });
  23
  24 var longNameFilter = new Ext.util.Filter({
  25     filterFn: function(item) {
  26         return item.name.length > 4;
  27     }
  28 });
  29
  30 //a new MixedCollection with the 3 names longer than 4 characters
  31 var longNames = allNames.filter(longNameFilter);
  32
  33 //a new MixedCollection with the 2 people of age 24:
  34 var youngFolk = allNames.filter(ageFilter);
  35 </code></pre>
  36  * @constructor
  37  * @param {Object} config Config object
  38  */
  39 Ext.define('Ext.util.Filter', {
  40
  41     /* Begin Definitions */
  42
  43     /* End Definitions */
  44     /**
  45      * @cfg {String} property The property to filter on. Required unless a {@link #filter} is passed
  46      */
  47
  48     /**
  49      * @cfg {Function} filterFn A custom filter function which is passed each item in the {@link Ext.util.MixedCollection}
  50      * in turn. Should return true to accept each item or false to reject it
  51      */
  52
  53     /**
  54      * @cfg {Boolean} anyMatch True to allow any match - no regex start/end line anchors will be added. Defaults to false
  55      */
  56     anyMatch: false,
  57
  58     /**
  59      * @cfg {Boolean} exactMatch True to force exact match (^ and $ characters added to the regex). Defaults to false.
  60      * Ignored if anyMatch is true.
  61      */
  62     exactMatch: false,
  63
  64     /**
  65      * @cfg {Boolean} caseSensitive True to make the regex case sensitive (adds 'i' switch to regex). Defaults to false.
  66      */
  67     caseSensitive: false,
  68
  69     /**
  70      * @cfg {String} root Optional root property. This is mostly useful when filtering a Store, in which case we set the
  71      * root to 'data' to make the filter pull the {@link #property} out of the data object of each item
  72      */
  73
  74     constructor: function(config) {
  75         Ext.apply(this, config);
  76
  77         //we're aliasing filter to filterFn mostly for API cleanliness reasons, despite the fact it dirties the code here.
  78         //Ext.util.Sorter takes a sorterFn property but allows .sort to be called - we do the same here
  79         this.filter = this.filter || this.filterFn;
  80
  81         if (this.filter == undefined) {
  82             if (this.property == undefined || this.value == undefined) {
  83                 // Commented this out temporarily because it stops us using string ids in models. TODO: Remove this once
  84                 // Model has been updated to allow string ids
  85
  86                 // Ext.Error.raise("A Filter requires either a property or a filterFn to be set");
  87             } else {
  88                 this.filter = this.createFilterFn();
  89             }
  90
  91             this.filterFn = this.filter;
  92         }
  93     },
  94
  95     /**
  96      * @private
  97      * Creates a filter function for the configured property/value/anyMatch/caseSensitive options for this Filter
  98      */
  99     createFilterFn: function() {
 100         var me       = this,
 101             matcher  = me.createValueMatcher(),
 102             property = me.property;
 103
 104         return function(item) {
 105             return matcher.test(me.getRoot.call(me, item)[property]);
 106         };
 107     },
 108
 109     /**
 110      * @private
 111      * Returns the root property of the given item, based on the configured {@link #root} property
 112      * @param {Object} item The item
 113      * @return {Object} The root property of the object
 114      */
 115     getRoot: function(item) {
 116         return this.root == undefined ? item : item[this.root];
 117     },
 118
 119     /**
 120      * @private
 121      * Returns a regular expression based on the given value and matching options
 122      */
 123     createValueMatcher : function() {
 124         var me            = this,
 125             value         = me.value,
 126             anyMatch      = me.anyMatch,
 127             exactMatch    = me.exactMatch,
 128             caseSensitive = me.caseSensitive,
 129             escapeRe      = Ext.String.escapeRegex;
 130
 131         if (!value.exec) { // not a regex
 132             value = String(value);
 133
 134             if (anyMatch === true) {
 135                 value = escapeRe(value);
 136             } else {
 137                 value = '^' + escapeRe(value);
 138                 if (exactMatch === true) {
 139                     value += '$';
 140                 }
 141             }
 142             value = new RegExp(value, caseSensitive ? '' : 'i');
 143          }
 144
 145          return value;
 146     }
 147 });