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.
Below is an in-depth review of what is new in Select2, as well as some of the major changes that have been made.
The notable features of this new release include:
<select> elements for all
data adapters, removing the need for hidden <input>
elements.
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 options section for adapters, 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.
Select2 now uses an AMD-based build system, 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
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.
There are a few breaking changes that migrators should be aware of when they are coming from older versions of Select2.
If you use the full build of Select2 (select2.full.js), 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.
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.
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 matcher
function was only given the individual option, even if it was a nested
options, without any context.
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.
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
select2/compat/matcher module, which should just wrap the old
matcher function.
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...
function matchStart (term, text) {
if (text.toUpperCase().indexOf(term.toUpperCase()) == 0) {
return true;
}
return false;
}
$("select").select2({
matcher: matchStart
})
Then in Select2 4.0, you would need to wrap the matchStart
method (or the name of the matcher you created) with a
oldMatcher method that we have created.
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)
})
});
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.
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 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.
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.
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.
initSelection
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 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(data.text, data.id, true, true);
// Append it to the select
$element.append(option);
}
// Update the selected options that are displayed
$element.trigger('change');
});
query
In the past, 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 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,
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.
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, they have been
renamed to templateSelection and templateResult
and their signatures have changed as well.
You should refer to the updated documentation on templates when migrating from previous versions of Select2.
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 incorrect data
to the expected format.
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.
The same code that was given above can be used in the
processResults method of an AJAX call to map properties there
as well.
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 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.
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.
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 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 delare it as...
<select data-data="[{id: '1', text: 'One', id: '2', text: 'Two'}]" data-tags="true"></select>
As Select2 now uses a <select> element for all data
sources, a few methods that were available by calling
.select2() are no longer required.
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 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);