 + '.png)
' + state.text + ' + '.png)
' + state.text + 'Select2 4.0.0
+ ++ 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. +
+New features
+ ++ 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 + 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. +
+AMD-based build system
+ ++ 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.
+
Migrating from Select2 3.5
+ ++ 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.
+
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…
+
+ It will need to be recreated as a <select> element with
+ some <option> tags that have value
+ attributes that match the old value.
+
+ 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, 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… +
+ +{% highlight js linenos %} +function matchStart (term, text) { + if (text.toUpperCase().indexOf(term.toUpperCase()) == 0) { + return true; + } + + return false; +} + +$("select").select2({ + matcher: matchStart +}) +{% endhighlight %} + +
+ 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.
+
+ 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 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…
+
+ 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.
+
+ 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
+
+
+
+ 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.
+
+ 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).
+
+ 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.
+
+ Custom data adapters instead of 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.
+
+ 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.
+
+ 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, 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. +
+ +
+ 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 incorrect data
+ 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.
+
+ 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 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.
+
+ 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… +
+ +{% highlight html linenos %} + +{% endhighlight %} + ++ …then you should now declare it as… +
+ +{% highlight html linenos %} + +{% endhighlight %} + +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.
+
.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.
+