From 0840c3923f0cddda76360cb4c2181a4053fc7545 Mon Sep 17 00:00:00 2001
From: Kevin Brown <kevin@kevin-brown.com>
Date: Thu, 14 Jan 2016 19:30:11 -0500
Subject: [PATCH] Code samples and docs for selections

---
 .../selections/clearing-selections.html       | 17 +++++++++
 .../options/selections/placeholder.html       | 35 +++++++++++++++++--
 .../options/selections/templating.html        | 14 ++++++++
 3 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/docs/_includes/options/selections/clearing-selections.html b/docs/_includes/options/selections/clearing-selections.html
index 2e81614b..fb393bd5 100644
--- a/docs/_includes/options/selections/clearing-selections.html
+++ b/docs/_includes/options/selections/clearing-selections.html
@@ -3,6 +3,23 @@
     Can I allow users to clear their selections?
   </h2>
 
+  <p>
+    You can allow people to clear their current selections with the <code>allowClear</code> option when initializing Select2. Setting this option to <code>true</code> will enable an "x" icon that will reset the selection to the placeholder.
+  </p>
+
+<pre class="prettyprint">
+$('select').select2({
+  placeholder: 'This is my placeholder',
+  allowClear: true
+});
+</pre>
+
+  <h3>
+    Why is a placeholder required?
+  </h3>
+
+  {% include options/not-written.html %}
+
   <h3>
     The "x" icon is not clearing the selection
   </h3>
diff --git a/docs/_includes/options/selections/placeholder.html b/docs/_includes/options/selections/placeholder.html
index bcb08b5f..a6d29a1f 100644
--- a/docs/_includes/options/selections/placeholder.html
+++ b/docs/_includes/options/selections/placeholder.html
@@ -7,6 +7,12 @@
     Select2 supports displaying a placeholder by default using the <code>placeholder</code> option. This can be either a data object matching the placeholder option, or a string to display as the placeholder if you are using a blank placeholder option.
   </p>
 
+<pre class="prettyprint">
+$('select').select2({
+  placeholder: 'Select an option'
+});
+</pre>
+
   <h3>
     My first option is being displayed instead of my placeholder
   </h3>
@@ -35,12 +41,37 @@
     The <code>placeholder</code> option allows you to pass in a data object instead of just a string if you need more flexibility. The <code>id</code> of the data object should match the <code>value</code> of the placeholder option.
   </p>
 
+<pre class="prettyprint">
+$('select').select2({
+  placeholder: {
+    id: '-1', // the value of the option
+    text: 'Select an option'
+  }
+});
+</pre>
+
   <h3>
     Can I change how the placeholder looks?
   </h3>
 
   <p>
-    The placeholder option should go through the standard templating methods, including <code>templateSelection</code>, so you can change how it is displayed.
+    When using Select2 <strong>when only a single selection can be made</strong>, the placeholder option will be passed through the standard templating methods, incluidng the <code>templateSelection</code> option, so you are able to change how it is displayed.
+  </p>
+
+<pre class="prettyprint">
+$('select').select2({
+  templateResult: function (data) {
+    if (data.id === '') { // adjust for custom placeholder values
+      return 'Custom styled placeholder text';
+    }
+
+    return data.text;
+  }
+});
+</pre>
+
+  <p>
+    <strong>When multiple selections are allowed</strong>, the placeholder will be displayed using the <code>placeholder</code> attribute on the search box. You can cusotmize the display of this placholder using CSS, as explained in the following Stack Overflow answer: <a href="http://stackoverflow.com/q/2610497/359284">Change an input's HTML5 placeholder color with CSS</a>
   </p>
 
   <h3>
@@ -48,6 +79,6 @@
   </h3>
 
   <p>
-    Select2 uses the native <code>placeholder</code> attribute on input boxes for the multiple select, and that attribute is not supported in older versions of Internet Explorer. You need to include Placeholders.js on your page, or use the full build, in order to add <code>placeholder</code> attribute support to input boxes.
+    Select2 uses the native <code>placeholder</code> attribute on input boxes for the multiple select, and that attribute is not supported in older versions of Internet Explorer. You need to include <a href="https://github.com/jamesallardice/Placeholders.js">Placeholders.js</a> on your page, or use the full build, in order to add <code>placeholder</code> attribute support to input boxes.
   </p>
 </section>
\ No newline at end of file
diff --git a/docs/_includes/options/selections/templating.html b/docs/_includes/options/selections/templating.html
index 7063561a..2e9fad57 100644
--- a/docs/_includes/options/selections/templating.html
+++ b/docs/_includes/options/selections/templating.html
@@ -3,6 +3,20 @@
     How can I customize the way selections are displayed?
   </h2>
 
+  <p>
+    When a selection is made by the user Select2 will display the text of the option by default, just like how it is displayed in a standard select box.  You can override the display of the selection by setting the <code>templateSelection</code> option to a JavaScript function.
+  </p>
+
+<pre class="prettyprint">
+function template(data, container) {
+  return data.text;
+}
+
+$('select').select2({
+  templateSelection: template
+});
+</pre>
+
   <h3>
     Nothing is being displayed when I select an option
   </h3>