From 41e4795578609d71291994140a66bc1a243eefb1 Mon Sep 17 00:00:00 2001
From: Kevin Brown <kevin@kevin-brown.com>
Date: Sat, 29 Aug 2015 19:51:52 -0400
Subject: [PATCH] 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 @@
+<section>
+  <h1>
+    Core options
+  </h1>
+  
+  {% include options-new/core/data-attributes.html %}
+  {% include options-new/core/amd-support.html %}
+</section>
\ 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 @@
+<section>
+  <h2 id="amd">
+    Can I use Select2 with my AMD or CommonJS loader?
+  </h2>
+  
+  <h3>
+    How do I tell Select2 where to look for modules?
+  </h3>
+  
+  <h3>
+    Select2 is being placed before jQuery in my JavaScript file
+  </h3>
+</section>
\ 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 @@
+<section>
+  <h2 id="data-attributes">
+    Can I declare my configuration within the HTML?
+  </h2>
+  
+  <p>
+    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 <code>data-*</code> attributes, which will override
+    any options set when initializing Select2 and any defaults.
+  </p>
+  
+  <h3>
+    How should <code>camelCase</code> options be written?
+  </h3>
+  
+  <p>
+    This means that if you declare your <code>&lt;select&gt;</code> tag as...
+  </p>
+
+<pre class="prettyprint">
+&lt;select data-tags="true" data-placeholder="Select an option"&gt;&lt;/select&gt;
+</pre>
+
+  <p>
+    Will be interpreted the same as initializing Select2 as...
+  </p>
+
+<pre class="prettyprint linenums">
+$("select").select2({
+  tags: "true",
+  placeholder: "Select an option"
+});
+</pre>
+  
+  <h3>
+    Are options with nested configurations supported?
+  </h3>
+  
+  <p>
+    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 (<code>--</code>) instead of one. Due to
+    <a href="https://github.com/jquery/jquery/issues/2070">a jQuery bug</a>,
+    nested options using <code>data-*</code> attributes
+    <a href="https://github.com/select2/select2/issues/2969">do not work in jQuery 1.x</a>.
+  </p>
+
+<pre class="prettyprint">
+&lt;select data-ajax--url="http://example.org/api/test" data-ajax--cache="true"&gt;&lt;/select&gt;
+</pre>
+
+  <p>
+    Which will be interpreted the same as initializing Select2 with...
+  </p>
+
+<pre class="prettyprint linenums">
+$("select").select2({
+  ajax: {
+    url: "http://example.org/api/test",
+    cache: "true"
+  }
+});
+</pre>
+
+  <p>
+    The value of the option is subject to jQuery's
+    <a href="https://api.jquery.com/data/#data-html5">parsing rules</a> for
+    HTML5 data attributes.
+  </p>
+</section>
\ 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 @@
+<section>
+  <p>
+    This documentation is set up in the form of a FAQ.
+  </p>
+</section>
\ 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 @@
+<section>
+  <h1>
+    Selections
+  </h1>
+  
+  {% 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 %}
+</section>
\ 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 @@
+<section>
+  <h2 id="allowClear">
+    Can I allow users to clear their selections?
+  </h2>
+  
+  <h3>
+    The "x" icon is not clearing the selection
+  </h3>
+
+  <h3>
+    Can users remove all of their selections in a multiple select at once?
+  </h3>
+</section>
\ 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 @@
+<section>
+  <h2 id="multiple">
+    Can I allow users to make multiple selections?
+  </h2>
+</section>
\ 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 @@
+<section>
+  <h2 id="placeholder">
+    How can I have Select2 display a placeholder?
+  </h2>
+  
+  <h3>
+    My first option is being displayed instead of my placeholder
+  </h3>
+  
+  <h3>
+    I am using AJAX, can I still show a placeholder?
+  </h3>
+  
+  <h3>
+    Can I use a placeholder without a blank value?
+  </h3>
+  
+  <h3>
+    Can I change how the placeholder looks?
+  </h3>
+</section>
\ 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 @@
+<section>
+  <h2 id="templateSelection">
+    How can I customize the way selections are displayed?
+  </h2>
+  
+  <h3>
+    Nothing is being displayed when I select an option
+  </h3>
+  
+  <h3>
+    I am using HTML in my selection template but it isn't displaying it
+  </h3>
+  
+  <h3>
+    How can I access the container where the selection is displayed?
+  </h3>
+</section>
\ 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
+---
+
+<section class="jumbotron">
+  <div class="container">
+    <h1>
+      Options
+    </h1>
+    <p class="lead">
+      Select2 supports a wide variety of options that allow you to customize it to your needs.
+    </p>
+  </div>
+</section>
+
+<div class="container s2-docs-container">
+  <div class="row">
+    <div class="col-md-9" role="main">
+      {% include options-new/introduction.html %}
+      {% include options-new/core.html %}
+      {% include options-new/selections.html %}
+    </div>
+    <div class="col-md-3" role="complementary">
+      {% include nav/options.html %}
+    </div>
+  </div>
+</div>
+
+<script type="text/javascript">
+  prettyPrint();
+</script>