From 75abd407c8868c4d9553055784e7398be998ab0f Mon Sep 17 00:00:00 2001
From: Kevin Brown <kevin@kevin-brown.com>
Date: Mon, 31 Aug 2015 20:43:01 -0400
Subject: [PATCH] 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 @@
+<nav class="s2-docs-sidebar hidden-print hidden-xs hidden-sm">
+  <ul class="nav s2-docs-sidenav">
+    <li>
+      <a href="#core-options">Core Options</a>
+      <ul class="nav">
+        <li><a href="#data-attributes">Declaring configuration in the <code>data-*</code> attributes</a></li>
+        <li><a href="#amd">AMD compatibility</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#data-adapters">Data adapters</a>
+      <ul class="nav">
+        <li>
+          <a href="#data-adapters-select-tag">Using a <code>&lt;select&gt;</code></a>
+        </li>
+        <li>
+          <a href="#data">Loading data from an array</a>
+        </li>
+        <li>
+          <a href="#ajax">Connecting to a remote data source</a>
+        </li>
+      </ul>
+    </li>
+    <li>
+      <a href="#selections">Displaying selections</a>
+      <ul class="nav">
+        <li>
+          <a href="#placeholder">Showing a placeholder</a>
+        </li>
+        <li>
+          <a href="#allowClear">Resetting selections back to the placeholder</a>
+        </li>
+        <li>
+          <a href="#templateSelection">Templating</a>
+        </li>
+      </ul>
+    </li>
+    <li>
+      <a href="#results">Displaying results</a>
+    </li>
+    <li>
+      <a href="#dropdown">Dropdown</a>
+      <ul class="nav">
+        <li><a href="#dropdownParent">Attached to body</a></li>
+        <li><a href="#dropdown-attachContainer">Attached below the container</a></li>
+        <li><a href="#dropdown-search">Search</a></li>
+        <li><a href="#dropdown-select-on-close">Select the highlighted option on close</a></li>
+        <li><a href="#closeOnSelect">Close the dropdown when a result is selected</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#events">Events</a>
+      <ul class="nav">
+        <li><a href="#events-public">Public events</a></li>
+        <li><a href="#events-internal">Internal events</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#adapters">The plugin system (adapters)</a>
+      <ul class="nav">
+        <li><a href="#adapters-all">All adapters</a></li>
+        <li><a href="#selectionAdapter">Container (selection)</a></li>
+        <li><a href="#dataAdapter">Data set</a></li>
+        <li><a href="#dropdownAdapter">Dropdown</a></li>
+        <li><a href="#resultsAdapter">Results</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#setting-default-options">Setting default options</a>
+    </li>
+    <li>
+      <a href="#backwards-compatibility">Backwards compatibility</a>
+      <ul class="nav">
+        <li><a href="#compat-matcher">Simplified function for matching data objects</a></li>
+        <li><a href="#initSelection">Old initial selections with <code>initSelection</code></a></li>
+        <li><a href="#query">Querying old data with <code>query</code></a></li>
+        <li><a href="#input-fallback">Compatibility with <code>&lt;input type="text" /&gt;</code></a></li>
+      </ul>
+    </li>
+  </ul>
+  <a class="back-to-top" href="#top">
+    Back to top
+  </a>
+</nav>
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
   </h1>
   
+  {% include options-new/core/options.html %}
   {% 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/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 @@
+<section>
+  <h2 id="options">
+    How should Select2 be initialized?
+  </h2>
+
+  <h3>
+    Can default options be set for all dropdowns?
+  </h3>
+</section>
\ 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 @@
+<section>
+  <h1>
+    Data adapters
+  </h1>
+  
+  {% include options-new/data/select.html %}
+  {% include options-new/data/array.html %}
+  {% include options-new/data/ajax.html %}
+</section>
\ 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 @@
+<section>
+  <h2 id="ajax">
+    Can Select2 be connected to a remote data source?
+  </h2>
+
+  <h3>
+    How can I set the initially selected options when using AJAX?
+  </h3>
+
+  <h3>
+    What should the results returned to Select2 look like?
+  </h3>
+
+  <h3>
+    Is there a way to modify the response before passing it back to Select2?
+  </h3>
+
+  <h3>
+    A request is being triggered on every key stroke, can I delay this?
+  </h3>
+
+  <h3>
+    I want to add more query parameters to the request, where can this be done?
+  </h3>
+
+  <h3>
+    Can an AJAX plugin other than <code>jQuery.ajax</code> be used?
+  </h3>
+</section>
\ 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 @@
+<section>
+  <h2 id="data">
+    Can I load data into Select2 using an array?
+  </h2>
+  
+  <p>
+    Yes, but only when you are initially creating it.
+  </p>
+  
+  <h3>
+    What properties are required on the objects passed in to the array?
+  </h3>
+  
+  <h3>
+    How should nested results be formatted?
+  </h3>
+  
+  <h3>
+    How many levels of nesting are allowed?
+  </h3>
+  
+  <h3>
+    Why are <code>&lt;option&gt;</code> tags being created?
+  </h3>
+  
+  <p>
+    The <code>data</code> option is a shortcut that Select2 provides which allows you to load options into your <code>select</code> from a data array.
+  </p>
+  
+  <h3>
+    My objects don&apos;t use <code>id</code> for their unique identifiers, what can I do?
+  </h3>
+  
+  <h3>
+    My objects use a property other than <code>text</code> for the text that needs to be displayed
+  </h3>
+</section>
\ 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 @@
+<section>
+  <h2 id="data-adapters-select-tag">
+    Can Select2 be used with a <code>&lt;select&gt;</code> tag?
+  </h2>
+
+  <h3>
+    Does Select2 support nesting options?
+  </h3>
+
+  <p>
+    Yes, just like in a standard <code>select</code>.
+  </p>
+
+  <h3>
+    How many levels of nesting can there be?
+  </h3>
+
+  <p>
+    Only a single level of nesting is allowed per the HTML specification.
+  </p>
+
+  <h3>
+    Can <code>&lt;optgroup&gt;</code> tags be made selectable?
+  </h3>
+
+  <p>
+    No.
+  </p>
+
+  <h3>
+    How are <code>&lt;option&gt;</code> and <code>&lt;optgroup&gt;</code> tags serialized into data objects?
+  </h3>
+</section>
\ 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 @@
 <section>
-  <h1>
-    Selections
+  <h1 id="selections">
+    Displaying selections
   </h1>
   
   {% 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 @@
   <h3>
     Can I change how the placeholder looks?
   </h3>
+  
+  <h3>
+    My placeholders aren&apos;t being displayed in Internet Explorer
+  </h3>
+  
+  <p>
+    You need to include Placeholders.js on your page, or use the full build.
+  </p>
 </section>
\ 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
     <div class="col-md-9" role="main">
       {% include options-new/introduction.html %}
       {% include options-new/core.html %}
+      {% include options-new/data.html %}
       {% include options-new/selections.html %}
     </div>
     <div class="col-md-3" role="complementary">
-      {% include nav/options.html %}
+      {% include nav/options-new.html %}
     </div>
   </div>
 </div>