@@ -290,17 +290,99 @@ $("select").select2({
- 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. +
+ +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 initializion 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.
+ 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.
- 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.
@@ -353,18 +442,22 @@ $("select").select2({
- The val method has been deprecated and will be removed in
+ 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
+ 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"); // instead of $("select").select2("val", "1");
+
+
@@ -374,6 +467,10 @@ $("select").select2({
<select> element. Support for the old methods will be
completely removed in Select2 4.1.
+$("select").prop("disabled", true); // instead of $("select").enable(false);
+
diff --git a/docs/options.html b/docs/options.html
index 39e213aa..3953da4f 100644
--- a/docs/options.html
+++ b/docs/options.html
@@ -155,9 +155,9 @@ $("select").select2({
option in
- single-value select boxes is selected, you must add an empty
+ single-value select boxes is selected, you should add an empty
<option></option> tag that the placeholder
- should use, or it will not work.
+ should use or it may not work.