Added matcher example and reworked compat

The matcher example now matches the old matcher example, and the
compatibility module has been turned into a function decorator
instead of a class decorator.

dist/js/select2.amd.full.js

@@ -968,6 +968,7 @@ define('select2/data/select',[
 ], function (BaseAdapter, Utils, $) {
   function SelectAdapter ($element, options) {
     this.$element = $element;
+    this.options = options;
 
     SelectAdapter.__super__.constructor.call(this);
   }
@@ -1143,34 +1144,9 @@ define('select2/data/select',[
   };
 
   SelectAdapter.prototype.matches = function (params, data) {
-    var match = $.extend(true, {}, data);
+    var matcher = this.options.get('matcher');
 
-    if (data.children) {
+    return matcher(params, data);
-      for (var c = data.children.length - 1; c >= 0; c--) {
-        var child = data.children[c];
-
-        var matches = this.matches(params, child);
-
-        // If there wasn't a match, remove the object in the array
-        if (matches === null) {
-          match.children.splice(c, 1);
-        }
-      }
-
-      if (match.children.length > 0) {
-        return match;
-      }
-    }
-
-    if ($.trim(params.term) === '') {
-      return match;
-    }
-
-    if (data.text.toUpperCase().indexOf(params.term.toUpperCase()) > -1) {
-      return match;
-    }
-
-    return null;
   };
 
   return SelectAdapter;
@@ -1660,6 +1636,49 @@ define('select2/i18n/en',[],function () {
   };
 });
 
+define('select2/compat/matcher',[
+
+], function () {
+  function oldMatcher (matcher) {
+    function wrappedMatcher (params, data) {
+      var match = $.extend(true, {}, data);
+
+      if (params.term == null || $.trim(params.term) === '') {
+        return match;
+      }
+
+      if (data.children) {
+        for (var c = data.children.length - 1; c >= 0; c--) {
+          var child = data.children[c];
+
+          // Check if the child object matches
+          // The old matcher returned a boolean true or false
+          var doesMatch = matcher(params.term, child.text, child);
+
+          // If the child didn't match, pop it off
+          if (!doesMatch) {
+            match.children.splice(c, 1);
+          }
+        }
+
+        if (match.children.length > 0) {
+          return match;
+        }
+      }
+
+      if (matcher(params.term, data.text, data)) {
+        return match;
+      }
+
+      return null;
+    }
+
+    return wrappedMatcher;
+  }
+
+  return oldMatcher;
+});
+
 define('select2/defaults',[
   'jquery',
   './results',
@@ -1682,7 +1701,8 @@ define('select2/defaults',[
   './dropdown/hidePlaceholder',
   './dropdown/infiniteScroll',
 
-  './i18n/en'
+  './i18n/en',
+  './compat/matcher'
 ], function ($, ResultsList,
              SingleSelection, MultipleSelection, Placeholder,
              Utils, Translation,
@@ -1791,8 +1811,40 @@ define('select2/defaults',[
   };
 
   Defaults.prototype.reset = function () {
+    function matcher (params, data) {
+      var match = $.extend(true, {}, data);
+
+      if (data.children) {
+        for (var c = data.children.length - 1; c >= 0; c--) {
+          var child = data.children[c];
+
+          var matches = matcher(params, child);
+
+          // If there wasn't a match, remove the object in the array
+          if (matches === null) {
+            match.children.splice(c, 1);
+          }
+        }
+
+        if (match.children.length > 0) {
+          return match;
+        }
+      }
+
+      if ($.trim(params.term) === '') {
+        return match;
+      }
+
+      if (data.text.toUpperCase().indexOf(params.term.toUpperCase()) > -1) {
+        return match;
+      }
+
+      return null;
+    }
+
     this.defaults = {
       language: ['select2/i18n/en'],
+      matcher: matcher,
       minimumInputLength: 0,
       templateResult: function (result) {
         return result.text;

dist/js/select2.amd.js

@@ -968,6 +968,7 @@ define('select2/data/select',[
 ], function (BaseAdapter, Utils, $) {
   function SelectAdapter ($element, options) {
     this.$element = $element;
+    this.options = options;
 
     SelectAdapter.__super__.constructor.call(this);
   }
@@ -1143,34 +1144,9 @@ define('select2/data/select',[
   };
 
   SelectAdapter.prototype.matches = function (params, data) {
-    var match = $.extend(true, {}, data);
+    var matcher = this.options.get('matcher');
 
-    if (data.children) {
+    return matcher(params, data);
-      for (var c = data.children.length - 1; c >= 0; c--) {
-        var child = data.children[c];
-
-        var matches = this.matches(params, child);
-
-        // If there wasn't a match, remove the object in the array
-        if (matches === null) {
-          match.children.splice(c, 1);
-        }
-      }
-
-      if (match.children.length > 0) {
-        return match;
-      }
-    }
-
-    if ($.trim(params.term) === '') {
-      return match;
-    }
-
-    if (data.text.toUpperCase().indexOf(params.term.toUpperCase()) > -1) {
-      return match;
-    }
-
-    return null;
   };
 
   return SelectAdapter;
@@ -1660,6 +1636,49 @@ define('select2/i18n/en',[],function () {
   };
 });
 
+define('select2/compat/matcher',[
+
+], function () {
+  function oldMatcher (matcher) {
+    function wrappedMatcher (params, data) {
+      var match = $.extend(true, {}, data);
+
+      if (params.term == null || $.trim(params.term) === '') {
+        return match;
+      }
+
+      if (data.children) {
+        for (var c = data.children.length - 1; c >= 0; c--) {
+          var child = data.children[c];
+
+          // Check if the child object matches
+          // The old matcher returned a boolean true or false
+          var doesMatch = matcher(params.term, child.text, child);
+
+          // If the child didn't match, pop it off
+          if (!doesMatch) {
+            match.children.splice(c, 1);
+          }
+        }
+
+        if (match.children.length > 0) {
+          return match;
+        }
+      }
+
+      if (matcher(params.term, data.text, data)) {
+        return match;
+      }
+
+      return null;
+    }
+
+    return wrappedMatcher;
+  }
+
+  return oldMatcher;
+});
+
 define('select2/defaults',[
   'jquery',
   './results',
@@ -1682,7 +1701,8 @@ define('select2/defaults',[
   './dropdown/hidePlaceholder',
   './dropdown/infiniteScroll',
 
-  './i18n/en'
+  './i18n/en',
+  './compat/matcher'
 ], function ($, ResultsList,
              SingleSelection, MultipleSelection, Placeholder,
              Utils, Translation,
@@ -1791,8 +1811,40 @@ define('select2/defaults',[
   };
 
   Defaults.prototype.reset = function () {
+    function matcher (params, data) {
+      var match = $.extend(true, {}, data);
+
+      if (data.children) {
+        for (var c = data.children.length - 1; c >= 0; c--) {
+          var child = data.children[c];
+
+          var matches = matcher(params, child);
+
+          // If there wasn't a match, remove the object in the array
+          if (matches === null) {
+            match.children.splice(c, 1);
+          }
+        }
+
+        if (match.children.length > 0) {
+          return match;
+        }
+      }
+
+      if ($.trim(params.term) === '') {
+        return match;
+      }
+
+      if (data.text.toUpperCase().indexOf(params.term.toUpperCase()) > -1) {
+        return match;
+      }
+
+      return null;
+    }
+
     this.defaults = {
       language: ['select2/i18n/en'],
+      matcher: matcher,
       minimumInputLength: 0,
       templateResult: function (result) {
         return result.text;

dist/js/select2.full.js

@@ -10503,6 +10503,7 @@ define('select2/data/select',[
 ], function (BaseAdapter, Utils, $) {
   function SelectAdapter ($element, options) {
     this.$element = $element;
+    this.options = options;
 
     SelectAdapter.__super__.constructor.call(this);
   }
@@ -10678,34 +10679,9 @@ define('select2/data/select',[
   };
 
   SelectAdapter.prototype.matches = function (params, data) {
-    var match = $.extend(true, {}, data);
+    var matcher = this.options.get('matcher');
 
-    if (data.children) {
+    return matcher(params, data);
-      for (var c = data.children.length - 1; c >= 0; c--) {
-        var child = data.children[c];
-
-        var matches = this.matches(params, child);
-
-        // If there wasn't a match, remove the object in the array
-        if (matches === null) {
-          match.children.splice(c, 1);
-        }
-      }
-
-      if (match.children.length > 0) {
-        return match;
-      }
-    }
-
-    if ($.trim(params.term) === '') {
-      return match;
-    }
-
-    if (data.text.toUpperCase().indexOf(params.term.toUpperCase()) > -1) {
-      return match;
-    }
-
-    return null;
   };
 
   return SelectAdapter;
@@ -11195,6 +11171,49 @@ define('select2/i18n/en',[],function () {
   };
 });
 
+define('select2/compat/matcher',[
+
+], function () {
+  function oldMatcher (matcher) {
+    function wrappedMatcher (params, data) {
+      var match = $.extend(true, {}, data);
+
+      if (params.term == null || $.trim(params.term) === '') {
+        return match;
+      }
+
+      if (data.children) {
+        for (var c = data.children.length - 1; c >= 0; c--) {
+          var child = data.children[c];
+
+          // Check if the child object matches
+          // The old matcher returned a boolean true or false
+          var doesMatch = matcher(params.term, child.text, child);
+
+          // If the child didn't match, pop it off
+          if (!doesMatch) {
+            match.children.splice(c, 1);
+          }
+        }
+
+        if (match.children.length > 0) {
+          return match;
+        }
+      }
+
+      if (matcher(params.term, data.text, data)) {
+        return match;
+      }
+
+      return null;
+    }
+
+    return wrappedMatcher;
+  }
+
+  return oldMatcher;
+});
+
 define('select2/defaults',[
   'jquery',
   './results',
@@ -11217,7 +11236,8 @@ define('select2/defaults',[
   './dropdown/hidePlaceholder',
   './dropdown/infiniteScroll',
 
-  './i18n/en'
+  './i18n/en',
+  './compat/matcher'
 ], function ($, ResultsList,
              SingleSelection, MultipleSelection, Placeholder,
              Utils, Translation,
@@ -11326,8 +11346,40 @@ define('select2/defaults',[
   };
 
   Defaults.prototype.reset = function () {
+    function matcher (params, data) {
+      var match = $.extend(true, {}, data);
+
+      if (data.children) {
+        for (var c = data.children.length - 1; c >= 0; c--) {
+          var child = data.children[c];
+
+          var matches = matcher(params, child);
+
+          // If there wasn't a match, remove the object in the array
+          if (matches === null) {
+            match.children.splice(c, 1);
+          }
+        }
+
+        if (match.children.length > 0) {
+          return match;
+        }
+      }
+
+      if ($.trim(params.term) === '') {
+        return match;
+      }
+
+      if (data.text.toUpperCase().indexOf(params.term.toUpperCase()) > -1) {
+        return match;
+      }
+
+      return null;
+    }
+
     this.defaults = {
       language: ['select2/i18n/en'],
+      matcher: matcher,
       minimumInputLength: 0,
       templateResult: function (result) {
         return result.text;

dist/js/select2.js

@@ -1396,6 +1396,7 @@ define('select2/data/select',[
 ], function (BaseAdapter, Utils, $) {
   function SelectAdapter ($element, options) {
     this.$element = $element;
+    this.options = options;
 
     SelectAdapter.__super__.constructor.call(this);
   }
@@ -1571,34 +1572,9 @@ define('select2/data/select',[
   };
 
   SelectAdapter.prototype.matches = function (params, data) {
-    var match = $.extend(true, {}, data);
+    var matcher = this.options.get('matcher');
 
-    if (data.children) {
+    return matcher(params, data);
-      for (var c = data.children.length - 1; c >= 0; c--) {
-        var child = data.children[c];
-
-        var matches = this.matches(params, child);
-
-        // If there wasn't a match, remove the object in the array
-        if (matches === null) {
-          match.children.splice(c, 1);
-        }
-      }
-
-      if (match.children.length > 0) {
-        return match;
-      }
-    }
-
-    if ($.trim(params.term) === '') {
-      return match;
-    }
-
-    if (data.text.toUpperCase().indexOf(params.term.toUpperCase()) > -1) {
-      return match;
-    }
-
-    return null;
   };
 
   return SelectAdapter;
@@ -2088,6 +2064,49 @@ define('select2/i18n/en',[],function () {
   };
 });
 
+define('select2/compat/matcher',[
+
+], function () {
+  function oldMatcher (matcher) {
+    function wrappedMatcher (params, data) {
+      var match = $.extend(true, {}, data);
+
+      if (params.term == null || $.trim(params.term) === '') {
+        return match;
+      }
+
+      if (data.children) {
+        for (var c = data.children.length - 1; c >= 0; c--) {
+          var child = data.children[c];
+
+          // Check if the child object matches
+          // The old matcher returned a boolean true or false
+          var doesMatch = matcher(params.term, child.text, child);
+
+          // If the child didn't match, pop it off
+          if (!doesMatch) {
+            match.children.splice(c, 1);
+          }
+        }
+
+        if (match.children.length > 0) {
+          return match;
+        }
+      }
+
+      if (matcher(params.term, data.text, data)) {
+        return match;
+      }
+
+      return null;
+    }
+
+    return wrappedMatcher;
+  }
+
+  return oldMatcher;
+});
+
 define('select2/defaults',[
   'jquery',
   './results',
@@ -2110,7 +2129,8 @@ define('select2/defaults',[
   './dropdown/hidePlaceholder',
   './dropdown/infiniteScroll',
 
-  './i18n/en'
+  './i18n/en',
+  './compat/matcher'
 ], function ($, ResultsList,
              SingleSelection, MultipleSelection, Placeholder,
              Utils, Translation,
@@ -2219,8 +2239,40 @@ define('select2/defaults',[
   };
 
   Defaults.prototype.reset = function () {
+    function matcher (params, data) {
+      var match = $.extend(true, {}, data);
+
+      if (data.children) {
+        for (var c = data.children.length - 1; c >= 0; c--) {
+          var child = data.children[c];
+
+          var matches = matcher(params, child);
+
+          // If there wasn't a match, remove the object in the array
+          if (matches === null) {
+            match.children.splice(c, 1);
+          }
+        }
+
+        if (match.children.length > 0) {
+          return match;
+        }
+      }
+
+      if ($.trim(params.term) === '') {
+        return match;
+      }
+
+      if (data.text.toUpperCase().indexOf(params.term.toUpperCase()) > -1) {
+        return match;
+      }
+
+      return null;
+    }
+
     this.defaults = {
       language: ['select2/i18n/en'],
+      matcher: matcher,
       minimumInputLength: 0,
       templateResult: function (result) {
         return result.text;

docs/examples.html

@@ -292,6 +292,63 @@ $(".js-example-tags").select2({
     </div>
   </section>
 
+  <section id="matcher" class="row">
+    <div class="col-md-4">
+      <h1>Custom matcher</h1>
+
+      <p>
+        Unlike other dropdowns on this page, this one matches options only if
+        the term appears in the beginning of the string as opposed to anywhere:
+      </p>
+
+      <p>
+        <select class="js-example-matcher-start js-states form-control"></select>
+      </p>
+    </div>
+    <div class="col-md-8">
+      <h2>Example code</h2>
+
+      <pre data-fill-from=".js-code-matcher-start"></pre>
+
+<script type="text/x-example-code" class="js-code-matcher-start">
+function matchStart (params, data) {
+  var match = $.extend(true, {}, data);
+
+  if (data.children) {
+    for (var c = data.children.length - 1; c >= 0; c--) {
+      var child = data.children[c];
+
+      var matches = matchStart(params, child);
+
+      // If there wasn't a match, remove the object in the array
+      if (matches === null) {
+        match.children.splice(c, 1);
+      }
+    }
+
+    if (match.children.length > 0) {
+      return match;
+    }
+  }
+
+  if ($.trim(params.term) === '') {
+    return match;
+  }
+
+  if (data.text.toUpperCase().indexOf(params.term.toUpperCase()) == 0) {
+    return match;
+  }
+
+  return null;
+}
+
+$(".js-example-matcher-start").select2({
+  matcher: matchStart
+})
+</script>
+    </div>
+  </section>
+
   <section id="language" class="row">
     <div class="col-md-4">
       <h1>Multiple languages</h1>
@@ -342,7 +399,8 @@ $(".js-example-language").select2({
     <option value="AZ">Arizona</option>
     <option value="CO">Colorado</option>
     <option value="ID">Idaho</option>
-    <option value="MT">Montana</option><option value="NE">Nebraska</option>
+    <option value="MT">Montana</option>
+    <option value="NE">Nebraska</option>
     <option value="NM">New Mexico</option>
     <option value="ND">North Dakota</option>
     <option value="UT">Utah</option>
@@ -375,12 +433,16 @@ $(".js-example-language").select2({
     <option value="MD">Maryland</option>
     <option value="MA">Massachusetts</option>
     <option value="MI">Michigan</option>
-    <option value="NH">New Hampshire</option><option value="NJ">New Jersey</option>
+    <option value="NH">New Hampshire</option>
+    <option value="NJ">New Jersey</option>
     <option value="NY">New York</option>
     <option value="NC">North Carolina</option>
     <option value="OH">Ohio</option>
-    <option value="PA">Pennsylvania</option><option value="RI">Rhode Island</option><option value="SC">South Carolina</option>
+    <option value="PA">Pennsylvania</option>
-    <option value="VT">Vermont</option><option value="VA">Virginia</option>
+    <option value="RI">Rhode Island</option>
+    <option value="SC">South Carolina</option>
+    <option value="VT">Vermont</option>
+    <option value="VA">Virginia</option>
     <option value="WV">West Virginia</option>
   </optgroup>
 </select>
@@ -406,7 +468,9 @@ $("[data-fill-from]").each(function () {
 
 prettyPrint();
 
-$.fn.select2.amd.require(["select2/core", "select2/utils"], function (Select2, Utils) {
+$.fn.select2.amd.require(
+    ["select2/core", "select2/utils", "select2/compat/matcher"],
+    function (Select2, Utils, oldMatcher) {
   var $basicSingle = $(".js-example-basic-single");
   var $basicMultiple = $(".js-example-basic-multiple");
 
@@ -424,6 +488,8 @@ $.fn.select2.amd.require(["select2/core", "select2/utils"], function (Select2, U
 
   var $tags = $(".js-example-tags");
 
+  var $matcherStart = $('.js-example-matcher-start');
+
   var $language = $(".js-example-language");
 
   $basicSingle.select2();
@@ -498,6 +564,18 @@ $.fn.select2.amd.require(["select2/core", "select2/utils"], function (Select2, U
     tags: true
   });
 
+  function matchStart (term, text) {
+    if (text.toUpperCase().indexOf(term.toUpperCase()) == 0) {
+      return true;
+    }
+
+    return false;
+  }
+
+  $matcherStart.select2({
+    matcher: oldMatcher(matchStart)
+  });
+
   $language.select2({
     language: "en"
   });

src/js/select2/compat/matcher.js

@@ -1,27 +1,21 @@
 define([
 
 ], function () {
-  function OldMatcher (decorated, $element, options) {
+  function oldMatcher (matcher) {
-    decorated.call(this, $element, options);
+    function wrappedMatcher (params, data) {
-
-    this.matcher = options.get('matcher');
-  }
-
-  OldMatcher.prototype.matches = function (decorated, params, data) {
-    // If there is no custom matcher, call the original matcher function
-    if (this.matcher == null) {
-      return decorated.call(params, data);
-    }
-
       var match = $.extend(true, {}, data);
 
+      if (params.term == null || $.trim(params.term) === '') {
+        return match;
+      }
+
       if (data.children) {
         for (var c = data.children.length - 1; c >= 0; c--) {
           var child = data.children[c];
 
           // Check if the child object matches
           // The old matcher returned a boolean true or false
-        var doesMatch = this.matcher(params.term, child.text, child);
+          var doesMatch = matcher(params.term, child.text, child);
 
           // If the child didn't match, pop it off
           if (!doesMatch) {
@@ -34,14 +28,15 @@ define([
         }
       }
 
-    if ($.trim(params.term) === '') {
+      if (matcher(params.term, data.text, data)) {
-      return match;
-    }
-
-    if (this.matcher(params.term, data.text, data)) {
         return match;
       }
 
       return null;
-  };
+    }
+
+    return wrappedMatcher;
+  }
+
+  return oldMatcher;
 });

src/js/select2/data/select.js

@@ -5,6 +5,7 @@ define([
 ], function (BaseAdapter, Utils, $) {
   function SelectAdapter ($element, options) {
     this.$element = $element;
+    this.options = options;
 
     SelectAdapter.__super__.constructor.call(this);
   }
@@ -180,34 +181,9 @@ define([
   };
 
   SelectAdapter.prototype.matches = function (params, data) {
-    var match = $.extend(true, {}, data);
+    var matcher = this.options.get('matcher');
 
-    if (data.children) {
+    return matcher(params, data);
-      for (var c = data.children.length - 1; c >= 0; c--) {
-        var child = data.children[c];
-
-        var matches = this.matches(params, child);
-
-        // If there wasn't a match, remove the object in the array
-        if (matches === null) {
-          match.children.splice(c, 1);
-        }
-      }
-
-      if (match.children.length > 0) {
-        return match;
-      }
-    }
-
-    if ($.trim(params.term) === '') {
-      return match;
-    }
-
-    if (data.text.toUpperCase().indexOf(params.term.toUpperCase()) > -1) {
-      return match;
-    }
-
-    return null;
   };
 
   return SelectAdapter;

src/js/select2/defaults.js

@@ -20,7 +20,8 @@ define([
   './dropdown/hidePlaceholder',
   './dropdown/infiniteScroll',
 
-  './i18n/en'
+  './i18n/en',
+  './compat/matcher'
 ], function ($, ResultsList,
              SingleSelection, MultipleSelection, Placeholder,
              Utils, Translation,
@@ -129,8 +130,40 @@ define([
   };
 
   Defaults.prototype.reset = function () {
+    function matcher (params, data) {
+      var match = $.extend(true, {}, data);
+
+      if (data.children) {
+        for (var c = data.children.length - 1; c >= 0; c--) {
+          var child = data.children[c];
+
+          var matches = matcher(params, child);
+
+          // If there wasn't a match, remove the object in the array
+          if (matches === null) {
+            match.children.splice(c, 1);
+          }
+        }
+
+        if (match.children.length > 0) {
+          return match;
+        }
+      }
+
+      if ($.trim(params.term) === '') {
+        return match;
+      }
+
+      if (data.text.toUpperCase().indexOf(params.term.toUpperCase()) > -1) {
+        return match;
+      }
+
+      return null;
+    }
+
     this.defaults = {
       language: ['select2/i18n/en'],
+      matcher: matcher,
       minimumInputLength: 0,
       templateResult: function (result) {
         return result.text;