<p>Select2 also supports multi-value select boxes. The <code>select</code> below is declared with the <code>multiple</code> attribute. Select2 automatially picks up on this:</p>
<p>The placeholder can be declared via a <code>data-placeholder</code> attribute attached to the <code>select</code>, or via the <code>placeholder</code> configuration element as seen in the example code</p>
<p>Optionally, a clear button (visible once a selection is made) is available to reset the select box back to the placeholder value.</p>
<p>Select2 uses a function to load result data. Here is a trivial example that creates choices that consist of user's input repeated a number of times:</p>
<p>
<inputtype="hidden"id="e5"style="width:300px"/>
</p>
<p>In order to take advantage of custom data loading Select2 should be attached to an <code>input type='hidden'</code> tag, otherwise data is parsed from <code>select</code>'s <code>option</code> tags.</code></p>
<p>Select2 provides some shortcuts that make it easy to access local data stored in an array instead of having to write a <code>query</code> function mentioned in the example above.</p>
<p>Example below inlines the data by specifying an array in the <code>data</code> element. Items in such an array must have <code>id</code> and <code>text</code> keys.</p>
<p>
<inputtype="hidden"id="e10"style="width:300px"/>
</p>
<p>If your data does not have a <code>text</code> key, an alternative key can be specified as a string:</p>
<pclass="alert alert-warning">If this example does not work it is probably because the Rotten Tomatoes API key usage of 10000 requests per day has been exhausted. Please try again tomorrow.</p>
<p>Select2 uses jQuery's <code>$.ajax</code> function to execute the remote call by default. An alternative <code>transport</code> function can be specified in the ajax settings, or an entirely custom implementation can be built by providing a custom <code>query</code> function instead of using the <code>ajax</code> helper</p>
</div>
</article>
<articleclass="row"id="infinite">
<divclass="span12">
<h3>Infinite Scroll with Remote Data</h3>
<p>Select2 supports lazy-appending of results when the result list is scrolled to the end.
In order to enable the remote service must support some sort of a paging mechanism and
the query function given to Select2 must take advantage of it. The following example demonstrates
how this can be set up. Search for some keyword and then scroll the result list to the end to
<pclass="alert alert-warning">If this example does not work it is probably because the Rotten Tomatoes API key usage of 10000 requests per day has been exhausted. Please try again tomorrow.</p>
Select2 supports drag and drop sorting of selected choices. Select2 does not, itself, provide the necessary code to perform dragging and dropping, instead it provides hooks that other libraries can use to provide the behavior. In this example we are using JQuery UI's <code>sortable()</code> plugin.
</p>
<pclass="alert alert-info">The sorting is only available when Select2 is attached to a hidden <code>input</code> field.</p>
<p>The dropdown below matches on custom attributes of the <code>option</code> tag. For example, the `blue` option can be matched by entering either `blue` or `cyan`.</p>
<p>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.</p>
<p><selectmultiple="multiple"id="e18_2"style="width:75%"placeholder="Select a state"class="populate placeholder"></select><br/></p>
<pclass="alert alert-warning">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.</p>
Controls the <code>width</code> style attribute of the Select2 container div. The following values are supported:
<dl>
<dt>off</dt><dd>No width attribute will be set. Keep in mind that the container div copies classes from the source element so setting the width attribute may not always be necessary.</dd>
<dt>element</dt><dd>Uses javascript to calculate the width of the source element.</dd>
<dt>copy</dt><dd>Copies the value of the width style attribute set on the source element</dd>
<dt>resolve</dt><dd>First attempts to <u>copy</u> than falls back on <u>element</u></dd>
<dt>other values</dt><dd>if the width attribute contains a function it will be avaluated, otherwise the value is used verbatim</dd>
</dl>
</td></tr>
<tr><td>minimumInputLength</td><td>int</td><td>Number of characters necessary to start a search</td></tr>
<pclass="alert alert-warning">Note that because browsers assume the first <code>option</code> element
is selected in non-multi-value select boxes an empty first <code>option</code> element must be provided (<code><option></option></code>)
for the placeholder to work.
</p>
</td></tr>
<tr><td>separator</td><td>string</td><td>
<p>
Separator character or string used to delimit ids in <code>value</code> attribute of the multi-valued selects.
The default delimiter is the <code>,</code> character.
</p>
</td></tr>
<tr>
<td>allowClear</td>
<td>boolean</td>
<td>
<p>
Whether or not a clear button is displayed when the select box has a selection. The
button,
when clicked, resets the value of the select box back to the placeholder, thus this option is
only
available when the placeholder is specified.
</p>
<p>This option only works when the placeholder is specified</p>
<pclass="alert alert-warning">When attached to a <code>select</code> an <code>option</code> with an empty value must be provided.
This is the option that will be selected when the button is pressed since a select box requires
at least one selection <code>option</code>.</p>
<p>
Also, note that this option only works with
non-multi-value based selects because multi-value selects always provide such a button for every
selected option.
</p>
</td>
</tr>
<tr>
<td>multiple</td>
<td>boolean</td>
<td>
<p>
Whether or not Select2 allows selection of multiple values.
</p>
<p>When Select2 is attached to a <code>select</code> element this value will be ignored and <code>select</code>'s
<code>multiple</code> attribute will be used instead.
</p>
</td>
</tr>
<tr>
<td>closeOnSelect</td>
<td>boolean</td>
<td>
<p>
If set to true the dropdown is not closed after a selection is made, allowing for rapid selection of multiple items. By default this option is disabled.
</p>
<pclass="alert alert-info">
Only applies when configured in multi-select mode.
</p>
</td>
</tr>
<tr>
<td>openOnEnter</td>
<td>boolean</td>
<td>
<p>
If set to true the dropdown is opened when the user presses the enter key and Select2 is closed. By default this option is enabled.
</p>
</td>
</tr>
<tr><td>id</td><td>function</td><td>
Function used to get the id from the choice object or a string representing the key under which the id is stored.
Used to determine whether or not the search term matches an option when a built-in query function is used.
The built in query function is used when Select2 is attached to a <code>select</code>, or the <code>local</code> or <code>tags</code> helpers are used.
<tr><td>text</td><td>string</td><td>text of the option being matched</td></tr>
<tr><td>option</td><td>jquery object</td>
<td>the <code>option</code> element we are trying to match. Only given when attached to <code>select</code>.
Can be used to match against custom attributes on the <code>option</code> tag in addition to matching on the <code>option</code>'s text.</code></td></tr>
<tr><td><returns></td><td>boolean</td><td><code>true</code> if search term matches the text, or <code>false</code> otherwise</td></tr>
</table>
The default implementation is case insensitive and matches anywhere in ther term:
<tr><td>object</td><td>object</td><td>The selected result object returned from the <code>query</code> function</td></tr>
<tr><td>container</td><td>jQuery object</td><td>jQuery wrapper of the node to which the selection should be appended</td></tr>
<tr><td><returns></td><td>string (optional)</td><td>Html string, a DOM element, or a jQuery object that renders the selection</td></tr>
</table>
<p>The default implementation expects the object to have a <code>text</code> property that is returned.</p>
<p>The implementation may choose to append elements directly to the provided <code>container</code> object, or return a single value and have it automatically appended</p>
<br><br>
<p>
When attached to a <code>select</code> the original <code><option></code> (or <optgroup>) element is accessible inside the specified function through the property <code>item.element</code>:
<tr><td>object</td><td>object</td><td>One of the result objects returned from the <code>query</code> function</td></tr>
<tr><td>container</td><td>jQuery object</td><td>jQuery wrapper of the node that should contain the representation of the result</td></tr>
<tr><td>query</td><td>object</td><td>The query object used to request this set of results</td></tr>
<tr><td><returns></td><td>string (optional)</td><td>Html string, a DOM element, or a jQuery object that represents the result</td></tr>
</table>
<p>The default implementation expects the object to have a <code>text</code> property that is returned.</p>
<p>The implementation may choose to append elements directly to the provided <code>container</code> object, or return a single value and have it automatically appended</p>
<br><br>
<p>
When attached to a <code>select</code> the original <code><option></code> (or <optgroup>) element is accessible inside the specified function through the property <code>item.element</code>:
<tr><td>element</td><td>jQuery array</td><td>element Select2 is attached to</td></tr>
<tr><td>callback</td><td>function</td><td>callback function that should be called with the data which is either an object in case of a single select or an array of objects in case of multi-select</td></tr>
</table>
<pclass="alert alert-info">This function will only be called when there is initial input to be processed.</p>
Here is an example implementation used for tags. Tags are the simplest form of data where the id is also
<tr><td>input</td><td>string</td><td>The text entered into the search field so far</td></tr>
<tr><td>selection</td><td>array</td><td>Array of objects representing the current selection.
Useful if tokenizer needs to filter out duplicates.</td></tr>
<tr><td>selectCallback</td><td>function</td><td>Callback that can be used to add objects to the selection</td></tr>
<tr><td>opts</td><td>object</td><td>Options with which Select2 was initialized. Useful if tokenizer needs to access some properties in the options.</td></tr>
<tr><td><returns></td><td>string (optional)</td><td>Returns the string to which the input of
the search field should be set to. Usually this is the remainder, of any, of the string after
the tokens have been stripped. If <code>undefined</code> or <code>null</code> is returned the
input of the search field is unchanged.</code></td></tr>
</table>
The default tokenizer will only be used if the <code>tokenSeparators</code> and <code>createSearchChoice</code>
options are specified. The default tokenizer will split the string using any separator in <code>tokenSeparators</code>
and will create and select choice objects using <code>createSearhChoice</code> option. It will also
ignore duplicates, silently swallowing those tokens.
<tr><td>options.term</td><td>string</td><td>Search string entered by user</td></tr>
<tr><td>options.page</td><td>int</td><td>1-based page number tracked by Select2 for use with infinite scrolling of results</td></tr>
<tr><td>options.context</td><td>object</td><td>An object that persists across the lifecycle of queries for the same search term (the query to retrieve the initial results, and subsequent queries to retrieve more result pages for the same search term). When this function is first called for a new search term this object will be null. The user may choose to set any object in the <code>results.context</code> field - this object will then be used as the context parameter for all calls to the <code>query</code> method that will load more search results for the initial search term. The object will be reset back to null when a new search term is queried. This feature is useful when a page number is not easily mapped against the server side paging mechanism. For example, some server side paging mechanism may return a "continuation token" that needs to be passed back to them in order to retrieve the next page of search results.</td></tr>
<tr><td>result.results</td><td>[object]</td><td>Array of result objects. The default renderers expect objects with <code>id</code> and <code>text</code> keys</code>. The <code>id</code> attribute is required</code>, even if custom renderers are used. The object may also contain a <code>children</code>key if hierarchical data is displayed.</td></tr>
<tr><td>result.more</td><td>boolean</td><td><code>true</code>if more results are available for the current search term</td></tr>
<tr><td>results.context</td><td>object</td><td>A user-defined object that should be made available as the <code>context</code> parameter to the <code>query</code> function on subsequent queries to load more result pages for the same search term. See the description of <ahref="#doc-query-options-context">options.context</code></a> parameter.</td></tr>
<pclass="alert alert-warning">In order for this function to work Select2 should be attached to a <code>input type='hidden'</code> tag instead of a <code>select</code>.</p>
Options for the built in ajax query function. This object acts as a shortcut for having to manually write a function that performs ajax requests. The built-in function supports more advanced features such as throttling and dropping out-of-order responses.
<tr><td>transport</td><td>function</td><td>Function that will be used to perform the ajax request. Must be parameter-compatible with <code>$.ajax</code>. Defaults to <code>$.ajax</code> if not specified.
Allows the use of various ajax wrapper libraries such as: <ahref="http://www.protofunc.com/scripts/jquery/ajaxManager/">AjaxManager</a>. </td></tr>
<tr><td>page</td><td>int</td><td>1-based page number tracked by Select2 for use with infinite scrolling of results</td></tr>
<tr><td>context</td><td>object</td><td>See <ahref="#doc-query-options-callback"><code>options.context</code></a> parameter to the <ahref="#doc-query"><code>query</code></a> function above.</td></tr>
<tr><td>page</td><td>int</td><td>Page number that was passed into the <code>data</code> function above</td></tr>
<tr><td>context</td><td>object</td><td>See <ahref="#doc-query-options-callback"><code>options.context</code></a> parameter to the <ahref="#doc-query"><code>query</code></a> function above.</td></tr>
<tr><td><returns></td><td>object</td><td>Results object. See "options.callback" in the "query" function for format.</td></tr>
</table>
</td></tr>
</table>
<pclass="alert alert-warning">In order for this function to work Select2 should be attached to a <code>input type='hidden'</code> tag instead of a <code>select</code>.</p>
</td></tr>
<tr><td>data</td><td>array/object</td><td>
Options for the built in query function that works with arrays.
<p>If this element contains an array, each element in the array must contain <code>id</code> and <code>text</code> keys</p>
<p>Alternatively, this element can be specified as an object in which <code>results</code> key must contain the data as an array and a <code>text</code> key can either be the name of the key in data items that contains text or a function that retrieves the text given a data element from the array</p>
</td></tr>
<tr><td>tags</td><td>array/function</td><td>
Puts Select2 into 'tagging'mode where the user can add new choices and pre-existing tags are provided via
this options attribute which is either an <code>array</code> or a <code>function</code> that returns an
array of <code>objects</code> or <code>strings</code>. If <code>strings</code> are used instead of <code>objects</code>
they will be converted into an object that has an <code>id</code> and <code>text</code> attribute equal
Inline css that will be added to select2's container. Either an object containing css property/value key pairs or a function that returns such an object.
Inline css that will be added to select2's dropdown container. Either an object containing css property/value key pairs or a function that returns such an object.
Css class that will be added to select2's dropdown container
</td></tr>
</table>
<divclass="row">
<divclass="span12"><h3>val</h3></div>
</div>
<p>Gets or sets the selection. If the <code>value</code> parameter is not specified, the <code>id</code> attribute of the currently selected element is returned. If the <code>value</code> parameter is specified it will become the current selection.</code></p>
<p><code>val</code> method invoked on a single-select with an unset value will return <code>""</code>, while a <code>val</code> method invoked on an empty multi-select will return <code>[]</code></p>
Example: <preclass="prettyprint">alert("Selected value is: "+$("#e8").select2("val")); $("#e8").select2("val", {id:"CA", text:"Califoria"});</pre>
<divclass="row">
<divclass="span12"><h3>data</h3></div>
</div>
<p>Gets or sets the selection. Analogous to <code>val</code> method, but works with objects instead of ids.</p>
<p><code>data</code> method invoked on a single-select with an unset value will return <code>null</code>, while a <code>data</code> method invoked on an empty multi-select will return <code>[]</code></p>
<divclass="row">
<divclass="span12"><h3>destroy</h3></div>
</div>
<p>Reverts changes to DOM done by Select2. Any selection done via Select2 will be preserved.</p>
<divclass="row">
<divclass="span12"><h3>open</h3></div>
</div>
<p>Opens the dropdown</p>
<divclass="row">
<divclass="span12"><h3>close</h3></div>
</div>
<p>Closes the dropdown</p>
<divclass="row">
<divclass="span12"><h3>disable</h3></div>
</div>
<p>Disables Select2. During this mode the user is not allowed to manipulate the selection.</p>
<p>Notifies Select2 that a drag and drop sorting operation has started. Select2 will hide all non-selection list items such as the search container, etc.
<p>Notifies Select2 that a drag and drop sorting operation has finished. Select2 will re-display any elements previously hidden and update the selection of the element it is attached to.
Select2 exposes its default options via the <code>$.fn.select2.defaults</code> object. Properties changed in this object (same properties configurable through the constructor) will take effect for every instance created after the change
