Reorganize and expand AJAX documentation

pages/06.data-sources/02.ajax/docs.md

@@ -1,5 +1,7 @@
 ---
 title: Ajax (remote data)
+metadata:
+    description: Select2 provides extensive support for populating dropdown items from a remote data source.
 taxonomy:
     category: docs
 process:
@@ -7,98 +9,58 @@ process:
 never_cache_twig: true
 ---
 
-Select2 comes with AJAX support built in, using jQuery's AJAX methods. In this example, we can search for repositories using GitHub's API.
+Select2 comes with AJAX support built in, using jQuery's AJAX methods. In this example, we can search for repositories using GitHub's API:
 
-<select class="js-example-data-ajax form-control">
-  <option value="3620194" selected="selected">select2/select2</option>
-</select>
+<select class="js-example-data-ajax form-control"></select>
 
-When using Select2 with remote data, the HTML required for the `select` is the same as any other Select2. If you need to provide default selections, you just need to include an `option` for each selection that contains the value and text that should be displayed.
+**In your HTML:**
 
 ```
-<select class="js-data-example-ajax">
-  <option value="3620194" selected="selected">select2/select2</option>
-</select>
+<select class="js-data-example-ajax"></select>
 ```
 
-You can configure how Select2 searches for remote data using the `ajax` option:
+**In your Javascript:**
 
-<pre data-fill-from=".js-code-placeholder"></pre>
-
-<script type="text/javascript" class="js-code-placeholder">
-
-$(".js-example-data-ajax").select2({
+```
+$('.js-example-data-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, params) {
-      // 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, except to indicate that infinite
-      // scrolling can be used
-      params.page = params.page || 1;
-
-      return {
-        results: data.items,
-        pagination: {
-          more: (params.page * 30) < data.total_count
-        }
-      };
-    },
-    cache: true
-  },
-  escapeMarkup: function (markup) { return markup; }, // let our custom formatter work
-  minimumInputLength: 1,
-  templateResult: formatRepo,
-  templateSelection: formatRepoSelection
-});
-
-function formatRepo (repo) {
-  if (repo.loading) return repo.text;
-
-  var markup = "<div class='select2-result-repository clearfix'>" +
-    "<div class='select2-result-repository__avatar'><img src='" + repo.owner.avatar_url + "' /></div>" +
-    "<div class='select2-result-repository__meta'>" +
-      "<div class='select2-result-repository__title'>" + repo.full_name + "</div>";
-
-  if (repo.description) {
-    markup += "<div class='select2-result-repository__description'>" + repo.description + "</div>";
+    url: 'https://api.github.com/search/repositories',
+    dataType: 'json'
+    // Additional AJAX parameters go here; see the end of this chapter for the full code of this example
   }
+});
+```
 
-  markup += "<div class='select2-result-repository__statistics'>" +
-    "<div class='select2-result-repository__forks'><i class='fa fa-flash'></i> " + repo.forks_count + " Forks</div>" +
-    "<div class='select2-result-repository__stargazers'><i class='fa fa-star'></i> " + repo.stargazers_count + " Stars</div>" +
-    "<div class='select2-result-repository__watchers'><i class='fa fa-eye'></i> " + repo.watchers_count + " Watchers</div>" +
-  "</div>" +
-  "</div></div>";
+You can configure how Select2 searches for remote data using the `ajax` option.  Select2 will pass any options in the `ajax` object to jQuery's `$.ajax` function, or the `transport` function you specify.
 
-  return markup;
-}
+>>> For **remote data sources only**, Select2 does not create a new `<option>` element until the item has been selected for the first time.  This is done for performance reasons.  Once an `<option>` has been created, it will remain in the DOM even if the selection is later changed.
 
-function formatRepoSelection (repo) {
-  return repo.full_name || repo.text;
-}
-</script>
+## Request parameters
 
-Select2 will pass any options in the `ajax` object to jQuery's `$.ajax` function, or the `transport` function you specify.
+Select2 will issue a request to the specified URL when the user opens the control (unless there is a `minimumInputLength` set), and again every time the user types in the search box.  By default, it will send the following as query string parameters:
 
->>> Select2 expects results from the remote endpoint to be filtered on the **server side**. If server-side filtering is not possible, you may be interested in using Select2's <a href="examples.html#data-array">support for data arrays</a> instead.
+- `term` : The current search term in the search box.
+- `q`    : Contains the same contents as `term`.
+- `_type`: A "request type".  Will usually be `query`, but changes to `query_append` for paginated requests.
+- `page` : The current page number to request.  Only sent for paginated (infinite scrolling) searches.
 
-## Rate-limiting requests
+For example, Select2 might issue a request that looks like: `https://api.github.com/search/repositories?term=sel&_type=query&q=sel`.
 
-You can tell Select2 to wait until the user has finished typing their search term before triggering the AJAX request.  Simply use the `ajax.delay` configuration option to tell Select2 how long to wait after a user has stopped typing before sending the request:
+Sometimes, you may need to add additional query parameters to the request.  You can modify the parameters that are sent with the request by overriding the `ajax.data` option:
 
 ```
-$('select').select2({
+$('#mySelect2').select2({
   ajax: {
-    delay: 250 // wait 250 milliseconds before triggering the request
+    url: 'https://api.github.com/search/repositories',
+    data: function (params) {
+      var query = {
+        search: params.term,
+        page: params.page
+      }
+
+      // Query parameters will be ?search=[term]&page=[page]
+      return query;
+    }
   }
 });
 ```
@@ -108,10 +70,11 @@ $('select').select2({
 You can use the `ajax.processResults` option to transform the data returned by your API into the format expected by Select2:
 
 ```
-$('select').select2({
+$('#mySelect2').select2({
   ajax: {
     url: '/example/api',
     processResults: function (data) {
+      // Tranforms the top-level key of the response object from 'items' to 'results'
       return {
         results: data.items
       };
@@ -120,30 +83,30 @@ $('select').select2({
 });
 ```
 
-## Default values
+>>> Select2 expects results from the remote endpoint to be filtered on the **server side**. If server-side filtering is not possible, you may be interested in using Select2's [support for data arrays](/data-sources/arrays) instead.
+
+## Default (pre-selected) values
 
 You may wish to set a pre-selected default value for a Select2 control that receives its data from an AJAX request.
 
-To do this, please refer to the following Stack Overflow answer: [Select2 4.0.0 initial value with AJAX](http://stackoverflow.com/q/30316586/359284#30328989).
+To provide default selections, you may include an `<option>` for each selection that contains the value and text that should be displayed:
+
+```
+<select class="js-example-data-ajax form-control">
+  <option value="3620194" selected="selected">select2/select2</option>
+</select>
+```
 
-## Additional request parameters
+To achieve this programmatically, you will need to [create and append a new `Option`](/programmatic-control/add-select-clear-items).
 
-By default, Select2 will send the search query term as well as the pagination data as query parameters in requests.
+## Rate-limiting requests
 
-Sometimes, you may need to add additional query parameters to the request.  You can modify the parameters that are sent with the request by overriding the `ajax.data` option:
+You can tell Select2 to wait until the user has finished typing their search term before triggering the AJAX request.  Simply use the `ajax.delay` configuration option to tell Select2 how long to wait after a user has stopped typing before sending the request:
 
 ```
-$('select').select2({
+$('#mySelect2').select2({
   ajax: {
-    data: function (params) {
-      var query = {
-        search: params.term,
-        page: params.page
-      }
-
-      // Query parameters will be ?search=[term]&page=[page]
-      return query;
-    }
+    delay: 250 // wait 250 milliseconds before triggering the request
   }
 });
 ```
@@ -153,7 +116,7 @@ $('select').select2({
 If there isn't a single url for your search results, or you need to call a function to determine the url to use, you can specify a callback for the `ajax.url` option to generate the url. The current search query will be passed in through the `params` option:
 
 ```
-$('select').select2({
+$('#mySelect2').select2({
   ajax: {
     url: function (params) {
       return '/some/url/' + params.term;
@@ -167,7 +130,7 @@ $('select').select2({
 Select2 uses the transport method defined in `ajax.transport` to send requests to your API. By default this transport method is `jQuery.ajax`, but it can be easily overridden:
 
 ```
-$('select').select2({
+$('#mySelect2').select2({
   ajax: {
     transport: function (params, success, failure) {
       var request = new AjaxRequest(params.url, params);
@@ -251,3 +214,75 @@ ajax: {
   }
 }
 ```
+
+## Additional examples
+
+This code powers the Github example presented at the beginning of this chapter:
+
+<pre data-fill-from=".js-code-placeholder"></pre>
+
+<script type="text/javascript" class="js-code-placeholder">
+
+$(".js-example-data-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, params) {
+      // 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, except to indicate that infinite
+      // scrolling can be used
+      params.page = params.page || 1;
+
+      return {
+        results: data.items,
+        pagination: {
+          more: (params.page * 30) < data.total_count
+        }
+      };
+    },
+    cache: true
+  },
+  placeholder: 'Search for a repository',
+  escapeMarkup: function (markup) { return markup; }, // let our custom formatter work
+  minimumInputLength: 1,
+  templateResult: formatRepo,
+  templateSelection: formatRepoSelection
+});
+
+function formatRepo (repo) {
+  if (repo.loading) {
+    return repo.text;
+  }
+
+  var markup = "<div class='select2-result-repository clearfix'>" +
+    "<div class='select2-result-repository__avatar'><img src='" + repo.owner.avatar_url + "' /></div>" +
+    "<div class='select2-result-repository__meta'>" +
+      "<div class='select2-result-repository__title'>" + repo.full_name + "</div>";
+
+  if (repo.description) {
+    markup += "<div class='select2-result-repository__description'>" + repo.description + "</div>";
+  }
+
+  markup += "<div class='select2-result-repository__statistics'>" +
+    "<div class='select2-result-repository__forks'><i class='fa fa-flash'></i> " + repo.forks_count + " Forks</div>" +
+    "<div class='select2-result-repository__stargazers'><i class='fa fa-star'></i> " + repo.stargazers_count + " Stars</div>" +
+    "<div class='select2-result-repository__watchers'><i class='fa fa-eye'></i> " + repo.watchers_count + " Watchers</div>" +
+  "</div>" +
+  "</div></div>";
+
+  return markup;
+}
+
+function formatRepoSelection (repo) {
+  console.log(repo);
+  return repo.full_name || repo.text;
+}
+</script>

pages/06.data-sources/03.arrays/docs.md

@@ -60,6 +60,8 @@ $(".js-example-data-array-selected").select2({
 })
 </script>
 
+Unlike the case of items supplied by [AJAX data sources](/data-sources/ajax), items supplied as an array will be immediately rendered as `<option>` elements in the target `<select>` control.
+
 ## Backwards compatibility with the `tags` option
 
 In Select2 v3.5, this option was called `tags`.  However in version 4.0, `tags` now handles the [tagging feature](/tagging).