integrate announcements and backwards-compat
This commit is contained in:
alexweissman
parent
94c5c3a3fe
commit
bb1fda2654
@ -1,14 +0,0 @@
|
||||
---
|
||||
title: Initializing
|
||||
taxonomy:
|
||||
category: docs
|
||||
---
|
||||
|
||||
|
||||
To configure custom options, simply pass an object containing all of the options with which you would like to initialize Select2, in your call to `.select2()`:
|
||||
|
||||
```
|
||||
$('.js-example-basic-single').select2({
|
||||
placeholder: 'Select an option'
|
||||
});
|
||||
```
|
||||
50
pages/02.configuration/01.options-api/docs.md
Normal file
50
pages/02.configuration/01.options-api/docs.md
Normal file
@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Configuration API
|
||||
taxonomy:
|
||||
category: docs
|
||||
---
|
||||
|
||||
The following is an attempt to provide a comprehensive list of all configuration options available in Select2.
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
| ------ | ---- | ------- | ----------- |
|
||||
| `adaptContainerCssClass` | | | |
|
||||
| `adaptDropdownCssClass` | | | |
|
||||
| `ajax` | object | `null` | Provides support for [ajax data sources](/data-sources/ajax). |
|
||||
| `allowClear` | boolean | `false` | Provides support for [clearable selections](/selections#clearable-selections). |
|
||||
| `amdBase` | string | `select2/` | The base AMD loader path to be used for select2 dependency resolution. This 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. |
|
||||
| `amdLanguageBase` | string | `select2/i18n/` | The base AMD loader language path to be used for select2 language file resolution. This 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. |
|
||||
| `closeOnSelect` | boolean | `true` | Controls whether the dropdown is [closed after a selection is made](/dropdown#forcing-the-dropdown-to-remain-open-after-selection). |
|
||||
| `containerCss` | | | |
|
||||
| `containerCssClass` | | | |
|
||||
| `dataAdapter` | | `SelectAdapter` | Used to override the built-in [DataAdapter](/advanced/default-adapters/data). |
|
||||
| `debug` | boolean | | |
|
||||
| `dir` | | |
|
||||
| `disabled` | boolean | `false` | When set to `true`, the select control will be disabled. |
|
||||
| `dropdownAdapter` | | `DropdownAdapter` | Used to override the built-in [DropdownAdapter](/advanced/default-adapters/dropdown) |
|
||||
| `dropdownAutoWidth` | boolean | | |
|
||||
| `dropdownCss` | string | | |
|
||||
| `dropdownCssClass` | string | | |
|
||||
| `dropdownParent` | jQuery selector or DOM node | | Allows you to [customize placement](/dropdown#dropdown-placement) of the dropdown. |
|
||||
| `escapeMarkup` | | |
|
||||
| `initSelection` | callback | | See [`initSelection`](/upgrading/migrating-from-35#removed-the-requirement-of-initselection). **This option was deprecated in Select2 v4.0, and will be removed in v4.1.** |
|
||||
| `language` | string or object | | |
|
||||
| `matcher` | A callback taking search `params` and the `data` object. | | |
|
||||
| `maximumInputLength` | integer | `0` | [Maximum number of characters](/searching#maximum-search-term-length) that may be provided for a search term. |
|
||||
| `maximumSelectionLength` | integer | `0` | The maximum number of items that may be selected in a multi-select control. If the value of this option is less than 1, the number of selected items will not be limited.
|
||||
| `minimumInputLength` | integer | `0` | [Minimum number of characters required to start a search.](/searching#minimum-search-term-length) |
|
||||
| `minimumResultsForSearch` | integer | `0` | The minimum number of results required to [display the search box](/searching#limiting-display-of-the-search-box-to-large-result-sets). |
|
||||
| `multiple` | boolean | `false` | This option enables multi-select (pillbox) mode. Select2 will automatically map the value of the `multiple` HTML attribute to this option during initialization. |
|
||||
| `placeholder` | string or object | | |
|
||||
| `query` | A function taking `params` (including a `callback`) | | **This option was deprecated in Select2 v4.0, and will be removed in v4.1.** |
|
||||
| `resultsAdapter` | | `ResultsAdapter` | Used to override the built-in [ResultsAdapter](/advanced/default-adapters/results). |
|
||||
| `selectionAdapter` | | `SingleSelection` or `MultipleSelection`, depending on the value of `multiple`. | Used to override the built-in [SelectionAdapter](/advanced/default-adapters/selection). |
|
||||
| `selectOnClose` | boolean | `false` | Implements [automatic selection](/dropdown#automatic-selection) when the dropdown is closed. |
|
||||
| `sorter` | function | | |
|
||||
| `tags` | boolean / array of objects | `false` | Used to enable [free text responses](/tagging). |
|
||||
| `templateResult` | callback | | |
|
||||
| `templateSelection` | callback | | |
|
||||
| `theme` | string | `default` | Allows you to set the [theme](/appearance#themes). |
|
||||
| `tokenizer` | | |
|
||||
| `tokenSeparators` | | | |
|
||||
| `width` | string | `resolve` | Supports [customization of the container width](/appearance#container-width). |
|
||||
@ -1,210 +0,0 @@
|
||||
---
|
||||
title: Deprecated options
|
||||
taxonomy:
|
||||
category: docs
|
||||
---
|
||||
|
||||
<section>
|
||||
<p>
|
||||
Select2 offers limited backwards compatibility with the previously 3.5.x
|
||||
release line, allowing people more efficiently transfer across releases
|
||||
and get the latest features. For many of the larger changes, such as the
|
||||
change in how custom data adapters work, compatibility modules were
|
||||
created that will be used to assist in the upgrade process. It is not
|
||||
recommended to rely on these compatibility modules, as they will not
|
||||
always exist, but they make upgrading easier for major changes.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<strong>The compatibility modules are only included in the
|
||||
<a href="index.html#builds-full" class="alert-link">full builds</a> of
|
||||
Select2</strong>. These files end in <code>.full.js</code>, and the
|
||||
compatibility modules are prefixed with <code>select2/compat</code>.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2 id="compat-matcher">
|
||||
Simplified function for matching data objects
|
||||
</h2>
|
||||
|
||||
<p class="alert alert-info">
|
||||
<a href="announcements-4.0.html#new-matcher" class="alert-link">Added in Select2 4.0.0.</a>
|
||||
This method was added to make upgrading easier from earlier versions of
|
||||
Select2.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
During the <a href="announcements-4.0.html">Select2 4.0.0 release</a>, the
|
||||
<code>matcher</code> function was changed to allow for more complex
|
||||
matching of nested objects.
|
||||
</p>
|
||||
|
||||
<div class="row">
|
||||
<div class="col-sm-6">
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Key</dt>
|
||||
<dd>
|
||||
<code>matcher</code>
|
||||
</dd>
|
||||
|
||||
<dt>Value</dt>
|
||||
<dd>
|
||||
A function taking a search <code>term</code> and the data object
|
||||
<code>text</code>.
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
|
||||
<div class="col-sm-6">
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Adapter</dt>
|
||||
<dd>
|
||||
<code title="select2/compat/matcher">oldMatcher</code>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
The <a href="examples.html#matcher">custom matcher example</a> provides a
|
||||
guide for how to use this in your own application. For those upgrading
|
||||
from older versions of Select2, you just need to wrap your old
|
||||
<code>matcher</code> with this function to maintain compatibility.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2 id="initSelection">
|
||||
Old initial selections with <code>initSelection</code>
|
||||
</h2>
|
||||
|
||||
<p class="alert alert-warning">
|
||||
<a href="announcements-4.0.html#removed-initselection" class="alert-link">Deprecated in Select2 4.0.</a>
|
||||
This has been replaced by another option and is only available in the
|
||||
<a href="index.html#builds-full" class="alert-link">full builds</a> of
|
||||
Select2.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
In the past, Select2 required an option called <code>initSelection</code>
|
||||
that was defined whenever a custom data source was being used, allowing
|
||||
for the initial selection for the component to be determined. This has
|
||||
been replaced by the <code>current</code> method on the
|
||||
<a href="#dataAdapter">data adapter</a>.
|
||||
</p>
|
||||
|
||||
<div class="row">
|
||||
<div class="col-sm-6">
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Key</dt>
|
||||
<dd>
|
||||
<code>initSelection</code>
|
||||
</dd>
|
||||
|
||||
<dt>Value</dt>
|
||||
<dd>
|
||||
A function taking a <code>callback</code>
|
||||
</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/compat/initSelection">InitSelection</code>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2 id="query">
|
||||
Querying old data with <code>query</code>
|
||||
</h2>
|
||||
|
||||
<p class="alert alert-warning">
|
||||
<a href="announcements-4.0.html#query-to-data-adapter" class="alert-link">Deprecated in Select2 4.0.</a>
|
||||
This has been replaced by another option and is only available in the
|
||||
<a href="index.html#builds-full" class="alert-link">full builds</a> of
|
||||
Select2.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
In the past, Select2 supported an option called <code>query</code> that
|
||||
allowed for a custom data source to be used. This option has been replaced
|
||||
by the <code>query</code> method on the
|
||||
<a href="#dataAdapter">data adapter</a> and takes a very similar set of
|
||||
parameters.
|
||||
</p>
|
||||
|
||||
<div class="row">
|
||||
<div class="col-sm-6">
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Key</dt>
|
||||
<dd>
|
||||
<code>query</code>
|
||||
</dd>
|
||||
|
||||
<dt>Value</dt>
|
||||
<dd>
|
||||
A function taking <code>params</code> (including a <code>callback</code>)
|
||||
</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/compat/query">Query</code>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2 id="input-fallback">
|
||||
Compatibility with <code><input type="text" /></code>
|
||||
</h2>
|
||||
|
||||
<p class="alert alert-warning">
|
||||
<a href="announcements-4.0.html#hidden-input" class="alert-link">Deprecated in Select2 4.0.</a>
|
||||
It is now encouraged to use the <code><select></code> tag instead.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
In past versions of Select2, a <code><select></code> element could
|
||||
only be used with a limited subset of options. An
|
||||
<code><input type="hidden" /></code> was required instead, which did
|
||||
not allow for a graceful fallback for users who did not have JavaScript
|
||||
enabled. Select2 now supports the <code><select></code> element for
|
||||
all options, so it is no longer required to use <code><input /></code>
|
||||
elements with Select2.
|
||||
</p>
|
||||
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Adapter</dt>
|
||||
<dd>
|
||||
<code title="select2/data/base">DataAdapter</code>
|
||||
</dd>
|
||||
|
||||
<dt>Decorator</dt>
|
||||
<dd>
|
||||
<code title="select2/compat/inputData">InputData</code>
|
||||
</dd>
|
||||
</dl>
|
||||
</section>
|
||||
@ -1,10 +1,10 @@
|
||||
---
|
||||
title: Via data-* attributes
|
||||
title: data-* attributes
|
||||
taxonomy:
|
||||
category: docs
|
||||
---
|
||||
|
||||
It is recommended that you declare your configuration options by [passing in an object](/options/initializing) when initializing Select2. However, you may also define your configuration options by using the HTML5 `data-*` attributes, which will override any options set when initializing Select2 and any [defaults](/options/initializing/defaults).
|
||||
It is recommended that you declare your configuration options by [passing in an object](/configuration) when initializing Select2. However, you may also define your configuration options by using the HTML5 `data-*` attributes, which will override any options set when initializing Select2 and any [defaults](/configuration/defaults).
|
||||
|
||||
```
|
||||
<select data-placeholder="Select a state">
|
||||
@ -4,296 +4,10 @@ taxonomy:
|
||||
category: docs
|
||||
---
|
||||
|
||||
Select2 has the following configuration options available. Note that this page is a work
|
||||
in progress. The <a href="http://select2.github.io/select2/#documentation">previous
|
||||
release's documentation</a> should cover the gaps here for the time being.
|
||||
To configure custom options when you initialize Select2, simply pass an object in your call to `.select2()`:
|
||||
|
||||
<table class="table table-bordered table-striped">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Option</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr id="adaptContainerCssClass">
|
||||
<td>adaptContainerCssClass</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="adaptDropdownCssClass">
|
||||
<td>adaptDropdownCssClass</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="ajax">
|
||||
<td>ajax</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="allowClear">
|
||||
<td>allowClear</td>
|
||||
<td>boolean</td>
|
||||
<td>
|
||||
<p>When set to <strong>true</strong>, causes a clear button to appear on the select box
|
||||
when a value is selected. Clicking the clear button will clear the selected value,
|
||||
effectively resetting the select box back to its placeholder value.</p>
|
||||
|
||||
<p>Default value: <strong>false</strong></p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="amdBase">
|
||||
<td>amdBase</td>
|
||||
<td>string</td>
|
||||
<td>
|
||||
<p>The base AMD loader path to be used for select2 dependency resolution. This 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>
|
||||
|
||||
<p>Default value: `select2/`</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="amdLanguageBase">
|
||||
<td>amdLanguageBase</td>
|
||||
<td>string</td>
|
||||
<td>
|
||||
<p>The base AMD loader language path to be used for select2 language file resolution. This
|
||||
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>
|
||||
|
||||
<p>Default value: `select2/i18n/`</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="closeOnSelect">
|
||||
<td>closeOnSelect</td>
|
||||
<td>boolean</td>
|
||||
<td>
|
||||
<p>When set to <strong>false</strong>, keeps the dropdown open upon selecting an option,
|
||||
making it easy to quickly select multiple items. <em>Note that this option is only
|
||||
applicable to multi-select controls</em>.</p>
|
||||
|
||||
<p>Default value: `true`</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="containerCss">
|
||||
<td>containerCss</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="containerCssClass">
|
||||
<td>containerCssClass</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="dataAdapter">
|
||||
<td>dataAdapter</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="debug">
|
||||
<td>debug</td>
|
||||
<td>boolean</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="dir">
|
||||
<td>dir</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="disabled">
|
||||
<td>disabled</td>
|
||||
<td>boolean</td>
|
||||
<td>
|
||||
<p>When set to <strong>true</strong>, the select control will be disabled.</p>
|
||||
|
||||
<p>Default value: <strong>false</strong></p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="dropdownAdapter">
|
||||
<td>dropdownAdapter</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="dropdownAutoWidth">
|
||||
<td>dropdownAutoWidth</td>
|
||||
<td>boolean</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="dropdownCss">
|
||||
<td>dropdownCss</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="dropdownCssClass">
|
||||
<td>dropdownCssClass</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="dropdownParent">
|
||||
<td>dropdownParent</td>
|
||||
<td>jQuery selector or DOM node</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="escapeMarkup">
|
||||
<td>escapeMarkup</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="initSelection">
|
||||
<td>initSelection</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="language">
|
||||
<td>language</td>
|
||||
<td>string or object</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="matcher">
|
||||
<td>matcher</td>
|
||||
<td>A callback taking search <code>params</code> and the
|
||||
<code>data</code> object.</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="maximumInputLength">
|
||||
<td>maximumInputLength</td>
|
||||
<td>integer</td>
|
||||
<td>
|
||||
<p>Maximum number of characters that may be provided for a search term.</p>
|
||||
|
||||
<p>Default value: <strong>0</strong></p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="maximumSelectionLength">
|
||||
<td>maximumSelectionLength</td>
|
||||
<td>integer</td>
|
||||
<td>
|
||||
<p>The maximum number of items that may be selected in a multi-select control. If the
|
||||
value of this option is less than 1, the number of selected items will not be limited.</p>
|
||||
|
||||
<p>Default value: <strong>0</strong></p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="minimumInputLength">
|
||||
<td>minimumInputLength</td>
|
||||
<td>integer</td>
|
||||
<td>
|
||||
<p>Minimum number of characters required to start a search. This options is primarily
|
||||
useful in cases where data is loaded via the <code>ajax</code> option.</p>
|
||||
|
||||
<p>Default value: <strong>0</strong></p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="minimumResultsForSearch">
|
||||
<td>minimumResultsForSearch</td>
|
||||
<td>integer</td>
|
||||
<td>
|
||||
<p>The minimum number of results required in the initial population of the dropdown to
|
||||
keep 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.</p>
|
||||
|
||||
<p>Default value: <strong>0</strong></p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="multiple">
|
||||
<td>multiple</td>
|
||||
<td>boolean</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.
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="placeholder">
|
||||
<td>placeholder</td>
|
||||
<td>string or object</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="query">
|
||||
<td>query</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="resultsAdapter">
|
||||
<td>resultsAdapter</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="selectionAdapter">
|
||||
<td>selectionAdapter</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="selectOnClose">
|
||||
<td>selectOnClose</td>
|
||||
<td>boolean</td>
|
||||
<td>
|
||||
<p>Default value: <strong>false</strong></p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="sorter">
|
||||
<td>sorter</td>
|
||||
<td>function</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="tags">
|
||||
<td>tags</td>
|
||||
<td>boolean / array of objects</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="templateResult">
|
||||
<td>templateResult</td>
|
||||
<td>callback</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="templateSelection">
|
||||
<td>templateSelection</td>
|
||||
<td>callback</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="theme">
|
||||
<td>theme</td>
|
||||
<td>string</td>
|
||||
<td>
|
||||
<p>Default value: <strong>default</strong></p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="tokenizer">
|
||||
<td>tokenizer</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="tokenSeparators">
|
||||
<td>tokenSeparators</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr id="width">
|
||||
<td>width</td>
|
||||
<td>string</td>
|
||||
<td>
|
||||
<p>Specifies the <code>width</code> style attribute of the select2 container. The
|
||||
following values are supported:</p>
|
||||
|
||||
<dl class="dl-horizontal">
|
||||
<dt>element</dt>
|
||||
<dd>Uses the computed element width from any applicable CSS rules.</dd>
|
||||
|
||||
<dt>resolve</dt>
|
||||
<dd>Uses the <code>style</code> attribute value if available, falling
|
||||
back to the computed element width as necessary.</dd>
|
||||
|
||||
<dt>style</dt>
|
||||
<dd>Width is determined from the <code>select</code> element's <code>style</code>
|
||||
attribute. If no <code>style</code> attribute is found, null is returned as the
|
||||
width.</dd>
|
||||
|
||||
<dt><em>{width_value}</em></dt>
|
||||
<dd>Valid CSS values can be passed as a string (i.e. <code>80%</code>).</dd>
|
||||
</dl>
|
||||
|
||||
<p>Default value: <strong>resolve</strong></p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
```
|
||||
$('.js-example-basic-single').select2({
|
||||
placeholder: 'Select an option'
|
||||
});
|
||||
```
|
||||
|
||||
@ -118,6 +118,24 @@ You can, and should, use a `<label>` with Select2, just like any other `<select>
|
||||
|
||||
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):
|
||||
|
||||
<dl class="dl-horizontal">
|
||||
|
||||
<dt>element</dt>
|
||||
|
||||
<dd>Uses the computed element width from any applicable CSS rules.</dd>
|
||||
|
||||
<dt>resolve</dt>
|
||||
|
||||
<dd>Uses the `style` attribute value if available, falling back to the computed element width as necessary.</dd>
|
||||
|
||||
<dt>style</dt>
|
||||
|
||||
<dd>Width is determined from the `select` element's `style` attribute. If no `style` attribute is found, null is returned as the width.</dd>
|
||||
|
||||
<dt>_{width_value}_</dt>
|
||||
|
||||
<dd>Valid CSS values can be passed as a string (i.e. `80%`).</dd>
|
||||
|
||||
<table class="table table-striped table-bordered">
|
||||
<thead>
|
||||
<tr>
|
||||
@ -185,7 +203,7 @@ $(".js-example-responsive").select2({
|
||||
|
||||
>>>> 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
|
||||
## Themes
|
||||
|
||||
Select2 supports custom themes using the `theme` option so you can style Select2 to match the rest of your application.
|
||||
|
||||
|
||||
@ -59,3 +59,10 @@ $(".js-example-data-array-selected").select2({
|
||||
data: data
|
||||
})
|
||||
</script>
|
||||
|
||||
## Backwards compatibility with the `tags` option
|
||||
|
||||
In Select2 v3.5, this option was called `tags`. However in version 4.0, `tags` now handles the [tagging feature](/tagging).
|
||||
|
||||
For backwards compatibility the `tags` option can still accept an array of objects, in which case they will be handled in the same manner as the `data` option.
|
||||
|
||||
@ -70,6 +70,8 @@ $('select').select2({
|
||||
});
|
||||
```
|
||||
|
||||
>>> Note that this option is only applicable to multi-select controls.
|
||||
|
||||
## Dropdown placement
|
||||
|
||||
The `dropdownParent` option allows you to pick an element for the dropdown to be appended to:
|
||||
|
||||
@ -70,7 +70,7 @@ $(".js-example-basic-multiple-limit").select2({
|
||||
|
||||
## Clearable selections
|
||||
|
||||
You can allow users to clear their current selections with the `allowClear` option when initializing Select2. Setting this option to `true` will enable an "x" icon that will reset the selection to the placeholder.
|
||||
When set to `true`, causes a clear button ("x" icon) to appear on the select box when a value is selected. Clicking the clear button will clear the selected value, effectively resetting the select box back to its placeholder value.
|
||||
|
||||
```
|
||||
$('select').select2({
|
||||
|
||||
@ -67,13 +67,9 @@ Try entering a value that isn't listed in the dropdown - you'll be able to add i
|
||||
|
||||
## Automatic tokenization into tags
|
||||
|
||||
Select2 supports ability to add choices automatically as the user is
|
||||
typing into the search field. Try typing in the search field below and
|
||||
entering a space or a comma.
|
||||
Select2 supports ability to add choices automatically as the user is typing into the search field. Try typing in the search field below and entering a space or a comma.
|
||||
|
||||
The separators that should be used when tokenizing can be specified
|
||||
using the <a href="options.html#tokenSeparators">tokenSeparators</a>
|
||||
options.
|
||||
The separators that should be used when tokenizing can be specified using the `tokenSeparators` options.
|
||||
|
||||
<div class="s2-example">
|
||||
<p>
|
||||
|
||||
@ -6,7 +6,7 @@ taxonomy:
|
||||
|
||||
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.
|
||||
Most of the built-in features, such as those described in the previous chapters, are implemented via one of the [built-in adapters](/advanced/default-adapters). You may further extend the functionality of Select2 by implementing your own adapters.
|
||||
|
||||
## Adapter interfaces
|
||||
|
||||
@ -127,4 +127,4 @@ $.fn.select2.amd.require(
|
||||
|
||||
## 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.
|
||||
You can find more information on how to integrate Select2 with your existing AMD-based project [here](/getting-started/builds-and-modules). 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.
|
||||
|
||||
@ -22,14 +22,6 @@ 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`
|
||||
|
||||
@ -46,3 +38,31 @@ This decorator implements the [maximum search term length](/searching#maximum-se
|
||||
**AMD Modules:**
|
||||
|
||||
`select2/data/maximumInputLength`
|
||||
|
||||
### `InitSelection`
|
||||
|
||||
This decorator provides backwards compatibility for the `initSelection` callback in version 3.5.
|
||||
|
||||
In the past, Select2 required an option called `initSelection` that was defined whenever a custom data source was being used, allowing for the initial selection for the component to be determined. This has been replaced by the `current` method on the data adapter.
|
||||
|
||||
**AMD Modules:**
|
||||
|
||||
`select2/compat/initSelection"`
|
||||
|
||||
### `Query`
|
||||
|
||||
This decorator provides backwards compatibility for the `query` callback in version 3.5.
|
||||
|
||||
**AMD Modules:**
|
||||
|
||||
`select2/compat/query`
|
||||
|
||||
### `InputData`
|
||||
|
||||
This decorator implements backwards compatibility with version 3.5's `<input type="hidden" >` elements.
|
||||
|
||||
In past versions of Select2, a `<select>` element could only be used with a limited subset of options. An `<input type="hidden" >` tag was required instead, which did not allow for a graceful fallback for users who did not have JavaScript enabled. Select2 now supports the `<select>` element for all options, so it is no longer required to use `<input />` elements with Select2.
|
||||
|
||||
**AMD Modules:**
|
||||
|
||||
`select2/compat/inputData`
|
||||
|
||||
@ -1,752 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Select2 4.0.0 Released
|
||||
slug: announcements-4.0
|
||||
---
|
||||
<section id="pre-release" class="jumbotron">
|
||||
<div class="container">
|
||||
<h1>Announcing Select2 4.0.0</h1>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<div class="container s2-docs-container">
|
||||
<div class="row">
|
||||
<div class="col-md-9" role="main">
|
||||
|
||||
<section id="release">
|
||||
<h1 class="page-header">Select2 4.0.0</h1>
|
||||
|
||||
<p class="lead">
|
||||
The 4.0 release of Select2 is the result of three years of working on the
|
||||
code base and watching where it needs to go. At the core, it is a full
|
||||
rewrite that addresses many of the extensibility and usability problems
|
||||
that could not be addressed in previous versions.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
This release contains many breaking changes, but easy-upgrade paths have
|
||||
been created as well as helper modules that will allow for backwards
|
||||
compatibility to be maintained with past versions of Select2. Upgrading
|
||||
<em>will</em> require you to read the release notes carefully, but the
|
||||
migration path should be relatively straightforward. You can view a list
|
||||
of the most common changes that you will need to make
|
||||
<a href="https://github.com/select2/select2/releases">in the release notes</a>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Below is an in-depth review of what is new in Select2, as well as some of
|
||||
the major changes that have been made.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section id="new">
|
||||
<h2>New features</h2>
|
||||
|
||||
<p>
|
||||
The notable features of this new release include:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
A more flexible plugin framework that allows you to override Select2 to
|
||||
behave exactly how you want it to.
|
||||
</li>
|
||||
<li>
|
||||
Consistency with standard <code><select></code> elements for all
|
||||
data adapters, removing the need for hidden <code><input></code>
|
||||
elements.
|
||||
</li>
|
||||
<li>
|
||||
A new build system that uses AMD to keep everything organized.
|
||||
</li>
|
||||
<li>
|
||||
Less specific selectors allowing for Select2 to be styled to fit the
|
||||
rest of your application.
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<section id="plugins">
|
||||
<h2>Plugin system</h2>
|
||||
|
||||
<p>
|
||||
Select2 now provides interfaces that allow for it to be easily extended,
|
||||
allowing for anyone to create a plugin that changes the way Select2 works.
|
||||
This is the result of Select2 being broken into four distinct sections,
|
||||
each of which can be extended and used together to create your unique
|
||||
Select2.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The adapters implement a consistent interface that is documented in the
|
||||
<a href="options.html#adapters">options section for adapters</a>, allowing
|
||||
you to customize Select2 to do exactly what you are looking for. Select2
|
||||
is designed such that you can mix and match plugins, with most of the core
|
||||
options being built as decorators that wrap the standard adapters.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section id="amd-builds">
|
||||
<h2>AMD-based build system</h2>
|
||||
|
||||
<p>
|
||||
Select2 now uses an
|
||||
<a href="https://en.wikipedia.org/wiki/Asynchronous_module_definition">AMD-based build system</a>,
|
||||
allowing for builds that only require the parts of Select2 that you need.
|
||||
While a custom build system has not yet been created, Select2 is open
|
||||
source and will gladly accept a pull request for one.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Select2 includes the minimal <a href="https://github.com/jrburke/almond">almond</a>
|
||||
AMD loader, but a custom <code>select2.amd.js</code> build is available
|
||||
if you already use an AMD loader. The code base (available in the
|
||||
<code>src</code> directory) also uses AMD, allowing you to include Select2
|
||||
in your own build system and generate your own builds alongside your
|
||||
existing infrastructure.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The AMD methods used by Select2 are available as
|
||||
<code>jQuery.fn.select2.amd.define()/require()</code>, allowing you to use the
|
||||
included almond loader. These methods are primarily used by the
|
||||
translations, but they are the recommended way to access custom modules
|
||||
that Select2 provides.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section id="migrating">
|
||||
<h1>Migrating from Select2 3.5</h1>
|
||||
|
||||
<p>
|
||||
There are a few breaking changes that migrators should be aware of when
|
||||
they are coming from older versions of Select2.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
If you use the full build of Select2 (<code>select2.full.js</code>), you
|
||||
will be automatically notified of the major breaking changes, and
|
||||
compatibility modules will be used in some cases to ensure that your code
|
||||
still behaves how you were expecting.
|
||||
</p>
|
||||
|
||||
<h2 id="hidden-input">No more hidden input tags</h2>
|
||||
|
||||
<p>
|
||||
In past versions of Select2, an <code><input type="hidden" /></code>
|
||||
tag was recommended if you wanted to do anything advanced with Select2,
|
||||
such as work with remote data sources or allow users to add their own
|
||||
tags. This had the unfortunate side-effect of servers not receiving the
|
||||
data from Select2 as an array, like a standard <code><select></code>
|
||||
element does, but instead sending a string containing the comma-separated
|
||||
strings. The code base ended up being littered with special cases for the
|
||||
hidden input, and libraries using Select2 had to work around the
|
||||
differences it caused.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
In Select2 4.0, the <code><select></code> element supports all core
|
||||
options, and support for the old
|
||||
<code><input type="hidden" /></code> has been deprecated. This means
|
||||
that if you previously declared an AJAX field with some pre-selected
|
||||
options that looked like…
|
||||
</p>
|
||||
|
||||
{% highlight html linenos %}
|
||||
<input type="hidden" name="select-boxes" value="1,2,4,6" />
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
It will need to be recreated as a <code><select></code> element with
|
||||
some <code><option></code> tags that have <code>value</code>
|
||||
attributes that match the old value.
|
||||
</p>
|
||||
|
||||
{% highlight html linenos %}
|
||||
<select name="select-boxes" multiple="multiple">
|
||||
<option value="1" selected="selected">Select2</option>
|
||||
<option value="2" selected="selected">Chosen</option>
|
||||
<option value="4" selected="selected">selectize.js</option>
|
||||
<option value="6" selected="selected">typeahead.js</option>
|
||||
</select>
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
The options that you create should have <code>selected="selected"</code>
|
||||
set so Select2 and the browser knows that they should be selected. The
|
||||
<code>value</code> attribute of the option should also be set to the value
|
||||
that will be returned from the server for the result, so Select2 can
|
||||
highlight it as selected in the dropdown. The text within the option
|
||||
should also reflect the value that should be displayed by default for the
|
||||
option.
|
||||
</p>
|
||||
|
||||
<h2 id="new-matcher">Advanced matching of searches</h2>
|
||||
|
||||
<p>
|
||||
In past versions of Select2, when matching search terms to individual
|
||||
options, which limited the control that you had when displaying results,
|
||||
especially in cases where there was nested data. The <code>matcher</code>
|
||||
function was only given the individual option, even if it was a nested
|
||||
options, without any context.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
With the new matcher function, only the root-level options are matched and
|
||||
matchers are expected to limit the results of any children options that
|
||||
they contain. This allows developers to customize how options within
|
||||
groups can be displayed, and modify how the results are returned.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
A function has been created that allows old-style matcher functions to be
|
||||
converted to the new style. You can retrieve the function from the
|
||||
<code>select2/compat/matcher</code> module, which should just wrap the old
|
||||
matcher function.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
So if your old code used a matcher that only displayed options if they
|
||||
started with the term that was entered, it would look something like…
|
||||
</p>
|
||||
|
||||
{% highlight js linenos %}
|
||||
function matchStart (term, text) {
|
||||
if (text.toUpperCase().indexOf(term.toUpperCase()) == 0) {
|
||||
return true;
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
$("select").select2({
|
||||
matcher: matchStart
|
||||
})
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
Then in Select2 4.0, you would need to wrap the <code>matchStart</code>
|
||||
method (or the name of the matcher you created) with a
|
||||
<code>oldMatcher</code> method that we have created.
|
||||
</p>
|
||||
|
||||
{% highlight js linenos %}
|
||||
function matchStart (term, text) {
|
||||
if (text.toUpperCase().indexOf(term.toUpperCase()) == 0) {
|
||||
return true;
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
$.fn.select2.amd.require(['select2/compat/matcher'], function (oldMatcher) {
|
||||
$("select").select2({
|
||||
matcher: oldMatcher(matchStart)
|
||||
})
|
||||
});
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
This will work for any matchers that only took in the search term and the
|
||||
text of the option as parameters. If your matcher relied on the third
|
||||
parameter containing the jQuery element representing the original
|
||||
<code><option></code> tag, then you may need to slightly change
|
||||
your matcher to expect the full JavaScript data object being passed in
|
||||
instead. You can still retrieve the jQuery element from the data object
|
||||
using the <code>data.element</code> property.
|
||||
</p>
|
||||
|
||||
<h2 id="flexible-placeholders">More flexible placeholders</h2>
|
||||
|
||||
<p>
|
||||
In the most recent versions of Select2, placeholders could only be
|
||||
applied to the first (typically the default) option in a
|
||||
<code><select></code> if it was blank. The
|
||||
<code>placeholderOption</code> option was added to Select2 to allow users
|
||||
using the <code>select</code> tag to select a different option, typically
|
||||
an automatically generated option with a different value.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The <code>placeholder</code> option can now take an object as well as just
|
||||
a string. This replaces the need for the old
|
||||
<code>placeholderOption</code>, as now the <code>id</code> of the object
|
||||
can be set to the <code>value</code> attribute of the
|
||||
<code><option></code> tag.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For a select that looks like the following, where the first option (with a
|
||||
value of <code>-1</code>) is the placeholder option…
|
||||
</p>
|
||||
|
||||
{% highlight html linenos %}
|
||||
<select>
|
||||
<option value="-1" selected="selected">Select an option</option>
|
||||
<option value="1">Something else</option>
|
||||
</select>
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
You would have previously had to get the placeholder option through the
|
||||
<code>placeholderOption</code>, but now you can do it through the
|
||||
<code>placeholder</code> option by setting an <code>id</code>.
|
||||
</p>
|
||||
|
||||
{% highlight js linenos %}
|
||||
$("select").select2({
|
||||
placeholder: {
|
||||
id: "-1",
|
||||
placeholder: "Select an option"
|
||||
}
|
||||
})
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
And Select2 will automatically display the placeholder when the value of
|
||||
the select is <code>-1</code>, which it will be by default. This does not
|
||||
break the old functionality of Select2 where the placeholder option was
|
||||
blank by default.
|
||||
</p>
|
||||
|
||||
<h2 id="value-ordering">Display reflects the actual order of the values</h2>
|
||||
|
||||
<p>
|
||||
In past versions of Select2, choices were displayed in the order that
|
||||
they were selected. In cases where Select2 was used on a
|
||||
<code><select></code> element, the order that the server received
|
||||
the selections did not always match the order that the choices were
|
||||
displayed, resulting in confusion in situations where the order is
|
||||
important.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Select2 will now order selected choices in the same order that will be
|
||||
sent to the server.
|
||||
</p>
|
||||
|
||||
<h2 id="changed-options">Changed method and option names</h2>
|
||||
|
||||
<p>
|
||||
When designing the future option set for Select2 4.0, special care was
|
||||
taken to ensure that the most commonly used options were brought over.
|
||||
For the most part, the commonly used options of Select2 can still be
|
||||
referenced under their previous names, but there were some changes which
|
||||
have been noted.
|
||||
</p>
|
||||
|
||||
<h3 id="removed-initselection">
|
||||
Removed the requirement of <code>initSelection</code>
|
||||
</h3>
|
||||
|
||||
<p>
|
||||
In the past, whenever you wanted to use a custom data adapter, such as
|
||||
AJAX or tagging, you needed to help Select2 out in determining the initial
|
||||
values that were selected. This was typically done through the
|
||||
<code>initSelection</code> option, which took the underlying data of the
|
||||
input and converted it into data objects that Select2 could use.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
This is now handled by
|
||||
<a href="options.html#dataAdapter">the data adapter</a> in the
|
||||
<code>current</code> method, which allows Select2 to convert the currently
|
||||
selected values into data objects that can be displayed. The default
|
||||
implementation converts the text and value of <code>option</code> elements
|
||||
into data objects, and is probably suitable for most cases. An example of
|
||||
the old <code>initSelection</code> option is included below, which
|
||||
converts the value of the selected options into a data object with both
|
||||
the <code>id</code> and <code>text</code> matching the selected value.
|
||||
</p>
|
||||
|
||||
{% highlight js linenos %}
|
||||
{
|
||||
initSelection : function (element, callback) {
|
||||
var data = [];
|
||||
$(element.val()).each(function () {
|
||||
data.push({id: this, text: this});
|
||||
});
|
||||
callback(data);
|
||||
}
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
When using the new <code>current</code> method of the custom data adapter,
|
||||
<strong>this method is called any time Select2 needs a list</strong> of
|
||||
the currently selected options. This is different from the old
|
||||
<code>initSelection</code> in that it was only called once, so it could
|
||||
suffer from being relatively slow to process the data (such as from a
|
||||
remote data source).
|
||||
</p>
|
||||
|
||||
{% highlight js linenos %}
|
||||
$.fn.select2.amd.require([
|
||||
'select2/data/array',
|
||||
'select2/utils'
|
||||
], function (ArrayData, Utils) {
|
||||
function CustomData ($element, options) {
|
||||
CustomData.__super__.constructor.call(this, $element, options);
|
||||
}
|
||||
|
||||
Utils.Extend(CustomData, ArrayData);
|
||||
|
||||
CustomData.prototype.current = function (callback) {
|
||||
var data = [];
|
||||
var currentVal = this.$element.val();
|
||||
|
||||
if (!this.$element.prop('multiple')) {
|
||||
currentVal = [currentVal];
|
||||
}
|
||||
|
||||
for (var v = 0; v < currentVal.length; v++) {
|
||||
data.push({
|
||||
id: currentVal[v],
|
||||
text: currentVal[v]
|
||||
});
|
||||
}
|
||||
|
||||
callback(data);
|
||||
};
|
||||
|
||||
$("#select").select2({
|
||||
dataAdapter: CustomData
|
||||
});
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
The new <code>current</code> method of the data adapter works in a similar
|
||||
way to the old <code>initSelection</code> method, with three notable
|
||||
differences. The first, and most important, is that <strong>it is called
|
||||
whenever the current selections are needed</strong> to ensure that Select2
|
||||
is always displaying the most accurate and up to date data. No matter
|
||||
what type of element Select2 is attached to, whether it supports a
|
||||
single or multiple selections, the data passed to the callback
|
||||
<strong>must be an array, even if it contains one selection</strong>.
|
||||
The last is that there is only one parameter, the callback to be
|
||||
executed with the latest data, and the current element that Select2 is
|
||||
attached to is available on the class itself as
|
||||
<code>this.$element</code>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
If you only need to load in the initial options once, and otherwise will
|
||||
be letting Select2 handle the state of the selections, you don't need to
|
||||
use a custom data adapter. You can just create the
|
||||
<code><option></code> tags on your own, and Select2 will pick up
|
||||
the changes.
|
||||
</p>
|
||||
|
||||
{% highlight js linenos %}
|
||||
var $element = $('select').select2(); // the select element you are working with
|
||||
|
||||
var $request = $.ajax({
|
||||
url: '/my/remote/source' // wherever your data is actually coming from
|
||||
});
|
||||
|
||||
$request.then(function (data) {
|
||||
// This assumes that the data comes back as an array of data objects
|
||||
// The idea is that you are using the same callback as the old `initSelection`
|
||||
|
||||
for (var d = 0; d < data.length; d++) {
|
||||
var item = data[d];
|
||||
|
||||
// Create the DOM option that is pre-selected by default
|
||||
var option = new Option(item.text, item.id, true, true);
|
||||
|
||||
// Append it to the select
|
||||
$element.append(option);
|
||||
}
|
||||
|
||||
// Update the selected options that are displayed
|
||||
$element.trigger('change');
|
||||
});
|
||||
{% endhighlight %}
|
||||
|
||||
<h3 id="query-to-data-adapter">
|
||||
Custom data adapters instead of <code>query</code>
|
||||
</h3>
|
||||
|
||||
<p>
|
||||
<a href="http://select2.github.io/select2/#data">In the past</a>, any time
|
||||
you wanted to hook Select2 up to a different data source you would be
|
||||
required to implement custom <code>query</code> and
|
||||
<code>initSelection</code> methods. This allowed Select2 to determine the
|
||||
initial selection and the list of results to display, and it would handle
|
||||
everything else internally, which was fine more most people.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The custom <code>query</code> and <code>initSelection</code> methods have
|
||||
been replaced by
|
||||
<a href="options.html#dataAdapter">custom data adapters</a> that handle
|
||||
how Select2 stores and retrieves the data that will be displayed to the
|
||||
user. An example of the old <code>query</code> option is provided below,
|
||||
which is
|
||||
<a href="http://select2.github.io/select2/#data">the same as the old example</a>,
|
||||
and it generates results that contain the search term repeated a certain
|
||||
number of times.
|
||||
</p>
|
||||
|
||||
{% highlight js linenos %}
|
||||
{
|
||||
query: function (query) {
|
||||
var data = {results: []}, i, j, s;
|
||||
for (i = 1; i < 5; i++) {
|
||||
s = "";
|
||||
for (j = 0; j < i; j++) {s = s + query.term;}
|
||||
data.results.push({id: query.term + i, text: s});
|
||||
}
|
||||
query.callback(data);
|
||||
}
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
This has been replaced by custom data adapters which define a similarly
|
||||
named <code>query</code> method. The comparable data adapter is provided
|
||||
below as an example.
|
||||
</p>
|
||||
|
||||
{% highlight js linenos %}
|
||||
$.fn.select2.amd.require([
|
||||
'select2/data/array',
|
||||
'select2/utils'
|
||||
], function (ArrayData, Utils) {
|
||||
function CustomData ($element, options) {
|
||||
CustomData.__super__.constructor.call(this, $element, options);
|
||||
}
|
||||
|
||||
Utils.Extend(CustomData, ArrayData);
|
||||
|
||||
CustomData.prototype.query = function (params, callback) {
|
||||
var data = {
|
||||
results: []
|
||||
};
|
||||
|
||||
for (var i = 1; i < 5; i++) {
|
||||
var s = "";
|
||||
|
||||
for (var j = 0; j < i; j++) {
|
||||
s = s + params.term;
|
||||
}
|
||||
|
||||
data.results.push({
|
||||
id: params.term + i,
|
||||
text: s
|
||||
});
|
||||
}
|
||||
|
||||
callback(data);
|
||||
};
|
||||
|
||||
$("#select").select2({
|
||||
dataAdapter: CustomData
|
||||
});
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
The new <code>query</code> method of the data adapter is very similar to
|
||||
the old <code>query</code> option that was passed into Select2 when
|
||||
initializing it. The old <code>query</code> argument is mostly the same as
|
||||
the new <code>params</code> that are passed in to query on, and the
|
||||
callback that should be used to return the results is now passed in as the
|
||||
second parameter.
|
||||
</p>
|
||||
|
||||
<h3 id="changed-templating">Renamed templating options</h3>
|
||||
|
||||
<p>
|
||||
Select2 previously provided multiple options for formatting the results
|
||||
list and selected options, commonly referred to as "formatters", using the
|
||||
<code>formatSelection</code> and <code>formatResult</code> options. As the
|
||||
"formatters" were also used for things such as localization,
|
||||
<a href="#changed-translations">which has also changed</a>, they have been
|
||||
renamed to <code>templateSelection</code> and <code>templateResult</code>
|
||||
and their signatures have changed as well.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
You should refer to the updated
|
||||
<a href="options.html#templating">documentation on templates</a> when
|
||||
migrating from previous versions of Select2.
|
||||
</p>
|
||||
|
||||
<h3 id="changed-id">
|
||||
The <code>id</code> and <code>text</code> properties are strictly enforced
|
||||
</h3>
|
||||
|
||||
<p>
|
||||
When working with array and AJAX data in the past, Select2 allowed a
|
||||
custom <code>id</code> function or attribute to be set in various places,
|
||||
ranging from the initialization of Select2 to when the remote data was
|
||||
being returned. This allowed Select2 to better integrate with existing
|
||||
data sources that did not necessarily use the <code>id</code> attribute to
|
||||
indicate the unique identifier for an object.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Select2 no longer supports a custom <code>id</code> or <code>text</code>
|
||||
to be used, but provides integration points for converting incorrect data
|
||||
to the expected format.
|
||||
</p>
|
||||
|
||||
<h4>
|
||||
When working with array data
|
||||
</h4>
|
||||
|
||||
<p>
|
||||
Select2 previously supported defining array data as an object that matched
|
||||
the signature of an AJAX response. A <code>text</code> property could be
|
||||
specified that would map the given property to the <code>text</code>
|
||||
property on the individual objects. You can now do this when initializing
|
||||
Select2 by using the following jQuery code to map the old
|
||||
<code>text</code> and <code>id</code> properties to the new ones.
|
||||
</p>
|
||||
|
||||
{% highlight js linenos %}
|
||||
var data = $.map([
|
||||
{
|
||||
pk: 1,
|
||||
word: 'one'
|
||||
},
|
||||
{
|
||||
pk: 2,
|
||||
word: 'two'
|
||||
}
|
||||
], function (obj) {
|
||||
obj.id = obj.id || obj.pk;
|
||||
obj.text = obj.text || obj.word;
|
||||
|
||||
return obj;
|
||||
});
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
This will result in an array of data objects that have the <code>id</code>
|
||||
properties that match the existing <code>pk</code> properties and
|
||||
<code>text</code> properties that match the existing <code>word</code>
|
||||
properties.
|
||||
</p>
|
||||
|
||||
<h4>
|
||||
When working with remote data
|
||||
</h4>
|
||||
|
||||
<p>
|
||||
The same code that was given above can be used in the
|
||||
<code>processResults</code> method of an AJAX call to map properties there
|
||||
as well.
|
||||
</p>
|
||||
|
||||
<h3 id="changed-translations">Renamed translation options</h3>
|
||||
|
||||
<p>
|
||||
In previous versions of Select2, the default messages provided to users
|
||||
could be localized to fit the language of the website that it was being
|
||||
used on. Select2 only comes with the English language by default, but
|
||||
provides
|
||||
<a href="options.html#language">community-contributed translations</a> for
|
||||
many common languages. Many of the formatters have been moved to the
|
||||
<code>language</code> option and the signatures of the formatters have
|
||||
been changed to handle future additions.
|
||||
</p>
|
||||
|
||||
<h3 id="changed-data">
|
||||
Declaring options using <code>data-*</code> attributes
|
||||
</h3>
|
||||
|
||||
<p>
|
||||
In the past, Select2 has only supported declaring a subset of options
|
||||
using <code>data-*</code> attributes. Select2 now supports declaring all
|
||||
options using the attributes, using
|
||||
<a href="options.html#data-attributes">the format specified in the documentation</a>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
You could previously declare the URL that was used for AJAX requests using
|
||||
the <code>data-ajax-url</code> attribute. While Select2 still allows for
|
||||
this, the new attribute that should be used is the
|
||||
<code>data-ajax--url</code> attribute. Support for the old attribute will
|
||||
be removed in Select2 4.1.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Although it was not documented, a list of possible tags could also be
|
||||
provided using the <code>data-select2-tags</code> attribute and passing in
|
||||
a JSON-formatted array of objects for tags. As the method for specifying
|
||||
tags has changed in 4.0, you should now provide the array of objects using
|
||||
the <code>data-data</code> attribute, which maps to
|
||||
<a href="options.html#data">the array data</a> option. You should also
|
||||
enable tags by setting <code>data-tags="true"</code> on the object, to
|
||||
maintain the ability for users to create their own options as well.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
If you previously declared the list of tags as…
|
||||
</p>
|
||||
|
||||
{% highlight html linenos %}
|
||||
<select data-select2-tags='[{"id": "1", "text": "One"}, {"id": "2", "text": "Two"}]'></select>
|
||||
{% endhighlight %}
|
||||
|
||||
<p>
|
||||
…then you should now declare it as…
|
||||
</p>
|
||||
|
||||
{% highlight html linenos %}
|
||||
<select data-data='[{"id": "1", "text": "One"}, {"id": "2", "text": "Two"}]' data-tags="true"></select>
|
||||
{% endhighlight %}
|
||||
|
||||
<h2 id="removed-methods">Deprecated and removed methods</h2>
|
||||
|
||||
<p>
|
||||
As Select2 now uses a <code><select></code> element for all data
|
||||
sources, a few methods that were available by calling
|
||||
<code>.select2()</code> are no longer required.
|
||||
</p>
|
||||
|
||||
<h3>.select2("val")</h3>
|
||||
|
||||
<p>
|
||||
The <code>"val"</code> method has been deprecated and will be removed in
|
||||
Select2 4.1. The deprecated method no longer includes the
|
||||
<code>triggerChange</code> parameter.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
You should directly call <code>.val</code> on the underlying
|
||||
<code><select></code> element instead. If you needed the second
|
||||
parameter (<code>triggerChange</code>), you should also call
|
||||
<code>.trigger("change")</code> on the element.
|
||||
</p>
|
||||
|
||||
{% highlight js linenos %}
|
||||
$("select").val("1").trigger("change"); // instead of $("select").select2("val", "1");
|
||||
{% endhighlight %}
|
||||
|
||||
<h3>.select2("enable")</h3>
|
||||
|
||||
<p>
|
||||
Select2 will respect the <code>disabled</code> property of the underlying
|
||||
select element. In order to enable or disable Select2, you should call
|
||||
<code>.prop('disabled', true/false)</code> on the
|
||||
<code><select></code> element. Support for the old methods will be
|
||||
completely removed in Select2 4.1.
|
||||
</p>
|
||||
|
||||
{% highlight js linenos %}
|
||||
$("select").prop("disabled", true); // instead of $("select").enable(false);
|
||||
{% endhighlight %}
|
||||
|
||||
</section>
|
||||
</div>
|
||||
<div class="col-md-3" role="complementary">
|
||||
|
||||
{% include nav/announcements-4.0.html %}
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
@ -1,231 +0,0 @@
|
||||
|
||||
|
||||
|
||||
### 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>
|
||||
<div class="page-header">
|
||||
<h1 id="compatibility">Backwards compatibility</h1>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
Select2 offers limited backwards compatibility with the previously 3.5.x
|
||||
release line, allowing people more efficiently transfer across releases
|
||||
and get the latest features. For many of the larger changes, such as the
|
||||
change in how custom data adapters work, compatibility modules were
|
||||
created that will be used to assist in the upgrade process. It is not
|
||||
recommended to rely on these compatibility modules, as they will not
|
||||
always exist, but they make upgrading easier for major changes.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<strong>The compatibility modules are only included in the
|
||||
<a href="index.html#builds-full" class="alert-link">full builds</a> of
|
||||
Select2</strong>. These files end in <code>.full.js</code>, and the
|
||||
compatibility modules are prefixed with <code>select2/compat</code>.
|
||||
</p>
|
||||
|
||||
<h2 id="compat-matcher">
|
||||
Simplified function for matching data objects
|
||||
</h2>
|
||||
|
||||
<p class="alert alert-info">
|
||||
<a href="announcements-4.0.html#new-matcher" class="alert-link">Added in Select2 4.0.0.</a>
|
||||
This method was added to make upgrading easier from earlier versions of
|
||||
Select2.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
During the <a href="announcements-4.0.html">Select2 4.0.0 release</a>, the
|
||||
<code>matcher</code> function was changed to allow for more complex
|
||||
matching of nested objects.
|
||||
</p>
|
||||
|
||||
<div class="row">
|
||||
<div class="col-sm-6">
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Key</dt>
|
||||
<dd>
|
||||
<code>matcher</code>
|
||||
</dd>
|
||||
|
||||
<dt>Value</dt>
|
||||
<dd>
|
||||
A function taking a search <code>term</code> and the data object
|
||||
<code>text</code>.
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
|
||||
<div class="col-sm-6">
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Adapter</dt>
|
||||
<dd>
|
||||
<code title="select2/compat/matcher">oldMatcher</code>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
The <a href="examples.html#matcher">custom matcher example</a> provides a
|
||||
guide for how to use this in your own application. For those upgrading
|
||||
from older versions of Select2, you just need to wrap your old
|
||||
<code>matcher</code> with this function to maintain compatibility.
|
||||
</p>
|
||||
|
||||
<h2 id="initSelection">
|
||||
Old initial selections with <code>initSelection</code>
|
||||
</h2>
|
||||
|
||||
<p class="alert alert-warning">
|
||||
<a href="announcements-4.0.html#removed-initselection" class="alert-link">Deprecated in Select2 4.0.</a>
|
||||
This has been replaced by another option and is only available in the
|
||||
<a href="index.html#builds-full" class="alert-link">full builds</a> of
|
||||
Select2.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
In the past, Select2 required an option called <code>initSelection</code>
|
||||
that was defined whenever a custom data source was being used, allowing
|
||||
for the initial selection for the component to be determined. This has
|
||||
been replaced by the <code>current</code> method on the
|
||||
<a href="#dataAdapter">data adapter</a>.
|
||||
</p>
|
||||
|
||||
<div class="row">
|
||||
<div class="col-sm-6">
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Key</dt>
|
||||
<dd>
|
||||
<code>initSelection</code>
|
||||
</dd>
|
||||
|
||||
<dt>Value</dt>
|
||||
<dd>
|
||||
A function taking a <code>callback</code>
|
||||
</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/compat/initSelection">InitSelection</code>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h2 id="query">
|
||||
Querying old data with <code>query</code>
|
||||
</h2>
|
||||
|
||||
<p class="alert alert-warning">
|
||||
<a href="announcements-4.0.html#query-to-data-adapter" class="alert-link">Deprecated in Select2 4.0.</a>
|
||||
This has been replaced by another option and is only available in the
|
||||
<a href="index.html#builds-full" class="alert-link">full builds</a> of
|
||||
Select2.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
In the past, Select2 supported an option called <code>query</code> that
|
||||
allowed for a custom data source to be used. This option has been replaced
|
||||
by the <code>query</code> method on the
|
||||
<a href="#dataAdapter">data adapter</a> and takes a very similar set of
|
||||
parameters.
|
||||
</p>
|
||||
|
||||
<div class="row">
|
||||
<div class="col-sm-6">
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Key</dt>
|
||||
<dd>
|
||||
<code>query</code>
|
||||
</dd>
|
||||
|
||||
<dt>Value</dt>
|
||||
<dd>
|
||||
A function taking <code>params</code> (including a <code>callback</code>)
|
||||
</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/compat/query">Query</code>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h2 id="input-fallback">
|
||||
Compatibility with <code><input type="text" /></code>
|
||||
</h2>
|
||||
|
||||
<p class="alert alert-warning">
|
||||
<a href="announcements-4.0.html#hidden-input" class="alert-link">Deprecated in Select2 4.0.</a>
|
||||
It is now encouraged to use the <code><select></code> tag instead.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
In past versions of Select2, a <code><select></code> element could
|
||||
only be used with a limited subset of options. An
|
||||
<code><input type="hidden" /></code> was required instead, which did
|
||||
not allow for a graceful fallback for users who did not have JavaScript
|
||||
enabled. Select2 now supports the <code><select></code> element for
|
||||
all options, so it is no longer required to use <code><input /></code>
|
||||
elements with Select2.
|
||||
</p>
|
||||
|
||||
<dl class="dl-horizontal">
|
||||
<dt>Adapter</dt>
|
||||
<dd>
|
||||
<code title="select2/data/base">DataAdapter</code>
|
||||
</dd>
|
||||
|
||||
<dt>Decorator</dt>
|
||||
<dd>
|
||||
<code title="select2/compat/inputData">InputData</code>
|
||||
</dd>
|
||||
</dl>
|
||||
</section>
|
||||
30
pages/14.upgrading/01.new-in-40/docs.md
Normal file
30
pages/14.upgrading/01.new-in-40/docs.md
Normal file
@ -0,0 +1,30 @@
|
||||
---
|
||||
title: What's new in 4.0
|
||||
taxonomy:
|
||||
category: docs
|
||||
---
|
||||
|
||||
The 4.0 release of Select2 is the result of three years of working on the code base and watching where it needs to go. At the core, it is a full rewrite that addresses many of the extensibility and usability problems that could not be addressed in previous versions.
|
||||
|
||||
This release contains many breaking changes, but easy-upgrade paths have been created as well as helper modules that will allow for backwards compatibility to be maintained with past versions of Select2. Upgrading **will** require you to read the release notes carefully, but the migration path should be relatively straightforward. You can view a list of the most common changes that you will need to make [in the release notes](https://github.com/select2/select2/releases).
|
||||
|
||||
The notable features of this new release include:
|
||||
|
||||
- A more flexible plugin framework that allows you to override Select2 to behave exactly how you want it to.
|
||||
- Consistency with standard `<select>` elements for all data adapters, removing the need for hidden `<input>` elements.
|
||||
- A new build system that uses AMD to keep everything organized.
|
||||
- Less specific selectors allowing for Select2 to be styled to fit the rest of your application.
|
||||
|
||||
## Plugin system
|
||||
|
||||
Select2 now provides interfaces that allow for it to be easily extended, allowing for anyone to create a plugin that changes the way Select2 works. This is the result of Select2 being broken into four distinct sections, each of which can be extended and used together to create your unique Select2.
|
||||
|
||||
The adapters implement a consistent interface that is documented in the [advanced chapter](/advanced/adapters-and-decorators), allowing you to customize Select2 to do exactly what you are looking for. Select2 is designed such that you can mix and match plugins, with most of the core options being built as decorators that wrap the standard adapters.
|
||||
|
||||
## AMD-based build system
|
||||
|
||||
Select2 now uses an [AMD-based build system](https://en.wikipedia.org/wiki/Asynchronous_module_definition), allowing for builds that only require the parts of Select2 that you need. While a custom build system has not yet been created, Select2 is open source and will gladly accept a pull request for one.
|
||||
|
||||
Select2 includes the minimal [almond](https://github.com/jrburke/almond) AMD loader, but a custom `select2.amd.js` build is available if you already use an AMD loader. The code base (available in the `src` directory) also uses AMD, allowing you to include Select2 in your own build system and generate your own builds alongside your existing infrastructure.
|
||||
|
||||
The AMD methods used by Select2 are available as `jQuery.fn.select2.amd.define()/require()`, allowing you to use the included almond loader. These methods are primarily used by the translations, but they are the recommended way to access custom modules that Select2 provides.
|
||||
356
pages/14.upgrading/02.migrating-from-35/docs.md
Normal file
356
pages/14.upgrading/02.migrating-from-35/docs.md
Normal file
@ -0,0 +1,356 @@
|
||||
---
|
||||
title: Migrating from Select2 3.5
|
||||
taxonomy:
|
||||
category: docs
|
||||
---
|
||||
|
||||
Select2 offers limited backwards compatibility with the previous 3.5.x release line, allowing people to more efficiently transfer across releases and get the latest features. For many of the larger changes, such as the change in how custom data adapters work, compatibility modules were created that will be used to assist in the upgrade process. It is not recommended to rely on these compatibility modules as they will eventually be removed in future releases, but they make upgrading easier for major changes.
|
||||
|
||||
If you use the full build of Select2 (`select2.full.js`), you will be automatically notified of the major breaking changes, and [compatibility modules](/upgrading/backwards-compatibility) will be automatically applied to ensure that your code still behaves how you were expecting.
|
||||
|
||||
The compatibility modules are only included in the [full builds](/getting-started/builds-and-modules) of Select2. These files end in `.full.js`, and the compatibility modules are prefixed with `select2/compat`.
|
||||
|
||||
## No more hidden input tags
|
||||
|
||||
In past versions of Select2, an `<input type="hidden">` tag was recommended if you wanted to do anything advanced with Select2, such as work with remote data sources or allow users to add their own tags. This had the unfortunate side-effect of servers not receiving the data from Select2 as an array, like a standard `<select>` element does, but instead sending a string containing the comma-separated strings. The code base ended up being littered with special cases for the hidden input, and libraries using Select2 had to work around the differences it caused.
|
||||
|
||||
In Select2 4.0, the `<select>` element supports all core options, and support for the old `<input type="hidden">` has been deprecated. This means that if you previously declared an AJAX field with some pre-selected options that looked like:
|
||||
|
||||
```
|
||||
<input type="hidden" name="select-boxes" value="1,2,4,6" />
|
||||
```
|
||||
|
||||
It will need to be recreated as a `<select>` element with some `<option>` tags that have `value` attributes that match the old value:
|
||||
|
||||
```
|
||||
<select name="select-boxes" multiple="multiple">
|
||||
<option value="1" selected="selected">Select2</option>
|
||||
<option value="2" selected="selected">Chosen</option>
|
||||
<option value="4" selected="selected">selectize.js</option>
|
||||
<option value="6" selected="selected">typeahead.js</option>
|
||||
</select>
|
||||
```
|
||||
|
||||
The options that you create should have `selected="selected"` set so Select2 and the browser knows that they should be selected. The `value` attribute of the option should also be set to the value that will be returned from the server for the result, so Select2 can highlight it as selected in the dropdown. The text within the option should also reflect the value that should be displayed by default for the option.
|
||||
|
||||
## Advanced matching of searches
|
||||
|
||||
In past versions of Select2 the `matcher` callback processed options at every level, which limited the control that you had when displaying results, especially in cases where there was nested data. The `matcher` function was only given the individual option, even if it was a nested options, without any context.
|
||||
|
||||
With the new [matcher function](/searching), only the root-level options are matched and matchers are expected to limit the results of any children options that they contain. This allows developers to customize how options within groups can be displayed, and modify how the results are returned.
|
||||
|
||||
### Wrapper for old-style `matcher` callbacks
|
||||
|
||||
For backwards compatibility, a wrapper function has been created that allows old-style matcher functions to be converted to the new style.
|
||||
|
||||
This custom matcher uses a [compatibility function](/configuration/deprecated) that is only bundled in the [full version of Select2](/getting-started/builds). You can retrieve the function from the `select2/compat/matcher` module, which should just wrap the old matcher function.
|
||||
|
||||
<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>
|
||||
|
||||
>>>> This will work for any matchers that only took in the search term and the text of the option as parameters. If your matcher relied on the third parameter containing the jQuery element representing the original `<option>` tag, then you may need to slightly change your matcher to expect the full JavaScript data object being passed in instead. You can still retrieve the jQuery element from the data object using the `data.element` property.
|
||||
|
||||
## More flexible placeholders
|
||||
|
||||
In the most recent versions of Select2, placeholders could only be applied to the first (typically the default) option in a `<select>` if it was blank. The `placeholderOption` option was added to Select2 to allow users using the `select` tag to select a different option, typically an automatically generated option with a different value.
|
||||
|
||||
The [`placeholder` option](/placeholders) can now take an object as well as just a string. This replaces the need for the old `placeholderOption`, as now the `id` of the object can be set to the `value` attribute of the `<option>` tag.
|
||||
|
||||
For a select that looks like the following, where the first option (with a value of `-1`) is the placeholder option:
|
||||
|
||||
```
|
||||
<select>
|
||||
<option value="-1" selected="selected">Select an option</option>
|
||||
<option value="1">Something else</option>
|
||||
</select>
|
||||
```
|
||||
|
||||
You would have previously had to get the placeholder option through the `placeholderOption`, but now you can do it through the `placeholder` option by setting an `id`.
|
||||
|
||||
```
|
||||
$("select").select2({
|
||||
placeholder: {
|
||||
id: "-1",
|
||||
placeholder: "Select an option"
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
And Select2 will automatically display the placeholder when the value of the select is `-1`, which it will be by default. This does not break the old functionality of Select2 where the placeholder option was blank by default.
|
||||
|
||||
## Display reflects the actual order of the values
|
||||
|
||||
In past versions of Select2, choices were displayed in the order that they were selected. In cases where Select2 was used on a `<select>` element, the order that the server received the selections did not always match the order that the choices were displayed, resulting in confusion in situations where the order is important.
|
||||
|
||||
Select2 will now order selected choices in the same order that will be sent to the server.
|
||||
|
||||
## Changed method and option names
|
||||
|
||||
When designing the future option set for Select2 4.0, special care was taken to ensure that the most commonly used options were brought over. For the most part, the commonly used options of Select2 can still be referenced under their previous names, but there were some changes which have been noted.
|
||||
|
||||
### Removed the requirement of `initSelection`
|
||||
|
||||
>>>> **Deprecated in Select2 4.0.** This has been replaced by another option and is only available in the [full builds](/getting-started/builds-and-modules) of Select2.
|
||||
|
||||
In the past, whenever you wanted to use a custom data adapter, such as AJAX or tagging, you needed to help Select2 out in determining the initial
|
||||
values that were selected. This was typically done through the `initSelection` option, which took the underlying data of the input and converted it into data objects that Select2 could use.
|
||||
|
||||
This is now handled by [the data adapter](/advanced/default-adapters/data) in the `current` method, which allows Select2 to convert the currently
|
||||
selected values into data objects that can be displayed. The default implementation converts the text and value of `option` elements into data objects, and is probably suitable for most cases. An example of the old `initSelection` option is included below, which converts the value of the selected options into a data object with both the `id` and `text` matching the selected value.
|
||||
|
||||
```
|
||||
{
|
||||
initSelection : function (element, callback) {
|
||||
var data = [];
|
||||
$(element.val()).each(function () {
|
||||
data.push({id: this, text: this});
|
||||
});
|
||||
callback(data);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When using the new `current` method of the custom data adapter, **this method is called any time Select2 needs a list** of the currently selected options. This is different from the old `initSelection` in that it was only called once, so it could suffer from being relatively slow to process the data (such as from a remote data source).
|
||||
|
||||
```
|
||||
$.fn.select2.amd.require([
|
||||
'select2/data/array',
|
||||
'select2/utils'
|
||||
], function (ArrayData, Utils) {
|
||||
function CustomData ($element, options) {
|
||||
CustomData.__super__.constructor.call(this, $element, options);
|
||||
}
|
||||
|
||||
Utils.Extend(CustomData, ArrayData);
|
||||
|
||||
CustomData.prototype.current = function (callback) {
|
||||
var data = [];
|
||||
var currentVal = this.$element.val();
|
||||
|
||||
if (!this.$element.prop('multiple')) {
|
||||
currentVal = [currentVal];
|
||||
}
|
||||
|
||||
for (var v = 0; v < currentVal.length; v++) {
|
||||
data.push({
|
||||
id: currentVal[v],
|
||||
text: currentVal[v]
|
||||
});
|
||||
}
|
||||
|
||||
callback(data);
|
||||
};
|
||||
|
||||
$("#select").select2({
|
||||
dataAdapter: CustomData
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
The new `current` method of the data adapter works in a similar way to the old `initSelection` method, with three notable differences. The first, and most important, is that **it is called whenever the current selections are needed** to ensure that Select2 is always displaying the most accurate and up to date data. No matter what type of element Select2 is attached to, whether it supports a single or multiple selections, the data passed to the callback **must be an array, even if it contains one selection**.
|
||||
|
||||
The last is that there is only one parameter, the callback to be executed with the latest data, and the current element that Select2 is attached to is available on the class itself as `this.$element`.
|
||||
|
||||
If you only need to load in the initial options once, and otherwise will be letting Select2 handle the state of the selections, you don't need to use a custom data adapter. You can just create the `<option>` tags on your own, and Select2 will pick up the changes.
|
||||
|
||||
```
|
||||
var $element = $('select').select2(); // the select element you are working with
|
||||
|
||||
var $request = $.ajax({
|
||||
url: '/my/remote/source' // wherever your data is actually coming from
|
||||
});
|
||||
|
||||
$request.then(function (data) {
|
||||
// This assumes that the data comes back as an array of data objects
|
||||
// The idea is that you are using the same callback as the old `initSelection`
|
||||
|
||||
for (var d = 0; d < data.length; d++) {
|
||||
var item = data[d];
|
||||
|
||||
// Create the DOM option that is pre-selected by default
|
||||
var option = new Option(item.text, item.id, true, true);
|
||||
|
||||
// Append it to the select
|
||||
$element.append(option);
|
||||
}
|
||||
|
||||
// Update the selected options that are displayed
|
||||
$element.trigger('change');
|
||||
});
|
||||
```
|
||||
|
||||
### Custom data adapters instead of `query`
|
||||
|
||||
>>>> **Deprecated in Select2 4.0.** This has been replaced by another option and is only available in the [full builds](/getting-started/builds-and-modules) of Select2.
|
||||
|
||||
[In the past](http://select2.github.io/select2/#data), any time you wanted to hook Select2 up to a different data source you would be required to implement custom `query` and `initSelection` methods. This allowed Select2 to determine the initial selection and the list of results to display, and it would handle everything else internally, which was fine more most people.
|
||||
|
||||
The custom `query` and `initSelection` methods have been replaced by [custom data adapters](/advanced/default-adapters/data) that handle how Select2 stores and retrieves the data that will be displayed to the user. An example of the old `query` option is provided below, which is
|
||||
[the same as the old example](http://select2.github.io/select2/#data), and it generates results that contain the search term repeated a certain number of times.
|
||||
|
||||
```
|
||||
{
|
||||
query: function (query) {
|
||||
var data = {results: []}, i, j, s;
|
||||
for (i = 1; i < 5; i++) {
|
||||
s = "";
|
||||
for (j = 0; j < i; j++) {
|
||||
s = s + query.term;
|
||||
}
|
||||
data.results.push({
|
||||
id: query.term + i,
|
||||
text: s
|
||||
});
|
||||
}
|
||||
query.callback(data);
|
||||
}
|
||||
}
|
||||
```
|
||||
This has been replaced by custom data adapters which define a similarly named `query` method. The comparable data adapter is provided below as an example.
|
||||
|
||||
```
|
||||
$.fn.select2.amd.require([
|
||||
'select2/data/array',
|
||||
'select2/utils'
|
||||
], function (ArrayData, Utils) {
|
||||
function CustomData ($element, options) {
|
||||
CustomData.__super__.constructor.call(this, $element, options);
|
||||
}
|
||||
|
||||
Utils.Extend(CustomData, ArrayData);
|
||||
|
||||
CustomData.prototype.query = function (params, callback) {
|
||||
var data = {
|
||||
results: []
|
||||
};
|
||||
|
||||
for (var i = 1; i < 5; i++) {
|
||||
var s = "";
|
||||
|
||||
for (var j = 0; j < i; j++) {
|
||||
s = s + params.term;
|
||||
}
|
||||
|
||||
data.results.push({
|
||||
id: params.term + i,
|
||||
text: s
|
||||
});
|
||||
}
|
||||
|
||||
callback(data);
|
||||
};
|
||||
|
||||
$("#select").select2({
|
||||
dataAdapter: CustomData
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
The new `query` method of the data adapter is very similar to the old `query` option that was passed into Select2 when initializing it. The old `query` argument is mostly the same as the new `params` that are passed in to query on, and the callback that should be used to return the results is now passed in as the second parameter.
|
||||
|
||||
### Renamed templating options
|
||||
|
||||
Select2 previously provided multiple options for formatting the results list and selected options, commonly referred to as "formatters", using the `formatSelection` and `formatResult` options. As the "formatters" were also used for things such as localization, [which has also changed](#renamed-translation-options), they have been renamed to `templateSelection` and `templateResult` and their signatures have changed as well.
|
||||
|
||||
You should refer to the updated documentation on templates for [results](/dropdown) and [selections](/selections) when migrating from previous versions of Select2.
|
||||
|
||||
### The `id` and `text` properties are strictly enforced
|
||||
|
||||
When working with array and AJAX data in the past, Select2 allowed a custom `id` function or attribute to be set in various places, ranging from the initialization of Select2 to when the remote data was being returned. This allowed Select2 to better integrate with existing data sources that did not necessarily use the `id` attribute to indicate the unique identifier for an object.
|
||||
|
||||
Select2 no longer supports a custom `id` or `text` to be used, but provides integration points for converting to the expected format:
|
||||
|
||||
#### When working with array data
|
||||
|
||||
Select2 previously supported defining array data as an object that matched the signature of an AJAX response. A `text` property could be specified that would map the given property to the `text` property on the individual objects. You can now do this when initializing Select2 by using the following jQuery code to map the old `text` and `id` properties to the new ones.
|
||||
|
||||
```
|
||||
var data = $.map([
|
||||
{
|
||||
pk: 1,
|
||||
word: 'one'
|
||||
},
|
||||
{
|
||||
pk: 2,
|
||||
word: 'two'
|
||||
}
|
||||
], function (obj) {
|
||||
obj.id = obj.id || obj.pk;
|
||||
obj.text = obj.text || obj.word;
|
||||
|
||||
return obj;
|
||||
});
|
||||
```
|
||||
|
||||
This will result in an array of data objects that have the `id` properties that match the existing `pk` properties and `text` properties that match the existing `word` properties.
|
||||
|
||||
#### When working with remote data
|
||||
|
||||
The same code that was given above can be used in the `processResults` method of an AJAX call to map properties there as well.
|
||||
|
||||
### Renamed translation options
|
||||
|
||||
In previous versions of Select2, the default messages provided to users could be localized to fit the language of the website that it was being used on. Select2 only comes with the English language by default, but provides [community-contributed translations](/i18n) for many common languages. Many of the formatters have been moved to the `language` option and the signatures of the formatters have been changed to handle future additions.
|
||||
|
||||
### Declaring options using `data-*` attributes
|
||||
|
||||
In the past, Select2 has only supported declaring a subset of options using `data-*` attributes. Select2 now supports declaring all options using the attributes, using [the format specified in the documentation](/configuration/initializing/data-attributes).
|
||||
|
||||
You could previously declare the URL that was used for AJAX requests using the `data-ajax-url` attribute. While Select2 still allows for this, the new attribute that should be used is the `data-ajax--url` attribute. Support for the old attribute will be removed in Select2 4.1.
|
||||
|
||||
Although it was not documented, a list of possible tags could also be provided using the `data-select2-tags` attribute and passing in a JSON-formatted array of objects for tags. As the method for specifying tags has changed in 4.0, you should now provide the array of objects using the `data-data` attribute, which maps to [the array data](/data-sources/arrays) option. You should also enable tags by setting `data-tags="true"` on the object, to maintain the ability for users to create their own options as well.
|
||||
|
||||
If you previously declared the list of tags as:
|
||||
|
||||
```
|
||||
<select data-select2-tags='[{"id": "1", "text": "One"}, {"id": "2", "text": "Two"}]'></select>
|
||||
```
|
||||
|
||||
...then you should now declare it as...
|
||||
|
||||
```
|
||||
<select data-data='[{"id": "1", "text": "One"}, {"id": "2", "text": "Two"}]' data-tags="true"></select>
|
||||
```
|
||||
|
||||
## Deprecated and removed methods
|
||||
|
||||
As Select2 now uses a `<select>` element for all data sources, a few methods that were available by calling `.select2()` are no longer required.
|
||||
|
||||
### `.select2("val")`
|
||||
|
||||
The `"val"` method has been deprecated and will be removed in Select2 4.1. The deprecated method no longer includes the `triggerChange` parameter.
|
||||
|
||||
You should directly call `.val` on the underlying `<select>` element instead. If you needed the second parameter (`triggerChange`), you should also call `.trigger("change")` on the element.
|
||||
|
||||
```
|
||||
$("select").val("1").trigger("change"); // instead of $("select").select2("val", "1");
|
||||
```
|
||||
|
||||
### `.select2("enable")`
|
||||
|
||||
Select2 will respect the `disabled` property of the underlying select element. In order to enable or disable Select2, you should call `.prop('disabled', true/false)` on the `<select>` element. Support for the old methods will be completely removed in Select2 4.1.
|
||||
|
||||
```
|
||||
$("select").prop("disabled", true); // instead of $("select").enable(false);
|
||||
```
|
||||
7
pages/14.upgrading/chapter.md
Normal file
7
pages/14.upgrading/chapter.md
Normal file
@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Upgrading
|
||||
taxonomy:
|
||||
category: docs
|
||||
---
|
||||
|
||||
# Upgrading Select2
|
||||
Loading…
x
Reference in New Issue
Block a user