From 94c5c3a3feef4994f2e3226aba6321ee81d36004 Mon Sep 17 00:00:00 2001 From: alexweissman Date: Sun, 3 Sep 2017 19:02:00 -0400 Subject: [PATCH] begin integrating the "old options" page --- pages/02.configuration/docs.md | 23 +- pages/03.appearance/01.markup/docs.md | 115 --- pages/03.appearance/02.theming/docs.md | 72 -- pages/03.appearance/chapter.md | 11 - pages/03.appearance/docs.md | 218 +++++ pages/04.options/docs.md | 81 ++ pages/04.searching/docs.md | 80 -- .../01.formats/docs.md | 8 +- .../02.ajax/docs.md | 3 +- .../03.arrays/docs.md | 0 .../chapter.md | 2 - pages/05.dropdown/docs.md | 124 --- pages/06.dropdown/docs.md | 85 ++ .../{06.selections => 07.selections}/docs.md | 32 +- .../docs.md | 2 + pages/10.searching/docs.md | 150 ++++ .../01.methods/docs.md | 0 .../02.events/docs.md | 0 .../chapter.md | 2 - pages/12.advanced/adapters.html | 209 ----- pages/12.advanced/core-options.html | 790 ------------------ pages/12.advanced/dropdown.html | 308 ------- .../12.advanced/setting-default-options.html | 37 - pages/{11.i18n => 12.i18n}/docs.md | 28 +- .../01.adapters-and-decorators/docs.md | 130 +++ .../02.default-adapters/01.selection/docs.md | 39 + .../02.default-adapters/02.array/docs.md | 49 ++ .../02.default-adapters/03.ajax/docs.md | 118 +++ .../02.default-adapters/04.data/docs.md | 48 ++ .../02.default-adapters/05.results/docs.md | 31 + .../02.default-adapters/06.dropdown/docs.md | 157 ++++ pages/13.advanced/02.default-adapters/docs.md | 7 + .../announcements-4.0.html | 0 .../backwards-compatibility.html | 31 + pages/13.advanced/chapter.md | 7 + .../{12.advanced => 13.advanced}/events.html | 22 - 36 files changed, 1203 insertions(+), 1816 deletions(-) delete mode 100644 pages/03.appearance/01.markup/docs.md delete mode 100644 pages/03.appearance/02.theming/docs.md delete mode 100644 pages/03.appearance/chapter.md create mode 100644 pages/03.appearance/docs.md create mode 100644 pages/04.options/docs.md delete mode 100644 pages/04.searching/docs.md rename pages/{09.data-sources => 05.data-sources}/01.formats/docs.md (86%) rename pages/{09.data-sources => 05.data-sources}/02.ajax/docs.md (97%) rename pages/{09.data-sources => 05.data-sources}/03.arrays/docs.md (100%) rename pages/{09.data-sources => 05.data-sources}/chapter.md (94%) delete mode 100644 pages/05.dropdown/docs.md create mode 100644 pages/06.dropdown/docs.md rename pages/{06.selections => 07.selections}/docs.md (62%) rename pages/{07.placeholders => 09.placeholders}/docs.md (97%) create mode 100644 pages/10.searching/docs.md rename pages/{10.programmatic-control => 11.programmatic-control}/01.methods/docs.md (100%) rename pages/{10.programmatic-control => 11.programmatic-control}/02.events/docs.md (100%) rename pages/{10.programmatic-control => 11.programmatic-control}/chapter.md (85%) delete mode 100644 pages/12.advanced/adapters.html delete mode 100644 pages/12.advanced/core-options.html delete mode 100644 pages/12.advanced/dropdown.html delete mode 100644 pages/12.advanced/setting-default-options.html rename pages/{11.i18n => 12.i18n}/docs.md (61%) create mode 100644 pages/13.advanced/01.adapters-and-decorators/docs.md create mode 100644 pages/13.advanced/02.default-adapters/01.selection/docs.md create mode 100644 pages/13.advanced/02.default-adapters/02.array/docs.md create mode 100644 pages/13.advanced/02.default-adapters/03.ajax/docs.md create mode 100644 pages/13.advanced/02.default-adapters/04.data/docs.md create mode 100644 pages/13.advanced/02.default-adapters/05.results/docs.md create mode 100644 pages/13.advanced/02.default-adapters/06.dropdown/docs.md create mode 100644 pages/13.advanced/02.default-adapters/docs.md rename pages/{12.advanced => 13.advanced}/announcements-4.0.html (100%) rename pages/{12.advanced => 13.advanced}/backwards-compatibility.html (87%) create mode 100644 pages/13.advanced/chapter.md rename pages/{12.advanced => 13.advanced}/events.html (59%) diff --git a/pages/02.configuration/docs.md b/pages/02.configuration/docs.md index b66ec422..fc72c0cb 100644 --- a/pages/02.configuration/docs.md +++ b/pages/02.configuration/docs.md @@ -51,7 +51,7 @@ release's documentation should cover the gaps here for the time being. typically doesn't need to be changed, but is available for situations where module names may change as a result of certain build environments.

-

Default value: "./"

+

Default value: `select2/`

@@ -62,7 +62,7 @@ release's documentation should cover the gaps here for the time being. option typically doesn't need to be changed, but is available for situations where module names may change as a result of certain build environments.

-

Default value: "./i18n/"

+

Default value: `select2/i18n/`

@@ -73,7 +73,7 @@ release's documentation should cover the gaps here for the time being. making it easy to quickly select multiple items. Note that this option is only applicable to multi-select controls.

-

Default value: true

+

Default value: `true`

@@ -132,7 +132,7 @@ release's documentation should cover the gaps here for the time being. dropdownParent - + jQuery selector or DOM node @@ -147,12 +147,13 @@ release's documentation should cover the gaps here for the time being. language - + string or object matcher - + A callback taking search params and the + data object. @@ -198,14 +199,14 @@ release's documentation should cover the gaps here for the time being. multiple - + boolean This option enables multi-select (pillbox) mode. Select2 will automatically map the value of the `multiple` HTML attribute to this option during initialization. placeholder - + string or object @@ -237,17 +238,17 @@ release's documentation should cover the gaps here for the time being. tags - + boolean / array of objects templateResult - function + callback templateSelection - function + callback diff --git a/pages/03.appearance/01.markup/docs.md b/pages/03.appearance/01.markup/docs.md deleted file mode 100644 index 2ea41f5e..00000000 --- a/pages/03.appearance/01.markup/docs.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Basic markup -taxonomy: - category: docs -process: - twig: true -never_cache_twig: true ---- - -A standard `` element that contains ``) and any attributes on those elements using `.element`. - -## 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/pages/03.appearance/chapter.md b/pages/03.appearance/chapter.md
deleted file mode 100644
index a42194f8..00000000
--- a/pages/03.appearance/chapter.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-title: Appearance
-taxonomy:
-    category: docs
----
-
-### Chapter 3
-
-# Appearance
-
-The appearance of your Select2 controls can be customized via the standard HTML attributes for `` elements, as well as various [configuration options](/configuration).
+
+## Disabling a Select2 control
+
+Select2 will respond to the disabled attribute on `
+  

+
+  

+    
+  

+  

+    
+    
+  

+
+
+

+
+
+
+## Labels
+
+You can, and should, use a `
+  

+  

+    
+  

+
+
+```
+
+
+
+```
+
+
+
+## Container width
+
+Select2 will try to match the width of the original element as closely as possible. Sometimes this isn't perfect, in which case you may manually set the `width` [configuration option](/configuration):
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+  
+
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.
+      

+
+## 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.
+
+## Theme support
+
+Select2 supports custom themes using the `theme` option so you can style Select2 to match the rest of your application.
+
+These examples use the `classic` theme, which matches the old look of Select2.
+
+

+  

+    
+  

+  

+    
+  

+

+
+

+
+
+
+Various display options of the Select2 component can be changed.  You can access the ``) and any attributes on those elements using `.element`.
diff --git a/pages/04.options/docs.md b/pages/04.options/docs.md
new file mode 100644
index 00000000..7b56c711
--- /dev/null
+++ b/pages/04.options/docs.md
@@ -0,0 +1,81 @@
+---
+title: Options
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+A traditional `` element that contains `` elements will be converted into data objects using the following rules:
+
+```
+{
+  "text": "label attribute",
+  "children": [ option data object, ... ],
+  "element": HTMLOptGroupElement
+}
+```
+
+>>> Options sourced from [other data sources](/data-sources) must conform to this this same internal representation.  See ["The Select2 data format"](/data-sources/formats) for details.
+
+## Dropdown option groups
+
+In HTML, `` element:
+
+```
+
+```
+
+Select2 will automatically pick these up and render them appropriately in the dropdown.
+
+### Hierarchical options
+
+Only a single level of nesting is allowed per the HTML specification. If you nest an `` within another ``, Select2 will not be able to detect the extra level of nesting and errors may be triggered as a result.
+
+Furthermore, `` elements **cannot** be made selectable.  This is a limitation of the HTML specification and is not a limitation that Select2 can overcome.
+
+If you wish to create a true hierarchy of selectable options, use an `` and [change the style with CSS](http://stackoverflow.com/q/30820215/359284#30948247).  Please note that this approach may be considered "less accessible" as it relies on CSS styling, rather than the semantic meaning of ``, to generate the effect.
+
+## Disabling options
+
+Select2 will correctly handle disabled options, 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/pages/04.searching/docs.md b/pages/04.searching/docs.md
deleted file mode 100644
index f71a0b82..00000000
--- a/pages/04.searching/docs.md
+++ /dev/null
@@ -1,80 +0,0 @@
----
-title: Search
-taxonomy:
-    category: docs
-process:
-    twig: true
-never_cache_twig: true
----
-
-The appearance and behavior of the search control can be easily customized with Select2.
-
-## Customizing how results are matched
-
-You may customize the way that Select2 matches search terms by passing a callback to the `matcher` option. This example matches results only if the term appears in the beginning of the string as opposed to anywhere:
-
-

-    
-

-
-

-
-
-
->>> This custom matcher uses a [compatibility module](/configuration/deprecated) that is only bundled in the [full version of Select2](/getting-started/builds). You also have the option of using a more complex matcher.
-
-## Limiting search term length
-
-You may limit the maximum length of search terms by using the `maximumInputLength` option:
-
-```
-$('select').select2({
-  maximumInputLength: 20 // only allow terms up to 20 characters long
-});
-```
-
-## Limiting display of the search box to large result sets
-
-The `minimumResultsForSearch` option determines the minimum number of results required in the initial population of the dropdown to display the search box.
-
-This option is useful for cases where local data is used with a small result set, and the search box would simply be a waste of screen real estate. Set this value to -1 to permanently hide the search box.
-
-```
-$('select').select2({
-  minimumResultsForSearch: 20 // at least 20 results must be displayed
-});
-```
-
-## 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/pages/09.data-sources/01.formats/docs.md b/pages/05.data-sources/01.formats/docs.md
similarity index 86%
rename from pages/09.data-sources/01.formats/docs.md
rename to pages/05.data-sources/01.formats/docs.md
index baa23e64..a8850219 100644
--- a/pages/09.data-sources/01.formats/docs.md
+++ b/pages/05.data-sources/01.formats/docs.md
@@ -26,12 +26,10 @@ In order to accomplish this, Select2 expects a very specific data format.  This
 }
 ```
 
-Each object should contain, _at a minimum_, an `id` and a `text` property. The `text` property will be displayed by default unless you are using `templateResult` and `templateSelection` to customize the way options and selections are rendered.
+Each object should contain, _at a minimum_, an `id` and a `text` property.  Any additional parameters passed in with data objects will be included on the data objects that Select2 exposes.
 
 The response object may also contain pagination data, if you would like to use the "infinite scroll" feature.  This should be specified under the `pagination` key.
 
-Any additional parameters passed in with data objects will be included on the data objects that Select2 exposes.
-
 ## Transforming data into the required format
 
 ### Generating `id` properties
@@ -68,7 +66,7 @@ Select2 will attempt to convert anything that is not a string to a string, which
 
 Blank `id`s or an `id` with a value of `0` are not permitted.
 
-## Grouped options
+## Grouped data
 
 When options are to be generated in `` sections, options should be nested under the `children` key of each group object.  The label for the group should be specified as the `text` property on the group's corresponding data object.
 
@@ -108,4 +106,4 @@ When options are to be generated in `` sections, options should be nes
 }
 ```
 
->>>> Because Select2 generates an `` when creating nested options, only [a single level of nesting is supported](/dropdown/option-groups). Any additional levels of nesting is not guaranteed to be displayed properly across all browsers and devices.
+>>>> Because Select2 generates an `` when creating nested options, only [a single level of nesting is supported](/options#dropdown-option-groups). Any additional levels of nesting is not guaranteed to be displayed properly across all browsers and devices.
diff --git a/pages/09.data-sources/02.ajax/docs.md b/pages/05.data-sources/02.ajax/docs.md
similarity index 97%
rename from pages/09.data-sources/02.ajax/docs.md
rename to pages/05.data-sources/02.ajax/docs.md
index e47147c7..e5961680 100644
--- a/pages/09.data-sources/02.ajax/docs.md
+++ b/pages/05.data-sources/02.ajax/docs.md
@@ -21,8 +21,7 @@ When using Select2 with remote data, the HTML required for the `select` is the s
 
 ```
 
-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`](/configuration).
+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`](/configuration).
 
 

 
diff --git a/pages/09.data-sources/03.arrays/docs.md b/pages/05.data-sources/03.arrays/docs.md
similarity index 100%
rename from pages/09.data-sources/03.arrays/docs.md
rename to pages/05.data-sources/03.arrays/docs.md
diff --git a/pages/09.data-sources/chapter.md b/pages/05.data-sources/chapter.md
similarity index 94%
rename from pages/09.data-sources/chapter.md
rename to pages/05.data-sources/chapter.md
index 7d866b36..37d7a4c5 100644
--- a/pages/09.data-sources/chapter.md
+++ b/pages/05.data-sources/chapter.md
@@ -4,8 +4,6 @@ taxonomy:
     category: docs
 ---
 
-### Chapter 3
-
 # Data sources
 
 In addition to handling `` element:
-
-```
-
-```
-
-Select2 will automatically pick these up and render them appropriately in the dropdown.
-
-### Hierarchical options
-
-Only a single level of nesting is allowed per the HTML specification. If you nest an `` within another ``, Select2 will not be able to detect the extra level of nesting and errors may be triggered as a result.
-
-Furthermore, `` elements **cannot** be made selectable.  This is a limitation of the HTML specification and is not a limitation that Select2 can overcome.
-
-If you wish to create a true hierarchy of selectable options, use an `` and change the style with CSS.  Please note that this approach may be considered "less accessible" as it relies on CSS styling, rather than the semantic meaning of ``, to generate the effect.
diff --git a/pages/06.dropdown/docs.md b/pages/06.dropdown/docs.md
new file mode 100644
index 00000000..50479b1f
--- /dev/null
+++ b/pages/06.dropdown/docs.md
@@ -0,0 +1,85 @@
+---
+title: Dropdown
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+This chapter covers the appearance and behavior of the list of results in the dropdown menu.
+
+## Templating
+
+By default, Select2 will display the `text` property of each data object within the list of results.  The appearance of search results in the dropdown can be customized by using the `templateResult` option:
+
+

+    
+

+
+

+
+
+
+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.
+
+>>> You may find it helpful to use a client-side templating engine like [Handlebars](http://handlebarsjs.com/) to define your templates.
+
+### Built-in escaping
+
+By default, strings returned by `templateResult` are assumed to **contain only text** and will be passed through the `escapeMarkup` function, which strips any HTML markup.
+
+If you need to render HTML with your result template, you must wrap your rendered result in a jQuery object. In this case, the result will be passed [directly to `jQuery.fn.append`](https://api.jquery.com/append/) and will be handled directly by jQuery.  Any markup, such as HTML, will not be escaped and it is up to you to escape any malicious input provided by users.
+
+>>> **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.  You must ensure that your templating functions can support them.
+
+## Automatic selection
+
+Select2 can be configured to automatically select the currently highlighted result when the dropdown is closed by using the `selectOnClose` option:
+
+```
+$('select').select2({
+  selectOnClose: true
+});
+```
+
+## Forcing the dropdown to remain open after selection
+
+You may use the `closeOnSelect` option to prevent the dropdown from closing when a result is selected:
+
+```
+$('select').select2({
+  closeOnSelect: false
+});
+```
+
+## Dropdown placement
+
+The `dropdownParent` option allows you to pick an element for the dropdown to be appended to:
+
+```
+$('select').select2({
+  dropdownParent: $('#my_amazing_modal')
+});
+```
+
+### Using a Select2 control inside a Bootstrap modal
+
+If you're having trouble using the search box inside a Bootstrap modal, trying setting the `dropdownParent` option to the modal element.
diff --git a/pages/06.selections/docs.md b/pages/07.selections/docs.md
similarity index 62%
rename from pages/06.selections/docs.md
rename to pages/07.selections/docs.md
index adc08419..ba3a574d 100644
--- a/pages/06.selections/docs.md
+++ b/pages/07.selections/docs.md
@@ -7,27 +7,7 @@ process:
 never_cache_twig: true
 ---
 
-When a selection is made by the user, Select2 will convert the selected `` elements will be converted into data objects using the following rules:
-
-```
-{
-  "text": "label attribute",
-  "children": [ option data object, ... ],
-  "element": HTMLOptGroupElement
-}
-```
-
-By default, Select2 will then display the `text` property of the selected result.
+When an option is selected from the dropdown menu, Select2 will display the selected value in the container box.  By default, it will display the `text` property of Select2's [internal representation of the selected option](/options).
 
 ## Templating
 
@@ -58,7 +38,15 @@ $(".js-example-templating").select2({
 
 
 
-If your selection template contains HTML, you must wrap your rendered result in a jQuery object. Otherwise, Select2 will assume that your template only returns text and will escape it.  You may find it helpful to use a client-side templating engine like [Handlebars](http://handlebarsjs.com/) to define your templates.
+>>> You may find it helpful to use a client-side templating engine like [Handlebars](http://handlebarsjs.com/) to define your templates.
+
+### Built-in escaping
+
+By default, strings returned by `templateSelection` are assumed to **contain only text** and will be passed through the `escapeMarkup` function, which strips any HTML markup.
+
+If you need to render HTML with your selection template, you must wrap your rendered selection in a jQuery object. In this case, the selection will be passed [directly to `jQuery.fn.append`](https://api.jquery.com/append/) and will be handled directly by jQuery.  Any markup, such as HTML, will not be escaped and it is up to you to escape any malicious input provided by users.
+
+>>>> 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.
 
 ## Limiting the number of selections
 
diff --git a/pages/07.placeholders/docs.md b/pages/09.placeholders/docs.md
similarity index 97%
rename from pages/07.placeholders/docs.md
rename to pages/09.placeholders/docs.md
index 5ac4c2b6..34cd2449 100644
--- a/pages/07.placeholders/docs.md
+++ b/pages/09.placeholders/docs.md
@@ -54,6 +54,8 @@ $('select').select2({
 });
 ```
 
+This is useful, for example, when you are using a framework that creates its own placeholder option.
+
 ## Using placeholders with AJAX
 
 Select2 supports placeholders for all configurations, including AJAX. You will still need to add in the empty `