- 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.
+
- 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.
-
+ 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.
+
- There are a few breaking changes that migrators should be aware of when
- they are coming from older versions of Select2.
-
+ Migrating from Select2 3.5
-
- 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.
-
+
+ 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...
-
+
+ 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.
-
+
+ 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">
@@ -163,44 +171,44 @@ slug: announcements-4.0
</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.
-
+
+ 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
+ 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.
-
+
+ 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.
-
+
+ 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.
-
+
+ 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...
-
+
+ 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) {
@@ -216,11 +224,11 @@ $("select").select2({
})
-
- 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.
-
+
+ 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) {
@@ -238,39 +246,39 @@ $.fn.select2.amd.require(['select2/compat/matcher'], function (oldMatcher) {
});
-
- 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.
-
+
+ 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
+ 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.
-
+
+ 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.
-
+
+ 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...
-
+
+ For a select that looks like the following, where the first option (with a
+ value of -1) is the placeholder option…
+
<select>
@@ -279,11 +287,11 @@ $.fn.select2.amd.require(['select2/compat/matcher'], function (oldMatcher) {
</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.
-
+
+ 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({
@@ -294,62 +302,62 @@ $("select").select2({
})
-
- 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.
-
+
+ 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
+ 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.
-
+
+ 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.
-
+
+ Select2 will now order selected choices in the same order that will be
+ sent to the server.
+
- Changed method and option names
+ 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.
-
+
+ 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
-
+
+ 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.
-
+
+ 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.
-
+
+ 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) {
@@ -361,19 +369,20 @@ initSelection : function (element, callback) {
}
-
- 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).
-
+
+ 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) {
+$.fn.select2.amd.require([
+ 'select2/data/array',
+ 'select2/utils'
+], function (ArrayData, Utils) {
function CustomData ($element, options) {
CustomData.__super__.constructor.call(this, $element, options);
}
@@ -404,28 +413,28 @@ function (ArrayData, Utils) {
}
-
- 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.
-
+
+ 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.
-
+
+ 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
@@ -453,30 +462,30 @@ $request.then(function (data) {
});
-
- Custom data adapters instead of query
-
+
+ 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.
-
+
+ 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.
-
+
+ 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) {
@@ -490,16 +499,17 @@ query: function (query) {
}
-
- 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.
-
+
+ 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) {
+$.fn.select2.amd.require([
+ 'select2/data/array',
+ 'select2/utils'
+], function (ArrayData, Utils) {
function CustomData ($element, options) {
CustomData.__super__.constructor.call(this, $element, options);
}
@@ -533,64 +543,64 @@ function (ArrayData, Utils) {
}
-
- 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.
-
+
+ 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
+ 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.
-
+
+ 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.
-
+
+ You should refer to the updated
+ documentation on templates when
+ migrating from previous versions of Select2.
+
-
- The id and text properties are strictly enforced
-
+
+ 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.
-
+
+ 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 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
-
+
+ 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.
-
+
+ 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([
@@ -610,125 +620,133 @@ var data = $.map([
});
-
- 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.
-
+
+ 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
-
+
+ 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.
-
+
+ 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
+ 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.
-
+
+ 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
-
+
+ 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.
-
+
+ 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.
-
+
+ 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.
-
+
+ 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...
-
+
+ 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...
-
+
+ …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
+ 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.
-
+
+ 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")
+ .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.
-
+
+ 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.
-
+
+ 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("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.
-
+
+ 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);
-