Add back closeOnSelect option

The `closeOnSelect` option was previously used to control whether
or not the dropdown was closed when an option was selected.  This
could be simulated by triggering the `open` event after the `close`
event was received, but it makes sense to abstract it out into a
decorator.

This also adds support for not closing the dropdown when the control
key is being held.  This is useful when multiple options need to be
selected in quick succession, so the dropdown does not have to be
reopened.

This also adds documentation that covers both changes.

This closes https://github.com/select2/select2/pull/2735.
This closes https://github.com/select2/select2/issues/3017.

dist/js/select2.amd.full.js

@@ -3104,26 +3104,6 @@ define('select2/dropdown',[
     this.$dropdown.remove();
   };
 
-  Dropdown.prototype.bind = function (container, $container) {
-    var self = this;
-
-    container.on('select', function (params) {
-      self._onSelect(params);
-    });
-
-    container.on('unselect', function (params) {
-      self._onUnSelect(params);
-    });
-  };
-
-  Dropdown.prototype._onSelect = function () {
-    this.trigger('close');
-  };
-
-  Dropdown.prototype._onUnSelect = function () {
-    this.trigger('close');
-  };
-
   return Dropdown;
 });
 
@@ -3610,6 +3590,31 @@ define('select2/dropdown/selectOnClose',[
   return SelectOnClose;
 });
 
+define('select2/dropdown/closeOnSelect',[
+
+], function () {
+  function CloseOnSelect () { }
+
+  CloseOnSelect.prototype.bind = function (decorated, container, $container) {
+    var self = this;
+
+    decorated.call(this, container, $container);
+
+    container.on('select', function (evt) {
+      var originalEvent = evt.originalEvent;
+
+      // Don't close if the control key is being held
+      if (originalEvent && originalEvent.ctrlKey) {
+        return;
+      }
+
+      self.trigger('close');
+    });
+  };
+
+  return CloseOnSelect;
+});
+
 define('select2/i18n/en',[],function () {
   // English
   return {
@@ -3686,6 +3691,7 @@ define('select2/defaults',[
   './dropdown/attachBody',
   './dropdown/minimumResultsForSearch',
   './dropdown/selectOnClose',
+  './dropdown/closeOnSelect',
 
   './i18n/en'
 ], function ($, ResultsList,
@@ -3699,7 +3705,7 @@ define('select2/defaults',[
              MinimumInputLength, MaximumInputLength, MaximumSelectionLength,
 
              Dropdown, DropdownSearch, HidePlaceholder, InfiniteScroll,
-             AttachBody, MinimumResultsForSearch, SelectOnClose,
+             AttachBody, MinimumResultsForSearch, SelectOnClose, CloseOnSelect,
 
              EnglishTranslation) {
   function Defaults () {
@@ -3810,6 +3816,13 @@ define('select2/defaults',[
         );
       }
 
+      if (options.closeOnSelect) {
+        options.dropdownAdapter = Utils.Decorate(
+          options.dropdownAdapter,
+          CloseOnSelect
+        );
+      }
+
       options.dropdownAdapter = Utils.Decorate(
         options.dropdownAdapter,
         AttachBody
@@ -3966,6 +3979,7 @@ define('select2/defaults',[
     this.defaults = {
       amdBase: 'select2/',
       amdLanguageBase: 'select2/i18n/',
+      closeOnSelect: true,
       escapeMarkup: Utils.escapeMarkup,
       language: EnglishTranslation,
       matcher: matcher,

dist/js/select2.amd.js

@@ -3104,26 +3104,6 @@ define('select2/dropdown',[
     this.$dropdown.remove();
   };
 
-  Dropdown.prototype.bind = function (container, $container) {
-    var self = this;
-
-    container.on('select', function (params) {
-      self._onSelect(params);
-    });
-
-    container.on('unselect', function (params) {
-      self._onUnSelect(params);
-    });
-  };
-
-  Dropdown.prototype._onSelect = function () {
-    this.trigger('close');
-  };
-
-  Dropdown.prototype._onUnSelect = function () {
-    this.trigger('close');
-  };
-
   return Dropdown;
 });
 
@@ -3610,6 +3590,31 @@ define('select2/dropdown/selectOnClose',[
   return SelectOnClose;
 });
 
+define('select2/dropdown/closeOnSelect',[
+
+], function () {
+  function CloseOnSelect () { }
+
+  CloseOnSelect.prototype.bind = function (decorated, container, $container) {
+    var self = this;
+
+    decorated.call(this, container, $container);
+
+    container.on('select', function (evt) {
+      var originalEvent = evt.originalEvent;
+
+      // Don't close if the control key is being held
+      if (originalEvent && originalEvent.ctrlKey) {
+        return;
+      }
+
+      self.trigger('close');
+    });
+  };
+
+  return CloseOnSelect;
+});
+
 define('select2/i18n/en',[],function () {
   // English
   return {
@@ -3686,6 +3691,7 @@ define('select2/defaults',[
   './dropdown/attachBody',
   './dropdown/minimumResultsForSearch',
   './dropdown/selectOnClose',
+  './dropdown/closeOnSelect',
 
   './i18n/en'
 ], function ($, ResultsList,
@@ -3699,7 +3705,7 @@ define('select2/defaults',[
              MinimumInputLength, MaximumInputLength, MaximumSelectionLength,
 
              Dropdown, DropdownSearch, HidePlaceholder, InfiniteScroll,
-             AttachBody, MinimumResultsForSearch, SelectOnClose,
+             AttachBody, MinimumResultsForSearch, SelectOnClose, CloseOnSelect,
 
              EnglishTranslation) {
   function Defaults () {
@@ -3810,6 +3816,13 @@ define('select2/defaults',[
         );
       }
 
+      if (options.closeOnSelect) {
+        options.dropdownAdapter = Utils.Decorate(
+          options.dropdownAdapter,
+          CloseOnSelect
+        );
+      }
+
       options.dropdownAdapter = Utils.Decorate(
         options.dropdownAdapter,
         AttachBody
@@ -3966,6 +3979,7 @@ define('select2/defaults',[
     this.defaults = {
       amdBase: 'select2/',
       amdLanguageBase: 'select2/i18n/',
+      closeOnSelect: true,
       escapeMarkup: Utils.escapeMarkup,
       language: EnglishTranslation,
       matcher: matcher,

dist/js/select2.full.js

@@ -3542,26 +3542,6 @@ define('select2/dropdown',[
     this.$dropdown.remove();
   };
 
-  Dropdown.prototype.bind = function (container, $container) {
-    var self = this;
-
-    container.on('select', function (params) {
-      self._onSelect(params);
-    });
-
-    container.on('unselect', function (params) {
-      self._onUnSelect(params);
-    });
-  };
-
-  Dropdown.prototype._onSelect = function () {
-    this.trigger('close');
-  };
-
-  Dropdown.prototype._onUnSelect = function () {
-    this.trigger('close');
-  };
-
   return Dropdown;
 });
 
@@ -4048,6 +4028,31 @@ define('select2/dropdown/selectOnClose',[
   return SelectOnClose;
 });
 
+define('select2/dropdown/closeOnSelect',[
+
+], function () {
+  function CloseOnSelect () { }
+
+  CloseOnSelect.prototype.bind = function (decorated, container, $container) {
+    var self = this;
+
+    decorated.call(this, container, $container);
+
+    container.on('select', function (evt) {
+      var originalEvent = evt.originalEvent;
+
+      // Don't close if the control key is being held
+      if (originalEvent && originalEvent.ctrlKey) {
+        return;
+      }
+
+      self.trigger('close');
+    });
+  };
+
+  return CloseOnSelect;
+});
+
 define('select2/i18n/en',[],function () {
   // English
   return {
@@ -4124,6 +4129,7 @@ define('select2/defaults',[
   './dropdown/attachBody',
   './dropdown/minimumResultsForSearch',
   './dropdown/selectOnClose',
+  './dropdown/closeOnSelect',
 
   './i18n/en'
 ], function ($, ResultsList,
@@ -4137,7 +4143,7 @@ define('select2/defaults',[
              MinimumInputLength, MaximumInputLength, MaximumSelectionLength,
 
              Dropdown, DropdownSearch, HidePlaceholder, InfiniteScroll,
-             AttachBody, MinimumResultsForSearch, SelectOnClose,
+             AttachBody, MinimumResultsForSearch, SelectOnClose, CloseOnSelect,
 
              EnglishTranslation) {
   function Defaults () {
@@ -4248,6 +4254,13 @@ define('select2/defaults',[
         );
       }
 
+      if (options.closeOnSelect) {
+        options.dropdownAdapter = Utils.Decorate(
+          options.dropdownAdapter,
+          CloseOnSelect
+        );
+      }
+
       options.dropdownAdapter = Utils.Decorate(
         options.dropdownAdapter,
         AttachBody
@@ -4404,6 +4417,7 @@ define('select2/defaults',[
     this.defaults = {
       amdBase: 'select2/',
       amdLanguageBase: 'select2/i18n/',
+      closeOnSelect: true,
       escapeMarkup: Utils.escapeMarkup,
       language: EnglishTranslation,
       matcher: matcher,

dist/js/select2.js

@@ -3542,26 +3542,6 @@ define('select2/dropdown',[
     this.$dropdown.remove();
   };
 
-  Dropdown.prototype.bind = function (container, $container) {
-    var self = this;
-
-    container.on('select', function (params) {
-      self._onSelect(params);
-    });
-
-    container.on('unselect', function (params) {
-      self._onUnSelect(params);
-    });
-  };
-
-  Dropdown.prototype._onSelect = function () {
-    this.trigger('close');
-  };
-
-  Dropdown.prototype._onUnSelect = function () {
-    this.trigger('close');
-  };
-
   return Dropdown;
 });
 
@@ -4048,6 +4028,31 @@ define('select2/dropdown/selectOnClose',[
   return SelectOnClose;
 });
 
+define('select2/dropdown/closeOnSelect',[
+
+], function () {
+  function CloseOnSelect () { }
+
+  CloseOnSelect.prototype.bind = function (decorated, container, $container) {
+    var self = this;
+
+    decorated.call(this, container, $container);
+
+    container.on('select', function (evt) {
+      var originalEvent = evt.originalEvent;
+
+      // Don't close if the control key is being held
+      if (originalEvent && originalEvent.ctrlKey) {
+        return;
+      }
+
+      self.trigger('close');
+    });
+  };
+
+  return CloseOnSelect;
+});
+
 define('select2/i18n/en',[],function () {
   // English
   return {
@@ -4124,6 +4129,7 @@ define('select2/defaults',[
   './dropdown/attachBody',
   './dropdown/minimumResultsForSearch',
   './dropdown/selectOnClose',
+  './dropdown/closeOnSelect',
 
   './i18n/en'
 ], function ($, ResultsList,
@@ -4137,7 +4143,7 @@ define('select2/defaults',[
              MinimumInputLength, MaximumInputLength, MaximumSelectionLength,
 
              Dropdown, DropdownSearch, HidePlaceholder, InfiniteScroll,
-             AttachBody, MinimumResultsForSearch, SelectOnClose,
+             AttachBody, MinimumResultsForSearch, SelectOnClose, CloseOnSelect,
 
              EnglishTranslation) {
   function Defaults () {
@@ -4248,6 +4254,13 @@ define('select2/defaults',[
         );
       }
 
+      if (options.closeOnSelect) {
+        options.dropdownAdapter = Utils.Decorate(
+          options.dropdownAdapter,
+          CloseOnSelect
+        );
+      }
+
       options.dropdownAdapter = Utils.Decorate(
         options.dropdownAdapter,
         AttachBody
@@ -4404,6 +4417,7 @@ define('select2/defaults',[
     this.defaults = {
       amdBase: 'select2/',
       amdLanguageBase: 'select2/i18n/',
+      closeOnSelect: true,
       escapeMarkup: Utils.escapeMarkup,
       language: EnglishTranslation,
       matcher: matcher,

docs/options.html

@@ -856,6 +856,50 @@ matcher: function (params, data) {
         <code title="select2/dropdown/selectOnClose">SelectOnClose</code>
       </dd>
     </dl>
+
+    <h2 id="closeOnSelect">
+      Close the dropdown when a result is selected
+    </h2>
+
+    <p>
+      Select2 will automatically close the dropdown when an element is selected,
+      similar to what is done with a normal select box.  This behavior can be
+      changed though to keep the dropdown open when results are selected,
+      allowing for multiple options to be selected quickly.
+    </p>
+
+    <div class="row">
+      <div class="col-sm-6">
+        <dl class="dl-horizontal">
+          <dt>Key</dt>
+          <dd><code>closeOnSelect</code></dd>
+
+          <dt>Default</dt>
+          <dd><code>true</code></dd>
+        </dl>
+      </div>
+
+      <div class="col-sm-6">
+        <dl class="dl-horizontal">
+          <dt>Adapter</dt>
+          <dd>
+            <code title="select2/dropdown">DropdownAdapter</code>
+          </dd>
+
+          <dt>Decorator</dt>
+          <dd>
+            <code title="select2/dropdown/closeOnSelect">CloseOnSelect</code>
+          </dd>
+        </dl>
+      </div>
+    </div>
+
+    <p>
+      If this decorator is not used (or <code>closeOnSelect</code> is set to
+      <code>false</code>), the dropdown will not automatically close when a
+      result is selected.  The dropdown will also never close if the
+      <kbd>ctrl</kbd> key is held down when the result is selected.
+    </p>
   </section>
 
   <section id="events">

src/js/select2/defaults.js

@@ -29,6 +29,7 @@ define([
   './dropdown/attachBody',
   './dropdown/minimumResultsForSearch',
   './dropdown/selectOnClose',
+  './dropdown/closeOnSelect',
 
   './i18n/en'
 ], function ($, ResultsList,
@@ -42,7 +43,7 @@ define([
              MinimumInputLength, MaximumInputLength, MaximumSelectionLength,
 
              Dropdown, DropdownSearch, HidePlaceholder, InfiniteScroll,
-             AttachBody, MinimumResultsForSearch, SelectOnClose,
+             AttachBody, MinimumResultsForSearch, SelectOnClose, CloseOnSelect,
 
              EnglishTranslation) {
   function Defaults () {
@@ -153,6 +154,13 @@ define([
         );
       }
 
+      if (options.closeOnSelect) {
+        options.dropdownAdapter = Utils.Decorate(
+          options.dropdownAdapter,
+          CloseOnSelect
+        );
+      }
+
       options.dropdownAdapter = Utils.Decorate(
         options.dropdownAdapter,
         AttachBody
@@ -309,6 +317,7 @@ define([
     this.defaults = {
       amdBase: 'select2/',
       amdLanguageBase: 'select2/i18n/',
+      closeOnSelect: true,
       escapeMarkup: Utils.escapeMarkup,
       language: EnglishTranslation,
       matcher: matcher,

src/js/select2/dropdown.js

@@ -34,25 +34,5 @@ define([
     this.$dropdown.remove();
   };
 
-  Dropdown.prototype.bind = function (container, $container) {
-    var self = this;
-
-    container.on('select', function (params) {
-      self._onSelect(params);
-    });
-
-    container.on('unselect', function (params) {
-      self._onUnSelect(params);
-    });
-  };
-
-  Dropdown.prototype._onSelect = function () {
-    this.trigger('close');
-  };
-
-  Dropdown.prototype._onUnSelect = function () {
-    this.trigger('close');
-  };
-
   return Dropdown;
 });

src/js/select2/dropdown/closeOnSelect.js

@@ -0,0 +1,24 @@
+define([
+
+], function () {
+  function CloseOnSelect () { }
+
+  CloseOnSelect.prototype.bind = function (decorated, container, $container) {
+    var self = this;
+
+    decorated.call(this, container, $container);
+
+    container.on('select', function (evt) {
+      var originalEvent = evt.originalEvent;
+
+      // Don't close if the control key is being held
+      if (originalEvent && originalEvent.ctrlKey) {
+        return;
+      }
+
+      self.trigger('close');
+    });
+  };
+
+  return CloseOnSelect;
+});