From d14631325686d7bfe5b1c63485c407fc85b68491 Mon Sep 17 00:00:00 2001
From: Kevin Brown <kevin@kevinbrown.in>
Date: Sat, 14 Mar 2015 19:58:50 -0400
Subject: [PATCH] More about `initSelection`

In the past, `initSelection` was used for loading in data objects
for the pre-selected options. Now that Select2 is using a `<select>`
element, there is no need for doing this because the `<option>`
elements should provide the relevant information. So you can now
just pull this information from the remote data source
(or static array, in some cases) and build out the `<option>`
elements manually.

In most cases you don't need to go the full length with a custom
data adapter, but instead are just looking to pre-load elements on
the initial page load.

This improves https://github.com/select2/select2/issues/3116.
---
 docs/announcements-4.0.html | 54 ++++++++++++++++++++++++++++++-------
 docs/index.html             | 11 --------
 2 files changed, 44 insertions(+), 21 deletions(-)

diff --git a/docs/announcements-4.0.html b/docs/announcements-4.0.html
index c6fbf79b..392faa5c 100644
--- a/docs/announcements-4.0.html
+++ b/docs/announcements-4.0.html
@@ -375,17 +375,51 @@ function (ArrayData, Utils) {
       The new <code>current</code> method of the data adapter works in a similar
       way to the old <code>initSelection</code> method, with three notable
       differences. The first, and most important, is that <code>it is called
-        whenever the current selections are needed</code> to ensure that Select2
-        is always displaying the most accurate and up to date data. No matter
-        what type of element Select2 is attached to, whether it supports a
-        single or multiple selections, the data passed to the callback
-        <strong>must be an array, even if it contains one selection</strong>.
-        The last is that there is only one parameter, the callback to be
-        executed with the latest data, and the current element that Select2 is
-        attached to is available on the class itself as
-        <code>this.$element</code>.
+      whenever the current selections are needed</code> to ensure that Select2
+      is always displaying the most accurate and up to date data. No matter
+      what type of element Select2 is attached to, whether it supports a
+      single or multiple selections, the data passed to the callback
+      <strong>must be an array, even if it contains one selection</strong>.
+      The last is that there is only one parameter, the callback to be
+      executed with the latest data, and the current element that Select2 is
+      attached to is available on the class itself as
+      <code>this.$element</code>.
     </p>
 
+    <p>
+      If you only need to load in the initial options once, and otherwise will
+      be letting Select2 handle the state of the selections, you don't need to
+      use a custom data adapter. You can just create the
+      <code>&lt;option&gt;</code> tags on your own, and Select2 will pick up
+      the changes.
+    </p>
+
+<pre class="prettyprint linenums">
+var $element = $('select').select2(); // the select element you are working with
+
+var $request = $.ajax({
+  url: '/my/remote/source' // wherever your data is actually coming from
+});
+
+$request.then(function (data) {
+  // This assumes that the data comes back as an array of data objects
+  // The idea is that you are using the same callback as the old `initSelection`
+
+  for (var d = 0; d < data.length; d++) {
+    var item = data[d];
+
+    // Create the DOM option that is pre-selected by default
+    var option = new Option(data.text, data.id, true, true);
+
+    // Append it to the select
+    $element.append(option);
+  }
+
+  // Update the selected options that are displayed
+  $element.trigger('change');
+});
+</pre>
+
     <h3 id="query-to-data-adapter">
       Custom data adapters instead of <code>query</code>
     </h3>
@@ -643,7 +677,7 @@ var data = $.map([
     </p>
 
 <pre class="prettyprint linenums">
-$("select").val("1"); // instead of $("select").select2("val", "1");
+$("select").val("1").trigger("change"); // instead of $("select").select2("val", "1");
 </pre>
 
     <h3>.select2("enable")</h3>
diff --git a/docs/index.html b/docs/index.html
index 4bac1dc7..1fb5848d 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -170,17 +170,6 @@ slug: home
             <a href="https://github.com/jquery/jquery-mousewheel">jquery.mousewheel</a>
           </td>
         </tr>
-        <tr id="builds-amd">
-          <td>
-            AMD (<code>select2.amd.js</code> / <code>select2.amd.full.js</code>)
-          </td>
-          <td>
-            This is the build that anyone who is using Select2 with an existing
-            AMD build system should use. It is also recommended that you read
-            the <a href="options.html#amd">AMD compatibility documentation</a>
-            to avoid any unexpected issues.
-          </td>
-        </tr>
       </tbody>
     </table>
   </section>