Finish off the incomplete options documentation

The documentation is not completely finished, but now we have no
placeholders waiting to be completed.

dist/js/i18n/en.js

@@ -1 +1 @@
-window.$=window.$||{},function(){$&&$.fn&&$.fn.select2&&$.fn.select2.amd&&(define=$.fn.select2.amd.define,require=$.fn.select2.amd.require),define("select2/i18n/en",[],function(){return{errorLoading:function(){return"The results could not be loaded."},inputTooLong:function(e){var t=e.input.length-e.maximum,n="Please delete "+t+" character";return t!=1&&(n+="s"),n},inputTooShort:function(e){var t=e.minimum-e.input.length,n="Please enter "+t+" or more character";return t!=1&&(n+="s"),n},loadingMore:function(){return"Loading more results…"},maximumSelected:function(e){var t="You can only select "+e.maximum+" item";return e.maximum!=1&&(t+="s"),t},noResults:function(){return"No results found"},searching:function(){return"Searching…"}}}),require("jquery.select2"),$.fn.select2.amd={define:define,require:require}}();
+window.$=window.$||{},function(){$&&$.fn&&$.fn.select2&&$.fn.select2.amd&&(define=$.fn.select2.amd.define,require=$.fn.select2.amd.require),define("select2/i18n/en",[],function(){return{errorLoading:function(){return"The results could not be loaded."},inputTooLong:function(e){var t=e.input.length-e.maximum,n="Please delete "+t+" character";return t!=1&&(n+="s"),n},inputTooShort:function(e){var t=e.minimum-e.input.length,n="Please enter "+t+" or more characters";return n},loadingMore:function(){return"Loading more results…"},maximumSelected:function(e){var t="You can only select "+e.maximum+" item";return e.maximum!=1&&(t+="s"),t},noResults:function(){return"No results found"},searching:function(){return"Searching…"}}}),require("jquery.select2"),$.fn.select2.amd={define:define,require:require}}();

dist/js/select2.amd.full.js

@@ -3008,11 +3008,7 @@ define('select2/i18n/en',[],function () {
     inputTooShort: function (args) {
       var remainingChars = args.minimum - args.input.length;
 
-      var message = 'Please enter ' + remainingChars + ' or more character';
-
-      if (remainingChars != 1) {
-        message += 's';
-      }
+      var message = 'Please enter ' + remainingChars + ' or more characters';
 
       return message;
     },

dist/js/select2.amd.js

@@ -3008,11 +3008,7 @@ define('select2/i18n/en',[],function () {
     inputTooShort: function (args) {
       var remainingChars = args.minimum - args.input.length;
 
-      var message = 'Please enter ' + remainingChars + ' or more character';
-
-      if (remainingChars != 1) {
-        message += 's';
-      }
+      var message = 'Please enter ' + remainingChars + ' or more characters';
 
       return message;
     },

dist/js/select2.full.js

@@ -12543,11 +12543,7 @@ define('select2/i18n/en',[],function () {
     inputTooShort: function (args) {
       var remainingChars = args.minimum - args.input.length;
 
-      var message = 'Please enter ' + remainingChars + ' or more character';
-
-      if (remainingChars != 1) {
-        message += 's';
-      }
+      var message = 'Please enter ' + remainingChars + ' or more characters';
 
       return message;
     },

dist/js/select2.js

@@ -3436,11 +3436,7 @@ define('select2/i18n/en',[],function () {
     inputTooShort: function (args) {
       var remainingChars = args.minimum - args.input.length;
 
-      var message = 'Please enter ' + remainingChars + ' or more character';
-
-      if (remainingChars != 1) {
-        message += 's';
-      }
+      var message = 'Please enter ' + remainingChars + ' or more characters';
 
       return message;
     },

docs/_includes/navigation.html

@@ -23,12 +23,12 @@
         </li>
         <li class="dropdown">
           <a href="#" class="dropdown-toggle" data-toggle="dropdown">
-            Announcements
+            Topics
             <span class="caret"></span>
           </a>
           <ul class="dropdown-menu">
             <li{% if page.slug == "announcements-4.0" %} class="active"{% endif %}>
-              <a href="./announcements-4.0.html">Select2 4.0</a>
+              <a href="./announcements-4.0.html">4.0 Announcement</a>
             </li>
           </ul>
         </li>

docs/examples.html

@@ -170,6 +170,7 @@ $(".js-example-data-array-selected").select2({
 
       <p>
         Select2 comes with AJAX support built in, using jQuery's AJAX methods.
+        In this example, we can search for repositories using GitHub's API.
       </p>
 
       <p>
@@ -178,15 +179,61 @@ $(".js-example-data-array-selected").select2({
         </select>
       </p>
 
+      <p>
+        When using Select2 with remote data, the HTML required for the
+        <code>select</code> is the same as any other Select2. If you need to
+        provide default selections, you just need to include an
+        <code>option</code> for each selection that contains the value and text
+        that should be displayed.
+      </p>
+
+      <pre data-fill-from=".js-code-data-ajax-html"></pre>
+
+      <p>
+        You can configure how Select2 searches for remote data using the
+        <code>ajax</code> option. More information on the individual options
+        that Select2 handles can be found in the
+        <a href="options.html#ajax">options documentation for <code>ajax</code></a>.
+      </p>
+
       <pre data-fill-from=".js-code-data-ajax"></pre>
 
       <p>
         Select2 will pass any options in the <code>ajax</code> object to
-        jQuery's <code>$.ajax</code> function.
+        jQuery's <code>$.ajax</code> function, or the <code>transport</code>
+        function you specify.
       </p>
 
 <script type="text/x-example-code" class="js-code-data-ajax">
+$(".js-data-example-ajax").select2({
+  ajax: {
+    url: "https://api.github.com/search/repositories",
+    dataType: 'json',
+    delay: 250,
+    data: function (params) {
+      return {
+        q: params.term, // search term
+        page: params.page
+      };
+    },
+    processResults: function (data, page) {
+      // parse the results into the format expected by Select2.
+      // since we are using custom formatting functions we do not need to
+      // alter the remote JSON data
+      return data.items;
+    },
+    cache: true
+  },
+  minimumInputLength: 1,
+  templateResult: formatRepo, // omitted for brevity, see the source of this page
+  templateSelection: formatRepoSelection // omitted for brevity, see the source of this page
+});
+</script>
 
+<script type="text/x-example-code" class="js-code-data-ajax-html">
+<select class="js-data-example-ajax">
+  <option value="ivaynberg/select2" selected="selected">ivaynberg/select2</option>
+</select>
 </script>
     </div>
   </section>

docs/options.html

@@ -18,10 +18,40 @@ slug: options
       adapters by default.
     </p>
 
+    <p>
+      Select2 will automatically apply decorators to any adapters which have not
+      been manually overriden. The only time you need to decorate adapters is
+      when you are using third-party adapters not provided by Select2, or you
+      are using features not provided in the Select2 core. You can apply a
+      decorator to an adapter using the
+      <code title="select2/utils">Utils.Decorate</code> method provided with
+      Select2.
+    </p>
+
+<pre class="prettyprint linenums">
+$.fn.select2.amd.require(
+    ["select2/utils", "select2/selection/single", "select2/selection/placeholder"],
+    function (Utils, SingleSelection, Placeholder) {
+  var CustomSelectionAdapter = Utils.Decorate(SingleSelection, Placeholder);
+});
+</pre>
+
+    <p>
+      All core options that use decorators or adapters will clearly state it
+      in the "Decorator" or "Adapter" part of the documentation. Decorators are
+      typically only compatible with a specific type of adapter, so make sure to
+      note what adapter is given.
+    </p>
+
     <h2>
       Display
     </h2>
 
+    <p>
+      Select2 provides options that allow you to directly affect how the
+      container that holds the current selection is displayed.
+    </p>
+
     <h3 id="placeholder">
       Placeholders
     </h3>
@@ -93,7 +123,7 @@ slug: options
       attribute on the <code>option</code>.
     </div>
 
-    <h3 id="translation">
+    <h3 id="language">
       Internationalization (Language support)
     </h3>
 
@@ -167,7 +197,7 @@ language: {
     <p>
       Select2 can work on many different data sets ranging from local options,
       the same way that a <code>&lt;select&gt;</code> typically works, from
-      remove options where a server generates the results that users can select
+      remote options where a server generates the results that users can select
       from.
     </p>
 
@@ -343,6 +373,210 @@ ajax: {
     <div class="page-header">
       <h1>Adapters</h1>
     </div>
+
+    <p>
+      Select2 allows plugins to add additional functionality through the core
+      adapters. You can change almost anything involving the way Select2 works
+      to the way Select2 interacts with the page by modifying the core adapters.
+      Most third-party plugins should provide decorators (used to wrap adapters)
+      and custom adpaters that you can use.
+    </p>
+
+    <p>
+      Each adapter contains a set of methods which will must always be defined.
+      Along with the global methods that all adapters must implement, these
+      methods must be implemented.
+    </p>
+
+    <h2>
+      All adapters
+    </h2>
+
+    <p>
+      All adapters must implement a set of methods that Select2 will use to
+      display them and bind any internal events.
+    </p>
+
+<pre class="prettyprint linenums">
+// The basic HTML that should be rendered by Select2. A jQuery or DOM element
+// should be returned, which will automatically be placed by Select2 within the
+// DOM.
+//
+// @returns A jQuery or DOM element that contains any elements that must be
+//   rendered by Select2.
+Adapter.render = function () {
+  return $jq;
+};
+
+// Bind to any Select2 or DOM events.
+//
+// @param container The Select2 object that is bound to the jQuery element.  You
+//   can listen to Select2 events with `on` and trigger Select2 events using the
+//   `trigger` method.
+// @param $container The jQuery DOM node that all default adapters will be
+//   rendered within.
+Adapter.bind = function (container, $container) { };
+
+// Position the DOM element within the Select2 DOM container, or in another
+// place. This allows adapters to be located outside of the Select2 DOM,
+// such as at the end of the document or in a specific place within the Select2
+// DOM node.
+//
+// Note: This method is not called on data adapters.
+//
+// @param $rendered The rendered DOM element that was returned from the call to
+//   `render`. This may have been modified by Select2, but the root element
+//   will always be the same.
+// @param $defaultContainer The default container that Select2 will typically
+//   place the rendered DOM element within. For most adapters, this is the
+//   Select2 DOM element.
+Adapter.position = function ($rendered, $defaultContainer) { };
+
+// Destroy any events or DOM elements that have been created.
+// This is called when `select2("destroy")` is called on an element.
+Adapter.destroy = function () { };
+</pre>
+
+    <h2 id="selectionAdapter">
+      Container (selection)
+    </h2>
+
+    <p>
+      The selection is what is shown to the user as a replacement of the
+      standard <code>&lt;select&gt;</code> box. It controls the display of the
+      selection option(s), as well anything else that needs to be embedded
+      within the container, such as a search box.
+    </p>
+
+    <dl class="dl-horizontal">
+      <dt>Key</dt>
+      <dd>
+        <code>selectionAdapter</code>
+      </dd>
+
+      <dt>Default</dt>
+      <dd>
+        <code title="select2/selection/single">SingleSelection</code> or
+        <code title="select2/selection/multiple">MultipleSelection</code>
+      </dd>
+
+      <dt>Base</dt>
+      <dd>
+        <code title="select2/selection/base">BaseSelection</code>
+      </dd>
+    </dl>
+
+<pre class="prettyprint linenums">
+// Update the selected data.
+//
+// @param data An array of data objects that have been generated by the data
+//   adapter. If no objects should be selected, an empty array will be passed.
+//
+// Note: An array will always be passed into this method, even if Select2 is
+// attached to a source which only accepts a single selection.
+SelectionAdapter.update = function (data) { };
+</pre>
+
+    <h2 id="dataAdapter">
+      Data set
+    </h2>
+
+    <p>
+      The data set is what Select2 uses to generate the possible results that
+      can be selected, as well as the currently selected results.
+    </p>
+
+    <dl class="dl-horizontal">
+      <dt>Key</dt>
+      <dd>
+        <code>dataAdapter</code>
+      </dd>
+
+      <dt>Default</dt>
+      <dd>
+        <code title="select2/data/select">SelectAdapter</code>
+      </dd>
+
+      <dt>Base</dt>
+      <dd>
+        <code title="select2/data/base">BaseAdapter</code>
+      </dd>
+    </dl>
+
+<pre class="prettyprint linenums">
+// Get the currently selected options. This is called when trying to get the
+// initial selection for Select2, as well as when Select2 needs to determine
+// what options within the results are selected.
+//
+// @param callback A function that should be called when the current selection
+//   has been retrieved. The first paramter to the function should be an array
+//   of data objects.
+DataAdapter.current = function (callback) {
+  callback(currentData);
+}
+
+// Get a set of options that are filtered based on the parameters that have
+// been passed on in.
+//
+// @param params An object containing any number of parameters that the query
+//   could be affected by. Only the core parameters will be documented.
+// @param params.term A user-supplied term. This is typically the value of the
+//   search box, if one exists, but can also be an empty string or null value.
+// @param params.page The specific page that should be loaded. This is typically
+//   provided when working with remote data sets, which rely on pagination to
+//   determine what objects should be displayed.
+// @param callback The function that should be called with the queried results.
+DataAdapter.query = function (params, callback) {
+  callback(queryiedData);
+}
+</pre>
+
+    <h2 id="dropdownAdapter">
+      Dropdown
+    </h2>
+
+    <p>
+      The dropdown adapter defines the main container that the dropdown should
+      be held in. <strong>It does not define any extra methods that can be used
+      for decorators</strong>, but it is common for decorators to attach to the
+      <code>render</code> and <code>position</code> methods to alter how the
+      dropdown is altered and positioned.
+    </p>
+
+    <dl class="dl-horizontal">
+      <dt>Key</dt>
+      <dd>
+        <code>dropdownAdapter</code>
+      </dd>
+
+      <dt>Default</dt>
+      <dd>
+        <code title="select2/dropdown">DropdownAdapter</code>
+      </dd>
+    </dl>
+
+    <h2 id="resultsAdapter">
+      Results
+    </h2>
+
+    <p>
+      The results adapter controls the list of results that the user can select
+      from. While the results adapter does not define any additional methods
+      that must be implemented, it makes extensive use of the Select2 event
+      system for cotrolling the display of results and messages.
+    </p>
+
+    <dl class="dl-horizontal">
+      <dt>Key</dt>
+      <dd>
+        <code>resultsAdapter</code>
+      </dd>
+
+      <dt>Default</dt>
+      <dd>
+        <code title="select2/results">ResultsAdapter</code>
+      </dd>
+    </dl>
   </section>
 </div>
 

src/js/select2/i18n/en.js

@@ -17,11 +17,7 @@ define(function () {
     inputTooShort: function (args) {
       var remainingChars = args.minimum - args.input.length;
 
-      var message = 'Please enter ' + remainingChars + ' or more character';
-
-      if (remainingChars != 1) {
-        message += 's';
-      }
+      var message = 'Please enter ' + remainingChars + ' or more characters';
 
       return message;
     },