From df2122c00f5724fdd7406cae8df0e74dc273485c Mon Sep 17 00:00:00 2001 From: Florian Kissling Date: Thu, 9 Apr 2015 20:27:45 +0200 Subject: [PATCH 01/85] Add anchor.js for pages using the `default` layout. * adds styles for anchor.js (similar to the official Bootstrap docs) * currently results some of the generated links to have a suffix (e. g. examples.html#templating-1) added due to sections having the same ID as the headline copy that we want to link to --- docs/_includes/head.html | 20 +++++++++ docs/_layouts/default.html | 6 +++ docs/vendor/css/anchor.css | 78 ++++++++++++++++++++++++++++++++++++ docs/vendor/js/anchor.min.js | 6 +++ 4 files changed, 110 insertions(+) create mode 100644 docs/vendor/css/anchor.css create mode 100644 docs/vendor/js/anchor.min.js diff --git a/docs/_includes/head.html b/docs/_includes/head.html index 9155095e..039168bf 100644 --- a/docs/_includes/head.html +++ b/docs/_includes/head.html @@ -10,15 +10,35 @@ + + diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index c64b9a22..aac314c5 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -9,6 +9,12 @@ {{ content }} {% include footer.html %} + +
+
+

+ Examples +

+

+ Lorem ipsum. +

+
+
+
From d98cbcec21d8f341d0ac308746409afd89a103c2 Mon Sep 17 00:00:00 2001 From: Florian Kissling Date: Fri, 24 Apr 2015 03:02:56 +0200 Subject: [PATCH 13/85] Add a fixed sidebar with anchor navigation to the sidebar. Borrowed from the Bootstrap doc implementation. --- docs/_includes/head.html | 206 ++- docs/_includes/nav/options.html | 54 + docs/_includes/navigation.html | 2 +- docs/_layouts/default.html | 52 +- docs/options.html | 2462 ++++++++++++++++--------------- docs/vendor/css/prettify.css | 11 +- 6 files changed, 1544 insertions(+), 1243 deletions(-) create mode 100644 docs/_includes/nav/options.html diff --git a/docs/_includes/head.html b/docs/_includes/head.html index 19568d16..5fcf54ef 100644 --- a/docs/_includes/head.html +++ b/docs/_includes/head.html @@ -20,6 +20,148 @@ diff --git a/docs/_includes/nav/options.html b/docs/_includes/nav/options.html new file mode 100644 index 00000000..27a12117 --- /dev/null +++ b/docs/_includes/nav/options.html @@ -0,0 +1,54 @@ + diff --git a/docs/_includes/navigation.html b/docs/_includes/navigation.html index f89d53f3..0df3d504 100644 --- a/docs/_includes/navigation.html +++ b/docs/_includes/navigation.html @@ -1,4 +1,4 @@ -
- -
-
-

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

+
-
-
-

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
@@ -1226,34 +1237,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.
@@ -1266,31 +1277,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
@@ -1320,295 +1331,300 @@ 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 +
+ +
-
-
-

Setting default options

-
+
+
+

Setting default options

+
-

- In some cases, you need to set the default options for all instances of - Select2 in your web application. This is especially useful when you are - migrating from past versions of Select2, or you are using non-standard - options like custom AMD builds. Select2 exposes the - default options through $.fn.select2.defaults, which allows - you to set them globally. -

+

+ In some cases, you need to set the default options for all instances of + Select2 in your web application. This is especially useful when you are + migrating from past versions of Select2, or you are using non-standard + options like custom AMD builds. Select2 exposes the + default options through $.fn.select2.defaults, which allows + you to set them globally. +

-

- When setting options globally, any past defaults that have been set will - be overriden. Default options are only used when an option is requested - that has not been set during initialization. -

+

+ When setting options globally, any past defaults that have been set will + be overriden. Default options are only used when an option is requested + that has not been set during initialization. +

-

- You can set default options by calling - $.fn.select2.defaults.set("key", "value"). The key that is - set should take the same format as keys set using - HTML data-* attributes which - means that two dashes (--) will be replaced by a level of - nesting, and a single dash (-) will convert it to a camelCase - string. -

+

+ You can set default options by calling + $.fn.select2.defaults.set("key", "value"). The key that is + set should take the same format as keys set using + HTML data-* attributes which + means that two dashes (--) will be replaced by a level of + nesting, and a single dash (-) will convert it to a camelCase + string. + 

 $.fn.select2.defaults.set("theme", "classic");
-

- You can reset the default options by calling - $.fn.select2.defaults.reset(). -

-
+

+ You can reset the default options by calling + $.fn.select2.defaults.reset(). +

+
-
-
-

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

- -

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

- -

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

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

Backwards compatibility

-
-
-
Adapter
-
- oldMatcher -
-
+

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

+ +

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

+ +

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

+ +
+
+
+
Key
+
+ matcher +
+ +
Value
+
+ A function taking a search term and the data object + text. +
+
+
+ +
+
+
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. +

+ +

+ 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 +
+ +
Value
+
+ A function taking a callback +
+
+
+ +
+
+
Adapter
+
+ DataAdapter +
+ +
Decorator
+
+ InitSelection +
+
+
+
+ +

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

+ +

+ 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 +
+ +
Value
+
+ A function taking params (including a callback) +
+
+
+ +
+
+
Adapter
+
+ DataAdapter +
+ +
Decorator
+
+ Query +
+
+
+
+
+ +

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

- 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. + It is now encouraged to use the <select> tag instead.

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

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

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

- -

- 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 -
- -
Value
-
- A function taking params (including a callback) -
-
-
- -
-
-
Adapter
-
- DataAdapter -
- -
Decorator
-
- Query -
-
-
-
+
Decorator
+
+ InputData +
+
- -

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

- -

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

- -
-
Adapter
-
- DataAdapter -
- -
Decorator
-
- InputData -
-
- +
+ + diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 235a815c..ab79164e 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -48,14 +48,6 @@ })(); - + {% include ga.html %} diff --git a/docs/_layouts/home.html b/docs/_layouts/home.html index 3d1f9927..1c47edba 100644 --- a/docs/_layouts/home.html +++ b/docs/_layouts/home.html @@ -17,14 +17,6 @@ {% include footer.html %} - + {% include ga.html %} From 69d8ac4485b35a3aeb07dcf30061405188138af0 Mon Sep 17 00:00:00 2001 From: Florian Kissling Date: Fri, 24 Apr 2015 03:10:54 +0200 Subject: [PATCH 15/85] Whitespace. --- docs/_layouts/default.html | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index ab79164e..627544a1 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -12,6 +12,7 @@ From 481a2f89c975790e6e522bc0b1a12fccb9c9017f Mon Sep 17 00:00:00 2001 From: Florian Kissling Date: Fri, 24 Apr 2015 03:16:56 +0200 Subject: [PATCH 16/85] Add ID. --- docs/options.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/options.html b/docs/options.html index 0ca4d9d5..8ccccea2 100644 --- a/docs/options.html +++ b/docs/options.html @@ -19,7 +19,7 @@ slug: options
-

Core options

+

Core options

Select2 supports a small subset of options in every build that is From 15f9922437ca1a5eccdf44920928511babb0829d Mon Sep 17 00:00:00 2001 From: Florian Kissling Date: Fri, 24 Apr 2015 03:36:45 +0200 Subject: [PATCH 17/85] Add .navbar-default. --- docs/_includes/navigation.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_includes/navigation.html b/docs/_includes/navigation.html index 0df3d504..f94a47d7 100644 --- a/docs/_includes/navigation.html +++ b/docs/_includes/navigation.html @@ -1,4 +1,4 @@ -

-
+

The basics

From d813feaa7bb8274ca02f0e89bddd87432e9b6d8e Mon Sep 17 00:00:00 2001 From: Florian Kissling Date: Fri, 24 Apr 2015 03:38:00 +0200 Subject: [PATCH 19/85] Simplify homepage .jumbotron. --- docs/_includes/head.html | 17 ++++++++++++++--- docs/index.html | 34 ++++++++++++++-------------------- 2 files changed, 28 insertions(+), 23 deletions(-) diff --git a/docs/_includes/head.html b/docs/_includes/head.html index 5fcf54ef..ad8bb90b 100644 --- a/docs/_includes/head.html +++ b/docs/_includes/head.html @@ -217,15 +217,26 @@ color: #333; background-color: transparent; border-color: #333; + padding: 15px 30px; + font-size: 20px; + } + + .btn-outline-inverse .fa { + margin-right: 8px; } .btn-outline-inverse:hover { - color: #428BCA; - background-color: white; + color: #fff; + border-color: #428BCA; + background-color: #428BCA; + } + + .version { + color: #999; } .navbar { - border-bottom: 1px solid #eee; + background-color: #fff; } /* anchor.js */ diff --git a/docs/index.html b/docs/index.html index 1030bf37..4f0dd0c2 100644 --- a/docs/index.html +++ b/docs/index.html @@ -5,26 +5,20 @@ slug: home ---
-
-
-
-

Select2

-

- The jQuery replacement for select boxes -

-
-
-

- - - Download - -

-

- Version 4.0.0-rc.2 -

-
-
+
+

Select2

+

+ The jQuery replacement for select boxes +

+

+ + + Download + +

+

+ Version 4.0.0-rc.2 +

From 8a1a35aa151e6d98a2fdbf46b923467cd2a7cae5 Mon Sep 17 00:00:00 2001 From: Florian Kissling Date: Fri, 24 Apr 2015 03:40:57 +0200 Subject: [PATCH 20/85] Make "Download" button stand out a little more. --- docs/_includes/head.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_includes/head.html b/docs/_includes/head.html index ad8bb90b..e14b5c11 100644 --- a/docs/_includes/head.html +++ b/docs/_includes/head.html @@ -214,9 +214,9 @@ } .btn-outline-inverse { - color: #333; + color: #428BCA; background-color: transparent; - border-color: #333; + border-color: #428BCA; padding: 15px 30px; font-size: 20px; } From 25ba1ef1f3642863677e55fd052988ed26c9e448 Mon Sep 17 00:00:00 2001 From: Florian Kissling Date: Sat, 25 Apr 2015 04:34:15 +0200 Subject: [PATCH 21/85] Prettify 
 on homepage.

---
 docs/_layouts/home.html | 7 +++++++
 docs/index.html         | 6 +++---
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/docs/_layouts/home.html b/docs/_layouts/home.html
index 1c47edba..64179ef2 100644
--- a/docs/_layouts/home.html
+++ b/docs/_layouts/home.html
@@ -19,4 +19,11 @@
 
         {% include ga.html %}
     
+        
 
diff --git a/docs/index.html b/docs/index.html
index 4f0dd0c2..a5857e7e 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -64,7 +64,7 @@ slug: home
         Include the following lines of code in the <head>
         section of your HTML.
 
-
+
 <link href="//cdnjs.cloudflare.com/ajax/libs/select2/4.0.0-rc.2/css/select2.min.css" rel="stylesheet" />
 <script src="//cdnjs.cloudflare.com/ajax/libs/select2/4.0.0-rc.2/js/select2.min.js"></script>
 

@@ -79,7 +79,7 @@ slug: home
         Initialize Select2 on the <select> element that you
         want to make awesome.
 
-
+
 <script type="text/javascript">
   $('select').select2();
 </script>
@@ -111,7 +111,7 @@ slug: home
         Include the following lines of code in the <head>
         section of your HTML.
 
-
+
 <link href="path/to/select2.min.css" rel="stylesheet" />
 <script src="path/to/select2.min.js"></script>
 


From b68a7b38a0cfd086122a00d41d7b7b568425760f Mon Sep 17 00:00:00 2001
From: Florian Kissling 
Date: Sat, 25 Apr 2015 04:35:55 +0200
Subject: [PATCH 22/85] Remove explicit "Home" link.

---
 docs/_includes/navigation.html | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/docs/_includes/navigation.html b/docs/_includes/navigation.html
index f94a47d7..f17522e6 100644
--- a/docs/_includes/navigation.html
+++ b/docs/_includes/navigation.html
@@ -12,9 +12,6 @@
-
+
+
+
-

Select2 4.0.0

+

Select2 4.0.0

The 4.0 release of Select2 is the result of three years of working on the @@ -690,6 +692,11 @@ $("select").val("1").trigger("change"); // instead of $("select").select2("val", $("select").prop("disabled", true); // instead of $("select").enable(false);

+
+ +
+ + {% include ga.html %} + From fb40644c42e91a6a46ee57d38555266edb49bef2 Mon Sep 17 00:00:00 2001 From: Florian Kissling Date: Tue, 28 Apr 2015 04:01:33 +0200 Subject: [PATCH 47/85] Add tags. --- docs/_includes/nav/options.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_includes/nav/options.html b/docs/_includes/nav/options.html index c9ee5be7..41436f2b 100644 --- a/docs/_includes/nav/options.html +++ b/docs/_includes/nav/options.html @@ -3,7 +3,7 @@
  • Core Options
      -
    • Declaring configuration in the data-* attributes
      • +
    • Declaring configuration in the data-* attributes
    • AMD compatibility
    • Display
    • Results
      • From 365ec579b7edaedddd9a298b4d6f0a4bd9344c1a Mon Sep 17 00:00:00 2001 From: Florian Kissling Date: Thu, 30 Apr 2015 00:59:06 +0200 Subject: [PATCH 48/85] Typography. --- docs/_sass/_s2-docs-home.scss | 6 ++++++ docs/announcements-4.0.html | 2 +- docs/css/s2-docs.scss | 5 +++++ 3 files changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/_sass/_s2-docs-home.scss b/docs/_sass/_s2-docs-home.scss index 0b534c15..8cea4b7a 100644 --- a/docs/_sass/_s2-docs-home.scss +++ b/docs/_sass/_s2-docs-home.scss @@ -12,3 +12,9 @@ .s2-docs-home .jumbotron { margin-bottom: 0; } + +#lead { + text-align: center; + max-width: 800px; + margin: 0 auto 80px; +} diff --git a/docs/announcements-4.0.html b/docs/announcements-4.0.html index 261324ca..9fe1e39d 100644 --- a/docs/announcements-4.0.html +++ b/docs/announcements-4.0.html @@ -18,7 +18,7 @@ slug: announcements-4.0

      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 diff --git a/docs/css/s2-docs.scss b/docs/css/s2-docs.scss index 63f8d3e9..47cbbe9b 100644 --- a/docs/css/s2-docs.scss +++ b/docs/css/s2-docs.scss @@ -38,6 +38,11 @@ color: #999; } +.page-header { + padding-bottom: 19px; + margin-bottom: 29px; +} + /* Inline code within headings retain the heading's background-color */ h2 code, h3 code, From 3ed07a6fda75b198be4c57d77d8ba1efa5be24c6 Mon Sep 17 00:00:00 2001 From: Florian Kissling Date: Fri, 1 May 2015 04:30:52 +0200 Subject: [PATCH 49/85] Stop anchorjs from suffixing its links for "Placeholders" and "Templating" headlines. Cosmetic changes for the homepage 3.x docs notice. --- docs/_sass/_s2-docs-home.scss | 1 - docs/examples.html | 8 ++++---- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/_sass/_s2-docs-home.scss b/docs/_sass/_s2-docs-home.scss index 8cea4b7a..668cbbec 100644 --- a/docs/_sass/_s2-docs-home.scss +++ b/docs/_sass/_s2-docs-home.scss @@ -2,7 +2,6 @@ padding: 15px 20px; color: #777; background-color: #FAFAFA; - border-top: 1px solid #FFF; border-bottom: 1px solid #eee; a { font-weight: bold; diff --git a/docs/examples.html b/docs/examples.html index 8475cd15..6737109f 100644 --- a/docs/examples.html +++ b/docs/examples.html @@ -94,9 +94,9 @@ $(".js-example-basic-multiple").select2();

    • -
    +
    -

    Placeholders

    +

    Placeholders

    A placeholder value can be defined and will be displayed until a selection is made. @@ -136,9 +136,9 @@ $(".js-example-placeholder-multiple").select2({

    -
    +
    -

    Templating

    +

    Templating

    Various display options of the Select2 component can be changed From bf7d273f895992fd14145af5c3ccb0c8e275c717 Mon Sep 17 00:00:00 2001 From: Florian Kissling Date: Sat, 2 May 2015 14:10:31 +0200 Subject: [PATCH 50/85] Add sidebar anchor navigation to the "Examples" page. --- docs/_includes/nav/examples.html | 67 ++ docs/_sass/_prettify.scss | 10 +- docs/_sass/_s2-docs-examples.scss | 83 +++ docs/css/s2-docs.scss | 9 +- docs/examples.html | 994 ++++++++++++++---------------- 5 files changed, 630 insertions(+), 533 deletions(-) create mode 100644 docs/_includes/nav/examples.html create mode 100644 docs/_sass/_s2-docs-examples.scss diff --git a/docs/_includes/nav/examples.html b/docs/_includes/nav/examples.html new file mode 100644 index 00000000..c2e2b301 --- /dev/null +++ b/docs/_includes/nav/examples.html @@ -0,0 +1,67 @@ +

    diff --git a/docs/_sass/_prettify.scss b/docs/_sass/_prettify.scss index bb85b289..830860d4 100644 --- a/docs/_sass/_prettify.scss +++ b/docs/_sass/_prettify.scss @@ -28,11 +28,11 @@ padding: 9px 14px; margin-bottom: 20px; margin-top: 20px; - border: 1px solid #e8e8e8; + border: 1px solid #eee; &.linenums { - -webkit-box-shadow: inset 40px 0 0 #fbfbfc, inset 41px 0 0 #ececf0; - -moz-box-shadow: inset 40px 0 0 #fbfbfc, inset 41px 0 0 #ececf0; - box-shadow: inset 40px 0 0 #fbfbfc, inset 41px 0 0 #ececf0; + -webkit-box-shadow: inset 40px 0 0 #fbfbfb, inset 41px 0 0 #f6f6f6; + -moz-box-shadow: inset 40px 0 0 #fbfbfb, inset 41px 0 0 #f6f6f6; + box-shadow: inset 40px 0 0 #fbfbfb, inset 41px 0 0 #f6f6f6; } } @@ -42,6 +42,6 @@ ol.linenums { } ol.linenums li { padding-left: 12px; - color: #bebec5; + color: #bebebe; line-height: 18px; } diff --git a/docs/_sass/_s2-docs-examples.scss b/docs/_sass/_s2-docs-examples.scss new file mode 100644 index 00000000..ce1440b4 --- /dev/null +++ b/docs/_sass/_s2-docs-examples.scss @@ -0,0 +1,83 @@ +.s2-example + pre, +.s2-event-log + pre { + margin: -15px -15px 15px; + border-radius: 0; + border-width: 0 0 1px; +} + +@media (min-width: 768px) { + .s2-example + pre, + .s2-event-log + pre { + margin-top: -16px; + margin-left: 0; + margin-right: 0; + border-width: 1px; + border-bottom-left-radius: 4px; + border-bottom-right-radius: 4px; + } +} + +.s2-event-log { + background: #002451; + font-family: Menlo, 'Bitstream Vera Sans Mono', 'DejaVu Sans Mono', Monaco, Consolas, monospace; + color: white; + position: relative; + padding: 45px 15px 15px; + margin: 0 -15px 15px; +} + +.s2-event-log:after { + content: "Event Log"; + position: absolute; + top: 15px; + left: 15px; + font-size: 12px; + font-weight: bold; + color: #BBB; + text-transform: uppercase; + letter-spacing: 1px; +} + +.s2-example { + position: relative; + padding: 45px 15px 15px; + margin: 0 -15px 15px; + background-color: #FAFAFA; + box-shadow: inset 0 3px 6px rgba(0, 0, 0, 0.05); + border-color: #E5E5E5 #EEE #EEE; + border-style: solid; + border-width: 1px 0; +} + +@media (min-width: 768px) { + .s2-example { + margin-left: 0; + margin-right: 0; + background-color: #FFF; + border-width: 1px; + border-color: #eee; + border-radius: 4px 4px 0 0; + box-shadow: none; + } + + .s2-event-log { + margin-left: 0; + margin-right: 0; + margin-top: -15px; + border-width: 1px; + border-color: #eee; + box-shadow: none; + } +} + +.s2-example:after { + content: "Example"; + position: absolute; + top: 15px; + left: 15px; + font-size: 12px; + font-weight: bold; + color: #BBB; + text-transform: uppercase; + letter-spacing: 1px; +} diff --git a/docs/css/s2-docs.scss b/docs/css/s2-docs.scss index 47cbbe9b..a11e67c3 100644 --- a/docs/css/s2-docs.scss +++ b/docs/css/s2-docs.scss @@ -8,6 +8,7 @@ @import "s2-docs-footer"; @import "s2-docs-alert"; @import "s2-docs-home"; +@import "s2-docs-examples"; @import "anchorjs"; @import "jumbotron"; @import "prettify"; @@ -62,11 +63,3 @@ pre { background-color: #f7f7f9; border: 1px solid #e1e1e8; } - -.s2-docs-headline-example { - font-size: 12px; - font-weight: 700; - color: #959595; - text-transform: uppercase; - letter-spacing: 1px; -} diff --git a/docs/examples.html b/docs/examples.html index 6737109f..46b5f5fc 100644 --- a/docs/examples.html +++ b/docs/examples.html @@ -26,30 +26,30 @@ slug: examples
    -
    -
    -

    The basics

    +
    +
    +
    +

    The basics

    -

    - Select2 can take a regular select box like this... -

    +

    + Select2 can take a regular select box like this... +

    -

    - -

    +

    + +

    -

    - and turn it into this... -

    +

    + and turn it into this... +

    -

    - -

    -
    -
    -

    Example code

    +
    +

    + +

    +
    - 
    
+        
    
 
 
-    
    
-  
    
+      
    
 
-  
    
-    
    
-      
    Multiple select boxes
    
+      
    
+        
    Multiple select boxes
    
 
-      
    
-        Select2 also supports multi-value select boxes. The select below is declared with the multiple attribute.
-      
    
+        
    
+          Select2 also supports multi-value select boxes. The select below is declared with the multiple attribute.
+        
    
 
-      
    
-        
-      
    
-    
    
-    
    
-      
    Example code
    
+        
    
+          
    
+            
+          
    
+        
    
 
-      
    
+        
    
 
 
-    
    
-  
    
+      
    
 
-  
    
-    
    
-      
    Placeholders
    
+      
    
+        
    Placeholders
    
 
-      
    
-        A placeholder value can be defined and will be displayed until a selection is made.
-      
    
+        
    
+          A placeholder value can be defined and will be displayed until a
+          selection is made. Select2 uses the placeholder attribute
+          on multiple select boxes, which requires IE 10+. You can support it in
+          older versions with
+          the Placeholders.js polyfill.
+        
    
 
-      
    
-        
-      
    
+        
    
+          
    
+            
+          
    
 
-      
    
-        Select2 uses the placeholder attribute on multiple select
-        boxes, which requires IE 10+. You can support it in older versions with
-        the Placeholders.js polyfill.
-      
    
+          
    
+            
+          
    
+        
    
 
-      
    
-        
-      
    
-    
    
-    
    
-      
    Example code
    
-
-      
    
+        
    
 
 
-    
    
-  
    
+      
 
-  
    
-    
    
-      
    Templating
    
+      
    
+        
    Templating
    
 
-      
    
-        Various display options of the Select2 component can be changed
-      
    
+        
    
+          Various display options of the Select2 component can be changed:
+          You can access the <option> element
+          (or <optgroup>) and any attributes on those elements
+          using .element.
+        
    
 
-      
    
-        
-      
    
+        
    
+          Templating is primarily controlled by the
+          templateResult
+          and templateSelection
+          options.
+        
    
 
-      
    
-        You can access the <option> element
-        (or <optgroup>) and any attributes on those elements
-        using .element.
-      
    
+        
    
+          
    
+            
+          
    
+        
    
 
-      
    
-        Templating is primarily controlled by the
-        templateResult
-        and templateSelection
-        options.
-      
    
-    
    
-    
    
-      
    Example code
    
-
-      
    
+        
    
 
 
-    
    
-  
    
+      
 
-  
    
-    
    
-      
    Loading array data
    
+      
    
+        
    Loading array data
    
 
-      
    
-        Select2 provides a way to load the data from a local array.
-      
    
+        
    
+          Select2 provides a way to load the data from a local array.
+          You can provide initial selections with array data by providing the
+          option tag for the selected values, similar to how it would be done for
+          a standard select.
+        
    
 
-      
    
-        
-      
    
+        
    
+          
    
+            
+          
    
 
-      
    
-        You can provide initial selections with array data by providing the
-        option tag for the selected values, similar to how it would be done for
-        a standard select.
-      
    
+          
    
+            
+          
    
+        
    
 
-      
    
-        
-      
    
-    
    
-    
    
-      
    Example code
    
-
-      
    
+        
    
 
 
-    
    
-  
    
+      
 
-  
    
-    
    
-      
    Loading remote data
    
+      
    
+        
    Loading remote data
    
 
-      
    
-        Select2 comes with AJAX support built in, using jQuery's AJAX methods.
-        In this example, we can search for repositories using GitHub's API.
-      
    
+        
    
+          Select2 comes with AJAX support built in, using jQuery's AJAX methods.
+          In this example, we can search for repositories using GitHub's API.
+        
    
 
-      
    
-        
-      
    
+        
    
+          
+        
    
 
-      
    
-        When using Select2 with remote data, the HTML required for the
-        select is the same as any other Select2. If you need to
-        provide default selections, you just need to include an
-        option for each selection that contains the value and text
-        that should be displayed.
-      
    
+        
    
+          When using Select2 with remote data, the HTML required for the
+          select is the same as any other Select2. If you need to
+          provide default selections, you just need to include an
+          option for each selection that contains the value and text
+          that should be displayed.
+        
    
 
-      
    
+        
    
 
-      
    
-        You can configure how Select2 searches for remote data using the
-        ajax option. More information on the individual options
-        that Select2 handles can be found in the
-        options documentation for ajax.
-      
    
+        
    
+          You can configure how Select2 searches for remote data using the
+          ajax option. More information on the individual options
+          that Select2 handles can be found in the
+          options documentation for ajax.
+        
    
 
-      
    
+        
    
 
-      
    
-        Select2 will pass any options in the ajax object to
-        jQuery's $.ajax function, or the transport
-        function you specify.
-      
    
+        
    
+          Select2 will pass any options in the ajax object to
+          jQuery's $.ajax function, or the transport
+          function you specify.
+        
    
 
 
-    
    
-  
    
+      
 
-  
    
-    
    
-      
    Responsive design - Percent width
    
+      
    
+        
    Responsive design - Percent width
    
 
-      
    
-        Select2's width can be set to a percentage of its parent to support
-        responsive design. The two Select2 boxes below are styled to 50% and 75%
-        width respectively.
-      
    
+        
    
+          Select2's width can be set to a percentage of its parent to support
+          responsive design. The two Select2 boxes below are styled to 50% and 75%
+          width respectively.
+        
    
 
-      
    
-        
-      
    
+        
    
+          
    
+            
+          
    
 
-      
    
-        
-      
    
-    
    
-    
    
-      
    Example code
    
+          
    
+            
+          
    
+        
    
 
-      
    
+        
    
 
-      
    
-        Select2 will do its best to resolve the percent width specified via a
-        css class, but it is not always possible. The best way to ensure that
-        Select2 is using a percent based width is to inline the
-        style declaration into the tag.
-      
    
+        
    
+          Select2 will do its best to resolve the percent width specified via a
+          css class, but it is not always possible. The best way to ensure that
+          Select2 is using a percent based width is to inline the
+          style declaration into the tag.
+        
    
 
 
-    
    
-  
    
+      
 
-  
    
-    
    
-      
    Disabled mode
    
+      
    
+        
    Disabled mode
    
 
-      
    
-        Select2 will response the disabled attribute on
-        <select> elements. You can also initialize Select2
-        with disabled: true to get the same effect.
-      
    
+        
    
+          Select2 will response the disabled attribute on
+          <select> elements. You can also initialize Select2
+          with disabled: true to get the same effect.
+        
    
 
-      
    
-        
-      
    
+        
    
 
-      
    
-        
-      
    
+          
    
+            
+          
    
 
-      
    
-        
-        
-      
    
+          
    
+            
+          
    
 
-    
    
+          
    
+            
+            
+          
    
 
-    
    
-      
    Example code
    
+        
    
 
-      
    
+        
    
 
 
-    
    
-  
    
+      
 
-  
    
-    
    
-      
    Disabled results
    
+      
    
+        
    Disabled results
    
 
-      
    
-        Select2 will correctly handled disabled results, both with data coming
-        from a standard select (when the disabled attribute is set)
-        and from remote sources, where the object has
-        disabled: true set.
-      
    
+        
    
+          Select2 will correctly handled disabled results, both with data coming
+          from a standard select (when the disabled attribute is set)
+          and from remote sources, where the object has
+          disabled: true set.
+        
    
 
-      
    
-        
-      
    
-    
    
-    
    
-      
    Example code
    
+        
    
+          
    
+            
+          
    
+        
    
 
-      
    
+        
    
 
 
-    
    
-  
    
+      
 
-  
    
-    
    
-      
    Programmatic access
    
+      
    
+        
    Programmatic access
    
 
-      
    
-        Select2 supports methods that allow programmatic control of the
-        component.
-      
    
+        
    
+          Select2 supports methods that allow programmatic control of the
+          component.
+        
    
 
-      
    
-        
-      
    
+        
    
+          
    
+            
+          
    
+
+          
+
+          
    
+            
+          
    
+
+          
    
+            
+            
+          
    
 
-      
 
-      
    
-        
-      
    
-
-      
    
-        
-        
-      
    
-
-    
    
-
-    
    
-      
    Example code
    
-
-      
    
+        
    
 
 
-    
    
-  
    
 
-  
    
-    
    
-      
    Limiting the number of selections
    
-      
    Select2 multi-value select boxes can set restrictions regarding the maximum number of options selected.
-        The select below is declared with the multiple attribute with maxSelectionLength in the select2 options
    
+      
    
 
-      
    
-        
-      
    
-    
    
-    
    
-      
    Example code
    
+      
    
 
-      
    
+        
    
+          Limiting the number of selections
+        
    
+
+        
    
+          Select2 multi-value select boxes can set restrictions regarding the
+          maximum number of options selected. The select below is declared with
+          the multiple attribute with maxSelectionLength
+          in the select2 options.
+        
    
+
+        
    
+          
    
+            
+          
    
+        
    
+
+        
    
 
 
-    
    
-  
    
 
-  
 
-      
    
-        Select2 allows you to hide the search box depending on the number of
-        options which are displayed. In this example, we use the value
-        Infinity to tell Select2 to never display the search box.
-      
    
+      
    
+        
    Hiding the search box
    
 
-      
    
-        
-      
    
-    
    
-    
    
-      
    Example code
    
+        
    
+          Select2 allows you to hide the search box depending on the number of
+          options which are displayed. In this example, we use the value
+          Infinity to tell Select2 to never display the search box.
+        
    
 
-      
    
+        
    
+          
    
+            
+          
    
+        
    
+
+        
    
 
 
-    
    
-  
 
-  
    
-    
    
-      
    Events
    
+      
    
 
-      
    
-        Select2 will trigger some events on the original select element,
-        allowing you to integrate it with other components. You can find more
-        information on events
-        on the options page.
-      
    
+      
    
+        
    Events
    
 
-      
    
-        
-      
    
+        
    
+          Select2 will trigger some events on the original select element,
+          allowing you to integrate it with other components. You can find more
+          information on events
+          on the options page.
+        
    
 
-      
    
-        
-      
    
+        
    
+          change is fired whenever an option is selected or removed.
+        
    
 
-      
    
-        change is fired whenever an option is selected or removed.
-      
    
+        
    
+          select2:open is fired whenever the dropdown is opened.
+          select2:opening is fired before this and can be prevented.
+        
    
 
-      
    
-        select2:open is fired whenever the dropdown is opened.
-        select2:opening is fired before this and can be prevented.
-      
    
+        
    
+          select2:close is fired whenever the dropdown is closed.
+          select2:closing is fired before this and can be prevented.
+        
    
 
-      
    
-        select2:close is fired whenever the dropdown is closed.
-        select2:closing is fired before this and can be prevented.
-      
    
+        
    
+          select2:select is fired whenever a result is selected.
+          select2:selecting is fired before this and can be prevented.
+        
    
 
-      
    
-        select2:select is fired whenever a result is selected.
-        select2:selecting is fired before this and can be prevented.
-      
    
+        
    
+          select2:unselect is fired whenever a result is unselected.
+          select2:unselecting is fired before this and can be prevented.
+        
    
 
-      
    
-        select2:unselect is fired whenever a result is unselected.
-        select2:unselecting is fired before this and can be prevented.
-      
    
-    
    
-    
    
-      
    Example code
    
+        
    
+          
    
+            
+          
    
 
-      
      
+          
      
+            
+          
      
+        
      
 
-      
      
+        
      
+          
        
+        
        
+
+        
        
 
 
-    
        
-  
+      
 
-  
        
-    
        
-      
        Tagging support
        
+      
        
+        
        Tagging support
        
 
-      
        
-        Select2 can be used to quickly set up fields used for tagging.
-      
        
+        
        
+          Select2 can be used to quickly set up fields used for tagging.
+        
        
 
-      
        
-        
-      
        
+        
        
+          Note that when tagging is enabled the user can select from pre-existing
+          options or create a new tag by picking the first choice, which is what
+          the user has typed into the search box so far.
+        
        
 
-      
        
-        Note that when tagging is enabled the user can select from pre-existing
-        options or create a new tag by picking the first choice, which is what
-        the user has typed into the search box so far.
-      
        
+        
        
+          
        
+            
+          
        
+        
        
 
-    
        
-    
        
-      
        Example code
        
-
-      
        
+        
        
 
 
-    
        
-  
        
 
-  
        
-    
        
-      
        Automatic tokenization
        
+      
        
 
-      
        
-        Select2 supports ability to add choices automatically as the user is
-        typing into the search field. Try typing in the search field below and
-        entering a space or a comma.
-      
        
+      
        
+        
        Automatic tokenization
        
 
-      
        
-        
-      
        
+        
        
+          Select2 supports ability to add choices automatically as the user is
+          typing into the search field. Try typing in the search field below and
+          entering a space or a comma.
+        
        
 
-      
        
-        The separators that should be used when tokenizing can be specified
-        using the tokenSeparators
-        options.
-      
        
+        
        
+          The separators that should be used when tokenizing can be specified
+          using the tokenSeparators
+          options.
+        
        
 
-    
        
-    
        
-      
        Example code
        
+        
        
+          
        
+            
+          
        
+        
        
 
-      
        
+        
        
 
 
-    
        
-  
 
-  
        
-    
        
-      
        Custom matcher
        
+      
        
 
-      
        
-        Unlike other dropdowns on this page, this one matches options only if
-        the term appears in the beginning of the string as opposed to anywhere:
-      
        
+      
        
+        
        Custom matcher
        
 
-      
        
-        
-      
        
+        
        
+          Unlike other dropdowns on this page, this one matches options only if
+          the term appears in the beginning of the string as opposed to anywhere:
+        
        
 
-      
        
-        This custom matcher uses a
-        compatibility module that is
-        only bundled in the
-        full version of Select2. You also
-        have the option of using a
-        more complex matcher.
-      
        
-    
        
-    
        
-      
        Example code
        
+        
        
+          This custom matcher uses a
+          compatibility module that is
+          only bundled in the
+          full version of Select2. You also
+          have the option of using a
+          more complex matcher.
+        
        
 
-      
        
+        
        
+          
        
+            
+          
        
+        
        
+
+        
        
 
 
-    
        
-  
 
-  
        
-    
        
-      
        Diacritics support
        
+      
        
 
-      
        
-        Select2's default matcher will ignore diacritics, making it easier for
-        users to filter results in international selects. Type "aero" into the
-        select below.
-      
        
+      
        
+        
        Diacritics support
        
 
-      
        
-        
-      
        
-    
-    
        
-      
        Example code
        
+        
        
+          Select2's default matcher will ignore diacritics, making it easier for
+          users to filter results in international selects. Type "aero" into the
+          select below.
+        
        
 
-      
        
+        
        
+          
        
+            
+          
        
+        
        
+
+        
        
 
 
-    
        
-  
        
 
-  
        
-    
        
-      
        Multiple languages
        
+      
        
 
-      
        
-        Select2 supports displaying the messages in different languages, as well
-        as providing your own
-        custom messages
-        that can be displayed.
-      
        
+      
        
+        
        Multiple languages
        
 
-      
        
-        
-      
        
+        
        
+          Select2 supports displaying the messages in different languages, as well
+          as providing your own
+          custom messages
+          that can be displayed.
+        
        
 
-      
        
-        The language does not have to be defined when Select2 is being
-        initialized, but instead can be defined in the [lang]
-        attribute of any parent elements as [lang="es"].
-      
        
-    
-    
        
-      
        Example code
        
+        
        
+          The language does not have to be defined when Select2 is being
+          initialized, but instead can be defined in the [lang]
+          attribute of any parent elements as [lang="es"].
+        
        
 
-      
        
+        
        
+          
        
+            
+          
        
+        
        
+
+        
        
 
 
-    
        
-  
        
 
-  
        
-    
        
-      
        Theme support
        
+      
        
 
-      
        
-        Select2 supports custom themes using the
-        theme option
-        so you can style Select2 to match the rest of your application.
-      
        
+      
        
+        
        Theme support
        
 
-      
        
-        
-      
        
+        
        
+          Select2 supports custom themes using the
+          theme option
+          so you can style Select2 to match the rest of your application.
+        
        
 
-      
        
-        These are using the classic theme, which matches the old
-        look of Select2.
-      
        
+        
        
+          These are using the classic theme, which matches the old
+          look of Select2.
+        
        
 
-      
        
-        
-      
        
-    
-    
        
-      
        Example code
        
+        
        
+          
        
+            
+          
        
 
-      
        
+          
        
+            
+          
        
+        
        
+
+        
        
 
 
-    
        
-  
        
 
-  
        
-    
        
-      
        RTL support
        
+      
        
 
-      
        
-        Select2 will work on RTL websites if the dir attribute is
-        set on the <select> or any parents of it.
-      
        
+      
        
+        
        RTL support
        
 
-      
        
-        
-      
        
+        
        
+          Select2 will work on RTL websites if the dir attribute is
+          set on the <select> or any parents of it. You can also
+          initialize Select2 with dir: "rtl" set.
+        
        
 
-      
        
-        You can also use initialize Select2 with dir: "rtl" set.
-      
        
-    
-    
        
-      
        Example code
        
+        
        
+          
        
+            
+          
        
+        
        
 
-      
        
+        
        
 
 
+
+      
        
     
-  
+    
+  
 
 
 
-              
-              
-              
-              
-              
-              
-              
-              
-              
-              
-            
-          
        
-        
-
-        
        
-
-
-
-      
-
-      
        
-        
        Multiple languages
        
-
-        
        
-          Select2 supports displaying the messages in different languages, as well
-          as providing your own
-          custom messages
-          that can be displayed.
-        
        
-
-        
        
-          The language does not have to be defined when Select2 is being
-          initialized, but instead can be defined in the [lang]
-          attribute of any parent elements as [lang="es"].
-        
        
-
-        
        
-          
        
-            
-          
        
-        
        
-
-        
        
-
-
-
-      
        
-
       
        
         
        Theme support
        
 
@@ -822,6 +755,40 @@ $(".js-example-theme-multiple").select2({
       
        
 
       
        
+        
        
+          Localization, RTL and diacritics support
+        
        
+
+        
        Multiple languages
        
+
+        
        
+          Select2 supports displaying the messages in different languages, as well
+          as providing your own
+          custom messages
+          that can be displayed.
+        
        
+
+        
        
+          The language does not have to be defined when Select2 is being
+          initialized, but instead can be defined in the [lang]
+          attribute of any parent elements as [lang="es"].
+        
        
+
+        
        
+          
        
+            
+          
        
+        
        
+
+        
        
+
+
+
         
        RTL support
        
 
         
        
@@ -842,6 +809,37 @@ $(".js-example-theme-multiple").select2({
 $(".js-example-rtl").select2({
   dir: "rtl"
 });
+
+
+        
        Diacritics support
        
+
+        
        
+          Select2's default matcher will ignore diacritics, making it easier for
+          users to filter results in international selects. Type "aero" into the
+          select below.
+        
        
+
+        
        
+          
        
+            
+          
        
+        
        
+
+        
        
+
+
 
       
        

From a728044fa9b8eb5281ff9535bbb91932656b296b Mon Sep 17 00:00:00 2001
From: Florian Kissling 
Date: Mon, 4 May 2015 03:04:09 +0200
Subject: [PATCH 52/85] More grouping on the "Examples" page.

* "Loading array data" and "Loading remote data" now go together under "Other data sources",
* "Events" and "Programmatic access" under "Programmatic control",
* "Theme support", "Responsive design" and "Templating" under "Themes, templating and responsive design"
---
 docs/_includes/nav/examples.html |  54 ++--
 docs/examples.html               | 436 ++++++++++++++++---------------
 2 files changed, 266 insertions(+), 224 deletions(-)

diff --git a/docs/_includes/nav/examples.html b/docs/_includes/nav/examples.html
index c7bef5ad..5a1902ae 100644
--- a/docs/_includes/nav/examples.html
+++ b/docs/_includes/nav/examples.html
@@ -10,16 +10,17 @@
       Placeholders
     
     
      • 
-      Templating
-    
        • 
-    
      • 
-      Loading array data
-    
        • 
-    
      • 
-      Loading remote data
-    
        • 
-    
      • 
-      Responsive design
+      
+        Other data sources
+      
+      
     
        • 
     
      • 
       Disabled mode
@@ -27,9 +28,6 @@
     
      • 
       Disabled results
     
        • 
-    
      • 
-      Programmatic access
-    
        • 
     
      • 
       Limiting the number of selections
     
        • 
@@ -37,7 +35,15 @@
       Hiding the search box
     
     
      • 
-      Events
+      Programmatic control
+      
     
        • 
     
      • 
       Tagging support
@@ -48,9 +54,6 @@
     
      • 
       Custom matcher
     
        • 
-    
      • 
-      Theme support
-    
        • 
     
      • 
       Localization, RTL and diacritics support
       
+    
        • 
+    
      • 
+      
+        Themes, templating and responsive design
+      
+      
+    
        • 
   
   
     Back to top
diff --git a/docs/examples.html b/docs/examples.html
index aa51b0f8..a2bc91da 100644
--- a/docs/examples.html
+++ b/docs/examples.html
@@ -91,6 +91,7 @@ $(".js-example-basic-multiple").select2();
       
 
       
        
+
         
        Placeholders
        
 
         
        
@@ -125,49 +126,15 @@ $(".js-example-placeholder-multiple").select2({
   placeholder: "Select a state"
 });
 
+
       
        
 
       
        
-        
        Templating
        
 
-        
        
-          Various display options of the Select2 component can be changed:
-          You can access the <option> element
-          (or <optgroup>) and any attributes on those elements
-          using .element.
-        
        
+        
        
+          Other data sources
+        
        
 
-        
        
-          Templating is primarily controlled by the
-          templateResult
-          and templateSelection
-          options.
-        
        
-
-        
        
-          
        
-            
-          
        
-        
        
-
-        
        
-
-
-      
        
-
-      
        
         
        Loading array data
        
 
         
        
@@ -208,10 +175,8 @@ $(".js-example-data-array-selected").select2({
   
 
 
-      
        
 
-      
        
-        
        Loading remote data
        
+        
        Loading remote data
        
 
         
        
           Select2 comes with AJAX support built in, using jQuery's AJAX methods.
@@ -283,43 +248,11 @@ $(".js-data-example-ajax").select2({
   
 
 
+
       
        
 
       
        
-        
        Responsive design - Percent width
        
 
-        
        
-          Select2's width can be set to a percentage of its parent to support
-          responsive design. The two Select2 boxes below are styled to 50% and 75%
-          width respectively.
-        
        
-
-        
        
-          
        
-            
-          
        
-
-          
        
-            
-          
        
-        
        
-
-        
        
-
-        
        
-          Select2 will do its best to resolve the percent width specified via a
-          css class, but it is not always possible. The best way to ensure that
-          Select2 is using a percent based width is to inline the
-          style declaration into the tag.
-        
        
-
-
-      
        
-
-      
        
         
        Disabled mode
        
 
         
        
@@ -362,6 +295,7 @@ $(".js-programmatic-disable").on("click", function () {
   $(".js-example-disabled-multi").prop("disabled", true);
 });
 
+
       
        
 
       
        
@@ -395,78 +329,6 @@ $(".js-programmatic-disable").on("click", function () {
 
       
        
 
-      
        
-        
        Programmatic access
        
-
-        
        
-          Select2 supports methods that allow programmatic control of the
-          component.
-        
        
-
-        
        
-          
        
-            
-          
        
-
-          
-
-          
        
-            
-          
        
-
-          
        
-            
-            
-          
        
-
-        
        
-
-        
        
-
-
-
-      
        
-
       
        
 
         
        
@@ -497,6 +359,7 @@ $(".js-example-basic-multiple-limit").select2({
       
        
 
       
        
+
         
        Hiding the search box
        
 
         
        
@@ -522,7 +385,12 @@ $(".js-example-basic-hide-search").select2({
       
        
 
       
        
-        
        Events
        
+
+        
        
+          Programmatic control
+        
        
+
+        
        Events
        
 
         
        
           Select2 will trigger some events on the original select element,
@@ -601,9 +469,80 @@ function log (name, evt) {
   });
 }
 
+
+        
        Programmatic access
        
+
+        
        
+          Select2 supports methods that allow programmatic control of the
+          component.
+        
        
+
+        
        
+          
        
+            
+          
        
+
+          
+
+          
        
+            
+          
        
+
+          
        
+            
+            
+          
        
+
+        
        
+
+        
        
+
+
+
       
        
 
       
        
+
         
        Tagging support
        
 
         
        
@@ -637,6 +576,7 @@ $(".js-example-tags").select2({
       
        
 
       
        
+
         
        Automatic tokenization
        
 
         
        
@@ -673,6 +613,7 @@ $(".js-example-tokenizer").select2({
       
        
 
       
        
+
         
        Custom matcher
        
 
         
        
@@ -716,7 +657,108 @@ $.fn.select2.amd.require(['select2/compat/matcher'], function (oldMatcher) {
       
        
 
       
        
-        
        Theme support
        
+
+
+      
        
+
+      
        
+
+        
        
+          Localization, RTL and diacritics support
+        
        
+
+        
        Multiple languages
        
+
+        
        
+          Select2 supports displaying the messages in different languages, as well
+          as providing your own
+          custom messages
+          that can be displayed.
+        
        
+
+        
        
+          The language does not have to be defined when Select2 is being
+          initialized, but instead can be defined in the [lang]
+          attribute of any parent elements as [lang="es"].
+        
        
+
+        
        
+          
        
+            
+          
        
+        
        
+
+        
        
+
+
+
+        
        RTL support
        
+
+        
        
+          Select2 will work on RTL websites if the dir attribute is
+          set on the <select> or any parents of it. You can also
+          initialize Select2 with dir: "rtl" set.
+        
        
+
+        
        
+          
        
+            
+          
        
+        
        
+
+        
        
+
+
+
+        
        Diacritics support
        
+
+        
        
+          Select2's default matcher will ignore diacritics, making it easier for
+          users to filter results in international selects. Type "aero" into the
+          select below.
+        
        
+
+        
        
+          
        
+            
+          
        
+        
        
+
+        
        
+
+
+
+      
        
+
+      
        
+
+        
        
+          Themes, templating and responsive design
+        
        
+
+        
        Theme support
        
 
         
        
           Select2 supports custom themes using the
@@ -752,94 +794,74 @@ $(".js-example-theme-multiple").select2({
 });
 
 
-      
        
-
-      
        
-        
        
-          Localization, RTL and diacritics support
-        
        
-
-        
        Multiple languages
        
+        
        Templating
        
 
         
        
-          Select2 supports displaying the messages in different languages, as well
-          as providing your own
-          custom messages
-          that can be displayed.
+          Various display options of the Select2 component can be changed:
+          You can access the <option> element
+          (or <optgroup>) and any attributes on those elements
+          using .element.
         
        
 
         
        
-          The language does not have to be defined when Select2 is being
-          initialized, but instead can be defined in the [lang]
-          attribute of any parent elements as [lang="es"].
+          Templating is primarily controlled by the
+          templateResult
+          and templateSelection
+          options.
         
        
 
         
        
           
        
-            
+            
           
        
         
        
 
-        
        
+        
        
 
-
 
-        
        RTL support
        
+        
        Responsive design - Percent width
        
 
         
        
-          Select2 will work on RTL websites if the dir attribute is
-          set on the <select> or any parents of it. You can also
-          initialize Select2 with dir: "rtl" set.
+          Select2's width can be set to a percentage of its parent to support
+          responsive design. The two Select2 boxes below are styled to 50% and 75%
+          width respectively.
         
        
 
         
        
           
        
-            
+            
           
        
-        
        
 
-        
        
-
-
-
-        
        Diacritics support
        
-
-        
        
-          Select2's default matcher will ignore diacritics, making it easier for
-          users to filter results in international selects. Type "aero" into the
-          select below.
-        
        
-
-        
        
           
        
-            
+            
           
        
         
        
 
-        
        
+        
        
 
-
 
       
        

From f54993050ec1c1a9743ef12146ce533a911b2cb0 Mon Sep 17 00:00:00 2001
From: Florian Kissling 
Date: Mon, 4 May 2015 04:28:28 +0200
Subject: [PATCH 53/85] This h1 should be an h2.

---
 docs/examples.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/examples.html b/docs/examples.html
index a2bc91da..60fb565c 100644
--- a/docs/examples.html
+++ b/docs/examples.html
@@ -135,7 +135,7 @@ $(".js-example-placeholder-multiple").select2({
           Other data sources
         
 
-        
        Loading array data
        
+        
        Loading array data
        
 
         
        
           Select2 provides a way to load the data from a local array.

From b74a0ae6e0a3d32b61d5c1a5739125f9cd41d99e Mon Sep 17 00:00:00 2001
From: Florian Kissling 
Date: Wed, 6 May 2015 01:19:05 +0200
Subject: [PATCH 54/85] Move all examples to partials.

---
 docs/_includes/examples/basics.html           |  37 +
 docs/_includes/examples/data.html             | 120 +++
 docs/_includes/examples/disabled-mode.html    |  43 +
 docs/_includes/examples/disabled-results.html |  32 +
 docs/_includes/examples/hide-search.html      |  25 +
 .../examples/localization-rtl-diacritics.html |  90 ++
 docs/_includes/examples/matcher.html          |  43 +
 docs/_includes/examples/multiple-max.html     |  28 +
 docs/_includes/examples/multiple.html         |  27 +
 docs/_includes/examples/placeholders.html     |  37 +
 .../examples/programmatic-control.html        | 156 ++++
 docs/_includes/examples/tags.html             |  33 +
 .../themes-templating-responsive-design.html  | 111 +++
 docs/_includes/examples/tokenizer.html        |  36 +
 docs/examples.html                            | 851 +-----------------
 15 files changed, 834 insertions(+), 835 deletions(-)
 create mode 100644 docs/_includes/examples/basics.html
 create mode 100644 docs/_includes/examples/data.html
 create mode 100644 docs/_includes/examples/disabled-mode.html
 create mode 100644 docs/_includes/examples/disabled-results.html
 create mode 100644 docs/_includes/examples/hide-search.html
 create mode 100644 docs/_includes/examples/localization-rtl-diacritics.html
 create mode 100644 docs/_includes/examples/matcher.html
 create mode 100644 docs/_includes/examples/multiple-max.html
 create mode 100644 docs/_includes/examples/multiple.html
 create mode 100644 docs/_includes/examples/placeholders.html
 create mode 100644 docs/_includes/examples/programmatic-control.html
 create mode 100644 docs/_includes/examples/tags.html
 create mode 100644 docs/_includes/examples/themes-templating-responsive-design.html
 create mode 100644 docs/_includes/examples/tokenizer.html

diff --git a/docs/_includes/examples/basics.html b/docs/_includes/examples/basics.html
new file mode 100644
index 00000000..2481f64d
--- /dev/null
+++ b/docs/_includes/examples/basics.html
@@ -0,0 +1,37 @@
+
        
+
+  
        The basics
        
+
+  
        
+    Select2 can take a regular select box like this...
+  
        
+
+  
        
+    
+  
        
+
+  
        
+    and turn it into this...
+  
        
+
+  
        
+    
        
+      
+    
        
+  
        
+
+  
        
+
+
+
+
        
diff --git a/docs/_includes/examples/data.html b/docs/_includes/examples/data.html
new file mode 100644
index 00000000..d4c5a3e7
--- /dev/null
+++ b/docs/_includes/examples/data.html
@@ -0,0 +1,120 @@
+
        
+
+  
        
+    Other data sources
+  
        
+
+  
        Loading array data
        
+
+  
        
+    Select2 provides a way to load the data from a local array.
+    You can provide initial selections with array data by providing the
+    option tag for the selected values, similar to how it would be done for
+    a standard select.
+  
        
+
+  
        
+    
        
+      
+    
        
+    
        
+      
+    
        
+  
        
+
+  
        
+
+
+
+  
        Loading remote data
        
+
+  
        
+    Select2 comes with AJAX support built in, using jQuery's AJAX methods.
+    In this example, we can search for repositories using GitHub's API.
+  
        
+
+  
        
+    
+  
        
+
+  
        
+    When using Select2 with remote data, the HTML required for the
+    select is the same as any other Select2. If you need to
+    provide default selections, you just need to include an
+    option for each selection that contains the value and text
+    that should be displayed.
+  
        
+
+  
        
+
+  
        
+    You can configure how Select2 searches for remote data using the
+    ajax option. More information on the individual options
+    that Select2 handles can be found in the
+    options documentation for ajax.
+  
        
+
+  
        
+
+  
        
+    Select2 will pass any options in the ajax object to
+    jQuery's $.ajax function, or the transport
+    function you specify.
+  
        
+
+
+
+
+
+
        
diff --git a/docs/_includes/examples/disabled-mode.html b/docs/_includes/examples/disabled-mode.html
new file mode 100644
index 00000000..b90c1377
--- /dev/null
+++ b/docs/_includes/examples/disabled-mode.html
@@ -0,0 +1,43 @@
+
        
+
+  
        Disabled mode
        
+
+  
        
+    Select2 will response the disabled attribute on
+    <select> elements. You can also initialize Select2
+    with disabled: true to get the same effect.
+  
        
+
+  
        
+    
        
+      
+    
        
+
+    
        
+      
+    
        
+    
        
+      
+      
+    
        
+  
        
+
+  
        
+
+
+
+
        
diff --git a/docs/_includes/examples/disabled-results.html b/docs/_includes/examples/disabled-results.html
new file mode 100644
index 00000000..b93cf450
--- /dev/null
+++ b/docs/_includes/examples/disabled-results.html
@@ -0,0 +1,32 @@
+
        
+
+  
        Disabled results
        
+
+  
        
+    Select2 will correctly handled disabled results, both with data coming
+    from a standard select (when the disabled attribute is set)
+    and from remote sources, where the object has
+    disabled: true set.
+  
        
+
+  
        
+    
        
+      
+    
        
+  
        
+
+  
        
+
+
+
+
        
diff --git a/docs/_includes/examples/hide-search.html b/docs/_includes/examples/hide-search.html
new file mode 100644
index 00000000..8984bab3
--- /dev/null
+++ b/docs/_includes/examples/hide-search.html
@@ -0,0 +1,25 @@
+
        
+
+  
        Hiding the search box
        
+
+  
        
+    Select2 allows you to hide the search box depending on the number of
+    options which are displayed. In this example, we use the value
+    Infinity to tell Select2 to never display the search box.
+  
        
+
+  
        
+    
        
+      
+    
        
+  
        
+
+  
        
+
+
+
+
        
diff --git a/docs/_includes/examples/localization-rtl-diacritics.html b/docs/_includes/examples/localization-rtl-diacritics.html
new file mode 100644
index 00000000..8ced4b83
--- /dev/null
+++ b/docs/_includes/examples/localization-rtl-diacritics.html
@@ -0,0 +1,90 @@
+
        
+
+  
        
+    Localization, RTL and diacritics support
+  
        
+
+  
        Multiple languages
        
+
+  
        
+    Select2 supports displaying the messages in different languages, as well
+    as providing your own
+    custom messages
+    that can be displayed.
+  
        
+
+  
        
+    The language does not have to be defined when Select2 is being
+    initialized, but instead can be defined in the [lang]
+    attribute of any parent elements as [lang="es"].
+  
        
+
+  
        
+    
        
+      
+    
        
+  
        
+
+  
        
+
+
+
+  
        RTL support
        
+
+  
        
+    Select2 will work on RTL websites if the dir attribute is
+    set on the <select> or any parents of it. You can also
+    initialize Select2 with dir: "rtl" set.
+  
        
+
+  
        
+    
        
+      
+    
        
+  
        
+
+  
        
+
+
+
+  
        Diacritics support
        
+
+  
        
+    Select2's default matcher will ignore diacritics, making it easier for
+    users to filter results in international selects. Type "aero" into the
+    select below.
+  
        
+
+  
        
+    
        
+      
+    
        
+  
        
+
+  
        
+
+
+
+
        
diff --git a/docs/_includes/examples/matcher.html b/docs/_includes/examples/matcher.html
new file mode 100644
index 00000000..7832405b
--- /dev/null
+++ b/docs/_includes/examples/matcher.html
@@ -0,0 +1,43 @@
+
        
+
+  
        Custom matcher
        
+
+  
        
+    Unlike other dropdowns on this page, this one matches options only if
+    the term appears in the beginning of the string as opposed to anywhere:
+  
        
+
+  
        
+    This custom matcher uses a
+    compatibility module that is
+    only bundled in the
+    full version of Select2. You also
+    have the option of using a
+    more complex matcher.
+  
        
+
+  
        
+    
        
+      
+    
        
+  
        
+
+  
        
+
+
+
+
        
diff --git a/docs/_includes/examples/multiple-max.html b/docs/_includes/examples/multiple-max.html
new file mode 100644
index 00000000..a82c9f53
--- /dev/null
+++ b/docs/_includes/examples/multiple-max.html
@@ -0,0 +1,28 @@
+
        
+
+  
        
+    Limiting the number of selections
+  
        
+
+  
        
+    Select2 multi-value select boxes can set restrictions regarding the
+    maximum number of options selected. The select below is declared with
+    the multiple attribute with maxSelectionLength
+    in the select2 options.
+  
        
+
+  
        
+    
        
+      
+    
        
+  
        
+
+  
        
+
+
+
+
        
diff --git a/docs/_includes/examples/multiple.html b/docs/_includes/examples/multiple.html
new file mode 100644
index 00000000..e1c031bc
--- /dev/null
+++ b/docs/_includes/examples/multiple.html
@@ -0,0 +1,27 @@
+
        
+
+  
        Multiple select boxes
        
+
+  
        
+    Select2 also supports multi-value select boxes. The select below is declared with the multiple attribute.
+  
        
+
+  
        
+    
        
+      
+    
        
+  
        
+
+  
        
+
+
+
+
        
diff --git a/docs/_includes/examples/placeholders.html b/docs/_includes/examples/placeholders.html
new file mode 100644
index 00000000..992ddec2
--- /dev/null
+++ b/docs/_includes/examples/placeholders.html
@@ -0,0 +1,37 @@
+
        
+
+  
        Placeholders
        
+
+  
        
+    A placeholder value can be defined and will be displayed until a
+    selection is made. Select2 uses the placeholder attribute
+    on multiple select boxes, which requires IE 10+. You can support it in
+    older versions with
+    the Placeholders.js polyfill.
+  
        
+
+  
        
+    
        
+      
+    
        
+    
        
+      
+    
        
+  
        
+
+  
        
+
+
+
+
        
diff --git a/docs/_includes/examples/programmatic-control.html b/docs/_includes/examples/programmatic-control.html
new file mode 100644
index 00000000..d759e5a5
--- /dev/null
+++ b/docs/_includes/examples/programmatic-control.html
@@ -0,0 +1,156 @@
+
        
+
+  
        
+    Programmatic control
+  
        
+
+  
        Events
        
+
+  
        
+    Select2 will trigger some events on the original select element,
+    allowing you to integrate it with other components. You can find more
+    information on events
+    on the options page.
+  
        
+
+  
        
+    change is fired whenever an option is selected or removed.
+  
        
+
+  
        
+    select2:open is fired whenever the dropdown is opened.
+    select2:opening is fired before this and can be prevented.
+  
        
+
+  
        
+    select2:close is fired whenever the dropdown is closed.
+    select2:closing is fired before this and can be prevented.
+  
        
+
+  
        
+    select2:select is fired whenever a result is selected.
+    select2:selecting is fired before this and can be prevented.
+  
        
+
+  
        
+    select2:unselect is fired whenever a result is unselected.
+    select2:unselecting is fired before this and can be prevented.
+  
        
+
+  
        
+    
        
+      
+    
        
+    
        
+      
+    
        
+  
        
+
+  
        
+    
          
+  
          
+
+  
          
+
+
+
+  
          Programmatic access
          
+
+  
          
+    Select2 supports methods that allow programmatic control of the
+    component.
+  
          
+
+  
          
+
+    
          
+      
+    
          
+
+    
+
+    
          
+      
+    
          
+
+    
          
+      
+      
+    
          
+
+  
          
+
+  
          
+
+
+
+
          
diff --git a/docs/_includes/examples/tags.html b/docs/_includes/examples/tags.html
new file mode 100644
index 00000000..db36060b
--- /dev/null
+++ b/docs/_includes/examples/tags.html
@@ -0,0 +1,33 @@
+
          
+
+  
          Tagging support
          
+
+  
          
+    Select2 can be used to quickly set up fields used for tagging.
+  
          
+
+  
          
+    Note that when tagging is enabled the user can select from pre-existing
+    options or create a new tag by picking the first choice, which is what
+    the user has typed into the search box so far.
+  
          
+
+  
          
+    
          
+      
+    
          
+  
          
+
+  
          
+
+
+
+
          
diff --git a/docs/_includes/examples/themes-templating-responsive-design.html b/docs/_includes/examples/themes-templating-responsive-design.html
new file mode 100644
index 00000000..645d4ff1
--- /dev/null
+++ b/docs/_includes/examples/themes-templating-responsive-design.html
@@ -0,0 +1,111 @@
+
          
+
+  
          
+    Themes, templating and responsive design
+  
          
+
+  
          Theme support
          
+
+  
          
+    Select2 supports custom themes using the
+    theme option
+    so you can style Select2 to match the rest of your application.
+  
          
+
+  
          
+    These are using the classic theme, which matches the old
+    look of Select2.
+  
          
+
+  
          
+    
          
+      
+    
          
+    
          
+      
+    
          
+  
          
+
+  
          
+
+
+
+
          Templating
          
+
+
          
+  Various display options of the Select2 component can be changed:
+  You can access the <option> element
+  (or <optgroup>) and any attributes on those elements
+  using .element.
+
          
+
+
          
+  Templating is primarily controlled by the
+  templateResult
+  and templateSelection
+  options.
+
          
+
+
          
+  
          
+    
+  
          
+
          
+
+
          
+
+
+
+
          Responsive design - Percent width
          
+
+
          
+  Select2's width can be set to a percentage of its parent to support
+  responsive design. The two Select2 boxes below are styled to 50% and 75%
+  width respectively.
+
          
+
+
          
+  
          
+    
+  
          
+  
          
+    
+  
          
+
          
+
+
          
+
+
          
+  Select2 will do its best to resolve the percent width specified via a
+  css class, but it is not always possible. The best way to ensure that
+  Select2 is using a percent based width is to inline the
+  style declaration into the tag.
+
          
+
+
+
+
          
diff --git a/docs/_includes/examples/tokenizer.html b/docs/_includes/examples/tokenizer.html
new file mode 100644
index 00000000..f10b74e3
--- /dev/null
+++ b/docs/_includes/examples/tokenizer.html
@@ -0,0 +1,36 @@
+
          
+
+  
          Automatic tokenization
          
+
+  
          
+    Select2 supports ability to add choices automatically as the user is
+    typing into the search field. Try typing in the search field below and
+    entering a space or a comma.
+  
          
+
+  
          
+    The separators that should be used when tokenizing can be specified
+    using the tokenSeparators
+    options.
+  
          
+
+  
          
+    
          
+      
+    
          
+  
          
+
+  
          
+
+
+
+
          
diff --git a/docs/examples.html b/docs/examples.html
index 60fb565c..4aeadd45 100644
--- a/docs/examples.html
+++ b/docs/examples.html
@@ -28,846 +28,27 @@ slug: examples
 
          
   
          
     
          
-      
          
-        
          The basics
          
 
-        
          
-          Select2 can take a regular select box like this...
-        
          
+      {% include examples/basics.html %}
+      {% include examples/multiple.html %}
+      {% include examples/placeholders.html %}
+      {% include examples/data.html %}
+      {% include examples/disabled-mode.html %}
+      {% include examples/disabled-results.html %}
+      {% include examples/multiple-max.html %}
+      {% include examples/hide-search.html %}
+      {% include examples/programmatic-control.html %}
+      {% include examples/tags.html %}
+      {% include examples/tokenizer.html %}
+      {% include examples/matcher.html %}
+      {% include examples/localization-rtl-diacritics.html %}
+      {% include examples/themes-templating-responsive-design.html %}
 
-        
          
-          
-        
          
-
-        
          
-          and turn it into this...
-        
          
-
-        
          
-          
          
-            
-          
          
-        
          
-
-        
          
-
-
-      
          
-
-      
          
-        
          Multiple select boxes
          
-
-        
          
-          Select2 also supports multi-value select boxes. The select below is declared with the multiple attribute.
-        
          
-
-        
          
-          
          
-            
-          
          
-        
          
-
-        
          
-
-
-      
          
-
-      
          
-
-        
          Placeholders
          
-
-        
          
-          A placeholder value can be defined and will be displayed until a
-          selection is made. Select2 uses the placeholder attribute
-          on multiple select boxes, which requires IE 10+. You can support it in
-          older versions with
-          the Placeholders.js polyfill.
-        
          
-
-        
          
-          
          
-            
-          
          
-
-          
          
-            
-          
          
-        
          
-
-        
          
-
-
-
-      
          
-
-      
          
-
-        
          
-          Other data sources
-        
          
-
-        
          Loading array data
          
-
-        
          
-          Select2 provides a way to load the data from a local array.
-          You can provide initial selections with array data by providing the
-          option tag for the selected values, similar to how it would be done for
-          a standard select.
-        
          
-
-        
          
-          
          
-            
-          
          
-
-          
          
-            
-          
          
-        
          
-
-        
          
-
-
-
-        
          Loading remote data
          
-
-        
          
-          Select2 comes with AJAX support built in, using jQuery's AJAX methods.
-          In this example, we can search for repositories using GitHub's API.
-        
          
-
-        
          
-          
-        
          
-
-        
          
-          When using Select2 with remote data, the HTML required for the
-          select is the same as any other Select2. If you need to
-          provide default selections, you just need to include an
-          option for each selection that contains the value and text
-          that should be displayed.
-        
          
-
-        
          
-
-        
          
-          You can configure how Select2 searches for remote data using the
-          ajax option. More information on the individual options
-          that Select2 handles can be found in the
-          options documentation for ajax.
-        
          
-
-        
          
-
-        
          
-          Select2 will pass any options in the ajax object to
-          jQuery's $.ajax function, or the transport
-          function you specify.
-        
          
-
-
-
-
-
-      
          
-
-      
          
-
-        
          Disabled mode
          
-
-        
          
-          Select2 will response the disabled attribute on
-          <select> elements. You can also initialize Select2
-          with disabled: true to get the same effect.
-        
          
-
-        
          
-
-          
          
-            
-          
          
-
-          
          
-            
-          
          
-
-          
          
-            
-            
-          
          
-
-        
          
-
-        
          
-
-
-
-      
          
-
-      
          
-        
          Disabled results
          
-
-        
          
-          Select2 will correctly handled disabled results, both with data coming
-          from a standard select (when the disabled attribute is set)
-          and from remote sources, where the object has
-          disabled: true set.
-        
          
-
-        
          
-          
          
-            
-          
          
-        
          
-
-        
          
-
-
-      
          
-
-      
          
-
-        
          
-          Limiting the number of selections
-        
          
-
-        
          
-          Select2 multi-value select boxes can set restrictions regarding the
-          maximum number of options selected. The select below is declared with
-          the multiple attribute with maxSelectionLength
-          in the select2 options.
-        
          
-
-        
          
-          
          
-            
-          
          
-        
          
-
-        
          
-
-
-
-      
          
-
-      
          
-
-        
          Hiding the search box
          
-
-        
          
-          Select2 allows you to hide the search box depending on the number of
-          options which are displayed. In this example, we use the value
-          Infinity to tell Select2 to never display the search box.
-        
          
-
-        
          
-          
          
-            
-          
          
-        
          
-
-        
          
-
-
-
-      
          
-
-      
          
-
-        
          
-          Programmatic control
-        
          
-
-        
          Events
          
-
-        
          
-          Select2 will trigger some events on the original select element,
-          allowing you to integrate it with other components. You can find more
-          information on events
-          on the options page.
-        
          
-
-        
          
-          change is fired whenever an option is selected or removed.
-        
          
-
-        
          
-          select2:open is fired whenever the dropdown is opened.
-          select2:opening is fired before this and can be prevented.
-        
          
-
-        
          
-          select2:close is fired whenever the dropdown is closed.
-          select2:closing is fired before this and can be prevented.
-        
          
-
-        
          
-          select2:select is fired whenever a result is selected.
-          select2:selecting is fired before this and can be prevented.
-        
          
-
-        
          
-          select2:unselect is fired whenever a result is unselected.
-          select2:unselecting is fired before this and can be prevented.
-        
          
-
-        
          
-          
          
-            
-          
          
-
-          
          
-            
-          
          
-        
          
-
-        
          
-          
            
-        
            
-
-        
            
-
-
-
-        
            Programmatic access
            
-
-        
            
-          Select2 supports methods that allow programmatic control of the
-          component.
-        
            
-
-        
            
-          
            
-            
-          
            
-
-          
-
-          
            
-            
-          
            
-
-          
            
-            
-            
-          
            
-
-        
            
-
-        
            
-
-
-
-      
            
-
-      
            
-
-        
            Tagging support
            
-
-        
            
-          Select2 can be used to quickly set up fields used for tagging.
-        
            
-
-        
            
-          Note that when tagging is enabled the user can select from pre-existing
-          options or create a new tag by picking the first choice, which is what
-          the user has typed into the search box so far.
-        
            
-
-        
            
-          
            
-            
-          
            
-        
            
-
-        
            
-
-
-
-      
            
-
-      
            
-
-        
            Automatic tokenization
            
-
-        
            
-          Select2 supports ability to add choices automatically as the user is
-          typing into the search field. Try typing in the search field below and
-          entering a space or a comma.
-        
            
-
-        
            
-          The separators that should be used when tokenizing can be specified
-          using the tokenSeparators
-          options.
-        
            
-
-        
            
-          
            
-            
-          
            
-        
            
-
-        
            
-
-
-
-      
            
-
-      
            
-
-        
            Custom matcher
            
-
-        
            
-          Unlike other dropdowns on this page, this one matches options only if
-          the term appears in the beginning of the string as opposed to anywhere:
-        
            
-
-        
            
-          This custom matcher uses a
-          compatibility module that is
-          only bundled in the
-          full version of Select2. You also
-          have the option of using a
-          more complex matcher.
-        
            
-
-        
            
-          
            
-            
-          
            
-        
            
-
-        
            
-
-
-
-      
            
-
-      
            
-
-
-      
            
-
-      
            
-
-        
            
-          Localization, RTL and diacritics support
-        
            
-
-        
            Multiple languages
            
-
-        
            
-          Select2 supports displaying the messages in different languages, as well
-          as providing your own
-          custom messages
-          that can be displayed.
-        
            
-
-        
            
-          The language does not have to be defined when Select2 is being
-          initialized, but instead can be defined in the [lang]
-          attribute of any parent elements as [lang="es"].
-        
            
-
-        
            
-          
            
-            
-          
            
-        
            
-
-        
            
-
-
-
-        
            RTL support
            
-
-        
            
-          Select2 will work on RTL websites if the dir attribute is
-          set on the <select> or any parents of it. You can also
-          initialize Select2 with dir: "rtl" set.
-        
            
-
-        
            
-          
            
-            
-          
            
-        
            
-
-        
            
-
-
-
-        
            Diacritics support
            
-
-        
            
-          Select2's default matcher will ignore diacritics, making it easier for
-          users to filter results in international selects. Type "aero" into the
-          select below.
-        
            
-
-        
            
-          
            
-            
-          
            
-        
            
-
-        
            
-
-
-
-      
            
-
-      
            
-
-        
            
-          Themes, templating and responsive design
-        
            
-
-        
            Theme support
            
-
-        
            
-          Select2 supports custom themes using the
-          theme option
-          so you can style Select2 to match the rest of your application.
-        
            
-
-        
            
-          These are using the classic theme, which matches the old
-          look of Select2.
-        
            
-
-        
            
-          
            
-            
-          
            
-
-          
            
-            
-          
            
-        
            
-
-        
            
-
-
-
-        
            Templating
            
-
-        
            
-          Various display options of the Select2 component can be changed:
-          You can access the <option> element
-          (or <optgroup>) and any attributes on those elements
-          using .element.
-        
            
-
-        
            
-          Templating is primarily controlled by the
-          templateResult
-          and templateSelection
-          options.
-        
            
-
-        
            
-          
            
-            
-          
            
-        
            
-
-        
            
-
-
-
-        
            Responsive design - Percent width
            
-
-        
            
-          Select2's width can be set to a percentage of its parent to support
-          responsive design. The two Select2 boxes below are styled to 50% and 75%
-          width respectively.
-        
            
-
-        
            
-          
            
-            
-          
            
-
-          
            
-            
-          
            
-        
            
-
-        
            
-
-        
            
-          Select2 will do its best to resolve the percent width specified via a
-          css class, but it is not always possible. The best way to ensure that
-          Select2 is using a percent based width is to inline the
-          style declaration into the tag.
-        
            
-
-
-
-      
            
     
            
     
   
            
 
            

From f822cd904b64d69f006ec0424985defe060488cf Mon Sep 17 00:00:00 2001
From: Florian Kissling 
Date: Wed, 6 May 2015 01:47:44 +0200
Subject: [PATCH 55/85] Convert "Options" page contents to partials.

---
 docs/_includes/options/adapters.html          |  209 +++
 .../options/backwards-compatibility.html      |  201 +++
 docs/_includes/options/core-options.html      |  790 ++++++++
 docs/_includes/options/dropdown.html          |  308 ++++
 docs/_includes/options/events.html            |   50 +
 .../options/settings-default-options.html     |   39 +
 docs/options.html                             | 1608 +----------------
 7 files changed, 1605 insertions(+), 1600 deletions(-)
 create mode 100644 docs/_includes/options/adapters.html
 create mode 100644 docs/_includes/options/backwards-compatibility.html
 create mode 100644 docs/_includes/options/core-options.html
 create mode 100644 docs/_includes/options/dropdown.html
 create mode 100644 docs/_includes/options/events.html
 create mode 100644 docs/_includes/options/settings-default-options.html

diff --git a/docs/_includes/options/adapters.html b/docs/_includes/options/adapters.html
new file mode 100644
index 00000000..78bf72ae
--- /dev/null
+++ b/docs/_includes/options/adapters.html
@@ -0,0 +1,209 @@
+    
            
+      
            
+        
            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.
+      
            
+
+      
            
+        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 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
+// should be returned, which will automatically be placed by Select2 within the
+// DOM.
+//
+// @returns A jQuery or DOM element that contains any elements that must be
+//   rendered by Select2.
+Adapter.render = function () {
+  return $jq;
+};
+
+// Bind to any Select2 or DOM events.
+//
+// @param container The Select2 object that is bound to the jQuery element.  You
+//   can listen to Select2 events with `on` and trigger Select2 events using the
+//   `trigger` method.
+// @param $container The jQuery DOM node that all default adapters will be
+//   rendered within.
+Adapter.bind = function (container, $container) { };
+
+// Position the DOM element within the Select2 DOM container, or in another
+// place. This allows adapters to be located outside of the Select2 DOM,
+// such as at the end of the document or in a specific place within the Select2
+// DOM node.
+//
+// Note: This method is not called on data adapters.
+//
+// @param $rendered The rendered DOM element that was returned from the call to
+//   `render`. This may have been modified by Select2, but the root element
+//   will always be the same.
+// @param $defaultContainer The default container that Select2 will typically
+//   place the rendered DOM element within. For most adapters, this is the
+//   Select2 DOM element.
+Adapter.position = function ($rendered, $defaultContainer) { };
+
+// Destroy any events or DOM elements that have been created.
+// This is called when `select2("destroy")` is called on an element.
+Adapter.destroy = function () { };
+
            
+
+      
            
+        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.
+      
            
+
+      
            
+        
            Key
            
+        
            
+          selectionAdapter
+        
            
+
+        
            Default
            
+        
            
+          SingleSelection or
+          MultipleSelection
+        
            
+
+        
            Base
            
+        
            
+          BaseSelection
+        
            
+      
            
+
+
            +// Update the selected data.
+//
+// @param data An array of data objects that have been generated by the data
+//   adapter. If no objects should be selected, an empty array will be passed.
+//
+// Note: An array will always be passed into this method, even if Select2 is
+// attached to a source which only accepts a single selection.
+SelectionAdapter.update = function (data) { };
+
            
+
+      
            
+        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.
+      
            
+
+      
            
+        
            Key
            
+        
            
+          dataAdapter
+        
            
+
+        
            Default
            
+        
            
+          SelectAdapter
+        
            
+
+        
            Base
            
+        
            
+          BaseAdapter
+        
            
+      
            
+
+
            +// Get the currently selected options. This is called when trying to get the
+// initial selection for Select2, as well as when Select2 needs to determine
+// what options within the results are selected.
+//
+// @param callback A function that should be called when the current selection
+//   has been retrieved. The first parameter to the function should be an array
+//   of data objects.
+DataAdapter.current = function (callback) {
+  callback(currentData);
+}
+
+// Get a set of options that are filtered based on the parameters that have
+// been passed on in.
+//
+// @param params An object containing any number of parameters that the query
+//   could be affected by. Only the core parameters will be documented.
+// @param params.term A user-supplied term. This is typically the value of the
+//   search box, if one exists, but can also be an empty string or null value.
+// @param params.page The specific page that should be loaded. This is typically
+//   provided when working with remote data sets, which rely on pagination to
+//   determine what objects should be displayed.
+// @param callback The function that should be called with the queried results.
+DataAdapter.query = function (params, callback) {
+  callback(queryiedData);
+}
+
            
+
+      
+
+      
            
+        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
+        
            
+
+        
            Default
            
+        
            
+          DropdownAdapter
+        
            
+      
            
+
+      
            
+        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.
+      
            
+
+      
            
+        
            Key
            
+        
            
+          resultsAdapter
+        
            
+
+        
            Default
            
+        
            
+          ResultsAdapter
+        
            
+      
            
+    
            
diff --git a/docs/_includes/options/backwards-compatibility.html b/docs/_includes/options/backwards-compatibility.html
new file mode 100644
index 00000000..fd5a0eb3
--- /dev/null
+++ b/docs/_includes/options/backwards-compatibility.html
@@ -0,0 +1,201 @@
+    
            
+      
            
+        
            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.
+      
            
+
+      
            
+        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
+      
            
+
+      
            
+        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.
+      
            
+
+      
            
+        
            
+          
            
+            
            Key
            
+            
            
+              matcher
+            
            
+
+            
            Value
            
+            
            
+              A function taking a search term and the data object
+              text.
+            
            
+          
            
+        
            
+
+        
            
+          
            
+            
            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.
+      
            
+
+      
            
+        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.
+      
            
+
+      
            
+        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
+            
            
+
+            
            Value
            
+            
            
+              A function taking a callback
+            
            
+          
            
+        
            
+
+        
            
+          
            
+            
            Adapter
            
+            
            
+              DataAdapter
+            
            
+
+            
            Decorator
            
+            
            
+              InitSelection
+            
            
+          
            
+        
            
+      
            
+
+      
            
+        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.
+      
            
+
+      
            
+        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
+            
            
+
+            
            Value
            
+            
            
+              A function taking params (including a callback)
+            
            
+          
            
+        
            
+
+        
            
+          
            
+            
            Adapter
            
+            
            
+              DataAdapter
+            
            
+
+            
            Decorator
            
+            
            
+              Query
+            
            
+          
            
+        
            
+      
            
+    
            
+
+    
            
+      Compatibility with <input type="text" />
+    
            
+
+    
            
+      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.
+    
            
+
+    
            
+      
            Adapter
            
+      
            
+        DataAdapter
+      
            
+
+      
            Decorator
            
+      
            
+        InputData
+      
            
+    
            
+  
diff --git a/docs/_includes/options/core-options.html b/docs/_includes/options/core-options.html
new file mode 100644
index 00000000..06471521
--- /dev/null
+++ b/docs/_includes/options/core-options.html
@@ -0,0 +1,790 @@
+    
            
+      
            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 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(
+    ["select2/utils", "select2/selection/single", "select2/selection/placeholder"],
+    function (Utils, SingleSelection, Placeholder) {
+  var CustomSelectionAdapter = Utils.Decorate(SingleSelection, Placeholder);
+});
+
            
+
+      
            
+        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
+      
            
+
+      
            
+        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...
+      
            
+
+
            +<select data-tags="true" data-placeholder="Select an option"></select>
+
            
+
+      
            
+        Will be interpreted the same as initializing Select2 as...
+      
            
+
+
            +$("select").select2({
+  tags: "true",
+  placeholder: "Select an option"
+});
+
            
+
+      
            
+        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...
+      
            
+
+
            +$("select").select2({
+  ajax: {
+    url: "http://example.org/api/test",
+    cache: "true"
+  }
+});
+
            
+
+      
            
+        The value of the option is subject to jQuery's
+        parsing rules for
+        HTML5 data attributes.
+      
            
+
+      
            
+        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.
+      
            
+
+      
            
+        
            
+          
            
+            
            Key
            
+            
            
+              amdBase
+            
            
+
+            
            Default
            
+            
            
+              select2/
+            
            
+          
            
+        
            
+        
            
+          
            
+            
            Key
            
+            
            
+              amdLanguageBase
+            
            
+
+            
            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.
+          
            
+        
            
+      
            
+
+      
            
+        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"
+
            
+
+      
            
+        If the value is an object, the object should be
+        compatible with Select2's internal objects. The id should
+        be the id to look for when determining if the placeholder should be
+        displayed. The text should be the placeholder to display
+        when that option is selected.
+      
            
+
+
            +placeholder: {
+  id: "-1",
+  text: "Select a repository"
+}
+
            
+
+      
            
+        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.
+      
            
+
+      
            
+        
            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
            
+          
            
+
+          
            
+
+          
            
+            
            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.
+      
            
+
+
            +language: {
+  // You can find all of the options in the language files provided in the
+  // build. They all must be functions that return the string that should be
+  // displayed.
+  inputTooShort: function () {
+    return "You must enter more characters...";
+  }
+}
+
            
+
+      
            
+        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.
+      
            
+
+      
            
+        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.
+      
            
+
+      
            
+        
            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
            
+            
            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.
+
+
            +ajax: {
+  // The number of milliseconds to wait for the user to stop typing before
+  // issuing the ajax request.
+  delay: 250,
+  // You can craft a custom url based on the parameters that are passed into the
+  // request. This is useful if you are using a framework which has
+  // JavaScript-based functions for generating the urls to make requests to.
+  //
+  // @param params The object containing the parameters used to generate the
+  //   request.
+  // @returns The url that the request should be made to.
+  url: function (params) {
+    return UrlGenerator.Random();
+  },
+  // You can pass custom data into the request based on the parameters used to
+  // make the request. For `GET` requests, the default method, these are the
+  // query parameters that are appended to the url. For `POST` requests, this
+  // is the form data that will be passed into the request. For other requests,
+  // the data returned from here should be customized based on what jQuery and
+  // your server are expecting.
+  //
+  // @param params The object containing the parameters used to generate the
+  //   request.
+  // @returns Data to be directly passed into the request.
+  data: function (params) {
+    var queryParameters = {
+      q: params.term
+    }
+
+    return queryParameters;
+  },
+  // You can modify the results that are returned from the server, allowing you
+  // to make last-minute changes to the data, or find the correct part of the
+  // response to pass to Select2. Keep in mind that results should be passed as
+  // an array of objects.
+  //
+  // @param data The data as it is returned directly by jQuery.
+  // @returns An object containing the results data as well as any required
+  //   metadata that is used by plugins. The object should contain an array of
+  //   data objects as the `results` key.
+  processResults: function (data) {
+    return {
+      results: data
+    };
+  },
+  // You can use a custom AJAX transport function if you do not want to use the
+  // default one provided by jQuery.
+  //
+  // @param params The object containing the parameters used to generate the
+  //   request.
+  // @param success A callback function that takes `data`, the results from the
+  //   request.
+  // @param failure A callback function that indicates that the request could
+  //   not be completed.
+  // @returns An object that has an `abort` function that can be called to abort
+  //   the request if needed.
+  transport: function (params, success, failure) {
+    var $request = $.ajax(params);
+
+    $request.then(success);
+    $request.fail(failure);
+
+    return $request;
+  }
+}
+
            
+      
            
+
+      
            
+        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.
+      
            
+
+      
            
+        
            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) {
+  // If there are no search terms, return all of the data
+  if ($.trim(params.term) === '') {
+    return data;
+  }
+
+  // `params.term` should be the term that is used for searching
+  // `data.text` is the text that is displayed for the data object
+  if (data.text.indexOf(params.term) > -1) {
+    var modifiedData = $.extend({}, data, true);
+    modifiedData.text += ' (matched)';
+
+    // You can return modified objects from here
+    // This includes matching the `children` how you want in nested data sets
+    return modifiedData;
+  }
+
+  // Return `null` if the term should not be displayed
+  return null;
+}
+
            
+
+      
            
+        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
new file mode 100644
index 00000000..bd6e5efa
--- /dev/null
+++ b/docs/_includes/options/dropdown.html
@@ -0,0 +1,308 @@
+    
diff --git a/docs/_includes/options/events.html b/docs/_includes/options/events.html
new file mode 100644
index 00000000..453f6682
--- /dev/null
+++ b/docs/_includes/options/events.html
@@ -0,0 +1,50 @@
+    
            
+      
            
+        
            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.
+      
            
+
+      
            
+        
            Adapter
            
+        
            
+          SelectionAdapter
+        
            
+
+        
            Decorator
            
+        
            
+          EventRelay
+        
            
+      
            
+
+      
            
+        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.
+      
            
+
+      
            
+        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.
+      
            
+
+      
            
+        You can find more information on the public events triggered by individual
+        adapters in the individual adapter documentation.
+      
            
+    
            
diff --git a/docs/_includes/options/settings-default-options.html b/docs/_includes/options/settings-default-options.html
new file mode 100644
index 00000000..61126ada
--- /dev/null
+++ b/docs/_includes/options/settings-default-options.html
@@ -0,0 +1,39 @@
+
            
+  
            
+    
            Setting default options
            
+  
            
+
+  
            
+    In some cases, you need to set the default options for all instances of
+    Select2 in your web application. This is especially useful when you are
+    migrating from past versions of Select2, or you are using non-standard
+    options like custom AMD builds. Select2 exposes the
+    default options through $.fn.select2.defaults, which allows
+    you to set them globally.
+  
            
+
+  
            
+    When setting options globally, any past defaults that have been set will
+    be overriden. Default options are only used when an option is requested
+    that has not been set during initialization.
+  
            
+
+  
            
+    You can set default options by calling
+    $.fn.select2.defaults.set("key", "value"). The key that is
+    set should take the same format as keys set using
+    HTML data-* attributes which
+    means that two dashes (--) will be replaced by a level of
+    nesting, and a single dash (-) will convert it to a camelCase
+    string.
+  
            
+
+
            +$.fn.select2.defaults.set("theme", "classic");
+
            
+
+  
            
+    You can reset the default options by calling
+    $.fn.select2.defaults.reset().
+  
            
+
            
diff --git a/docs/options.html b/docs/options.html
index 914b493b..965fe846 100644
--- a/docs/options.html
+++ b/docs/options.html
@@ -18,1611 +18,19 @@ slug: 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.
-      
            
+    {% include options/core-options.html %}
+    {% include options/dropdown.html %}
+    {% include options/events.html %}
+    {% include options/adapters.html %}
+    {% include options/setting-default-options.html %}
+    {% include options/backwards-compatibility.html %}
 
-      
            
-        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(
-    ["select2/utils", "select2/selection/single", "select2/selection/placeholder"],
-    function (Utils, SingleSelection, Placeholder) {
-  var CustomSelectionAdapter = Utils.Decorate(SingleSelection, Placeholder);
-});
-
            
-
-      
            
-        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
-      
            
-
-      
            
-        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...
-      
            
-
-
            -<select data-tags="true" data-placeholder="Select an option"></select>
-
            
-
-      
            
-        Will be interpreted the same as initializing Select2 as...
-      
            
-
-
            -$("select").select2({
-  tags: "true",
-  placeholder: "Select an option"
-});
-
            
-
-      
            
-        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...
-      
            
-
-
            -$("select").select2({
-  ajax: {
-    url: "http://example.org/api/test",
-    cache: "true"
-  }
-});
-
            
-
-      
            
-        The value of the option is subject to jQuery's
-        parsing rules for
-        HTML5 data attributes.
-      
            
-
-      
            
-        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.
-      
            
-
-      
            
-        
            
-          
            
-            
            Key
            
-            
            
-              amdBase
-            
            
-
-            
            Default
            
-            
            
-              select2/
-            
            
-          
            
-        
            
-        
            
-          
            
-            
            Key
            
-            
            
-              amdLanguageBase
-            
            
-
-            
            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.
-          
            
-        
            
-      
            
-
-      
            
-        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"
-
            
-
-      
            
-        If the value is an object, the object should be
-        compatible with Select2's internal objects. The id should
-        be the id to look for when determining if the placeholder should be
-        displayed. The text should be the placeholder to display
-        when that option is selected.
-      
            
-
-
            -placeholder: {
-  id: "-1",
-  text: "Select a repository"
-}
-
            
-
-      
            
-        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.
-      
            
-
-      
            
-        
            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
            
-          
            
-
-          
            
-
-          
            
-            
            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.
-      
            
-
-
            -language: {
-  // You can find all of the options in the language files provided in the
-  // build. They all must be functions that return the string that should be
-  // displayed.
-  inputTooShort: function () {
-    return "You must enter more characters...";
-  }
-}
-
            
-
-      
            
-        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.
-      
            
-
-      
            
-        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.
-      
            
-
-      
            
-        
            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
            
-            
            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.
-
-
            -ajax: {
-  // The number of milliseconds to wait for the user to stop typing before
-  // issuing the ajax request.
-  delay: 250,
-  // You can craft a custom url based on the parameters that are passed into the
-  // request. This is useful if you are using a framework which has
-  // JavaScript-based functions for generating the urls to make requests to.
-  //
-  // @param params The object containing the parameters used to generate the
-  //   request.
-  // @returns The url that the request should be made to.
-  url: function (params) {
-    return UrlGenerator.Random();
-  },
-  // You can pass custom data into the request based on the parameters used to
-  // make the request. For `GET` requests, the default method, these are the
-  // query parameters that are appended to the url. For `POST` requests, this
-  // is the form data that will be passed into the request. For other requests,
-  // the data returned from here should be customized based on what jQuery and
-  // your server are expecting.
-  //
-  // @param params The object containing the parameters used to generate the
-  //   request.
-  // @returns Data to be directly passed into the request.
-  data: function (params) {
-    var queryParameters = {
-      q: params.term
-    }
-
-    return queryParameters;
-  },
-  // You can modify the results that are returned from the server, allowing you
-  // to make last-minute changes to the data, or find the correct part of the
-  // response to pass to Select2. Keep in mind that results should be passed as
-  // an array of objects.
-  //
-  // @param data The data as it is returned directly by jQuery.
-  // @returns An object containing the results data as well as any required
-  //   metadata that is used by plugins. The object should contain an array of
-  //   data objects as the `results` key.
-  processResults: function (data) {
-    return {
-      results: data
-    };
-  },
-  // You can use a custom AJAX transport function if you do not want to use the
-  // default one provided by jQuery.
-  //
-  // @param params The object containing the parameters used to generate the
-  //   request.
-  // @param success A callback function that takes `data`, the results from the
-  //   request.
-  // @param failure A callback function that indicates that the request could
-  //   not be completed.
-  // @returns An object that has an `abort` function that can be called to abort
-  //   the request if needed.
-  transport: function (params, success, failure) {
-    var $request = $.ajax(params);
-
-    $request.then(success);
-    $request.fail(failure);
-
-    return $request;
-  }
-}
-
            
-      
            
-
-      
            
-        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.
-      
            
-
-      
            
-        
            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) {
-  // If there are no search terms, return all of the data
-  if ($.trim(params.term) === '') {
-    return data;
-  }
-
-  // `params.term` should be the term that is used for searching
-  // `data.text` is the text that is displayed for the data object
-  if (data.text.indexOf(params.term) > -1) {
-    var modifiedData = $.extend({}, data, true);
-    modifiedData.text += ' (matched)';
-
-    // You can return modified objects from here
-    // This includes matching the `children` how you want in nested data sets
-    return modifiedData;
-  }
-
-  // Return `null` if the term should not be displayed
-  return null;
-}
-
            
-
-      
            
-        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.
-      
            
-    
            
-
-    
-
-    
            
-      
            
-        
            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.
-      
            
-
-      
            
-        
            Adapter
            
-        
            
-          SelectionAdapter
-        
            
-
-        
            Decorator
            
-        
            
-          EventRelay
-        
            
-      
            
-
-      
            
-        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.
-      
            
-
-      
            
-        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.
-      
            
-
-      
            
-        You can find more information on the public events triggered by individual
-        adapters in the individual adapter documentation.
-      
            
-    
            
-
-    
            
-      
            
-        
            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.
-      
            
-
-      
            
-        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 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
-// should be returned, which will automatically be placed by Select2 within the
-// DOM.
-//
-// @returns A jQuery or DOM element that contains any elements that must be
-//   rendered by Select2.
-Adapter.render = function () {
-  return $jq;
-};
-
-// Bind to any Select2 or DOM events.
-//
-// @param container The Select2 object that is bound to the jQuery element.  You
-//   can listen to Select2 events with `on` and trigger Select2 events using the
-//   `trigger` method.
-// @param $container The jQuery DOM node that all default adapters will be
-//   rendered within.
-Adapter.bind = function (container, $container) { };
-
-// Position the DOM element within the Select2 DOM container, or in another
-// place. This allows adapters to be located outside of the Select2 DOM,
-// such as at the end of the document or in a specific place within the Select2
-// DOM node.
-//
-// Note: This method is not called on data adapters.
-//
-// @param $rendered The rendered DOM element that was returned from the call to
-//   `render`. This may have been modified by Select2, but the root element
-//   will always be the same.
-// @param $defaultContainer The default container that Select2 will typically
-//   place the rendered DOM element within. For most adapters, this is the
-//   Select2 DOM element.
-Adapter.position = function ($rendered, $defaultContainer) { };
-
-// Destroy any events or DOM elements that have been created.
-// This is called when `select2("destroy")` is called on an element.
-Adapter.destroy = function () { };
-
            
-
-      
            
-        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.
-      
            
-
-      
            
-        
            Key
            
-        
            
-          selectionAdapter
-        
            
-
-        
            Default
            
-        
            
-          SingleSelection or
-          MultipleSelection
-        
            
-
-        
            Base
            
-        
            
-          BaseSelection
-        
            
-      
            
-
-
            -// Update the selected data.
-//
-// @param data An array of data objects that have been generated by the data
-//   adapter. If no objects should be selected, an empty array will be passed.
-//
-// Note: An array will always be passed into this method, even if Select2 is
-// attached to a source which only accepts a single selection.
-SelectionAdapter.update = function (data) { };
-
            
-
-      
            
-        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.
-      
            
-
-      
            
-        
            Key
            
-        
            
-          dataAdapter
-        
            
-
-        
            Default
            
-        
            
-          SelectAdapter
-        
            
-
-        
            Base
            
-        
            
-          BaseAdapter
-        
            
-      
            
-
-
            -// Get the currently selected options. This is called when trying to get the
-// initial selection for Select2, as well as when Select2 needs to determine
-// what options within the results are selected.
-//
-// @param callback A function that should be called when the current selection
-//   has been retrieved. The first parameter to the function should be an array
-//   of data objects.
-DataAdapter.current = function (callback) {
-  callback(currentData);
-}
-
-// Get a set of options that are filtered based on the parameters that have
-// been passed on in.
-//
-// @param params An object containing any number of parameters that the query
-//   could be affected by. Only the core parameters will be documented.
-// @param params.term A user-supplied term. This is typically the value of the
-//   search box, if one exists, but can also be an empty string or null value.
-// @param params.page The specific page that should be loaded. This is typically
-//   provided when working with remote data sets, which rely on pagination to
-//   determine what objects should be displayed.
-// @param callback The function that should be called with the queried results.
-DataAdapter.query = function (params, callback) {
-  callback(queryiedData);
-}
-
            
-
-      
-
-      
            
-        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
-        
            
-
-        
            Default
            
-        
            
-          DropdownAdapter
-        
            
-      
            
-
-      
            
-        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.
-      
            
-
-      
            
-        
            Key
            
-        
            
-          resultsAdapter
-        
            
-
-        
            Default
            
-        
            
-          ResultsAdapter
-        
            
-      
            
-    
            
-
-    
            
-      
            
-        
            Setting default options
            
-      
            
-
-      
            
-        In some cases, you need to set the default options for all instances of
-        Select2 in your web application. This is especially useful when you are
-        migrating from past versions of Select2, or you are using non-standard
-        options like custom AMD builds. Select2 exposes the
-        default options through $.fn.select2.defaults, which allows
-        you to set them globally.
-      
            
-
-      
            
-        When setting options globally, any past defaults that have been set will
-        be overriden. Default options are only used when an option is requested
-        that has not been set during initialization.
-      
            
-
-      
            
-        You can set default options by calling
-        $.fn.select2.defaults.set("key", "value"). The key that is
-        set should take the same format as keys set using
-        HTML data-* attributes which
-        means that two dashes (--) will be replaced by a level of
-        nesting, and a single dash (-) will convert it to a camelCase
-        string.
-      
            
-
-
            -$.fn.select2.defaults.set("theme", "classic");
-
            
-
-      
            
-        You can reset the default options by calling
-        $.fn.select2.defaults.reset().
-      
            
-    
            
-
-    
            
-      
            
-        
            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.
-      
            
-
-      
            
-        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
-      
            
-
-      
            
-        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.
-      
            
-
-      
            
-        
            
-          
            
-            
            Key
            
-            
            
-              matcher
-            
            
-
-            
            Value
            
-            
            
-              A function taking a search term and the data object
-              text.
-            
            
-          
            
-        
            
-
-        
            
-          
            
-            
            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.
-      
            
-
-      
            
-        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.
-      
            
-
-      
            
-        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
-            
            
-
-            
            Value
            
-            
            
-              A function taking a callback
-            
            
-          
            
-        
            
-
-        
            
-          
            
-            
            Adapter
            
-            
            
-              DataAdapter
-            
            
-
-            
            Decorator
            
-            
            
-              InitSelection
-            
            
-          
            
-        
            
-      
            
-
-      
            
-        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.
-      
            
-
-      
            
-        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
-            
            
-
-            
            Value
            
-            
            
-              A function taking params (including a callback)
-            
            
-          
            
-        
            
-
-        
            
-          
            
-            
            Adapter
            
-            
            
-              DataAdapter
-            
            
-
-            
            Decorator
            
-            
            
-              Query
-            
            
-          
            
-        
            
-      
            
-    
            
-
-    
            
-      Compatibility with <input type="text" />
-    
            
-
-    
            
-      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.
-    
            
-
-    
            
-      
            Adapter
            
-      
            
-        DataAdapter
-      
            
-
-      
            Decorator
            
-      
            
-        InputData
-      
            
-    
            
-  
   
            
   
 
            
 
            

From dfc8eecdcbe57de4c9225178021179cf75c6d433 Mon Sep 17 00:00:00 2001
From: Florian Kissling 
Date: Wed, 6 May 2015 02:47:53 +0200
Subject: [PATCH 56/85] Add "type" to stylesheet link tag.

---
 docs/_includes/head.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/_includes/head.html b/docs/_includes/head.html
index 95015bd4..e3d619f3 100644
--- a/docs/_includes/head.html
+++ b/docs/_includes/head.html
@@ -17,4 +17,4 @@
 
 
 
-
+

From 60710af6ed2bc24fc189e373e27ab7cf02e79d18 Mon Sep 17 00:00:00 2001
From: Florian Kissling 
Date: Wed, 6 May 2015 02:51:10 +0200
Subject: [PATCH 57/85] Add GitHub fork and star buttons to footer.

Directly borrowed from the Bootstrap docs again.
---
 docs/_includes/footer.html         |  1 +
 docs/_includes/social-buttons.html | 10 ++++++++++
 docs/_sass/_s2-docs-social.scss    | 32 ++++++++++++++++++++++++++++++
 docs/css/s2-docs.scss              |  1 +
 4 files changed, 44 insertions(+)
 create mode 100644 docs/_includes/social-buttons.html
 create mode 100644 docs/_sass/_s2-docs-social.scss

diff --git a/docs/_includes/footer.html b/docs/_includes/footer.html
index 7337d7f7..b7fc59a2 100644
--- a/docs/_includes/footer.html
+++ b/docs/_includes/footer.html
@@ -1,5 +1,6 @@