From 275ae051283f1de8d7473d661c32692032ee92fb Mon Sep 17 00:00:00 2001
From: alexweissman <alex@alexanderweissman.com>
Date: Mon, 11 Sep 2017 21:06:38 -0400
Subject: [PATCH] Clarify #4244 and retrieval of selected items populated via
 AJAX

---
 .../02.retrieving-selections/docs.md                     | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/pages/12.programmatic-control/02.retrieving-selections/docs.md b/pages/12.programmatic-control/02.retrieving-selections/docs.md
index d0f8dd7f..41e0164c 100644
--- a/pages/12.programmatic-control/02.retrieving-selections/docs.md
+++ b/pages/12.programmatic-control/02.retrieving-selections/docs.md
@@ -10,7 +10,7 @@ There are two ways to programmatically access the current selection data: using
 
 ## Using the `data` method
 
-Calling `select2('data')` will return a JavaScript array of objects representing the current selection. Each object will contain all of the properties/values that were in the source data objects passed through `processResults` and `templateResult` callbacks (as in <a href="#data">Loading data from an array</a> and <a href="#ajax">Connecting to a remote data source</a>).
+Calling `select2('data')` will return a JavaScript array of objects representing the current selection. Each object will contain all of the properties/values that were in the source data objects passed through `processResults` and `templateResult` callbacks.
 
 ```
 $('#mySelect2').select2('data');
@@ -24,17 +24,20 @@ Selected items can also be accessed via the `:selected` jQuery selector:
 $('#mySelect2').find(':selected');
 ```
 
-It is possible to extend the `<option>` elements representing selection with the HTML data-* attributes containing arbitrary data from the source data objects:
+It is possible to extend the `<option>` elements representing the current selection(s) with HTML `data-*` attributes to contain arbitrary data from the source data objects:
 
 ```
 $('#mySelect2').select2({
   // ...
   templateSelection: function (data, container) {
+    // Add custom attributes to the <option> tag for the selected option
     $(data.element).attr('data-custom-attribute', data.customValue);
     return data.text;
   }
 });
 
 // Retrieve custom attribute value of the first selected element
-$('#mySelect2').find(':selected').attr('data-custom-attribute')
+$('#mySelect2').find(':selected').data('custom-attribute');
 ```
+
+>>>> Do not rely on the `selected` attribute of `<option>` elements to determine the currently selected item(s).  Select2 does not add the `selected` attribute when an element is created from a remotely-sourced option.  See [this issue](https://github.com/select2/select2/issues/3366#issuecomment-102566500) for more information.