Continued work on the documentation
This commit is contained in:
Kevin Brown
parent
10536370de
commit
78ee1bc01e
@ -69,6 +69,12 @@ $(document).ready(function() {
|
||||
|
||||
<script type="text/x-example-code" class="js-code-multiple">
|
||||
$(".js-example-basic-multiple").select2();
|
||||
|
||||
<select class="js-example-basic-multiple" multiple="multiple">
|
||||
<option value="AL">Alabama</option>
|
||||
...
|
||||
<option value="WY">Wyoming</option>
|
||||
</select>
|
||||
</script>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
@ -5,7 +5,347 @@ slug: options
|
||||
---
|
||||
|
||||
<div class="container">
|
||||
<section id="">
|
||||
<section id="core">
|
||||
<div class="page-header">
|
||||
<h1>Core options</h1>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h2>
|
||||
Display
|
||||
</h2>
|
||||
|
||||
<h3 id="placeholder">
|
||||
Placeholders
|
||||
</h3>
|
||||
|
||||
<p>
|
||||
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
|
||||
<a href="examples.html#placeholders">example page</a>.
|
||||
</p>
|
||||
|
||||
<div class="row">
|
||||
<div class="col-sm-4">
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Key</dt>
|
||||
<dd>
|
||||
<code>placeholder</code>
|
||||
</dd>
|
||||
|
||||
<dt>Value</dt>
|
||||
<dd>string or object</dd>
|
||||
</dl>
|
||||
|
||||
<hr />
|
||||
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Adapter</dt>
|
||||
<dd>
|
||||
<code title="select2/selection/base">SelectionAdapter</code>
|
||||
</dd>
|
||||
|
||||
<dt>Decorator</dt>
|
||||
<dd>
|
||||
<code title="select2/selection/placeholder">Placeholder</code>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
|
||||
<div class="col-sm-8">
|
||||
<div class="alert alert-warning">
|
||||
<strong>Heads up!</strong>
|
||||
Because browsers assume that the first <code>option</code> in
|
||||
single-value select boxes is selected, you must add an empty
|
||||
<code><option></option></code> tag that the placeholder
|
||||
should use, or it will not work.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
If the <strong>value is a string</strong>, the placeholder will be
|
||||
displayed when a <strong>blank option</strong> is used as the placeholder.
|
||||
The <strong>value</strong> will be the message to show to users as the
|
||||
placeholders.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
If the <strong>value is an object</strong>, the object should be
|
||||
compatible with Select2's internal objects. The <code>id</code> should
|
||||
be the id to look for when determining if the placeholder should be
|
||||
displayed. The <code>text</code> should be the placeholder to display
|
||||
when that option is selected.
|
||||
</p>
|
||||
|
||||
<div class="alert alert-info">
|
||||
You <strong>pass in an object</strong> when you are using a framework that
|
||||
<strong>creates its own placeholder option</strong>. The
|
||||
<strong>id</strong> should be the same as the <code>value</code>
|
||||
attribute on the <code>option</code>.
|
||||
</div>
|
||||
|
||||
<h3 id="translation">
|
||||
Internationalization (Language support)
|
||||
</h3>
|
||||
|
||||
<p>
|
||||
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
|
||||
<a href="community.html#translations">translated into many languages</a>
|
||||
by contributors to Select2, but you can also provide your own
|
||||
translations.
|
||||
</p>
|
||||
|
||||
<div class="row">
|
||||
<div class="col-sm-4">
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Key</dt>
|
||||
<dd><code>language</code></dd>
|
||||
|
||||
<dt>Value</dt>
|
||||
<dd>object or string</dd>
|
||||
</dl>
|
||||
|
||||
<hr />
|
||||
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Module</dt>
|
||||
<dd>
|
||||
<code title="select2/translation">Translation</code>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
|
||||
<div class="col-sm-8">
|
||||
<p class="alert alert-warning">
|
||||
<strong>Heads up!</strong> When using translations provided by Select2,
|
||||
you must make sure to include the translation file in your page after
|
||||
Select2.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
You can include your own translations by providing an object similar to
|
||||
the one below.
|
||||
</p>
|
||||
|
||||
<pre class="prettyprint">
|
||||
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...";
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
|
||||
<h2>
|
||||
Results
|
||||
</h2>
|
||||
|
||||
<p>
|
||||
Select2 can work on many different data sets ranging from local options,
|
||||
the same way that a <code><select></code> typically works, from
|
||||
remove options where a server generates the results that users can select
|
||||
from.
|
||||
</p>
|
||||
|
||||
<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>
|
||||
|
||||
<h3 id="ajax">
|
||||
AJAX
|
||||
</h3>
|
||||
|
||||
<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">
|
||||
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;
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
</p>
|
||||
|
||||
<h3 id="tags">
|
||||
Tags
|
||||
</h3>
|
||||
|
||||
<p>
|
||||
Users can create their own options based on the text that they have
|
||||
entered.
|
||||
</p>
|
||||
|
||||
<div class="row">
|
||||
<div class="col-sm-6">
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Key</dt>
|
||||
<dd><code>tags</code></dd>
|
||||
|
||||
<dt>Value</dt>
|
||||
<dd>boolean / array of objects</dd>
|
||||
</dl>
|
||||
</div>
|
||||
|
||||
<div class="col-sm-6">
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Adapter</dt>
|
||||
<dd>
|
||||
<code title="select2/data/base">DataAdapter</code>
|
||||
</dd>
|
||||
|
||||
<dt>Decorator</dt>
|
||||
<dd>
|
||||
<code title="select2/data/tags">Tags</code>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
If the <code>tags</code> 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.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<strong>For backwards compatibility</strong>, if an array of objects is
|
||||
passed in with the <code>tags</code> option, the options will be
|
||||
automatically created and the user will be able to select from them.
|
||||
This is the <strong>same as how <a href="#data">array data</a>
|
||||
works</strong>, and has similar limitations.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section id="adapters">
|
||||
<div class="page-header">
|
||||
<h1>Adapters</h1>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<script type="text/javascript">
|
||||
prettyPrint();
|
||||
</script>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user