diff --git a/docs/_includes/options/adapters.html b/docs/_includes/options/adapters.html index 78bf72ae..c0807ede 100644 --- a/docs/_includes/options/adapters.html +++ b/docs/_includes/options/adapters.html @@ -1,30 +1,30 @@ -
-
-

Adapters

-
+
+
+

Adapters

+
-

- Select2 allows plugins to add additional functionality through the core - adapters. You can change almost anything involving the way Select2 works - to the way Select2 interacts with the page by modifying the core adapters. - Most third-party plugins should provide decorators (used to wrap adapters) - and custom adapters that you can use. -

+

+ Select2 allows plugins to add additional functionality through the core + adapters. You can change almost anything involving the way Select2 works + to the way Select2 interacts with the page by modifying the core adapters. + Most third-party plugins should provide decorators (used to wrap adapters) + and custom adapters that you can use. +

-

- Each adapter contains a set of methods which will must always be defined. - Along with the global methods that all adapters must implement, these - methods must be implemented. -

+

+ Each adapter contains a set of methods which will must always be defined. + Along with the global methods that all adapters must implement, these + methods must be implemented. +

-

- All adapters -

+

+ All adapters +

-

- All adapters must implement a set of methods that Select2 will use to - display them and bind any internal events. -

+

+ All adapters must implement a set of methods that Select2 will use to + display them and bind any internal events. + 

 // The basic HTML that should be rendered by Select2. A jQuery or DOM element
@@ -66,34 +66,34 @@ Adapter.position = function ($rendered, $defaultContainer) { };
 Adapter.destroy = function () { };
-

- Container (selection) -

+

+ Container (selection) +

-

- The selection is what is shown to the user as a replacement of the - standard <select> box. It controls the display of the - selection option(s), as well anything else that needs to be embedded - within the container, such as a search box. -

+

+ The selection is what is shown to the user as a replacement of the + standard <select> box. It controls the display of the + selection option(s), as well anything else that needs to be embedded + within the container, such as a search box. +

-
-
Key
-
- selectionAdapter -
+
+
Key
+
+ selectionAdapter +
-
Default
-
- SingleSelection or - MultipleSelection -
+
Default
+
+ SingleSelection or + MultipleSelection +
-
Base
-
- BaseSelection -
-
+
Base
+
+ BaseSelection +
+ 
 // Update the selected data.
@@ -106,31 +106,31 @@ Adapter.destroy = function () { };
 SelectionAdapter.update = function (data) { };
-

- Data set -

+

+ Data set +

-

- The data set is what Select2 uses to generate the possible results that - can be selected, as well as the currently selected results. -

+

+ The data set is what Select2 uses to generate the possible results that + can be selected, as well as the currently selected results. +

-
-
Key
-
- dataAdapter -
+
+
Key
+
+ dataAdapter +
-
Default
-
- SelectAdapter -
+
Default
+
+ SelectAdapter +
-
Base
-
- BaseAdapter -
-
+
Base
+
+ BaseAdapter +
+ 
 // Get the currently selected options. This is called when trying to get the
@@ -160,50 +160,50 @@ DataAdapter.query = function (params, callback) {
 }
- + -

- The dropdown adapter defines the main container that the dropdown should - be held in. It does not define any extra methods that can be used - for decorators, but it is common for decorators to attach to the - render and position methods to alter how the - dropdown is altered and positioned. -

+

+ The dropdown adapter defines the main container that the dropdown should + be held in. It does not define any extra methods that can be used + for decorators, but it is common for decorators to attach to the + render and position methods to alter how the + dropdown is altered and positioned. +

-
-
Key
-
- dropdownAdapter -
+
+
Key
+
+ dropdownAdapter +
-
Default
-
- DropdownAdapter -
-
+
Default
+
+ DropdownAdapter +
+
-

- Results -

+

+ Results +

-

- The results adapter controls the list of results that the user can select - from. While the results adapter does not define any additional methods - that must be implemented, it makes extensive use of the Select2 event - system for controlling the display of results and messages. -

+

+ The results adapter controls the list of results that the user can select + from. While the results adapter does not define any additional methods + that must be implemented, it makes extensive use of the Select2 event + system for controlling the display of results and messages. +

-
-
Key
-
- resultsAdapter -
+
+
Key
+
+ resultsAdapter +
-
Default
-
- ResultsAdapter -
-
-
+
Default
+
+ ResultsAdapter +
+ +
diff --git a/docs/_includes/options/backwards-compatibility.html b/docs/_includes/options/backwards-compatibility.html index fd5a0eb3..4bdd9372 100644 --- a/docs/_includes/options/backwards-compatibility.html +++ b/docs/_includes/options/backwards-compatibility.html @@ -1,201 +1,200 @@ -
-
-

Backwards compatibility

-
+
+
+

Backwards compatibility

+
-

- Select2 offers limited backwards compatibility with the previously 3.5.x - release line, allowing people more efficiently transfer across releases - and get the latest features. For many of the larger changes, such as the - change in how custom data adapters work, compatibility modules were - created that will be used to assist in the upgrade process. It is not - recommended to rely on these compatibility modules, as they will not - always exist, but they make upgrading easier for major changes. -

+

+ Select2 offers limited backwards compatibility with the previously 3.5.x + release line, allowing people more efficiently transfer across releases + and get the latest features. For many of the larger changes, such as the + change in how custom data adapters work, compatibility modules were + created that will be used to assist in the upgrade process. It is not + recommended to rely on these compatibility modules, as they will not + always exist, but they make upgrading easier for major changes. +

-

- The compatibility modules are only included in the - full builds of - Select2. These files end in .full.js, and the - compatibility modules are prefixed with select2/compat. -

+

+ The compatibility modules are only included in the + full builds of + Select2. These files end in .full.js, and the + compatibility modules are prefixed with select2/compat. +

-

- Simplified function for matching data objects -

+

+ Simplified function for matching data objects +

-

- Added in Select2 4.0.0. - This method was added to make upgrading easier from earlier versions of - Select2. -

+

+ Added in Select2 4.0.0. + This method was added to make upgrading easier from earlier versions of + Select2. +

-

- During the Select2 4.0.0 release, the - matcher function was changed to allow for more complex - matching of nested objects. -

+

+ During the Select2 4.0.0 release, the + matcher function was changed to allow for more complex + matching of nested objects. +

-
-
-
-
Key
-
- matcher -
+
+
+
+
Key
+
+ matcher +
-
Value
-
- A function taking a search term and the data object - text. -
-
-
+
Value
+
+ A function taking a search term and the data object + text. +
+
+
-
-
-
Adapter
-
- oldMatcher -
-
-
-
+
+
+
Adapter
+
+ oldMatcher +
+
+
+ -

- The custom matcher example provides a - guide for how to use this in your own application. For those upgrading - from older versions of Select2, you just need to wrap your old - matcher with this function to maintain compatibility. -

+

+ The custom matcher example provides a + guide for how to use this in your own application. For those upgrading + from older versions of Select2, you just need to wrap your old + matcher with this function to maintain compatibility. +

-

- Old initial selections with initSelection -

+

+ Old initial selections with initSelection +

-

- Deprecated in Select2 4.0. - This has been replaced by another option and is only available in the - full builds of - Select2. -

+

+ Deprecated in Select2 4.0. + This has been replaced by another option and is only available in the + full builds of + Select2. +

-

- In the past, Select2 required an option called initSelection - that was defined whenever a custom data source was being used, allowing - for the initial selection for the component to be determined. This has - been replaced by the current method on the - data adapter. -

+

+ In the past, Select2 required an option called initSelection + that was defined whenever a custom data source was being used, allowing + for the initial selection for the component to be determined. This has + been replaced by the current method on the + data adapter. +

-
-
-
-
Key
-
- initSelection -
+
+
+
+
Key
+
+ initSelection +
-
Value
-
- A function taking a callback -
-
-
+
Value
+
+ A function taking a callback +
+
+
-
-
-
Adapter
-
- DataAdapter -
+
+
+
Adapter
+
+ DataAdapter +
-
Decorator
-
- InitSelection -
-
-
-
+
Decorator
+
+ InitSelection +
+ +
+ -

- Querying old data with query -

+

+ Querying old data with query +

-

- Deprecated in Select2 4.0. - This has been replaced by another option and is only available in the - full builds of - Select2. -

+

+ Deprecated in Select2 4.0. + This has been replaced by another option and is only available in the + full builds of + Select2. +

-

- In the past, Select2 supported an option called query that - allowed for a custom data source to be used. This option has been replaced - by the query method on the - data adapter and takes a very similar set of - parameters. -

+

+ In the past, Select2 supported an option called query that + allowed for a custom data source to be used. This option has been replaced + by the query method on the + data adapter and takes a very similar set of + parameters. +

-
-
-
-
Key
-
- query -
+
+
+
+
Key
+
+ query +
-
Value
-
- A function taking params (including a callback) -
-
-
+
Value
+
+ A function taking params (including a callback) +
+
+
-
-
-
Adapter
-
- DataAdapter -
+
+
+
Adapter
+
+ DataAdapter +
-
Decorator
-
- Query -
-
-
-
-
+
Decorator
+
+ Query +
+ + + -

- Compatibility with <input type="text" /> -

+

+ Compatibility with <input type="text" /> +

-

- Deprecated in Select2 4.0. - It is now encouraged to use the <select> tag instead. -

+

+ Deprecated in Select2 4.0. + It is now encouraged to use the <select> tag instead. +

-

- In past versions of Select2, a <select> element could - only be used with a limited subset of options. An - <input type="hidden" /> was required instead, which did - not allow for a graceful fallback for users who did not have JavaScript - enabled. Select2 now supports the <select> element for - all options, so it is no longer required to use <input /> - elements with Select2. -

+

+ In past versions of Select2, a <select> element could + only be used with a limited subset of options. An + <input type="hidden" /> was required instead, which did + not allow for a graceful fallback for users who did not have JavaScript + enabled. Select2 now supports the <select> element for + all options, so it is no longer required to use <input /> + elements with Select2. +

-
-
Adapter
-
- DataAdapter -
+
+
Adapter
+
+ DataAdapter +
-
Decorator
-
- InputData -
-
-
+
Decorator
+
+ InputData +
+ + diff --git a/docs/_includes/options/core-options.html b/docs/_includes/options/core-options.html index 06471521..d45629ff 100644 --- a/docs/_includes/options/core-options.html +++ b/docs/_includes/options/core-options.html @@ -1,23 +1,23 @@ -
-

Core options

+
+

Core options

-

- Select2 supports a small subset of options in every build that is - generated. Each option typically has a decorator that is required that - wraps an adapter, adding support for the option. This is only required - when a custom adapter is being used, as Select2 will build the required - adapters by default. -

+

+ Select2 supports a small subset of options in every build that is + generated. Each option typically has a decorator that is required that + wraps an adapter, adding support for the option. This is only required + when a custom adapter is being used, as Select2 will build the required + adapters by default. +

-

- Select2 will automatically apply decorators to any adapters which have not - been manually overridden. The only time you need to decorate adapters is - when you are using third-party adapters not provided by Select2, or you - are using features not provided in the Select2 core. You can apply a - decorator to an adapter using the - Utils.Decorate method provided with - Select2. -

+

+ Select2 will automatically apply decorators to any adapters which have not + been manually overridden. The only time you need to decorate adapters is + when you are using third-party adapters not provided by Select2, or you + are using features not provided in the Select2 core. You can apply a + decorator to an adapter using the + Utils.Decorate method provided with + Select2. + 

 $.fn.select2.amd.require(
@@ -27,35 +27,35 @@ $.fn.select2.amd.require(
 });
-

- All core options that use decorators or adapters will clearly state it - in the "Decorator" or "Adapter" part of the documentation. Decorators are - typically only compatible with a specific type of adapter, so make sure to - note what adapter is given. -

+

+ All core options that use decorators or adapters will clearly state it + in the "Decorator" or "Adapter" part of the documentation. Decorators are + typically only compatible with a specific type of adapter, so make sure to + note what adapter is given. +

-

- Declaring configuration in the data-* attributes -

+

+ Declaring configuration in the data-* attributes +

-

- It is recommended that you declare your configuration options for Select2 - when initializing Select2. You can also define your configuration options - by using the HTML5 data-* attributes, which will override - any options set when initializing Select2 and any defaults. -

+

+ It is recommended that you declare your configuration options for Select2 + when initializing Select2. You can also define your configuration options + by using the HTML5 data-* attributes, which will override + any options set when initializing Select2 and any defaults. +

-

- This means that if you declare your <select> tag as... -

+

+ This means that if you declare your <select> tag as... + 

 <select data-tags="true" data-placeholder="Select an option"></select>
-

- Will be interpreted the same as initializing Select2 as... -

+

+ Will be interpreted the same as initializing Select2 as... + 

 $("select").select2({
@@ -64,22 +64,22 @@ $("select").select2({
 });
-

- You can also define nested configurations, which are typically needed for - options such as AJAX. Each level of nesting should be separated by two - dashes (--) instead of one. Due to - a jQuery bug, - nested options using data-* attributes - do not work in jQuery 1.x. -

+

+ You can also define nested configurations, which are typically needed for + options such as AJAX. Each level of nesting should be separated by two + dashes (--) instead of one. Due to + a jQuery bug, + nested options using data-* attributes + do not work in jQuery 1.x. + 

 <select data-ajax--url="http://example.org/api/test" data-ajax--cache="true"></select>
-

- Which will be interpreted the same as initializing Select2 with... -

+

+ Which will be interpreted the same as initializing Select2 with... + 

 $("select").select2({
@@ -90,121 +90,121 @@ $("select").select2({
 });
-

- The value of the option is subject to jQuery's - parsing rules for - HTML5 data attributes. -

+

+ The value of the option is subject to jQuery's + parsing rules for + HTML5 data attributes. +

-

- AMD compatibility -

+

+ AMD compatibility +

-

- You can find more information on how to integrate Select2 with your - existing AMD-based project by - viewing the 4.0 release notes. - Select2 automatically loads some modules when the adapters are being - automatically constructed, so those who are using Select2 with a custom - AMD build using their own system may need to specify the paths that are - generated to the Select2 modules. -

+

+ You can find more information on how to integrate Select2 with your + existing AMD-based project by + viewing the 4.0 release notes. + Select2 automatically loads some modules when the adapters are being + automatically constructed, so those who are using Select2 with a custom + AMD build using their own system may need to specify the paths that are + generated to the Select2 modules. +

-
-
-
-
Key
-
- amdBase -
+
+
+
+
Key
+
+ amdBase +
-
Default
-
- select2/ -
-
-
-
-
-
Key
-
- amdLanguageBase -
+
Default
+
+ select2/ +
+
+
+
+
+
Key
+
+ amdLanguageBase +
-
Default
-
- select2/i18n/ -
-
-
+
Default
+
+ select2/i18n/ +
+
+
+
+ +

+ Display +

+ +

+ Select2 provides options that allow you to directly affect how the + container that holds the current selection is displayed. +

+ +

+ Placeholders +

+ +

+ Select2 can display a placeholder for a single-value select that will + replace an option, or be shown when no options are selected for + multiple-value selects. You can find an example on the + example page. +

+ +
+
+
+
Key
+
+ placeholder +
+ +
Value
+
string or object
+
+ +
+ +
+
Adapter
+
+ SelectionAdapter +
+ +
Decorator
+
+ Placeholder + and + HidePlaceholder +
+
+
+ +
+
+ Heads up! + Because browsers assume that the first option in + single-value select boxes is selected, you should add an empty + <option></option> tag that the placeholder + should use or it may not work.
+
+
-

- Display -

- -

- Select2 provides options that allow you to directly affect how the - container that holds the current selection is displayed. -

- -

- Placeholders -

- -

- Select2 can display a placeholder for a single-value select that will - replace an option, or be shown when no options are selected for - multiple-value selects. You can find an example on the - example page. -

- -
-
-
-
Key
-
- placeholder -
- -
Value
-
string or object
-
- -
- -
-
Adapter
-
- SelectionAdapter -
- -
Decorator
-
- Placeholder - and - HidePlaceholder -
-
-
- -
-
- Heads up! - Because browsers assume that the first option in - single-value select boxes is selected, you should add an empty - <option></option> tag that the placeholder - should use or it may not work. -
-
-
- -

- If the value is a string, the placeholder will be - displayed when a blank option is used as the placeholder. - The value will be the message to show to users as the - placeholders. -

+

+ If the value is a string, the placeholder will be + displayed when a blank option is used as the placeholder. + The value will be the message to show to users as the + placeholders. + 

 placeholder: "Select a repository"
@@ -225,186 +225,186 @@ placeholder: {
 }
-
- You should pass in an object when you are using a - framework that creates its own placeholder option. The - id should be the same as the value - attribute on the option. -
+
+ You should pass in an object when you are using a + framework that creates its own placeholder option. The + id should be the same as the value + attribute on the option. +
-

- You can allow a selected option to be cleared back to the placeholder by - enabling the allowClear option. -

- -
-
-
-
Key
-
allowClear
- -
Value
-
boolean
-
-
- -
-
-
Adapter
-
- SelectionAdapter -
- -
Decorator
-
- AllowClear -
-
-
-
- -

- This will display an "x" that the user can click to clear the current - selection. It is designed to be used for cases where a single selection - can be made. -

- -

- Multiple selections -

- -

- Select2 can display either a single selection or multiple selections. -

+

+ You can allow a selected option to be cleared back to the placeholder by + enabling the allowClear option. +

+
+
Key
-
multiple
+
allowClear
Value
-
boolean (true or false)
+
boolean
+
+
+ +
+
+
Adapter
+
+ SelectionAdapter +
+ +
Decorator
+
+ AllowClear +
+
+
+
+ +

+ This will display an "x" that the user can click to clear the current + selection. It is designed to be used for cases where a single selection + can be made. +

+ +

+ Multiple selections +

+ +

+ Select2 can display either a single selection or multiple selections. +

+ +
+
Key
+
multiple
+ +
Value
+
boolean (true or false)
+
+ +

+ This option will determine what the SelectAdapter (used by + default) should use to set the value of the underlying select + element. It will also determine if the MultipleSelection + adapter should be used. +

+ +

+ Container width +

+ +

+ Select2 will try to match the width of the original element as closely as + possible. Sometimes this isn't perfect, which is what you can tell Select2 + how to determine the width. +

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
"element" + Uses javascript to calculate the width of the source element. +
"style" + Copies the value of the width style attribute set on the source element. +
"resolve" + Tries to use style to determine the width, falling back to element. +
Anything else + The value of the width option is directly set as the width of the container. +
+
+
+
+
Key
+
width
+ +
Value
+
string
+
+
+
+ +

+ Internationalization (Language support) +

+ +

+ Messages will be displayed to users when necessary, such as when no + search results were found or more characters need to be entered in order + for a search to be made. These messages have been + translated into many languages + by contributors to Select2, but you can also provide your own + translations. +

+ +
+
+
+
Key
+
language
+ +
Value
+
object or string
-

- This option will determine what the SelectAdapter (used by - default) should use to set the value of the underlying select - element. It will also determine if the MultipleSelection - adapter should be used. +

+ +
+
Module
+
+ Translation +
+
+
+ +
+

+ Heads up! When using translations provided by Select2, + you must make sure to include the translation file in your page after + Select2.

+
+
-

- Container width -

+

+ When a string is passed in as the language, Select2 will try to resolve + it into a language file. This allows you to specify your own language + files, which must be defined as an AMD module. If the language file + cannot be found, Select2 will assume it is a language code controlled by + Select2, and it will try to load the translations for that language + instead. +

-

- Select2 will try to match the width of the original element as closely as - possible. Sometimes this isn't perfect, which is what you can tell Select2 - how to determine the width. -

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - -
ValueDescription
"element" - Uses javascript to calculate the width of the source element. -
"style" - Copies the value of the width style attribute set on the source element. -
"resolve" - Tries to use style to determine the width, falling back to element. -
Anything else - The value of the width option is directly set as the width of the container. -
-
-
-
-
Key
-
width
- -
Value
-
string
-
-
-
- -

- Internationalization (Language support) -

- -

- Messages will be displayed to users when necessary, such as when no - search results were found or more characters need to be entered in order - for a search to be made. These messages have been - translated into many languages - by contributors to Select2, but you can also provide your own - translations. -

- -
-
-
-
Key
-
language
- -
Value
-
object or string
-
- -
- -
-
Module
-
- Translation -
-
-
- -
-

- Heads up! When using translations provided by Select2, - you must make sure to include the translation file in your page after - Select2. -

-
-
- -

- When a string is passed in as the language, Select2 will try to resolve - it into a language file. This allows you to specify your own language - files, which must be defined as an AMD module. If the language file - cannot be found, Select2 will assume it is a language code controlled by - Select2, and it will try to load the translations for that language - instead. -

- -

- You can include your own translations by providing an object similar to - the one below. -

+

+ You can include your own translations by providing an object similar to + the one below. + 

 language: {
@@ -417,194 +417,194 @@ language: {
 }
-

- Templating results and selections -

+

+ Templating results and selections +

-

- By default, Select2 will display the option text within the list of - results and when the option has been selected. Select2 comes with options - that allow you to further customize the display of results and selections, - allowing you to display them however you want. -

+

+ By default, Select2 will display the option text within the list of + results and when the option has been selected. Select2 comes with options + that allow you to further customize the display of results and selections, + allowing you to display them however you want. +

-

- Customizing the display of selections -

+

+ Customizing the display of selections +

-

- When an option is displayed after it has been selected, it is passed - through a formatting function that determines what is displayed. By - default, the function only returns the text key of the data - object. -

+

+ When an option is displayed after it has been selected, it is passed + through a formatting function that determines what is displayed. By + default, the function only returns the text key of the data + object. +

+
+
Key
+
templateSelection
+ +
Value
+
A function taking a selection object
+
+ +
+ Anything rendered as a selection is templated. + This includes placeholders and pre-existing selections that are displayed, + so you must ensure that your templating functions can support them. +
+ +

+ The templateSelection function should return a string + containing the text to be displayed, or an object (such as a jQuery + object) that contains the data that should be displayed. +

+ +

+ Strings are assumed to contain only text and will be + passed through the escapeMarkup function, which strips any + HTML markup. +

+ +

+ + Anything else will be passed + directly to jQuery.fn.append + and will be handled directly by jQuery. Any markup, such as + HTML, returned will not be escaped and it is up to you to escape any + malicious input provided by users. +

+ +

+ Customizing the display of results +

+ +

+ When an option is displayed after it has been selected, it is passed + through a formatting function that determines what is displayed. By + default, the function only returns the text key of the data + object. +

+ +
+
Key
+
templateSelection
+ +
Value
+
A function taking a selection object
+
+ +
+ Anything rendered in the results is templated. + This includes results such as the "Searching..." and "Loading more..." + text which will periodically be displayed, which allows you to add more + advanced formatting to these automatically generated options. +
+ +

+ The templateResult function should return a string + containing the text to be displayed, or an object (such as a jQuery + object) that contains the data that should be displayed. It can also + return null, which will prevent the option from being + displayed in the results list. +

+ +

+ Strings are assumed to contain only text and will be + passed through the escapeMarkup function, which strips any + HTML markup. +

+ +

+ + Anything else will be passed + directly to jQuery.fn.append + and will be handled directly by jQuery. Any markup, such as + HTML, returned will not be escaped and it is up to you to escape any + malicious input provided by users. +

+ +

+ Results +

+ +

+ Select2 can work on many different data sets ranging from local options, + the same way that a <select> typically works, from + remote options where a server generates the results that users can select + from. +

+ +

+ Array +

+ +

+ Select2 allows creating the results based on an array of data objects that + is included when initializing Select2. +

+ +
+
Key
-
templateSelection
+
data
Value
-
A function taking a selection object
+
array of objects
+
-
- Anything rendered as a selection is templated. - This includes placeholders and pre-existing selections that are displayed, - so you must ensure that your templating functions can support them. -
+
+
+
Adapter
+
+ ArrayAdapter +
+
+
+
-

- The templateSelection function should return a string - containing the text to be displayed, or an object (such as a jQuery - object) that contains the data that should be displayed. -

+

+ The objects that the users can select from should be passed as an array + with each object containing id and text + properties. +

-

- Strings are assumed to contain only text and will be - passed through the escapeMarkup function, which strips any - HTML markup. -

+

+ AJAX +

-

- - Anything else will be passed - directly to jQuery.fn.append - and will be handled directly by jQuery. Any markup, such as - HTML, returned will not be escaped and it is up to you to escape any - malicious input provided by users. -

- -

- Customizing the display of results -

- -

- When an option is displayed after it has been selected, it is passed - through a formatting function that determines what is displayed. By - default, the function only returns the text key of the data - object. -

+

+ Select2 allows searching for results from remote data sources using AJAX + requests. +

+
+
Key
-
templateSelection
+
ajax
Value
-
A function taking a selection object
+
object
+
-
- Anything rendered in the results is templated. - This includes results such as the "Searching..." and "Loading more..." - text which will periodically be displayed, which allows you to add more - advanced formatting to these automatically generated options. -
+
+
+
Adapter
+
+ AjaxAdapter +
+
+
+
-

- The templateResult function should return a string - containing the text to be displayed, or an object (such as a jQuery - object) that contains the data that should be displayed. It can also - return null, which will prevent the option from being - displayed in the results list. -

- -

- Strings are assumed to contain only text and will be - passed through the escapeMarkup function, which strips any - HTML markup. -

- -

- - Anything else will be passed - directly to jQuery.fn.append - and will be handled directly by jQuery. Any markup, such as - HTML, returned will not be escaped and it is up to you to escape any - malicious input provided by users. -

- -

- Results -

- -

- Select2 can work on many different data sets ranging from local options, - the same way that a <select> typically works, from - remote options where a server generates the results that users can select - from. -

- -

- Array -

- -

- Select2 allows creating the results based on an array of data objects that - is included when initializing Select2. -

- -
-
-
-
Key
-
data
- -
Value
-
array of objects
-
-
- -
-
-
Adapter
-
- ArrayAdapter -
-
-
-
- -

- The objects that the users can select from should be passed as an array - with each object containing id and text - properties. -

- -

- AJAX -

- -

- Select2 allows searching for results from remote data sources using AJAX - requests. -

- -
-
-
-
Key
-
ajax
- -
Value
-
object
-
-
- -
-
-
Adapter
-
- AjaxAdapter -
-
-
-
- -

- All options passed to this option will be directly passed to the - $.ajax function that executes AJAX requests. There are a few - custom options that Select2 will intercept, allowing you to customize the - request as it is being made. +

+ All options passed to this option will be directly passed to the + $.ajax function that executes AJAX requests. There are a few + custom options that Select2 will intercept, allowing you to customize the + request as it is being made. 

 ajax: {
@@ -673,88 +673,88 @@ ajax: {
   }
 }
-

+

-

- Tags -

+

+ Tags +

-

- Users can create their own options based on the text that they have - entered. -

- -
-
-
-
Key
-
tags
- -
Value
-
boolean / array of objects
-
-
- -
-
-
Adapter
-
- DataAdapter -
- -
Decorator
-
- Tags -
-
-
-
- -

- If the tags option is passed into Select2, if a user types - anything into the search box which doesn't already exist, it will be - displayed at the top and the user will be able to select it. -

- -

- For backwards compatibility, if an array of objects is - passed in with the tags option, the options will be - automatically created and the user will be able to select from them. - This is the same as how array data - works, and has similar limitations. -

- -

- Change how options are matched when searching -

- -

- When users filter down the results by entering search terms into the - search box, Select2 uses an internal "matcher" to match search terms to - results. When a remote data set is used, Select2 expects that the - returned results have already been filtered. -

+

+ Users can create their own options based on the text that they have + entered. +

+
+
Key
-
- matcher -
+
tags
Value
+
boolean / array of objects
+
+
+ +
+
+
Adapter
- A function taking search params and the - data object. + DataAdapter +
+ +
Decorator
+
+ Tags
+
+
-

- Select2 will pass the individual data objects that have been passed back - from the data adapter into the matcher individually to - determine if they should be displayed. Only the first-level objects will - be passed in, so if you are working with nested data, you need to - match those individually. -

+

+ If the tags option is passed into Select2, if a user types + anything into the search box which doesn't already exist, it will be + displayed at the top and the user will be able to select it. +

+ +

+ For backwards compatibility, if an array of objects is + passed in with the tags option, the options will be + automatically created and the user will be able to select from them. + This is the same as how array data + works, and has similar limitations. +

+ +

+ Change how options are matched when searching +

+ +

+ When users filter down the results by entering search terms into the + search box, Select2 uses an internal "matcher" to match search terms to + results. When a remote data set is used, Select2 expects that the + returned results have already been filtered. +

+ +
+
Key
+
+ matcher +
+ +
Value
+
+ A function taking search params and the + data object. +
+
+ +

+ Select2 will pass the individual data objects that have been passed back + from the data adapter into the matcher individually to + determine if they should be displayed. Only the first-level objects will + be passed in, so if you are working with nested data, you need to + match those individually. + 

 matcher: function (params, data) {
@@ -779,12 +779,12 @@ matcher: function (params, data) {
 }
-

- This allows for more advanced matching when working with nested objects, - allowing you to handle them however you want. For those who are not - looking to implement highly customized matching, but instead are just - looking to change the matching algorithm for the text, a - compatibility modules has been created to - make it easier. -

-
+

+ This allows for more advanced matching when working with nested objects, + allowing you to handle them however you want. For those who are not + looking to implement highly customized matching, but instead are just + looking to change the matching algorithm for the text, a + compatibility modules has been created to + make it easier. +

+
diff --git a/docs/_includes/options/dropdown.html b/docs/_includes/options/dropdown.html index bd6e5efa..87629077 100644 --- a/docs/_includes/options/dropdown.html +++ b/docs/_includes/options/dropdown.html @@ -1,116 +1,76 @@ - + + +

+ When working with smaller data sets, the search box can take up more space + that is necessary, as there are not enough results for filtering to be + effective. Select2 allows you to only display the search box when the + number of search results reaches a certain threshold. +

+ +
+
+
+
Key
+
minimumResultsForSearch
+ +
Value
+
integer
+
+
+ +
+
+
Adapter
+
+ DropdownAdapter +
+ +
Decorator
+
+ MinimumResultsForSearch +
+
+
+
+ + + +

+ When users close the dropdown, the last highlighted option can be + automatically selected. This is commonly used in combination with + tagging and placeholders + and other situations where the user is required to select an option, or + they need to be able to quickly select multiple options. +

+ +
+
Adapter
+
+ ResultsAdapter +
+ +
Decorator
+
+ SelectOnClose +
+
+ +

+ Close the dropdown when a result is selected +

+ +

+ Select2 will automatically close the dropdown when an element is selected, + similar to what is done with a normal select box. This behavior can be + changed though to keep the dropdown open when results are selected, + allowing for multiple options to be selected quickly. +

+ +
+
+
+
Key
+
closeOnSelect
+ +
Default
+
true
+
+
+ +
+
+
Adapter
+
+ DropdownAdapter +
+ +
Decorator
+
+ CloseOnSelect +
+
+
+
+ +

+ If this decorator is not used (or closeOnSelect is set to + false), the dropdown will not automatically close when a + result is selected. The dropdown will also never close if the + ctrl key is held down when the result is selected. +

+ diff --git a/docs/_includes/options/events.html b/docs/_includes/options/events.html index 453f6682..bf4f39a9 100644 --- a/docs/_includes/options/events.html +++ b/docs/_includes/options/events.html @@ -1,50 +1,50 @@ -
-
-

Events

-
+
+
+

Events

+
-

- Select2 has an internal event system that is used to notify parts of the - component that state has changed, as well as an adapter that allows some - of these events to be relayed to the outside word. -

+

+ Select2 has an internal event system that is used to notify parts of the + component that state has changed, as well as an adapter that allows some + of these events to be relayed to the outside word. +

-
-
Adapter
-
- SelectionAdapter -
+
+
Adapter
+
+ SelectionAdapter +
-
Decorator
-
- EventRelay -
-
+
Decorator
+
+ EventRelay +
+
-

- Public events -

+

+ Public events +

-

- All public events are relayed using the jQuery event system, and they are - triggered on the <select> element that Select2 is - attached to. You can attach to them using the - .on method provided - by jQuery. -

+

+ All public events are relayed using the jQuery event system, and they are + triggered on the <select> element that Select2 is + attached to. You can attach to them using the + .on method provided + by jQuery. +

-

- Internal events -

+

+ Internal events +

-

- Select2 triggers internal events using its own internal event system, - which allows adapters to communicate with each other. These events are not - accessible through the jQuery event system. -

+

+ Select2 triggers internal events using its own internal event system, + which allows adapters to communicate with each other. These events are not + accessible through the jQuery event system. +

-

- You can find more information on the public events triggered by individual - adapters in the individual adapter documentation. -

-
+

+ You can find more information on the public events triggered by individual + adapters in the individual adapter documentation. +

+