Added back select2('val')

With the recent changes to how Select2 works internally, this really
isn't needed. This has been added to make the migration path
easier, and it just internally calls `val` on the underlying select
element. The only difference is that the `val` function will now
convert any non-string elements to strings.

The second argument (`triggerChange`) has not been migrated, as
Select2 now internally relies on the `change` event.

**Note:** As the old `initSelection` method has not been migrated,
it is not possible to set the `val` on remote data sources where
the value has not previously been selected.

dist/js/select2.amd.full.js

@@ -3750,6 +3750,22 @@ define('select2/core',[
     return this.$container.hasClass('select2-container--open');
   };
 
+  Select2.prototype.val = function (args) {
+    if (args.length === 0) {
+      return this.$element.val();
+    }
+
+    var newVal = args[0];
+
+    if ($.isArray(newVal)) {
+      newVal = $.map(newVal, function (obj) {
+        return obj.toString();
+      });
+    }
+
+    this.$element.val(newVal).trigger('change');
+  };
+
   Select2.prototype.destroy = function () {
     this.$container.remove();
 

dist/js/select2.amd.js

@@ -3750,6 +3750,22 @@ define('select2/core',[
     return this.$container.hasClass('select2-container--open');
   };
 
+  Select2.prototype.val = function (args) {
+    if (args.length === 0) {
+      return this.$element.val();
+    }
+
+    var newVal = args[0];
+
+    if ($.isArray(newVal)) {
+      newVal = $.map(newVal, function (obj) {
+        return obj.toString();
+      });
+    }
+
+    this.$element.val(newVal).trigger('change');
+  };
+
   Select2.prototype.destroy = function () {
     this.$container.remove();
 

dist/js/select2.full.js

@@ -13285,6 +13285,22 @@ define('select2/core',[
     return this.$container.hasClass('select2-container--open');
   };
 
+  Select2.prototype.val = function (args) {
+    if (args.length === 0) {
+      return this.$element.val();
+    }
+
+    var newVal = args[0];
+
+    if ($.isArray(newVal)) {
+      newVal = $.map(newVal, function (obj) {
+        return obj.toString();
+      });
+    }
+
+    this.$element.val(newVal).trigger('change');
+  };
+
   Select2.prototype.destroy = function () {
     this.$container.remove();
 

dist/js/select2.js

@@ -4178,6 +4178,22 @@ define('select2/core',[
     return this.$container.hasClass('select2-container--open');
   };
 
+  Select2.prototype.val = function (args) {
+    if (args.length === 0) {
+      return this.$element.val();
+    }
+
+    var newVal = args[0];
+
+    if ($.isArray(newVal)) {
+      newVal = $.map(newVal, function (obj) {
+        return obj.toString();
+      });
+    }
+
+    this.$element.val(newVal).trigger('change');
+  };
+
   Select2.prototype.destroy = function () {
     this.$container.remove();
 

docs/examples.html

@@ -283,6 +283,10 @@ $(".js-data-example-ajax").select2({
       </p>
 
       <p>
+        <button class="js-programmatic-set-val btn btn-primary">
+          Set to California
+        </button>
+
         <button class="js-programmatic-open btn btn-success">
           Open
         </button>
@@ -304,6 +308,20 @@ $(".js-data-example-ajax").select2({
         <select class="js-example-programmatic js-states form-control"></select>
       </p>
 
+      <p>
+        <button class="js-programmatic-multi-set-val btn btn-primary">
+          Set to California and Alabama
+        </button>
+
+        <button class="js-programmatic-multi-clear btn btn-primary">
+          Clear
+        </button>
+      </p>
+
+      <p>
+        <select class="js-example-programmatic-multi js-states form-control" multiple="multiple"></select>
+      </p>
+
     </div>
     <div class="col-md-8">
       <h2>Example code</h2>
@@ -312,12 +330,20 @@ $(".js-data-example-ajax").select2({
 
 <script type="text/javascript" class="js-code-programmatic">
 var $example = $(".js-example-programmatic");
+var $exampleMulti = $(".js-example-programmatic-multi");
+
+// Recommended to use $e.val("CA").trigger("change");
+$(".js-programmatic-set-val").on("click", function () { $example.select2("val", "CA"); });
 
 $(".js-programmatic-open").on("click", function () { $example.select2("open"); });
 $(".js-programmatic-close").on("click", function () { $example.select2("close"); });
 
 $(".js-programmatic-init").on("click", function () { $example.select2(); });
 $(".js-programmatic-destroy").on("click", function () { $example.select2("destroy"); });
+
+// Recommended to use $e.val(["CA", "AL"]).trigger("change");
+$(".js-programmatic-multi-set-val").on("click", function () { $exampleMulti.select2("val", ["CA", "AL"]); });
+$(".js-programmatic-multi-clear").on("click", function () { $exampleMulti.select2("val", null); });
 </script>
     </div>
   </section>
@@ -682,6 +708,7 @@ $.fn.select2.amd.require(
   $disabledResults.select2();
 
   $(".js-example-programmatic").select2();
+  $(".js-example-programmatic-multi").select2();
 
   $tags.select2({
     tags: ['red', 'blue', 'green']

src/js/select2/core.js

@@ -297,6 +297,22 @@ define([
     return this.$container.hasClass('select2-container--open');
   };
 
+  Select2.prototype.val = function (args) {
+    if (args.length === 0) {
+      return this.$element.val();
+    }
+
+    var newVal = args[0];
+
+    if ($.isArray(newVal)) {
+      newVal = $.map(newVal, function (obj) {
+        return obj.toString();
+      });
+    }
+
+    this.$element.val(newVal).trigger('change');
+  };
+
   Select2.prototype.destroy = function () {
     this.$container.remove();