From 78ee1bc01ec7c6e7bc14040a3914daba82587e82 Mon Sep 17 00:00:00 2001 From: Kevin Brown Date: Sat, 8 Nov 2014 16:48:57 -0500 Subject: [PATCH] Continued work on the documentation --- docs/examples.html | 6 + docs/options.html | 342 ++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 347 insertions(+), 1 deletion(-) diff --git a/docs/examples.html b/docs/examples.html index 0debc782..156dfd14 100644 --- a/docs/examples.html +++ b/docs/examples.html @@ -69,6 +69,12 @@ $(document).ready(function() { diff --git a/docs/options.html b/docs/options.html index 0bafb3b7..a5b60849 100644 --- a/docs/options.html +++ b/docs/options.html @@ -5,7 +5,347 @@ slug: options ---
-
+
+
+

Core options

+
+

+ Select2 supports a small subset of options in every build that is + generated. Each option typically has a decorator that is required that + wraps an adapter, adding support for the option. This is only required + when a custom adapter is being used, as Select2 will build the required + adapters by default. +

+ +

+ Display +

+ +

+ Placeholders +

+ +

+ Select2 can display a placeholder for a single-value select that will + replace an option, or be shown when no options are selected for + multiple-value selects. You can find an example on the + example page. +

+ +
+
+
+
Key
+
+ placeholder +
+ +
Value
+
string or object
+
+ +
+ +
+
Adapter
+
+ SelectionAdapter +
+ +
Decorator
+
+ Placeholder +
+
+
+ +
+
+ Heads up! + Because browsers assume that the first option in + single-value select boxes is selected, you must add an empty + <option></option> tag that the placeholder + should use, or it will not work. +
+
+
+ +

+ If the value is a string, the placeholder will be + displayed when a blank option is used as the placeholder. + The value will be the message to show to users as the + placeholders. +

+ +

+ If the value is an object, the object should be + compatible with Select2's internal objects. The id should + be the id to look for when determining if the placeholder should be + displayed. The text should be the placeholder to display + when that option is selected. +

+ +
+ You pass in an object when you are using a framework that + creates its own placeholder option. The + id should be the same as the value + attribute on the option. +
+ +

+ Internationalization (Language support) +

+ +

+ Messages will be displayed to users when necessary, such as 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. +

+ +
+
+
+
Key
+
language
+ +
Value
+
object or string
+
+ +
+ +
+
Module
+
+ Translation +
+
+
+ +
+

+ Heads up! When using translations provided by Select2, + you must make sure to include the translation file in your page after + Select2. +

+
+
+ +

+ When a string is passed in as the language, Select2 will try to resolve + it into a language file. This allows you to specify your own language + files, which must be defined as an AMD module. If the language file + cannot be found, Select2 will assume it is a language code controlled by + Select2, and it will try to load the translations for that language + instead. +

+ +

+ You can include your own translations by providing an object similar to + the one below. +

+ +
+language: {
+  // You can find all of the options in the language files provided in the
+  // build. They all must be functions that return the string that should be
+  // displayed.
+  inputTooShort: function () {
+    return "You must enter more characters...";
+  }
+}
+
+ +

+ Results +

+ +

+ Select2 can work on many different data sets ranging from local options, + the same way that a <select> typically works, from + remove options where a server generates the results that users can select + from. +

+ +

+ Array +

+ +

+ Select2 allows creating the results based on an array of data objects that + is included when initializing Select2. +

+ +
+
+
+
Key
+
data
+ +
Value
+
array of objects
+
+
+ +
+
+
Adapter
+
+ ArrayAdapter +
+
+
+
+ +

+ The objects that the users can select from should be passed as an array + with each object containing id and text + properties. +

+ +

+ AJAX +

+ +

+ Select2 allows searching for results from remote data sources using AJAX + requests. +

+ +
+
+
+
Key
+
ajax
+ +
Value
+
object
+
+
+ +
+
+
Adapter
+
+ AjaxAdapter +
+
+
+
+ +

+ All options passed to this option 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 array of objects that will be rendered by Select2.
+  processResults: function (data) {
+    return data;
+  }
+}
+
+

+ +

+ Tags +

+ +

+ Users can create their own options based on the text that they have + entered. +

+ +
+
+
+
Key
+
tags
+ +
Value
+
boolean / array of objects
+
+
+ +
+
+
Adapter
+
+ DataAdapter +
+ +
Decorator
+
+ Tags +
+
+
+
+ +

+ If the tags option is passed into Select2, if a user types + anything into the search box which doesn't already exist, it will be + displayed at the top and the user will be able to select it. +

+ +

+ For backwards compatibility, if an array of objects is + passed in with the tags option, the options will be + automatically created and the user will be able to select from them. + This is the same as how array data + works, and has similar limitations. +

+
+ +
+
+

Adapters

+
+ +