RetailCRM-Mirror/select2
1
0
Fork 0
mirror of synced 2024-11-29 08:06:03 +03:00
Code Issues Projects Releases Wiki Activity

begin integrating the "old options" page

Browse Source
This commit is contained in:
alexweissman 2017-09-03 19:02:00 -04:00
parent 38286400ca
commit 94c5c3a3fe
36 changed files with 1203 additions and 1816 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
pages/02.configuration/docs.md
View File

@ -51,7 +51,7 @@ release's documentation</a> should cover the gaps here for the time being.
typically doesn't need to be changed, but is available for situations where module names typically doesn't need to be changed, but is available for situations where module names
may change as a result of certain build environments.</p> may change as a result of certain build environments.</p>
<p>Default value: <strong>&quot;./&quot;</strong></p> <p>Default value: `select2/`</p>
</td> </td>
</tr> </tr>
<tr id="amdLanguageBase"> <tr id="amdLanguageBase">
@ -62,7 +62,7 @@ release's documentation</a> should cover the gaps here for the time being.
option typically doesn't need to be changed, but is available for situations where module option typically doesn't need to be changed, but is available for situations where module
names may change as a result of certain build environments.</p> names may change as a result of certain build environments.</p>
<p>Default value: <strong>&quot;./i18n/&quot;</strong></p> <p>Default value: `select2/i18n/`</p>
</td> </td>
</tr> </tr>
<tr id="closeOnSelect"> <tr id="closeOnSelect">
@ -73,7 +73,7 @@ release's documentation</a> should cover the gaps here for the time being.
making it easy to quickly select multiple items. <em>Note that this option is only making it easy to quickly select multiple items. <em>Note that this option is only
applicable to multi-select controls</em>.</p> applicable to multi-select controls</em>.</p>
<p>Default value: <strong>true</strong></p> <p>Default value: `true`</p>
</td> </td>
</tr> </tr>
<tr id="containerCss"> <tr id="containerCss">
@ -132,7 +132,7 @@ release's documentation</a> should cover the gaps here for the time being.
</tr> </tr>
<tr id="dropdownParent"> <tr id="dropdownParent">
<td>dropdownParent</td> <td>dropdownParent</td>
<td></td> <td>jQuery selector or DOM node</td>
<td></td> <td></td>
</tr> </tr>
<tr id="escapeMarkup"> <tr id="escapeMarkup">
@ -147,12 +147,13 @@ release's documentation</a> should cover the gaps here for the time being.
</tr> </tr>
<tr id="language"> <tr id="language">
<td>language</td> <td>language</td>
<td></td> <td>string or object</td>
<td></td> <td></td>
</tr> </tr>
<tr id="matcher"> <tr id="matcher">
<td>matcher</td> <td>matcher</td>
<td></td> <td>A callback taking search <code>params</code> and the
<code>data</code> object.</td>
<td></td> <td></td>
</tr> </tr>
<tr id="maximumInputLength"> <tr id="maximumInputLength">
@ -198,14 +199,14 @@ release's documentation</a> should cover the gaps here for the time being.
</tr> </tr>
<tr id="multiple"> <tr id="multiple">
<td>multiple</td> <td>multiple</td>
<td></td> <td>boolean</td>
<td> <td>
This option enables multi-select (pillbox) mode. Select2 will automatically map the value of the `multiple` HTML attribute to this option during initialization. This option enables multi-select (pillbox) mode. Select2 will automatically map the value of the `multiple` HTML attribute to this option during initialization.
</td> </td>
</tr> </tr>
<tr id="placeholder"> <tr id="placeholder">
<td>placeholder</td> <td>placeholder</td>
<td></td> <td>string or object</td>
<td></td> <td></td>
</tr> </tr>
<tr id="query"> <tr id="query">
@ -237,17 +238,17 @@ release's documentation</a> should cover the gaps here for the time being.
</tr> </tr>
<tr id="tags"> <tr id="tags">
<td>tags</td> <td>tags</td>
<td></td> <td>boolean / array of objects</td>
<td></td> <td></td>
</tr> </tr>
<tr id="templateResult"> <tr id="templateResult">
<td>templateResult</td> <td>templateResult</td>
<td>function</td> <td>callback</td>
<td></td> <td></td>
</tr> </tr>
<tr id="templateSelection"> <tr id="templateSelection">
<td>templateSelection</td> <td>templateSelection</td>
<td>function</td> <td>callback</td>
<td></td> <td></td>
</tr> </tr>
<tr id="theme"> <tr id="theme">

115
pages/03.appearance/01.markup/docs.md
View File

@ -1,115 +0,0 @@
---
title: Basic markup
taxonomy:
category: docs
process:
twig: true
never_cache_twig: true
---
A standard `<select>` box contains any number of `<option>` elements. Each of these is rendered as an option in the dropdown menu. Select2 preserves this behavior when initialized on a `<select>` element that contains `<option>` elements.
## Disabling a Select2 control
Select2 will respond to the <code>disabled</code> attribute on `<select>` elements. You can also initialize Select2 with `disabled: true` to get the same effect.
<div class="s2-example">
<p>
<select class="js-example-disabled js-states form-control" disabled="disabled"></select>
</p>
<p>
<select class="js-example-disabled-multi js-states form-control" multiple="multiple" disabled="disabled"></select>
</p>
<div class="btn-group btn-group-sm" role="group" aria-label="Programmatic enabling and disabling">
<button type="button" class="js-programmatic-enable btn btn-default">
Enable
</button>
<button type="button" class="js-programmatic-disable btn btn-default">
Disable
</button>
</div>
</div>
<pre data-fill-from=".js-code-disabled"></pre>
<script type="text/javascript" class="js-code-disabled">
$(".js-example-disabled").select2();
$(".js-example-disabled-multi").select2();
$(".js-programmatic-enable").on("click", function () {
$(".js-example-disabled").prop("disabled", false);
$(".js-example-disabled-multi").prop("disabled", false);
});
$(".js-programmatic-disable").on("click", function () {
$(".js-example-disabled").prop("disabled", true);
$(".js-example-disabled-multi").prop("disabled", true);
});
</script>
## Labels
You can, and should, use a `<label>` with Select2, just like any other `<select>` element.
<div class="s2-example">
<p>
<label for="id_label_single">
Click this to focus the single select element
<select class="js-example-basic-single js-states form-control" id="id_label_single"></select>
</label>
</p>
<p>
<label for="id_label_multiple">
Click this to focus the multiple select element
<select class="js-example-basic-multiple js-states form-control" id="id_label_multiple" multiple="multiple"></select>
</label>
</p>
</div>
```
<label for="id_label_single">
Click this to highlight the single select element
<select class="js-example-basic-single js-states form-control" id="id_label_single"></select>
</label>
<label for="id_label_multiple">
Click this to highlight the multiple select element
<select class="js-example-basic-multiple js-states form-control" id="id_label_multiple" multiple="multiple"></select>
</label>
```
<script type="text/javascript">
$.fn.select2.amd.require([
"select2/core",
"select2/utils"
], function (Select2, Utils, oldMatcher) {
var $basicSingle = $(".js-example-basic-single");
var $basicMultiple = $(".js-example-basic-multiple");
$.fn.select2.defaults.set("width", "100%");
$basicSingle.select2();
$basicMultiple.select2();
function formatState (state) {
if (!state.id) {
return state.text;
}
var $state = $(
'<span>' +
'<img src="vendor/images/flags/' +
state.element.value.toLowerCase() +
'.png" class="img-flag" /> ' +
state.text +
'</span>'
);
return $state;
};
});
</script>

72
pages/03.appearance/02.theming/docs.md
View File

@ -1,72 +0,0 @@
---
title: Theming
taxonomy:
category: docs
process:
twig: true
never_cache_twig: true
---
## Theme support
Select2 supports custom themes using the `theme` option so you can style Select2 to match the rest of your application.
These examples use the `classic` theme, which matches the old look of Select2.
<div class="s2-example">
<p>
<select class="js-example-theme-single js-states form-control">
</select>
</p>
<p>
<select class="js-example-theme-multiple js-states form-control" multiple="multiple"></select>
</p>
</div>
<pre data-fill-from=".js-code-example-theme"></pre>
<script type="text/javascript" class="js-code-example-theme">
$(".js-example-theme-single").select2({
theme: "classic"
});
$(".js-example-theme-multiple").select2({
theme: "classic"
});
</script>
Various display options of the Select2 component can be changed. You can access the `<option>` element (or `<optgroup>`) and any attributes on those elements using `.element`.
## Responsive design - Percent width
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.
<div class="s2-example">
<p>
<select class="js-example-responsive js-states" style="width: 50%"></select>
</p>
<p>
<select class="js-example-responsive js-states" multiple="multiple" style="width: 75%"></select>
</p>
</div>
```
<select class="js-example-responsive" style="width: 50%"></select>
<select class="js-example-responsive" multiple="multiple" style="width: 75%"></select>
```
<pre data-fill-from=".js-code-example-responsive"></pre>
<script type="text/javascript" class="js-code-example-responsive">
$(".js-example-responsive").select2({
width: 'resolve' // need to override the changed default
});
</script>
>>>> Select2 will do its best to resolve the percent width specified via a CSS class, but it is not always possible. The best way to ensure that Select2 is using a percent based width is to inline the `style` declaration into the tag.

11
pages/03.appearance/chapter.md
View File

@ -1,11 +0,0 @@
---
title: Appearance
taxonomy:
category: docs
---
### Chapter 3
# Appearance
The appearance of your Select2 controls can be customized via the standard HTML attributes for `<select>` elements, as well as various [configuration options](/configuration).

218
pages/03.appearance/docs.md Normal file
View File

@ -0,0 +1,218 @@
---
title: Appearance
taxonomy:
category: docs
process:
twig: true
never_cache_twig: true
---
The appearance of your Select2 controls can be customized via the standard HTML attributes for `<select>` elements, as well as various [configuration options](/configuration).
## Disabling a Select2 control
Select2 will respond to the <code>disabled</code> attribute on `<select>` elements. You can also initialize Select2 with `disabled: true` to get the same effect.
<div class="s2-example">
<p>
<select class="js-example-disabled js-states form-control" disabled="disabled"></select>
</p>
<p>
<select class="js-example-disabled-multi js-states form-control" multiple="multiple" disabled="disabled"></select>
</p>
<div class="btn-group btn-group-sm" role="group" aria-label="Programmatic enabling and disabling">
<button type="button" class="js-programmatic-enable btn btn-default">
Enable
</button>
<button type="button" class="js-programmatic-disable btn btn-default">
Disable
</button>
</div>
</div>
<pre data-fill-from=".js-code-disabled"></pre>
<script type="text/javascript" class="js-code-disabled">
$(".js-example-disabled").select2();
$(".js-example-disabled-multi").select2();
$(".js-programmatic-enable").on("click", function () {
$(".js-example-disabled").prop("disabled", false);
$(".js-example-disabled-multi").prop("disabled", false);
});
$(".js-programmatic-disable").on("click", function () {
$(".js-example-disabled").prop("disabled", true);
$(".js-example-disabled-multi").prop("disabled", true);
});
</script>
## Labels
You can, and should, use a `<label>` with Select2, just like any other `<select>` element.
<div class="s2-example">
<p>
<label for="id_label_single">
Click this to focus the single select element
<select class="js-example-basic-single js-states form-control" id="id_label_single"></select>
</label>
</p>
<p>
<label for="id_label_multiple">
Click this to focus the multiple select element
<select class="js-example-basic-multiple js-states form-control" id="id_label_multiple" multiple="multiple"></select>
</label>
</p>
</div>
```
<label for="id_label_single">
Click this to highlight the single select element
<select class="js-example-basic-single js-states form-control" id="id_label_single"></select>
</label>
<label for="id_label_multiple">
Click this to highlight the multiple select element
<select class="js-example-basic-multiple js-states form-control" id="id_label_multiple" multiple="multiple"></select>
</label>
```
<script type="text/javascript">
$.fn.select2.amd.require([
"select2/core",
"select2/utils"
], function (Select2, Utils, oldMatcher) {
var $basicSingle = $(".js-example-basic-single");
var $basicMultiple = $(".js-example-basic-multiple");
$.fn.select2.defaults.set("width", "100%");
$basicSingle.select2();
$basicMultiple.select2();
function formatState (state) {
if (!state.id) {
return state.text;
}
var $state = $(
'<span>' +
'<img src="vendor/images/flags/' +
state.element.value.toLowerCase() +
'.png" class="img-flag" /> ' +
state.text +
'</span>'
);
return $state;
};
});
</script>
## Container width
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):
<table class="table table-striped table-bordered">
<thead>
<tr>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>"element"</code></td>
<td>
Uses javascript to calculate the width of the source element.
</td>
</tr>
<tr>
<td><code>"style"</code></td>
<td>
Copies the value of the width <code>style</code> attribute set on the source element.
</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>.
</td>
</tr>
<tr>
<td>Anything else</td>
<td>
The value of the <code>width</code> option is directly set as the width of the container.
</td>
</tr>
</tbody>
</table>
## Responsive design - Percent width
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.
<div class="s2-example">
<p>
<select class="js-example-responsive js-states" style="width: 50%"></select>
</p>
<p>
<select class="js-example-responsive js-states" multiple="multiple" style="width: 75%"></select>
</p>
</div>
```
<select class="js-example-responsive" style="width: 50%"></select>
<select class="js-example-responsive" multiple="multiple" style="width: 75%"></select>
```
<pre data-fill-from=".js-code-example-responsive"></pre>
<script type="text/javascript" class="js-code-example-responsive">
$(".js-example-responsive").select2({
width: 'resolve' // need to override the changed default
});
</script>
>>>> Select2 will do its best to resolve the percent width specified via a CSS class, but it is not always possible. The best way to ensure that Select2 is using a percent based width is to inline the `style` declaration into the tag.
## Theme support
Select2 supports custom themes using the `theme` option so you can style Select2 to match the rest of your application.
These examples use the `classic` theme, which matches the old look of Select2.
<div class="s2-example">
<p>
<select class="js-example-theme-single js-states form-control">
</select>
</p>
<p>
<select class="js-example-theme-multiple js-states form-control" multiple="multiple"></select>
</p>
</div>
<pre data-fill-from=".js-code-example-theme"></pre>
<script type="text/javascript" class="js-code-example-theme">
$(".js-example-theme-single").select2({
theme: "classic"
});
$(".js-example-theme-multiple").select2({
theme: "classic"
});
</script>
Various display options of the Select2 component can be changed. You can access the `<option>` element (or `<optgroup>`) and any attributes on those elements using `.element`.

81
pages/04.options/docs.md Normal file
View File

@ -0,0 +1,81 @@
---
title: Options
taxonomy:
category: docs
process:
twig: true
never_cache_twig: true
---
A traditional `<select>` box contains any number of `<option>` elements. Each of these is rendered as an option in the dropdown menu. Select2 preserves this behavior when initialized on a `<select>` element that contains `<option>` elements, converting them into its internal JSON representation:
```
{
"id": "value attribute" || "option text",
"text": "label attribute" || "option text",
"element": HTMLOptionElement
}
```
`<optgroup>` elements will be converted into data objects using the following rules:
```
{
"text": "label attribute",
"children": [ option data object, ... ],
"element": HTMLOptGroupElement
}
```
>>> Options sourced from [other data sources](/data-sources) must conform to this this same internal representation. See ["The Select2 data format"](/data-sources/formats) for details.
## Dropdown option groups
In HTML, `<option>` elements can be grouped by wrapping them with in an `<optgroup>` element:
```
<select>
<optgroup label="Group Name">
<option>Nested option</option>
</optgroup>
</select>
```
Select2 will automatically pick these up and render them appropriately in the dropdown.
### Hierarchical options
Only a single level of nesting is allowed per the HTML specification. If you nest an `<optgroup>` within another `<optgroup>`, Select2 will not be able to detect the extra level of nesting and errors may be triggered as a result.
Furthermore, `<optgroup>` elements **cannot** be made selectable. This is a limitation of the HTML specification and is not a limitation that Select2 can overcome.
If you wish to create a true hierarchy of selectable options, use an `<option>` instead of an `<optgroup>` and [change the style with CSS](http://stackoverflow.com/q/30820215/359284#30948247). Please note that this approach may be considered "less accessible" as it relies on CSS styling, rather than the semantic meaning of `<optgroup>`, to generate the effect.
## Disabling options
Select2 will correctly handle disabled options, both with data coming from a standard select (when the `disabled` attribute is set) and from remote sources, where the object has `disabled: true` set.
<div class="s2-example">
<select class="js-example-disabled-results form-control">
<option value="one">First</option>
<option value="two" disabled="disabled">Second (disabled)</option>
<option value="three">Third</option>
</select>
</div>
<pre data-fill-from=".js-code-disabled-option"></pre>
```
<select class="js-example-disabled-results">
<option value="one">First</option>
<option value="two" disabled="disabled">Second (disabled)</option>
<option value="three">Third</option>
</select>
```
<script type="text/javascript" class="js-code-disabled-option">
var $disabledResults = $(".js-example-disabled-results");
$disabledResults.select2();
</script>

80
pages/04.searching/docs.md
View File

@ -1,80 +0,0 @@
---
title: Search
taxonomy:
category: docs
process:
twig: true
never_cache_twig: true
---
The appearance and behavior of the search control can be easily customized with Select2.
## Customizing how results are matched
You may customize the way that Select2 matches search terms by passing a callback to the `matcher` option. This example matches results only if the term appears in the beginning of the string as opposed to anywhere:
<div class="s2-example">
<select class="js-example-matcher-start js-states form-control"></select>
</div>
<pre data-fill-from=".js-code-example-matcher"></pre>
<script type="text/javascript" class="js-code-example-matcher">
function matchStart (term, text) {
if (text.toUpperCase().indexOf(term.toUpperCase()) == 0) {
return true;
}
return false;
}
$.fn.select2.amd.require(['select2/compat/matcher'], function (oldMatcher) {
$(".js-example-matcher-start").select2({
matcher: oldMatcher(matchStart)
})
});
</script>
>>> This custom matcher uses a [compatibility module](/configuration/deprecated) that is only bundled in the [full version of Select2](/getting-started/builds). You also have the option of using a <a href="options.html#matcher">more complex matcher</a>.
## Limiting search term length
You may limit the maximum length of search terms by using the `maximumInputLength` option:
```
$('select').select2({
maximumInputLength: 20 // only allow terms up to 20 characters long
});
```
## Limiting display of the search box to large result sets
The `minimumResultsForSearch` option determines the minimum number of results required in the initial population of the dropdown to display the search box.
This option is useful for cases where local data is used with a small result set, and the search box would simply be a waste of screen real estate. Set this value to -1 to permanently hide the search box.
```
$('select').select2({
minimumResultsForSearch: 20 // at least 20 results must be displayed
});
```
## Hiding the search box
Select2 allows you to hide the search box depending on the number of options which are displayed. In this example, we use the value `Infinity` to tell Select2 to never display the search box.
<div class="s2-example">
<select class="js-example-basic-hide-search js-states form-control"></select>
</div>
<pre data-fill-from=".js-code-example-basic-hide-search"></pre>
<script type="text/javascript" class="js-code-example-basic-hide-search">
$(".js-example-basic-hide-search").select2({
minimumResultsForSearch: Infinity
});
</script>

8
pages/09.data-sources/01.formats/docs.md → pages/05.data-sources/01.formats/docs.md
View File

@ -26,12 +26,10 @@ In order to accomplish this, Select2 expects a very specific data format. This
} }
``` ```
Each object should contain, _at a minimum_, an `id` and a `text` property. The `text` property will be displayed by default unless you are using `templateResult` and `templateSelection` to customize the way options and selections are rendered. Each object should contain, _at a minimum_, an `id` and a `text` property. Any additional parameters passed in with data objects will be included on the data objects that Select2 exposes.
The response object may also contain pagination data, if you would like to use the "infinite scroll" feature. This should be specified under the `pagination` key. The response object may also contain pagination data, if you would like to use the "infinite scroll" feature. This should be specified under the `pagination` key.
Any additional parameters passed in with data objects will be included on the data objects that Select2 exposes.
## Transforming data into the required format ## Transforming data into the required format
### Generating `id` properties ### Generating `id` properties
@ -68,7 +66,7 @@ Select2 will attempt to convert anything that is not a string to a string, which
Blank `id`s or an `id` with a value of `0` are not permitted. Blank `id`s or an `id` with a value of `0` are not permitted.
## Grouped options ## Grouped data
When options are to be generated in `<optgroup>` sections, options should be nested under the `children` key of each group object. The label for the group should be specified as the `text` property on the group's corresponding data object. When options are to be generated in `<optgroup>` sections, options should be nested under the `children` key of each group object. The label for the group should be specified as the `text` property on the group's corresponding data object.
@ -108,4 +106,4 @@ When options are to be generated in `<optgroup>` sections, options should be nes
} }
``` ```
>>>> Because Select2 generates an `<optgroup>` when creating nested options, only [a single level of nesting is supported](/dropdown/option-groups). Any additional levels of nesting is not guaranteed to be displayed properly across all browsers and devices. >>>> Because Select2 generates an `<optgroup>` when creating nested options, only [a single level of nesting is supported](/options#dropdown-option-groups). Any additional levels of nesting is not guaranteed to be displayed properly across all browsers and devices.

3
pages/09.data-sources/02.ajax/docs.md → pages/05.data-sources/02.ajax/docs.md
View File

@ -21,8 +21,7 @@ When using Select2 with remote data, the HTML required for the `select` is the s
</select> </select>
``` ```
You can configure how Select2 searches for remote data using the `ajax` option. More information on the individual options You can configure how Select2 searches for remote data using the `ajax` option. More information on the individual options that Select2 handles can be found in the [options documentation for `ajax`](/configuration).
that Select2 handles can be found in the [options documentation for `ajax`](/configuration).
<pre data-fill-from=".js-code-placeholder"></pre> <pre data-fill-from=".js-code-placeholder"></pre>

0
pages/09.data-sources/03.arrays/docs.md → pages/05.data-sources/03.arrays/docs.md
View File

2
pages/09.data-sources/chapter.md → pages/05.data-sources/chapter.md
View File

@ -4,8 +4,6 @@ taxonomy:
category: docs category: docs
--- ---
### Chapter 3
# Data sources # Data sources
In addition to handling `<option>` elements that explicitly appear in your markup, Select2 can also retrieve the results from other data sources such as a remote JSON API or a local Javascript array. In addition to handling `<option>` elements that explicitly appear in your markup, Select2 can also retrieve the results from other data sources such as a remote JSON API or a local Javascript array.

124
pages/05.dropdown/docs.md
View File

@ -1,124 +0,0 @@
---
title: Dropdown
taxonomy:
category: docs
process:
twig: true
never_cache_twig: true
---
This chapter covers the appearance and behavior of the dropdown menu.
## Templating
The appearance of search results in the dropdown can be customized by using the `templateResult` option:
<div class="s2-example">
<select class="js-example-templating js-states form-control"></select>
</div>
<pre data-fill-from=".js-code-example-templating"></pre>
<script type="text/javascript" class="js-code-example-templating">
function formatState (state) {
if (!state.id) {
return state.text;
}
var baseUrl = "{{ url('user://pages/images/flags') }}";
var $state = $(
'<span><img src="' + baseUrl + '/' + state.element.value.toLowerCase() + '.png" class="img-flag" /> ' + state.text + '</span>'
);
return $state;
};
$(".js-example-templating").select2({
templateResult: formatState
});
</script>
## Disabling options
Select2 will correctly handle disabled options, both with data coming from a standard select (when the `disabled` attribute is set) and from remote sources, where the object has <code>disabled: true</code> set.
<div class="s2-example">
<select class="js-example-disabled-results form-control">
<option value="one">First</option>
<option value="two" disabled="disabled">Second (disabled)</option>
<option value="three">Third</option>
</select>
</div>
<pre data-fill-from=".js-code-disabled-option"></pre>
```
<select class="js-example-disabled-results">
<option value="one">First</option>
<option value="two" disabled="disabled">Second (disabled)</option>
<option value="three">Third</option>
</select>
```
<script type="text/javascript" class="js-code-disabled-option">
var $disabledResults = $(".js-example-disabled-results");
$disabledResults.select2();
</script>
## Automatic selection
Select2 can be configured to automatically select the currently highlighted result when the dropdown is closed by using the `selectOnClose` option:
```
$('select').select2({
selectOnClose: true
});
```
## 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:
```
$('select').select2({
closeOnSelect: false
});
```
## Dropdown placement
The `dropdownParent` option allows you to pick an element for the dropdown to be appended to:
```
$('select').select2({
dropdownParent: $('#my_amazing_modal')
});
```
### Using a Select2 control inside a Bootstrap modal
If you're having trouble using the search box inside a Bootstrap modal, trying setting the `dropdownParent` option to the modal element.
## Dropdown option groups
In HTML, `<option>` elements can be grouped by wrapping them with in an `<optgroup>` element:
```
<select>
<optgroup label="Group Name">
<option>Nested option</option>
</optgroup>
</select>
```
Select2 will automatically pick these up and render them appropriately in the dropdown.
### Hierarchical options
Only a single level of nesting is allowed per the HTML specification. If you nest an `<optgroup>` within another `<optgroup>`, Select2 will not be able to detect the extra level of nesting and errors may be triggered as a result.
Furthermore, `<optgroup>` elements **cannot** be made selectable. This is a limitation of the HTML specification and is not a limitation that Select2 can overcome.
If you wish to create a true hierarchy of selectable options, use an `<option>` instead of an `<optgroup>` and <a href="http://stackoverflow.com/q/30820215/359284#30948247">change the style with CSS</a>. Please note that this approach may be considered "less accessible" as it relies on CSS styling, rather than the semantic meaning of `<optgroup>`, to generate the effect.

85
pages/06.dropdown/docs.md Normal file
View File

@ -0,0 +1,85 @@
---
title: Dropdown
taxonomy:
category: docs
process:
twig: true
never_cache_twig: true
---
This chapter covers the appearance and behavior of the list of results in the dropdown menu.
## Templating
By default, Select2 will display the `text` property of each data object within the list of results. The appearance of search results in the dropdown can be customized by using the `templateResult` option:
<div class="s2-example">
<select class="js-example-templating js-states form-control"></select>
</div>
<pre data-fill-from=".js-code-example-templating"></pre>
<script type="text/javascript" class="js-code-example-templating">
function formatState (state) {
if (!state.id) {
return state.text;
}
var baseUrl = "{{ url('user://pages/images/flags') }}";
var $state = $(
'<span><img src="' + baseUrl + '/' + state.element.value.toLowerCase() + '.png" class="img-flag" /> ' + state.text + '</span>'
);
return $state;
};
$(".js-example-templating").select2({
templateResult: formatState
});
</script>
The `templateResult` function should return a string containing the text to be displayed, or an object (such as a jQuery object) that contains the data that should be displayed. It can also return `null`, which will prevent the option from being displayed in the results list.
>>> You may find it helpful to use a client-side templating engine like [Handlebars](http://handlebarsjs.com/) to define your templates.
### Built-in escaping
By default, strings returned by `templateResult` are assumed to **contain only text** and will be passed through the `escapeMarkup` function, which strips any HTML markup.
If you need to render HTML with your result template, you must wrap your rendered result in a jQuery object. In this case, the result will be passed [directly to `jQuery.fn.append`](https://api.jquery.com/append/) and will be handled directly by jQuery. Any markup, such as HTML, will not be escaped and it is up to you to escape any malicious input provided by users.
>>> **Anything rendered in the results is templated.** This includes results such as the "Searching..." and "Loading more..." text which will periodically be displayed, which allows you to add more advanced formatting to these automatically generated options. You must ensure that your templating functions can support them.
## Automatic selection
Select2 can be configured to automatically select the currently highlighted result when the dropdown is closed by using the `selectOnClose` option:
```
$('select').select2({
selectOnClose: true
});
```
## 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:
```
$('select').select2({
closeOnSelect: false
});
```
## Dropdown placement
The `dropdownParent` option allows you to pick an element for the dropdown to be appended to:
```
$('select').select2({
dropdownParent: $('#my_amazing_modal')
});
```
### Using a Select2 control inside a Bootstrap modal
If you're having trouble using the search box inside a Bootstrap modal, trying setting the `dropdownParent` option to the modal element.

32
pages/06.selections/docs.md → pages/07.selections/docs.md
View File

@ -7,27 +7,7 @@ process:
never_cache_twig: true never_cache_twig: true
--- ---
When a selection is made by the user, Select2 will convert the selected `<option>` element into a JSON object based on the following rules: When an option is selected from the dropdown menu, Select2 will display the selected value in the container box. By default, it will display the `text` property of Select2's [internal representation of the selected option](/options).
```
{
"id": "value attribute" || "option text",
"text": "label attribute" || "option text",
"element": HTMLOptionElement
}
```
`<optgroup>` elements will be converted into data objects using the following rules:
```
{
"text": "label attribute",
"children": [ option data object, ... ],
"element": HTMLOptGroupElement
}
```
By default, Select2 will then display the `text` property of the selected result.
## Templating ## Templating
@ -58,7 +38,15 @@ $(".js-example-templating").select2({
</script> </script>
If your selection template contains HTML, you must wrap your rendered result in a jQuery object. Otherwise, Select2 will assume that your template only returns text and will escape it. You may find it helpful to use a client-side templating engine like [Handlebars](http://handlebarsjs.com/) to define your templates. >>> You may find it helpful to use a client-side templating engine like [Handlebars](http://handlebarsjs.com/) to define your templates.
### Built-in escaping
By default, strings returned by `templateSelection` are assumed to **contain only text** and will be passed through the `escapeMarkup` function, which strips any HTML markup.
If you need to render HTML with your selection template, you must wrap your rendered selection in a jQuery object. In this case, the selection will be passed [directly to `jQuery.fn.append`](https://api.jquery.com/append/) and will be handled directly by jQuery. Any markup, such as HTML, will not be escaped and it is up to you to escape any malicious input provided by users.
>>>> Anything rendered as a selection is templated. This includes placeholders and pre-existing selections that are displayed, so you must ensure that your templating functions can support them.
## Limiting the number of selections ## Limiting the number of selections

2
pages/07.placeholders/docs.md → pages/09.placeholders/docs.md
View File

@ -54,6 +54,8 @@ $('select').select2({
}); });
``` ```
This is useful, for example, when you are using a framework that creates its own placeholder option.
## Using placeholders with AJAX ## Using placeholders with AJAX
Select2 supports placeholders for all configurations, including AJAX. You will still need to add in the empty `<option>` if you are using a single select. Select2 supports placeholders for all configurations, including AJAX. You will still need to add in the empty `<option>` if you are using a single select.

150
pages/10.searching/docs.md Normal file
View File

@ -0,0 +1,150 @@
---
title: Search
taxonomy:
category: docs
process:
twig: true
never_cache_twig: true
---
The appearance and behavior of the search control can be easily customized with Select2.
## Customizing how results are matched
When users filter down the results by entering search terms into the search box, Select2 uses an internal "matcher" to match search terms to results. You may customize the way that Select2 matches search terms by specifying a callback for the `matcher` configuration option.
Select2 will pass each option as represented by its [internal representation](/options) into this callback to determine if it should be displayed:
```
function matchCustom(params, data) {
// If there are no search terms, return all of the data
if ($.trim(params.term) === '') {
return data;
}
// `params.term` should be the term that is used for searching
// `data.text` is the text that is displayed for the data object
if (data.text.indexOf(params.term) > -1) {
var modifiedData = $.extend({}, data, true);
modifiedData.text += ' (matched)';
// You can return modified objects from here
// This includes matching the `children` how you want in nested data sets
return modifiedData;
}
// Return `null` if the term should not be displayed
return null;
}
$(".js-example-matcher").select2({
matcher: matchCustom
});
```
>>>> When a remote data set is used, Select2 expects that the returned results have already been filtered.
### Matching grouped options
Only first-level objects will be passed in to the `matcher` callback. If you are working with nested data, you must iterate through the `children` array and match them individually. This allows for more advanced matching when working with nested objects, allowing you to handle them however you want.
This example matches results only if the term appears in the beginning of the string:
<div class="s2-example">
<select class="js-example-matcher-start js-states form-control"></select>
</div>
<pre data-fill-from=".js-code-example-matcher"></pre>
<script type="text/javascript" class="js-code-example-matcher">
function matchStart(params, data) {
// If there are no search terms, return all of the data
if ($.trim(params.term) === '') {
return data;
}
// `data.children` contains the actual options that we are matching against
var filteredChildren = [];
$.each(data.children, function (idx, child) {
if (child.text.toUpperCase().indexOf(params.term.toUpperCase()) == 0) {
filteredChildren.push(child);
}
});
// If we matched any of the timezone group's children, then set the matched children on the group
// and return the group object
if (filteredChildren.length) {
var modifiedData = $.extend({}, data, true);
modifiedData.children = filteredChildren;
// You can return modified objects from here
// This includes matching the `children` how you want in nested data sets
return modifiedData;
}
// Return `null` if the term should not be displayed
return null;
}
$(".js-example-matcher-start").select2({
matcher: matchStart
});
</script>
>>> A [compatibility module]() exists for using v3-style matcher callbacks.
## Minimum search term length
Sometimes when working with large data sets, it is more efficient to start filtering the results only when the search term is a certain length. This is very common when working with remote data sets, as it allows for only significant search terms to be used.
You may set a minimum search term length by using the `minimumInputLength` option:
```
$('select').select2({
minimumInputLength: 3 // only start searching when the user has input 3 or more characters
});
```
## Maximum search term length
In some cases, search terms need to be limited to a certain range. Select2 allows you to limit the length of the search term such that it does not exceed a certain length.
You may limit the maximum length of search terms by using the `maximumInputLength` option:
```
$('select').select2({
maximumInputLength: 20 // only allow terms up to 20 characters long
});
```
## Limiting display of the search box to large result sets
The `minimumResultsForSearch` option determines the minimum number of results required in the initial population of the dropdown to display the search box.
This option is useful for cases where local data is used with a small result set, and the search box would simply be a waste of screen real estate. Set this value to -1 to permanently hide the search box.
```
$('select').select2({
minimumResultsForSearch: 20 // at least 20 results must be displayed
});
```
## Hiding the search box
Select2 allows you to hide the search box depending on the number of options which are displayed. In this example, we use the value `Infinity` to tell Select2 to never display the search box.
<div class="s2-example">
<select class="js-example-basic-hide-search js-states form-control"></select>
</div>
<pre data-fill-from=".js-code-example-basic-hide-search"></pre>
<script type="text/javascript" class="js-code-example-basic-hide-search">
$(".js-example-basic-hide-search").select2({
minimumResultsForSearch: Infinity
});
</script>

0
pages/10.programmatic-control/01.methods/docs.md → pages/11.programmatic-control/01.methods/docs.md
View File

0
pages/10.programmatic-control/02.events/docs.md → pages/11.programmatic-control/02.events/docs.md
View File

2
pages/10.programmatic-control/chapter.md → pages/11.programmatic-control/chapter.md
View File

@ -4,6 +4,4 @@ taxonomy:
category: docs category: docs
--- ---
### Chapter 3
# Programmatic Control # Programmatic Control

209
pages/12.advanced/adapters.html
View File

@ -1,209 +0,0 @@
<section>
<div class="page-header">
<h1 id="adapters">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 adapters 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 id="adapters-all">
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 parameter 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 controlling 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>

790
pages/12.advanced/core-options.html
View File

@ -1,790 +0,0 @@
<section>
<h1 id="core-options" class="page-header">Core options</h1>
<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>
<p>
Select2 will automatically apply decorators to any adapters which have not
been manually overridden. 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 id="data-attributes">
Declaring configuration in the <code>data-*</code> attributes
</h2>
<p>
It is recommended that you declare your configuration options for Select2
when initializing Select2. You can also define your configuration options
by using the HTML5 <code>data-*</code> attributes, which will override
any options set when initializing Select2 and any defaults.
</p>
<p>
This means that if you declare your <code>&lt;select&gt;</code> tag as...
</p>
<pre class="prettyprint">
&lt;select data-tags="true" data-placeholder="Select an option"&gt;&lt;/select&gt;
</pre>
<p>
Will be interpreted the same as initializing Select2 as...
</p>
<pre class="prettyprint linenums">
$("select").select2({
tags: "true",
placeholder: "Select an option"
});
</pre>
<p>
You can also define nested configurations, which are typically needed for
options such as AJAX. Each level of nesting should be separated by two
dashes (<code>--</code>) instead of one. Due to
<a href="https://github.com/jquery/jquery/issues/2070">a jQuery bug</a>,
nested options using <code>data-*</code> attributes
<a href="https://github.com/select2/select2/issues/2969">do not work in jQuery 1.x</a>.
</p>
<pre class="prettyprint">
&lt;select data-ajax--url="http://example.org/api/test" data-ajax--cache="true"&gt;&lt;/select&gt;
</pre>
<p>
Which will be interpreted the same as initializing Select2 with...
</p>
<pre class="prettyprint linenums">
$("select").select2({
ajax: {
url: "http://example.org/api/test",
cache: "true"
}
});
</pre>
<p>
The value of the option is subject to jQuery's
<a href="https://api.jquery.com/data/#data-html5">parsing rules</a> for
HTML5 data attributes.
</p>
<h2 id="amd">
AMD compatibility
</h2>
<p>
You can find more information on how to integrate Select2 with your
existing AMD-based project by
<a href="announcements-4.0.html#builds">viewing the 4.0 release notes</a>.
Select2 automatically loads some modules when the adapters are being
automatically constructed, so those who are using Select2 with a custom
AMD build using their own system may need to specify the paths that are
generated to the Select2 modules.
</p>
<div class="row">
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Key</dt>
<dd>
<code>amdBase</code>
</dd>
<dt>Default</dt>
<dd>
<code>select2/</code>
</dd>
</dl>
</div>
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Key</dt>
<dd>
<code>amdLanguageBase</code>
</dd>
<dt>Default</dt>
<dd>
<code>select2/i18n/</code>
</dd>
</dl>
</div>
</div>
<h2 id="core-options-display">
Displaying selections
</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>
<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-6">
<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>
and
<code title="select2/dropdown/hidePlaceholder">HidePlaceholder</code>
</dd>
</dl>
</div>
<div class="col-sm-6">
<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 should add an empty
<code>&lt;option&gt;&lt;/option&gt;</code> tag that the placeholder
should use or it may 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>
<pre class="prettyprint">
placeholder: "Select a repository"
</pre>
<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>
<pre class="prettyprint linenums">
placeholder: {
id: "-1",
text: "Select a repository"
}
</pre>
<div class="alert alert-info">
You should <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>
<p id="allowClear">
You can allow a selected option to be cleared back to the placeholder by
enabling the <code>allowClear</code> option.
</p>
<div class="row">
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Key</dt>
<dd><code>allowClear</code></dd>
<dt>Value</dt>
<dd>boolean</dd>
</dl>
</div>
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Adapter</dt>
<dd>
<code title="select2/selection/base">SelectionAdapter</code>
</dd>
<dt>Decorator</dt>
<dd>
<code title="select2/selection/allowClear">AllowClear</code>
</dd>
</dl>
</div>
</div>
<p>
This will display an "x" that the user can click to clear the current
selection. It is designed to be used for cases where a single selection
can be made.
</p>
<h3 id="multiple">
Multiple selections
</h3>
<p>
Select2 can display either a single selection or multiple selections.
</p>
<dl class="dl-horizontal">
<dt>Key</dt>
<dd><code>multiple</code></dd>
<dt>Value</dt>
<dd>boolean (<code>true</code> or <code>false</code>)</dd>
</dl>
<p>
This option will determine what the <code>SelectAdapter</code> (used by
default) should use to set the value of the underlying <code>select</code>
element. It will also determine if the <code>MultipleSelection</code>
adapter should be used.
</p>
<h3 id="width">
Container width
</h3>
<p>
Select2 will try to match the width of the original element as closely as
possible. Sometimes this isn't perfect, which is what you can tell Select2
how to determine the width.
</p>
<div class="row">
<div class="col-sm-6">
<table class="table table-striped table-bordered">
<thead>
<tr>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>"element"</code></td>
<td>
Uses javascript to calculate the width of the source element.
</td>
</tr>
<tr>
<td><code>"style"</code></td>
<td>
Copies the value of the width <code>style</code> attribute set on the source element.
</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>.
</td>
</tr>
<tr>
<td>Anything else</td>
<td>
The value of the <code>width</code> option is directly set as the width of the container.
</td>
</tr>
</tbody>
</table>
</div>
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Key</dt>
<dd><code>width</code></dd>
<dt>Value</dt>
<dd>string</dd>
</dl>
</div>
</div>
<h3 id="language">
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-6">
<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-6">
<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 linenums">
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>
<h3 id="templating">
Templating results and selections
</h3>
<p>
By default, Select2 will display the option text within the list of
results and when the option has been selected. Select2 comes with options
that allow you to further customize the display of results and selections,
allowing you to display them however you want.
</p>
<h4 id="templateSelection">
Customizing the display of selections
</h4>
<p>
When an option is displayed after it has been selected, it is passed
through a formatting function that determines what is displayed. By
default, the function only returns the <code>text</code> key of the data
object.
</p>
<dl class="dl-horizontal">
<dt>Key</dt>
<dd><code>templateSelection</code></dd>
<dt>Value</dt>
<dd>A function taking a <code>selection</code> object</dd>
</dl>
<div class="alert alert-info">
<strong>Anything rendered as a selection is templated.</strong>
This includes placeholders and pre-existing selections that are displayed,
so you must ensure that your templating functions can support them.
</div>
<p>
The <code>templateSelection</code> function should return a string
containing the text to be displayed, or an object (such as a jQuery
object) that contains the data that should be displayed.
</p>
<p>
<strong>Strings are assumed to contain only text</strong> and will be
passed through the <code>escapeMarkup</code> function, which strips any
HTML markup.
</p>
<p>
<strong>
Anything else will be passed
<a href="https://api.jquery.com/append/">directly to <code>jQuery.fn.append</code></a>
</strong> and will be handled directly by jQuery. Any markup, such as
HTML, returned will not be escaped and it is up to you to escape any
malicious input provided by users.
</p>
<h4 id="templateResult">
Customizing the display of results
</h4>
<p>
When an option is displayed after it has been selected, it is passed
through a formatting function that determines what is displayed. By
default, the function only returns the <code>text</code> key of the data
object.
</p>
<dl class="dl-horizontal">
<dt>Key</dt>
<dd><code>templateResult</code></dd>
<dt>Value</dt>
<dd>A function taking a <code>result</code> object</dd>
</dl>
<div class="alert alert-info">
<strong>Anything rendered in the results is templated.</strong>
This includes results such as the "Searching..." and "Loading more..."
text which will periodically be displayed, which allows you to add more
advanced formatting to these automatically generated options.
</div>
<p>
The <code>templateResult</code> function should return a string
containing the text to be displayed, or an object (such as a jQuery
object) that contains the data that should be displayed. It can also
return <code>null</code>, which will prevent the option from being
displayed in the results list.
</p>
<p>
<strong>Strings are assumed to contain only text</strong> and will be
passed through the <code>escapeMarkup</code> function, which strips any
HTML markup.
</p>
<p>
<strong>
Anything else will be passed
<a href="https://api.jquery.com/append/">directly to <code>jQuery.fn.append</code></a>
</strong> and will be handled directly by jQuery. Any markup, such as
HTML, returned will not be escaped and it is up to you to escape any
malicious input provided by users.
</p>
<h2 id="core-options-results">
Returning and displaying results
</h2>
<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
remote 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 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>
<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>
<h3 id="matcher">
Change how options are matched when searching
</h3>
<p>
When users filter down the results by entering search terms into the
search box, Select2 uses an internal "matcher" to match search terms to
results. <strong>When a remote data set is used, Select2 expects that the
returned results have already been filtered.</strong>
</p>
<dl class="dl-horizontal">
<dt>Key</dt>
<dd>
<code>matcher</code>
</dd>
<dt>Value</dt>
<dd>
A function taking search <code>params</code> and the
<code>data</code> object.
</dd>
</dl>
<p>
Select2 will pass the individual data objects that have been passed back
from the data adapter into the <code>matcher</code> individually to
determine if they should be displayed. Only the first-level objects will
be passed in, so <strong>if you are working with nested data, you need to
match those individually</strong>.
</p>
<pre class="prettyprint linenums">
matcher: function (params, data) {
// If there are no search terms, return all of the data
if ($.trim(params.term) === '') {
return data;
}
// `params.term` should be the term that is used for searching
// `data.text` is the text that is displayed for the data object
if (data.text.indexOf(params.term) > -1) {
var modifiedData = $.extend({}, data, true);
modifiedData.text += ' (matched)';
// You can return modified objects from here
// This includes matching the `children` how you want in nested data sets
return modifiedData;
}
// Return `null` if the term should not be displayed
return null;
}
</pre>
<p>
This allows for more advanced matching when working with nested objects,
allowing you to handle them however you want. For those who are not
looking to implement highly customized matching, but instead are just
looking to change the matching algorithm for the text, a
<a href="#compat-matcher">compatibility modules</a> has been created to
make it easier.
</p>
</section>

308
pages/12.advanced/dropdown.html
View File

@ -1,308 +0,0 @@
<section>
<div class="page-header">
<h1 id="dropdown">Dropdown</h1>
</div>
<p>
Select2 allows you to change the way that the dropdown works, allowing you
to do anything from attach it to a different location in the document or
add a search box.
</p>
<h2 id="dropdownParent">
Attached to body
</h2>
<p>
By default, Select2 will attach the dropdown to the end of the body and
will absolutely position it to appear below the selection container.
</p>
<div class="row">
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Key</dt>
<dd><code>dropdownParent</code></dd>
<dt>Value</dt>
<dd>jQuery element or DOM node</dd>
<hr />
<dt>Adapter</dt>
<dd>
<code title="select2/dropdown">DropdownAdapter</code>
</dd>
<dt>Decorator</dt>
<dd>
<code title="select2/dropdown/attachBody">AttachBody</code>
</dd>
</dl>
</div>
<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>
<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">
<dl class="dl-horizontal">
<dt>Adapter</dt>
<dd>
<code title="select2/dropdown">DropdownAdapter</code>
</dd>
<dt>Decorator</dt>
<dd>
<code title="select2/dropdown/attachContainer">AttachContainer</code>
</dd>
</dl>
</div>
<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>
<h2 id="dropdown-search">
Search
</h2>
<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>
<dl class="dl-horizontal">
<dt>Adapter</dt>
<dd>
<code title="select2/dropdown">DropdownAdapter</code>
</dd>
<dt>Decorator</dt>
<dd>
<code title="select2/dropdown/search">DropdownSearch</code>
</dd>
</dl>
<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>
<h3 id="dropdown-minimumInputLength">
Minimum search term length to filter results
</h3>
<p>
Sometimes when working with large data sets, it is more efficient to start
filtering the results when the search term is a certain length. This is
very common when working with remote data sets, as allows for only
significant search terms to be used.
</p>
<div class="row">
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Key</dt>
<dd><code>minimumInputLength</code></dd>
<dt>Value</dt>
<dd>integer</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/minimumInputLength">MinimumInputLength</code>
</dd>
</dl>
</div>
</div>
<h3 id="dropdown-maximumInputLength">
Maximum search term length to filter results
</h3>
<p>
In some cases, search terms need to be limited to a certain range. Select2
allows you to limit the length of the search term such that it does not
exceed a certain length.
</p>
<div class="row">
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Key</dt>
<dd><code>maximumInputLength</code></dd>
<dt>Value</dt>
<dd>integer</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/maximumInputLength">MaximumInputLength</code>
</dd>
</dl>
</div>
</div>
<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 class="col-sm-6">
<dl class="dl-horizontal">
<dt>Adapter</dt>
<dd>
<code title="select2/dropdown">DropdownAdapter</code>
</dd>
<dt>Decorator</dt>
<dd>
<code title="select2/dropdown/minimumResultsForSearch">MinimumResultsForSearch</code>
</dd>
</dl>
</div>
</div>
<h2 id="dropdown-select-on-close">
Select the highlighted option on close
</h2>
<p>
When users close the dropdown, the last highlighted option can be
automatically selected. This is commonly used in combination with
<a href="#tags">tagging</a> and <a href="#placeholder">placeholders</a>
and other situations where the user is required to select an option, or
they need to be able to quickly select multiple options.
</p>
<dl class="dl-horizontal">
<dt>Adapter</dt>
<dd>
<code title="select2/results">ResultsAdapter</code>
</dd>
<dt>Decorator</dt>
<dd>
<code title="select2/dropdown/selectOnClose">SelectOnClose</code>
</dd>
</dl>
<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 class="col-sm-6">
<dl class="dl-horizontal">
<dt>Adapter</dt>
<dd>
<code title="select2/dropdown">DropdownAdapter</code>
</dd>
<dt>Decorator</dt>
<dd>
<code title="select2/dropdown/closeOnSelect">CloseOnSelect</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>
</section>

37
pages/12.advanced/setting-default-options.html
View File

@ -1,37 +0,0 @@
<section>
<h1 id="setting-default-options">Setting default options</h1>
<p>
In some cases, you need to set the default options for all instances of
Select2 in your web application. This is especially useful when you are
migrating from past versions of Select2, or you are using non-standard
options <a href="#amd">like custom AMD builds</a>. Select2 exposes the
default options through <code>$.fn.select2.defaults</code>, which allows
you to set them globally.
</p>
<p>
When setting options globally, any past defaults that have been set will
be overriden. Default options are only used when an option is requested
that has not been set during initialization.
</p>
<p>
<strong>You can set default options</strong> by calling
<code>$.fn.select2.defaults.set("key", "value")</code>. The key that is
set should take the same format as keys set using
<a href="#data-attributes">HTML <code>data-*</code> attributes</a> which
means that two dashes (<code>--</code>) will be replaced by a level of
nesting, and a single dash (<code>-</code>) will convert it to a camelCase
string.
</p>
<pre class="prettyprint">
$.fn.select2.defaults.set("theme", "classic");
</pre>
<p>
<strong>You can reset the default options</strong> by calling
<code>$.fn.select2.defaults.reset()</code>.
</p>
</section>

28
pages/11.i18n/docs.md → pages/12.i18n/docs.md
View File

@ -9,11 +9,15 @@ never_cache_twig: true
{% do assets.addJs('https://cdnjs.cloudflare.com/ajax/libs/select2/4.0.3/js/i18n/es.js', 90) %} {% do assets.addJs('https://cdnjs.cloudflare.com/ajax/libs/select2/4.0.3/js/i18n/es.js', 90) %}
## Multiple languages (localization) ## Message translations
Select2 can load message translations for different languages from language files. 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.
The language does not have to be defined when Select2 is being initialized, but instead can be defined in the `[lang]` attribute of any parent elements as `[lang="es"]`. ### Language files
Select2 can load message translations for different languages from language files. 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 is one of Select2's built-in languages, and it will try to load the translations for that language instead.
<div class="s2-example"> <div class="s2-example">
<p> <p>
@ -34,8 +38,24 @@ $(".js-example-language").select2({
}); });
</script> </script>
You may alternatively provide your own custom messages to be displayed. The language does not have to be defined when Select2 is being initialized, but instead can be defined in the `[lang]` attribute of any parent elements as `[lang="es"]`.
### Translation objects
You may alternatively provide your own custom messages to be displayed 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...";
}
}
```
>>> Translations are handled by the `select2/translation` module.
## RTL support ## RTL support

130
pages/13.advanced/01.adapters-and-decorators/docs.md Normal file
View File

@ -0,0 +1,130 @@
---
title: Adapters and Decorators
taxonomy:
category: docs
---
Starting in version 4.0, Select2 uses the [Adapter pattern](https://en.wikipedia.org/wiki/Adapter_pattern) as a powerful means of extending its features and behavior.
Most of the built-in features, such as those described in the previous chapters, are implemented via one of the [built-in adapters](/default-adapters). You may further extend the functionality of Select2 by implementing your own adapters.
## Adapter interfaces
All custom adapters must implement the methods described by the `Adapter` interface.
In addition, adapters that override the default `selectionAdapter` and `dataAdapter` behavior must implement the additional methods described by the corresponding `SelectionAdapter` and `DataAdapter` interfaces.
### `Adapter`
All adapters must implement the `Adapter` interface, which Select2 uses to render DOM elements for the adapter and bind any internal events:
```
// 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 () { };
```
### `SelectionAdapter`
The selection is what is shown to the user as a replacement of the standard `<select>` 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.
Adapters that will be used to override the default `selectionAdapter` must implement the `update` method as well:
```
// 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) { };
```
### `DataAdapter`
The data set is what Select2 uses to generate the possible results that can be selected, as well as the currently selected results.
Adapters that will be used to override the default `dataAdapter` must implement the `current` and `query` methods as well:
```
// 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 parameter 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);
}
```
## Decorators
Select2 uses [decorators](https://en.wikipedia.org/wiki/Decorator_pattern) to expose the functionality of adapters through its [configuration options](/configuration).
You can apply a decorator to an adapter using the `Utils.Decorate` method provided with Select2:
```
$.fn.select2.amd.require(
["select2/utils", "select2/selection/single", "select2/selection/placeholder"],
function (Utils, SingleSelection, Placeholder) {
var CustomSelectionAdapter = Utils.Decorate(SingleSelection, Placeholder);
});
```
>>> 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.
## AMD Compatibility
You can find more information on how to integrate Select2 with your existing AMD-based project by <a href="announcements-4.0.html#builds">viewing the 4.0 release notes</a>. Select2 automatically loads some modules when the adapters are being automatically constructed, so those who are using Select2 with a custom AMD build using their own system may need to specify the paths that are generated to the Select2 modules.

39
pages/13.advanced/02.default-adapters/01.selection/docs.md Normal file
View File

@ -0,0 +1,39 @@
---
title: Selection
taxonomy:
category: docs
---
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.
`select2/selection`
## Decorators
### `Placeholder` and `HidePlaceholder`
**AMD Modules:**
`select2/selection/placeholder`
`select2/dropdown/hidePlaceholder`
These decorators implement Select2's [placeholder](/placeholders) features.
### `AllowClear`
**AMD Modules:**
`select2/selection/allowClear`
This decorator implements [clearable selections](/selections#clearable-selections) as exposed through the `allowClear` option.
### `EventRelay`
**AMD Modules:**
`select2/selection/eventRelay`
Select2 has an internal event system that is used to notify parts of the component that state has changed, as well as an adapter that allows some of these events to be relayed to the outside word.

49
pages/13.advanced/02.default-adapters/02.array/docs.md Normal file
View File

@ -0,0 +1,49 @@
---
title: Array
taxonomy:
category: docs
---
<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

118
pages/13.advanced/02.default-adapters/03.ajax/docs.md Normal file
View File

@ -0,0 +1,118 @@
---
title: Ajax
taxonomy:
category: docs
---
<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 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

48
pages/13.advanced/02.default-adapters/04.data/docs.md Normal file
View File

@ -0,0 +1,48 @@
---
title: SelectAdapter
taxonomy:
category: docs
---
Select2 provides the `SelectAdapter` as a default implementation of the `DataAdapter` adapter. It extends `BaseAdapter`.
This adapter can be overridden by assigning a custom adapter to the `dataAdapter` configuration option.
**AMD Modules:**
- `select2/data/base`
- `select2/data/select`
## Decorators
### `Tags`
This decorator implements the [tagging](/tagging) feature.
**AMD Modules:**
`select2/data/tags`
<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>
### `MinimumInputLength`
This decorator implements the [minimum search term length](/searching#minimum-search-term-length) feature as exposed through the `minimumInputLength` configuration option.
**AMD Modules:**
`select2/data/minimumInputLength`
### `MaximumInputLength`
This decorator implements the [maximum search term length](/searching#maximum-search-term-length) feature as exposed through the `maximumInputLength` configuration option.
**AMD Modules:**
`select2/data/maximumInputLength`

31
pages/13.advanced/02.default-adapters/05.results/docs.md Normal file
View File

@ -0,0 +1,31 @@
---
title: Results
taxonomy:
category: docs
---
The `ResultsAdapter` controls the list of results that the user can select from.
The results adapter can be overridden by assigning a custom adapter to the `resultsAdapter` configuration option. While the results adapter does not define any additional methods that must be implemented, it makes extensive use of the Select2 event system for controlling the display of results and messages.
**AMD Modules:**
`select2/results`
## 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.
**AMD Modules:**
`select2/dropdown/selectOnClose`

157
pages/13.advanced/02.default-adapters/06.dropdown/docs.md Normal file
View File

@ -0,0 +1,157 @@
---
title: Dropdown
taxonomy:
category: docs
---
The dropdown adapter defines the main container that the dropdown should be held in. Select2 allows you to change the way that the dropdown works, allowing you to do anything from attach it to a different location in the document or add a search box.
It is common for decorators to attach to the `render` and `position` methods to alter how the dropdown is altered and positioned.
This adapter can be overridden by assigning a custom adapter to the `dropdownAdapter` configuration option.
`select2/dropdown`
## Decorators
### `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.
`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`
`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>
### `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>
<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>
### `MinimumResultsForSearch`
`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`
`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>

7
pages/13.advanced/02.default-adapters/docs.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Built-in adapters
taxonomy:
category: docs
---
This section describes the built-in adapters for Select2, as well as the decorators they use to expose their functionality.

0
pages/12.advanced/announcements-4.0.html → pages/13.advanced/announcements-4.0.html
View File

31
pages/12.advanced/backwards-compatibility.html → pages/13.advanced/backwards-compatibility.html
View File

@ -1,3 +1,34 @@
### Compatibility module for Select2 v3.5
This custom matcher uses a [compatibility module](/configuration/deprecated) that is only bundled in the [full version of Select2](/getting-started/builds). You also have the option of using a <a href="options.html#matcher">more complex matcher</a>.
<div class="s2-example">
<select class="js-example-matcher-compat js-states form-control"></select>
</div>
<pre data-fill-from=".js-code-example-matcher-compat"></pre>
<script type="text/javascript" class="js-code-example-matcher-compat">
function matchStart (term, text) {
if (text.toUpperCase().indexOf(term.toUpperCase()) == 0) {
return true;
}
return false;
}
$.fn.select2.amd.require(['select2/compat/matcher'], function (oldMatcher) {
$(".js-example-matcher-compat").select2({
matcher: oldMatcher(matchStart)
})
});
</script>
<section> <section>
<div class="page-header"> <div class="page-header">
<h1 id="compatibility">Backwards compatibility</h1> <h1 id="compatibility">Backwards compatibility</h1>

7
pages/13.advanced/chapter.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Advanced
taxonomy:
category: docs
---
# Advanced Features and Developer Guide

22
pages/12.advanced/events.html → pages/13.advanced/events.html
View File

@ -1,25 +1,3 @@
<section>
<div id="events" class="page-header">
<h1>Events</h1>
</div>
<p>
Select2 has an internal event system that is used to notify parts of the
component that state has changed, as well as an adapter that allows some
of these events to be relayed to the outside word.
</p>
<dl class="dl-horizontal">
<dt>Adapter</dt>
<dd>
<code title="select2/selection">SelectionAdapter</code>
</dd>
<dt>Decorator</dt>
<dd>
<code title="select2/selection/eventRelay">EventRelay</code>
</dd>
</dl>
<h2 id="events-public"> <h2 id="events-public">
Public events Public events