From 576f93778d014ac3534f32b9e9eb43e1f45a23dd Mon Sep 17 00:00:00 2001
From: Stan Senotrusov <stan@senotrusov.com>
Date: Sun, 1 May 2016 22:42:14 +0200
Subject: [PATCH] Add documentation on how to programmatically access a
 selection data.

---
 docs/_includes/nav/options.html               |  3 ++
 docs/_includes/options/data.html              |  1 +
 .../options/data/selection-access.html        | 40 +++++++++++++++++++
 3 files changed, 44 insertions(+)
 create mode 100644 docs/_includes/options/data/selection-access.html

diff --git a/docs/_includes/nav/options.html b/docs/_includes/nav/options.html
index 4c1be4f3..783eafb7 100644
--- a/docs/_includes/nav/options.html
+++ b/docs/_includes/nav/options.html
@@ -20,6 +20,9 @@
         <li>
           <a href="#ajax">Connecting to a remote data source</a>
         </li>
+        <li>
+          <a href="#selection-api-access">Accessing a selection data</a>
+        </li>
       </ul>
     </li>
     <li>
diff --git a/docs/_includes/options/data.html b/docs/_includes/options/data.html
index c9c6f684..4e53fbeb 100644
--- a/docs/_includes/options/data.html
+++ b/docs/_includes/options/data.html
@@ -6,4 +6,5 @@
   {% include options/data/select.html %}
   {% include options/data/array.html %}
   {% include options/data/ajax.html %}
+  {% include options/data/selection-access.html %}
 </section>
\ No newline at end of file
diff --git a/docs/_includes/options/data/selection-access.html b/docs/_includes/options/data/selection-access.html
new file mode 100644
index 00000000..14149762
--- /dev/null
+++ b/docs/_includes/options/data/selection-access.html
@@ -0,0 +1,40 @@
+<section>
+  <h2 id="selection-api-access">
+    How to programmatically access a selection data?
+  </h2>
+
+  <p>
+    There are few ways to programmatically access the selection data. Calling <code>select2('data')</code> will return the JavaScript array of an objects representing the current selection. Each object will have properties/values which was in the source data objects passed through <code>processResults</code> and <code>templateResult</code> functions (as in <a href="#data">Loading data from an array</a> and <a href="#ajax">Connecting to a remote data source</a>).
+  </p>
+
+{% highlight js linenos %}
+$('select').select2('data');
+{% endhighlight %}
+
+  <p>
+    As Select2 uses the HTML <code>&lt;SELECT&gt;</code> element to store the selection result, the selection data are represented by <code>&lt;OPTION&gt;</code> elements and can be accessed in the plain jQuery/DOM manner. The resulting elements will have properties/values from the source data objects, stored by the means of jQuery <code>data()</code> method and accessible by key <code>'data'</code>:
+  </p>
+
+{% highlight js linenos %}
+// Retrieve source data object's data of the first selected element
+$('select').find(':selected').data('data');
+{% endhighlight %}
+
+  <p>
+    Another technique is not to rely on jQuery's <code>data()</code> method but to extend the <code>&lt;OPTION&gt;</code> elements representing selection with the HTML data-* attributes containing arbitrary data from the source data objects:
+  </p>
+
+{% highlight js linenos %}
+$('select').select2({
+  // ...
+  templateSelection: function (data, container) {
+    $(data.element).attr('data-custom-attribute', data.customValue);
+    return data.text;
+  }
+});
+
+// Retrieve custom attribute value of the first selected element
+$('select').find(':selected').attr('data-custom-attribute')
+{% endhighlight %}
+
+</section>
\ No newline at end of file