docs/source/Filter.html

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