From 748eff7c4a60b43ddc3d48d09af8ea1ee99884d2 Mon Sep 17 00:00:00 2001
From: alexweissman <alex@alexanderweissman.com>
Date: Sun, 3 Sep 2017 23:09:17 -0400
Subject: [PATCH] finish advanced chapter

---
 pages/02.configuration/01.options-api/docs.md |   1 +
 pages/03.appearance/docs.md                   |  34 +----
 pages/05.data-sources/02.ajax/docs.md         |  74 ++++++++++
 pages/06.dropdown/docs.md                     |  18 ++-
 pages/10.searching/docs.md                    |   4 +-
 pages/12.i18n/docs.md                         |   2 +-
 .../02.default-adapters/02.array/docs.md      |  44 +-----
 .../02.default-adapters/03.ajax/docs.md       | 113 +-------------
 .../02.default-adapters/05.results/docs.md    |   8 -
 .../02.default-adapters/06.dropdown/docs.md   | 138 +++---------------
 .../14.upgrading/02.migrating-from-35/docs.md |   2 +-
 11 files changed, 123 insertions(+), 315 deletions(-)

diff --git a/pages/02.configuration/01.options-api/docs.md b/pages/02.configuration/01.options-api/docs.md
index a3fd3e23..5e6f0dc6 100644
--- a/pages/02.configuration/01.options-api/docs.md
+++ b/pages/02.configuration/01.options-api/docs.md
@@ -17,6 +17,7 @@ The following is an attempt to provide a comprehensive list of all configuration
 | `closeOnSelect` | boolean | `true` | Controls whether the dropdown is [closed after a selection is made](/dropdown#forcing-the-dropdown-to-remain-open-after-selection). |
 | `containerCss` | | | |
 | `containerCssClass` | | | |
+| `data` | array of objects | `null` | |
 | `dataAdapter` | | `SelectAdapter` | Used to override the built-in [DataAdapter](/advanced/default-adapters/data). |
 | `debug` | boolean | | |
 | `dir` | | |
diff --git a/pages/03.appearance/docs.md b/pages/03.appearance/docs.md
index ccdda1f6..63af76a7 100644
--- a/pages/03.appearance/docs.md
+++ b/pages/03.appearance/docs.md
@@ -118,24 +118,6 @@ You can, and should, use a `<label>` with Select2, just like any other `<select>
 
 Select2 will try to match the width of the original element as closely as possible. Sometimes this isn't perfect, in which case you may manually set the `width` [configuration option](/configuration):
 
-<dl class="dl-horizontal">
-
-<dt>element</dt>
-
-<dd>Uses the computed element width from any applicable CSS rules.</dd>
-
-<dt>resolve</dt>
-
-<dd>Uses the `style` attribute value if available, falling back to the computed element width as necessary.</dd>
-
-<dt>style</dt>
-
-<dd>Width is determined from the `select` element's `style` attribute. If no `style` attribute is found, null is returned as the width.</dd>
-
-<dt>_{width_value}_</dt>
-
-<dd>Valid CSS values can be passed as a string (i.e. `80%`).</dd>
-
 <table class="table table-striped table-bordered">
   <thead>
     <tr>
@@ -147,35 +129,33 @@ Select2 will try to match the width of the original element as closely as possib
     <tr>
       <td><code>"element"</code></td>
       <td>
-        Uses javascript to calculate the width of the source element.
+        Uses the computed element width from any applicable CSS rules.
       </td>
     </tr>
     <tr>
       <td><code>"style"</code></td>
       <td>
-        Copies the value of the width <code>style</code> attribute set on the source element.
+        Width is determined from the <code>select</code> element's <code>style</code> attribute. If no <code>style</code> attribute is found, null is returned as the width.
       </td>
     </tr>
     <tr>
       <td><code>"resolve"</code></td>
       <td>
-        Tries to use <code>style</code> to determine the width, falling back to <code>element</code>.
+        Uses the <code>style</code> attribute value if available, falling back to the computed element width as necessary.
       </td>
     </tr>
     <tr>
-      <td>Anything else</td>
+      <td><code>{width_value}</code></td>
       <td>
-        The value of the <code>width</code> option is directly set as the width of the container.
+        Valid CSS values can be passed as a string (i.e. <code>80%</code>).
       </td>
     </tr>
   </tbody>
 </table>
 
-## Responsive design - Percent width
+### Example
 
-Select2's width can be set to a percentage of its parent to support
-responsive design. The two Select2 boxes below are styled to 50% and 75%
-width respectively.
+The two Select2 boxes below are styled to `50%` and `75%` width respectively to support responsive design:
 
 <div class="s2-example">
   <p>
diff --git a/pages/05.data-sources/02.ajax/docs.md b/pages/05.data-sources/02.ajax/docs.md
index e5961680..a05f97b5 100644
--- a/pages/05.data-sources/02.ajax/docs.md
+++ b/pages/05.data-sources/02.ajax/docs.md
@@ -177,3 +177,77 @@ $('select').select2({
   }
 });
 ```
+
+## jQuery `$.ajax` options
+
+All options passed to `ajax` will be directly passed to the `$.ajax` function that executes AJAX requests.
+
+There are a few custom options that Select2 will intercept, allowing you to customize the request as it is being made:
+
+```
+ajax: {
+  // The number of milliseconds to wait for the user to stop typing before
+  // issuing the ajax request.
+  delay: 250,
+  // You can craft a custom url based on the parameters that are passed into the
+  // request. This is useful if you are using a framework which has
+  // JavaScript-based functions for generating the urls to make requests to.
+  //
+  // @param params The object containing the parameters used to generate the
+  //   request.
+  // @returns The url that the request should be made to.
+  url: function (params) {
+    return UrlGenerator.Random();
+  },
+  // You can pass custom data into the request based on the parameters used to
+  // make the request. For `GET` requests, the default method, these are the
+  // query parameters that are appended to the url. For `POST` requests, this
+  // is the form data that will be passed into the request. For other requests,
+  // the data returned from here should be customized based on what jQuery and
+  // your server are expecting.
+  //
+  // @param params The object containing the parameters used to generate the
+  //   request.
+  // @returns Data to be directly passed into the request.
+  data: function (params) {
+    var queryParameters = {
+      q: params.term
+    }
+
+    return queryParameters;
+  },
+  // You can modify the results that are returned from the server, allowing you
+  // to make last-minute changes to the data, or find the correct part of the
+  // response to pass to Select2. Keep in mind that results should be passed as
+  // an array of objects.
+  //
+  // @param data The data as it is returned directly by jQuery.
+  // @returns An object containing the results data as well as any required
+  //   metadata that is used by plugins. The object should contain an array of
+  //   data objects as the `results` key.
+  processResults: function (data) {
+    return {
+      results: data
+    };
+  },
+  // You can use a custom AJAX transport function if you do not want to use the
+  // default one provided by jQuery.
+  //
+  // @param params The object containing the parameters used to generate the
+  //   request.
+  // @param success A callback function that takes `data`, the results from the
+  //   request.
+  // @param failure A callback function that indicates that the request could
+  //   not be completed.
+  // @returns An object that has an `abort` function that can be called to abort
+  //   the request if needed.
+  transport: function (params, success, failure) {
+    var $request = $.ajax(params);
+
+    $request.then(success);
+    $request.fail(failure);
+
+    return $request;
+  }
+}
+```
diff --git a/pages/06.dropdown/docs.md b/pages/06.dropdown/docs.md
index 3bdcd2bc..3ded5ae3 100644
--- a/pages/06.dropdown/docs.md
+++ b/pages/06.dropdown/docs.md
@@ -62,7 +62,7 @@ $('select').select2({
 
 ## Forcing the dropdown to remain open after selection
 
-You may use the `closeOnSelect` option to prevent the dropdown from closing when a result is selected:
+Select2 will automatically close the dropdown when an element is selected, similar to what is done with a normal select box.  You may use the `closeOnSelect` option to prevent the dropdown from closing when a result is selected:
 
 ```
 $('select').select2({
@@ -70,11 +70,19 @@ $('select').select2({
 });
 ```
 
->>> Note that this option is only applicable to multi-select controls.
+Note that this option is only applicable to multi-select controls.
+
+>>> If the [`CloseOnSelect` decorator](/advanced/default-adapters/dropdown#closeonselect) is not used (or `closeOnSelect` 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.
 
 ## Dropdown placement
 
-The `dropdownParent` option allows you to pick an element for the dropdown to be appended to:
+>>>>> Attention [Harvest Chosen](https://harvesthq.github.io/chosen/) migrators!  If you are migrating to Select2 from Chosen, this option will cause Select2 to position the dropdown in a similar way.
+
+By default, Select2 will attach the dropdown to the end of the body and will absolutely position it to appear above or below the selection container.
+
+Select2 will display the dropdown above the container if there is not enough space below the container, but there is enough space above it.
+
+The `dropdownParent` option allows you to pick an alternative element for the dropdown to be appended to:
 
 ```
 $('select').select2({
@@ -82,6 +90,6 @@ $('select').select2({
 });
 ```
 
-### Using a Select2 control inside a Bootstrap modal
+This is useful when attempting to render Select2 correctly inside of modals and other small containers.  If you're having trouble using the search box inside a Bootstrap modal, for example, trying setting the `dropdownParent` option to the modal element.
 
-If you're having trouble using the search box inside a Bootstrap modal, trying setting the `dropdownParent` option to the modal element.
+>>>> This will cause DOM events to be raised outside of the standard Select2 DOM container. This can cause issues with third-party components such as modals.
diff --git a/pages/10.searching/docs.md b/pages/10.searching/docs.md
index 04b48227..dac75173 100644
--- a/pages/10.searching/docs.md
+++ b/pages/10.searching/docs.md
@@ -7,7 +7,7 @@ process:
 never_cache_twig: true
 ---
 
-The appearance and behavior of the search control can be easily customized with Select2.
+A search box is added to the top of the dropdown automatically for select boxes where only a single option can be selected. The behavior and appearance of the search box can be easily customized with Select2.
 
 ## Customizing how results are matched
 
@@ -93,7 +93,7 @@ $(".js-example-matcher-start").select2({
 
 </script>
 
->>> A [compatibility module]() exists for using v3-style matcher callbacks.
+>>> A [compatibility module](/upgrading/migrating-from-35#wrapper-for-old-style-matcher-callbacks) exists for using v3-style matcher callbacks.
 
 ## Minimum search term length
 
diff --git a/pages/12.i18n/docs.md b/pages/12.i18n/docs.md
index 6c65c5dc..f5ecfecf 100644
--- a/pages/12.i18n/docs.md
+++ b/pages/12.i18n/docs.md
@@ -11,7 +11,7 @@ never_cache_twig: true
 
 ## Message translations
 
-When necessary, Select2 displays certain messages to the user.  For example, a message will appear when no search results were found or more characters need to be entered in order for a search to be made. These messages have been <a href="community.html#translations">translated into many languages</a> by contributors to Select2, but you can also provide your own translations.
+When necessary, Select2 displays certain messages to the user.  For example, a message will appear when no search results were found or more characters need to be entered in order for a search to be made. These messages have been translated into many languages by contributors to Select2, but you can also provide your own translations.
 
 ### Language files
 
diff --git a/pages/13.advanced/02.default-adapters/02.array/docs.md b/pages/13.advanced/02.default-adapters/02.array/docs.md
index e03453fd..316be465 100644
--- a/pages/13.advanced/02.default-adapters/02.array/docs.md
+++ b/pages/13.advanced/02.default-adapters/02.array/docs.md
@@ -4,46 +4,8 @@ taxonomy:
     category: docs
 ---
 
+The `ArrayAdapter` implements support for creating results based on an [array of data objects](/data-sources/array).
 
+**AMD Modules:**
 
-  <h3 id="data">
-    Array
-  </h3>
-
-  <p>
-    Select2 allows creating the results based on an array of data objects that
-    is included when initializing Select2.
-  </p>
-
-  <div class="row">
-    <div class="col-sm-6">
-      <dl class="dl-horizontal">
-        <dt>Key</dt>
-        <dd><code>data</code></dd>
-
-        <dt>Value</dt>
-        <dd>array of objects</dd>
-      </dl>
-    </div>
-
-    <div class="col-sm-6">
-      <dl class="dl-horizontal">
-        <dt>Adapter</dt>
-        <dd>
-          <code title="select2/data/array">ArrayAdapter</code>
-        </dd>
-      </dl>
-    </div>
-  </div>
-
-  <p>
-    The objects that the users can select from should be passed as an array
-    with each object containing <code>id</code> and <code>text</code>
-    properties.
-  </p>
-
-Select2 provides the `SingleSelection` and `MultipleSelection` adapters as default implementations of the `SelectionAdapter` for single- and multi-select controls, respectively.  Both `SingleSelection` and `MultipleSelection` extend the base `BaseSelection` adapter.
-
-The selection adapter can be overridden by assigning a custom adapter to the `selectionAdapter` configuration option.
- 
-## Decorators
\ No newline at end of file
+`select2/data/array`
diff --git a/pages/13.advanced/02.default-adapters/03.ajax/docs.md b/pages/13.advanced/02.default-adapters/03.ajax/docs.md
index 7a105935..96c879e8 100644
--- a/pages/13.advanced/02.default-adapters/03.ajax/docs.md
+++ b/pages/13.advanced/02.default-adapters/03.ajax/docs.md
@@ -4,115 +4,8 @@ taxonomy:
     category: docs
 ---
 
+The `AjaxAdapter` implements support for creating results [from remote data sources using AJAX requests](/data-sources/ajax).
 
-  <h3 id="ajax">
-    AJAX
-  </h3>
+**AMD Modules:**
 
-  <p>
-    Select2 allows searching for results from remote data sources using AJAX
-    requests.
-  </p>
-
-  <div class="row">
-    <div class="col-sm-6">
-      <dl class="dl-horizontal">
-        <dt>Key</dt>
-        <dd><code>ajax</code></dd>
-
-        <dt>Value</dt>
-        <dd>object</dd>
-      </dl>
-    </div>
-
-    <div class="col-sm-6">
-      <dl class="dl-horizontal">
-        <dt>Adapter</dt>
-        <dd>
-          <code title="select2/data/ajax">AjaxAdapter</code>
-        </dd>
-      </dl>
-    </div>
-  </div>
-
-  <p>
-    All options passed to this option will be directly passed to the
-    <code>$.ajax</code> function that executes AJAX requests. There are a few
-    custom options that Select2 will intercept, allowing you to customize the
-    request as it is being made.
-
-<pre class="prettyprint linenums">
-ajax: {
-  // The number of milliseconds to wait for the user to stop typing before
-  // issuing the ajax request.
-  delay: 250,
-  // You can craft a custom url based on the parameters that are passed into the
-  // request. This is useful if you are using a framework which has
-  // JavaScript-based functions for generating the urls to make requests to.
-  //
-  // @param params The object containing the parameters used to generate the
-  //   request.
-  // @returns The url that the request should be made to.
-  url: function (params) {
-    return UrlGenerator.Random();
-  },
-  // You can pass custom data into the request based on the parameters used to
-  // make the request. For `GET` requests, the default method, these are the
-  // query parameters that are appended to the url. For `POST` requests, this
-  // is the form data that will be passed into the request. For other requests,
-  // the data returned from here should be customized based on what jQuery and
-  // your server are expecting.
-  //
-  // @param params The object containing the parameters used to generate the
-  //   request.
-  // @returns Data to be directly passed into the request.
-  data: function (params) {
-    var queryParameters = {
-      q: params.term
-    }
-
-    return queryParameters;
-  },
-  // You can modify the results that are returned from the server, allowing you
-  // to make last-minute changes to the data, or find the correct part of the
-  // response to pass to Select2. Keep in mind that results should be passed as
-  // an array of objects.
-  //
-  // @param data The data as it is returned directly by jQuery.
-  // @returns An object containing the results data as well as any required
-  //   metadata that is used by plugins. The object should contain an array of
-  //   data objects as the `results` key.
-  processResults: function (data) {
-    return {
-      results: data
-    };
-  },
-  // You can use a custom AJAX transport function if you do not want to use the
-  // default one provided by jQuery.
-  //
-  // @param params The object containing the parameters used to generate the
-  //   request.
-  // @param success A callback function that takes `data`, the results from the
-  //   request.
-  // @param failure A callback function that indicates that the request could
-  //   not be completed.
-  // @returns An object that has an `abort` function that can be called to abort
-  //   the request if needed.
-  transport: function (params, success, failure) {
-    var $request = $.ajax(params);
-
-    $request.then(success);
-    $request.fail(failure);
-
-    return $request;
-  }
-}
-</pre>
-  </p>
-  
-  
-Select2 provides the `SingleSelection` and `MultipleSelection` adapters as default implementations of the `SelectionAdapter` for single- and multi-select controls, respectively.  Both `SingleSelection` and `MultipleSelection` extend the base `BaseSelection` adapter.
-
-The selection adapter can be overridden by assigning a custom adapter to the `selectionAdapter` configuration option.
- 
-## Decorators
\ No newline at end of file
+`select2/data/ajax`
diff --git a/pages/13.advanced/02.default-adapters/05.results/docs.md b/pages/13.advanced/02.default-adapters/05.results/docs.md
index 25384baa..909d7e45 100644
--- a/pages/13.advanced/02.default-adapters/05.results/docs.md
+++ b/pages/13.advanced/02.default-adapters/05.results/docs.md
@@ -14,14 +14,6 @@ The results adapter can be overridden by assigning a custom adapter to the `resu
 
 ## Decorators
 
-### `Tags`
-
-This decorator implements the [tagging](/tagging) feature.
-
-**AMD Modules:**
-
-`select2/data/tags`
-
 ### `SelectOnClose`
 
 This decorator implements [automatic selection](/dropdown#automatic-selection) of the highlighted option when the dropdown is closed.
diff --git a/pages/13.advanced/02.default-adapters/06.dropdown/docs.md b/pages/13.advanced/02.default-adapters/06.dropdown/docs.md
index 099d987f..10ffb124 100644
--- a/pages/13.advanced/02.default-adapters/06.dropdown/docs.md
+++ b/pages/13.advanced/02.default-adapters/06.dropdown/docs.md
@@ -16,142 +16,40 @@ This adapter can be overridden by assigning a custom adapter to the `dropdownAda
 
 ### `AttachBody`
 
-By default, Select2 will attach the dropdown to the end of the body and will absolutely position it to appear below the selection container.
+This decorator implements the standard [`dropdownParent`](/dropdown#dropdown-placement) method of attaching the dropdown.
+
+**AMD Modules:**
 
 `select2/dropdown/attachBody`
 
-  <h2 id="dropdownParent">
-    Attached to body
-  </h2>
-
-
-    <div class="col-sm-6">
-      <div class="alert alert-warning">
-        <strong>Heads up!</strong>
-        This will cause DOM events to be raised outside of the standard
-        Select2 DOM container. This can cause issues with
-        third-party components such as modals.
-      </div>
-    </div>
-  </div>
-
-  <p>
-    When the dropdown is attached to the body, you are not limited to just
-    displaying the dropdown below the container. Select2 will display above
-    the container if there is not enough space below the container, but there
-    is enough space above it. You are also not limited to displaying the
-    dropdown within the parent container, which means Select2 will render
-    correctly inside of modals and other small containers.
-  </p>
-
 ### `AttachContainer`
 
+When this decorator is loaded, Select2 can place the dropdown directly after the selection container, so it will appear in the same location within the DOM as the rest of Select2.
+
+**AMD Modules:**
+
 `select2/dropdown/attachContainer`
 
-  <h2 id="dropdown-attachContainer">
-    Attached below the container
-  </h2>
-
-  <p>
-    Select2 can place the dropdown directly after the selection container, so
-    it will appear in the same location within the DOM as the rest of Select2.
-  </p>
-
-  <div class="row">
-
-    <div class="col-sm-6">
-      <div class="alert alert-warning">
-        <strong>Check your build.</strong> This module is only included in the
-        <a href="index.html#builds-full" class="alert-link">full builds</a> of
-        Select2.
-      </div>
-    </div>
-  </div>
-
-  <div class="alert alert-info">
-    <strong>
-      <a href="https://harvesthq.github.io/chosen/">Harvest Chosen</a>
-      migrators!
-    </strong>
-    If you are migrating to Select2 from Chosen, this option will cause
-    Select2 to position the dropdown in a similar way.
-  </div>
+>>>> **Check your build.** This module is only included in the [full builds](/getting-started/builds-and-modules) of Select2.
 
 ### `DropdownSearch`
 
-`select2/dropdown/search`
-      
-  <p>
-    Users can filter down the results by typing a search term into a box that
-    is displayed at the top of the dropdown.
-  </p>
+This decorator implements the [search box that is displayed at the top of the dropdown](/searching).
 
-  <p>
-    A search box is added to the top of the dropdown automatically for select
-    boxes where only a single option can be selected.
-  </p>
+**AMD Modules:**
+
+`select2/dropdown/search`
 
 ### `MinimumResultsForSearch`
 
+This decorator implements the [`minimumResultsForSearch` configuration option](/searching#limiting-display-of-the-search-box-to-large-result-sets).
+
+**AMD Modules:**
+
 `select2/dropdown/minimumResultsForSearch`
 
-  <h3 id="dropdown-maximumInputLength">
-    Minimum results to display the search box
-  </h3>
-
-  <p>
-    When working with smaller data sets, the search box can take up more space
-    that is necessary, as there are not enough results for filtering to be
-    effective. Select2 allows you to only display the search box when the
-    number of search results reaches a certain threshold.
-  </p>
-
-  <div class="row">
-    <div class="col-sm-6">
-      <dl class="dl-horizontal">
-        <dt>Key</dt>
-        <dd><code>minimumResultsForSearch</code></dd>
-
-        <dt>Value</dt>
-        <dd>integer</dd>
-      </dl>
-    </div>
-
-  </div>
-
 ### `CloseOnSelect`
 
+This decorator implements the [`closeOnSelect` configuration option](/dropdown#forcing-the-dropdown-to-remain-open-after-selection).
+
 `select2/dropdown/closeOnSelect`
-
-  <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>
-
-  <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>
-
diff --git a/pages/14.upgrading/02.migrating-from-35/docs.md b/pages/14.upgrading/02.migrating-from-35/docs.md
index 6ba020af..3e429bbb 100644
--- a/pages/14.upgrading/02.migrating-from-35/docs.md
+++ b/pages/14.upgrading/02.migrating-from-35/docs.md
@@ -43,7 +43,7 @@ With the new [matcher function](/searching), only the root-level options are mat
 
 For backwards compatibility, a wrapper function has been created that allows old-style matcher functions to be converted to the new style. 
 
-This custom matcher uses a [compatibility function](/configuration/deprecated) that is only bundled in the [full version of Select2](/getting-started/builds).  You can retrieve the function from the `select2/compat/matcher` module, which should just wrap the old matcher function.
+This wrapper function is only bundled in the [full version of Select2](/getting-started/builds-and-modules).  You can retrieve the function from the `select2/compat/matcher` module, which should just wrap the old matcher function.
 
 <div class="s2-example">
     <select class="js-example-matcher-compat js-states form-control"></select>