From 41e4795578609d71291994140a66bc1a243eefb1 Mon Sep 17 00:00:00 2001 From: Kevin Brown Date: Sat, 29 Aug 2015 19:51:52 -0400 Subject: [PATCH 01/14] Set up initial page with some questions Right now this sets up the new FAQ/Options page with most of the questions for the how to control the selection. Not all of these questions have answers, most of them weren't moved over, but there are plans to add detailed answers to all of them. The questions were aggregated based on common Stack Overflow and IRC questions, as well as commonly asked things on GitHub. --- docs/_includes/options-new/core.html | 8 +++ .../options-new/core/amd-support.html | 13 ++++ .../options-new/core/data-attributes.html | 71 +++++++++++++++++++ docs/_includes/options-new/introduction.html | 5 ++ docs/_includes/options-new/selections.html | 10 +++ .../selections/clearing-selections.html | 13 ++++ .../options-new/selections/multiple.html | 5 ++ .../options-new/selections/placeholder.html | 21 ++++++ .../options-new/selections/templating.html | 17 +++++ docs/options-new.html | 33 +++++++++ 10 files changed, 196 insertions(+) create mode 100644 docs/_includes/options-new/core.html create mode 100644 docs/_includes/options-new/core/amd-support.html create mode 100644 docs/_includes/options-new/core/data-attributes.html create mode 100644 docs/_includes/options-new/introduction.html create mode 100644 docs/_includes/options-new/selections.html create mode 100644 docs/_includes/options-new/selections/clearing-selections.html create mode 100644 docs/_includes/options-new/selections/multiple.html create mode 100644 docs/_includes/options-new/selections/placeholder.html create mode 100644 docs/_includes/options-new/selections/templating.html create mode 100644 docs/options-new.html diff --git a/docs/_includes/options-new/core.html b/docs/_includes/options-new/core.html new file mode 100644 index 00000000..63e15fd1 --- /dev/null +++ b/docs/_includes/options-new/core.html @@ -0,0 +1,8 @@ +
+

+ Core options +

+ + {% include options-new/core/data-attributes.html %} + {% include options-new/core/amd-support.html %} +
\ No newline at end of file diff --git a/docs/_includes/options-new/core/amd-support.html b/docs/_includes/options-new/core/amd-support.html new file mode 100644 index 00000000..8aeae54f --- /dev/null +++ b/docs/_includes/options-new/core/amd-support.html @@ -0,0 +1,13 @@ +
+

+ Can I use Select2 with my AMD or CommonJS loader? +

+ +

+ How do I tell Select2 where to look for modules? +

+ +

+ Select2 is being placed before jQuery in my JavaScript file +

+
\ No newline at end of file diff --git a/docs/_includes/options-new/core/data-attributes.html b/docs/_includes/options-new/core/data-attributes.html new file mode 100644 index 00000000..b4a4c3bd --- /dev/null +++ b/docs/_includes/options-new/core/data-attributes.html @@ -0,0 +1,71 @@ +
+

+ Can I declare my configuration within the HTML? +

+ +

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

+ +

+ How should camelCase options be written? +

+ +

+ 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"
+});
+
+ +

+ Are options with nested configurations supported? +

+ +

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

+
\ No newline at end of file diff --git a/docs/_includes/options-new/introduction.html b/docs/_includes/options-new/introduction.html new file mode 100644 index 00000000..6571be69 --- /dev/null +++ b/docs/_includes/options-new/introduction.html @@ -0,0 +1,5 @@ +
+

+ This documentation is set up in the form of a FAQ. +

+
\ No newline at end of file diff --git a/docs/_includes/options-new/selections.html b/docs/_includes/options-new/selections.html new file mode 100644 index 00000000..cf062a7c --- /dev/null +++ b/docs/_includes/options-new/selections.html @@ -0,0 +1,10 @@ +
+

+ Selections +

+ + {% include options-new/selections/multiple.html %} + {% include options-new/selections/placeholder.html %} + {% include options-new/selections/clearing-selections.html %} + {% include options-new/selections/templating.html %} +
\ No newline at end of file diff --git a/docs/_includes/options-new/selections/clearing-selections.html b/docs/_includes/options-new/selections/clearing-selections.html new file mode 100644 index 00000000..f66603fd --- /dev/null +++ b/docs/_includes/options-new/selections/clearing-selections.html @@ -0,0 +1,13 @@ +
+

+ Can I allow users to clear their selections? +

+ +

+ The "x" icon is not clearing the selection +

+ +

+ Can users remove all of their selections in a multiple select at once? +

+
\ No newline at end of file diff --git a/docs/_includes/options-new/selections/multiple.html b/docs/_includes/options-new/selections/multiple.html new file mode 100644 index 00000000..720db70d --- /dev/null +++ b/docs/_includes/options-new/selections/multiple.html @@ -0,0 +1,5 @@ +
+

+ Can I allow users to make multiple selections? +

+
\ No newline at end of file diff --git a/docs/_includes/options-new/selections/placeholder.html b/docs/_includes/options-new/selections/placeholder.html new file mode 100644 index 00000000..2a7d05cd --- /dev/null +++ b/docs/_includes/options-new/selections/placeholder.html @@ -0,0 +1,21 @@ +
+

+ How can I have Select2 display a placeholder? +

+ +

+ My first option is being displayed instead of my placeholder +

+ +

+ I am using AJAX, can I still show a placeholder? +

+ +

+ Can I use a placeholder without a blank value? +

+ +

+ Can I change how the placeholder looks? +

+
\ No newline at end of file diff --git a/docs/_includes/options-new/selections/templating.html b/docs/_includes/options-new/selections/templating.html new file mode 100644 index 00000000..0fb6aac1 --- /dev/null +++ b/docs/_includes/options-new/selections/templating.html @@ -0,0 +1,17 @@ +
+

+ How can I customize the way selections are displayed? +

+ +

+ Nothing is being displayed when I select an option +

+ +

+ I am using HTML in my selection template but it isn't displaying it +

+ +

+ How can I access the container where the selection is displayed? +

+
\ No newline at end of file diff --git a/docs/options-new.html b/docs/options-new.html new file mode 100644 index 00000000..375fb173 --- /dev/null +++ b/docs/options-new.html @@ -0,0 +1,33 @@ +--- +layout: default +title: Options - Select2 +slug: options +--- + +
+
+

+ Options +

+

+ Select2 supports a wide variety of options that allow you to customize it to your needs. +

+
+
+ +
+
+
+ {% include options-new/introduction.html %} + {% include options-new/core.html %} + {% include options-new/selections.html %} +
+ +
+
+ + From 75abd407c8868c4d9553055784e7398be998ab0f Mon Sep 17 00:00:00 2001 From: Kevin Brown Date: Mon, 31 Aug 2015 20:43:01 -0400 Subject: [PATCH 02/14] Continue building out the FAQ This adds more questions that will eventually get answers. Most of these questions are already answered either in the current documentation or on Stack Overflow, so it shouldn't be too difficult to fill out answers for them. --- docs/_includes/nav/options-new.html | 84 +++++++++++++++++++ docs/_includes/options-new/core.html | 1 + docs/_includes/options-new/core/options.html | 9 ++ docs/_includes/options-new/data.html | 9 ++ docs/_includes/options-new/data/ajax.html | 29 +++++++ docs/_includes/options-new/data/array.html | 37 ++++++++ docs/_includes/options-new/data/select.html | 33 ++++++++ docs/_includes/options-new/selections.html | 4 +- .../options-new/selections/placeholder.html | 8 ++ docs/options-new.html | 3 +- 10 files changed, 214 insertions(+), 3 deletions(-) create mode 100644 docs/_includes/nav/options-new.html create mode 100644 docs/_includes/options-new/core/options.html create mode 100644 docs/_includes/options-new/data.html create mode 100644 docs/_includes/options-new/data/ajax.html create mode 100644 docs/_includes/options-new/data/array.html create mode 100644 docs/_includes/options-new/data/select.html diff --git a/docs/_includes/nav/options-new.html b/docs/_includes/nav/options-new.html new file mode 100644 index 00000000..21b84e7a --- /dev/null +++ b/docs/_includes/nav/options-new.html @@ -0,0 +1,84 @@ + diff --git a/docs/_includes/options-new/core.html b/docs/_includes/options-new/core.html index 63e15fd1..f7b3d4c9 100644 --- a/docs/_includes/options-new/core.html +++ b/docs/_includes/options-new/core.html @@ -3,6 +3,7 @@ Core options + {% include options-new/core/options.html %} {% include options-new/core/data-attributes.html %} {% include options-new/core/amd-support.html %} \ No newline at end of file diff --git a/docs/_includes/options-new/core/options.html b/docs/_includes/options-new/core/options.html new file mode 100644 index 00000000..e14e6c37 --- /dev/null +++ b/docs/_includes/options-new/core/options.html @@ -0,0 +1,9 @@ +
+

+ How should Select2 be initialized? +

+ +

+ Can default options be set for all dropdowns? +

+
\ No newline at end of file diff --git a/docs/_includes/options-new/data.html b/docs/_includes/options-new/data.html new file mode 100644 index 00000000..f6d63ea2 --- /dev/null +++ b/docs/_includes/options-new/data.html @@ -0,0 +1,9 @@ +
+

+ Data adapters +

+ + {% include options-new/data/select.html %} + {% include options-new/data/array.html %} + {% include options-new/data/ajax.html %} +
\ No newline at end of file diff --git a/docs/_includes/options-new/data/ajax.html b/docs/_includes/options-new/data/ajax.html new file mode 100644 index 00000000..83f90fe3 --- /dev/null +++ b/docs/_includes/options-new/data/ajax.html @@ -0,0 +1,29 @@ +
+

+ Can Select2 be connected to a remote data source? +

+ +

+ How can I set the initially selected options when using AJAX? +

+ +

+ What should the results returned to Select2 look like? +

+ +

+ Is there a way to modify the response before passing it back to Select2? +

+ +

+ A request is being triggered on every key stroke, can I delay this? +

+ +

+ I want to add more query parameters to the request, where can this be done? +

+ +

+ Can an AJAX plugin other than jQuery.ajax be used? +

+
\ No newline at end of file diff --git a/docs/_includes/options-new/data/array.html b/docs/_includes/options-new/data/array.html new file mode 100644 index 00000000..727fd167 --- /dev/null +++ b/docs/_includes/options-new/data/array.html @@ -0,0 +1,37 @@ +
+

+ Can I load data into Select2 using an array? +

+ +

+ Yes, but only when you are initially creating it. +

+ +

+ What properties are required on the objects passed in to the array? +

+ +

+ How should nested results be formatted? +

+ +

+ How many levels of nesting are allowed? +

+ +

+ Why are <option> tags being created? +

+ +

+ The data option is a shortcut that Select2 provides which allows you to load options into your select from a data array. +

+ +

+ My objects don't use id for their unique identifiers, what can I do? +

+ +

+ My objects use a property other than text for the text that needs to be displayed +

+
\ No newline at end of file diff --git a/docs/_includes/options-new/data/select.html b/docs/_includes/options-new/data/select.html new file mode 100644 index 00000000..b1b89715 --- /dev/null +++ b/docs/_includes/options-new/data/select.html @@ -0,0 +1,33 @@ +
+

+ Can Select2 be used with a <select> tag? +

+ +

+ Does Select2 support nesting options? +

+ +

+ Yes, just like in a standard select. +

+ +

+ How many levels of nesting can there be? +

+ +

+ Only a single level of nesting is allowed per the HTML specification. +

+ +

+ Can <optgroup> tags be made selectable? +

+ +

+ No. +

+ +

+ How are <option> and <optgroup> tags serialized into data objects? +

+
\ No newline at end of file diff --git a/docs/_includes/options-new/selections.html b/docs/_includes/options-new/selections.html index cf062a7c..c65e847e 100644 --- a/docs/_includes/options-new/selections.html +++ b/docs/_includes/options-new/selections.html @@ -1,6 +1,6 @@
-

- Selections +

+ Displaying selections

{% include options-new/selections/multiple.html %} diff --git a/docs/_includes/options-new/selections/placeholder.html b/docs/_includes/options-new/selections/placeholder.html index 2a7d05cd..88eddea6 100644 --- a/docs/_includes/options-new/selections/placeholder.html +++ b/docs/_includes/options-new/selections/placeholder.html @@ -18,4 +18,12 @@

Can I change how the placeholder looks?

+ +

+ My placeholders aren't being displayed in Internet Explorer +

+ +

+ You need to include Placeholders.js on your page, or use the full build. +

\ No newline at end of file diff --git a/docs/options-new.html b/docs/options-new.html index 375fb173..f6877338 100644 --- a/docs/options-new.html +++ b/docs/options-new.html @@ -20,10 +20,11 @@ slug: options
{% include options-new/introduction.html %} {% include options-new/core.html %} + {% include options-new/data.html %} {% include options-new/selections.html %}
From a96ec9d91ceb56f2a770b412cd685968df3c8457 Mon Sep 17 00:00:00 2001 From: Kevin Brown Date: Mon, 31 Aug 2015 21:14:59 -0400 Subject: [PATCH 03/14] Added section for events Both public jQuery events and internal Select2 events will be documented. --- docs/_includes/nav/options-new.html | 4 ++-- docs/_includes/options-new/core/options.html | 8 ++++++++ docs/_includes/options-new/events.html | 8 ++++++++ docs/_includes/options-new/events/internal.html | 9 +++++++++ docs/_includes/options-new/events/jquery.html | 17 +++++++++++++++++ docs/options-new.html | 1 + 6 files changed, 45 insertions(+), 2 deletions(-) create mode 100644 docs/_includes/options-new/events.html create mode 100644 docs/_includes/options-new/events/internal.html create mode 100644 docs/_includes/options-new/events/jquery.html diff --git a/docs/_includes/nav/options-new.html b/docs/_includes/nav/options-new.html index 21b84e7a..c54afe1a 100644 --- a/docs/_includes/nav/options-new.html +++ b/docs/_includes/nav/options-new.html @@ -1,7 +1,7 @@