diff --git a/docs/announcements-4.0.html b/docs/announcements-4.0.html index d9c0d6ad..dbf17677 100644 --- a/docs/announcements-4.0.html +++ b/docs/announcements-4.0.html @@ -40,8 +40,7 @@ slug: announcements-4.0 will 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 at the compatibility guide for older - Select2 versions. + by looking through the release notes.

@@ -78,7 +77,7 @@ slug: announcements-4.0

-

Plugins

+

Plugin system

Select2 now provides interfaces that allow for it to be easily extended, @@ -88,38 +87,152 @@ slug: announcements-4.0 Select2.

-

- Container (selection) -

+

+ 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

+
+ +
+

Migrating from Select2 3.5

- This includes the primary container that users interact with to open the - dropdown. + There are a few breaking changes that migrators should be aware of when + they are coming from older versions of Select2.

-

- Dropdown -

+

No more hidden input tags

- This includes the dropdown that is opened when the container is clicked. - This also includes the results list, which is a separate component. + 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.

-

- Results -

-

- This includes the list of possible options that can be selected. + In Select2 4.0, the <select> element supports all core + options, and support for the old + <input type="hidden" /> has been removed. This means + that if you previously declared an AJAX field with some pre-selected + options that looked like...

-

- Data set -

+
+<input type="hidden" name="select-boxes" value="1,2,4,6" />
+

- This is how the options are calculated. + 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. +

+ +

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. +

+ +

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... +

+ +
+<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 is by default. This does not break + the old functionality of Select2 where the placeholder option was blank by + default.