314 lines
11 KiB
HTML
314 lines
11 KiB
HTML
---
|
|
layout: default
|
|
title: Select2 4.0.0 Released
|
|
slug: announcements-4.0
|
|
---
|
|
|
|
<div class="container">
|
|
<section id="pre-release">
|
|
<h1>Pre-release notes</h1>
|
|
|
|
<hr />
|
|
|
|
<p class="lead">
|
|
The 4.0 release is ready for early adopters interested in testing it out.
|
|
You can use the development version, available on GitHub, by getting the
|
|
source code available in the <code>select2-ng</code> branch. The source
|
|
code can be
|
|
<a href="https://github.com/ivaynberg/select2/archive/select2-ng.zip">
|
|
downloaded as a <code>zip</code> archive
|
|
</a> as well.
|
|
</p>
|
|
</section>
|
|
|
|
<hr />
|
|
|
|
<section id="release">
|
|
<h1>Select2 4.0.0</h1>
|
|
|
|
<p>
|
|
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 pathes 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 find more
|
|
information on the modules that have been created to make upgrading easier
|
|
by looking through <a href="release-notes.html">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>
|
|
|
|
<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 removed. This means
|
|
that if you previously declared an AJAX field with some pre-selected
|
|
options that looked like...
|
|
</p>
|
|
|
|
<pre class="prettyprint linenums">
|
|
<input type="hidden" name="select-boxes" value="1,2,4,6" />
|
|
</pre>
|
|
|
|
<p>
|
|
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>
|
|
|
|
<pre class="prettyprint linenums">
|
|
<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>
|
|
</pre>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<pre class="prettyprint linenums">
|
|
<select>
|
|
<option value="-1" selected="selected">Select an option</option>
|
|
<option value="1">Something else</option>
|
|
</select>
|
|
</pre>
|
|
|
|
<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>
|
|
|
|
<pre class="prettyprint linenums">
|
|
$("select").select2({
|
|
placeholder: {
|
|
id: "-1",
|
|
placeholder: "Select an option"
|
|
}
|
|
})
|
|
</pre>
|
|
|
|
<p>
|
|
And Select2 will automatically display the placeholder when the value of
|
|
the select is <code>-1</code>, which it is 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 recieved
|
|
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="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>
|
|
|
|
<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. This method will be completely
|
|
removed in Select2 4.1.
|
|
</p>
|
|
</section>
|
|
</div>
|