From 94b14f35a5afe6fbdd7ffd66a710a23c0192011c Mon Sep 17 00:00:00 2001
From: alexweissman <alex@alexanderweissman.com>
Date: Mon, 11 Sep 2017 17:54:22 -0400
Subject: [PATCH] clarify some basic JS and jQuery concepts

---
 .../01.getting-started/02.basic-usage/docs.md | 23 ++++++++++++++-----
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/pages/01.getting-started/02.basic-usage/docs.md b/pages/01.getting-started/02.basic-usage/docs.md
index d0aef025..0eea33c1 100644
--- a/pages/01.getting-started/02.basic-usage/docs.md
+++ b/pages/01.getting-started/02.basic-usage/docs.md
@@ -31,16 +31,21 @@ and turn it into this...
 
 <script type="text/javascript" class="js-code-example-basic-single">
 $(document).ready(function() {
-  $(".js-example-basic-single").select2();
+    $('.js-example-basic-single').select2();
 });
 </script>
 
 Select2 will register itself as a jQuery function if you use any of the distribution builds, so you can call `.select2()` on any jQuery selector where you would like to initialize Select2.
 
 ```
-$('.js-example-basic-single').select2();
+// In your Javascript (external .js resource or <script> tag)
+$(document).ready(function() {
+    $('.js-example-basic-single').select2();
+});
 ```
 
+>>>>>> The DOM cannot be safely manipulated until it is "ready".  To make sure that your DOM is ready before the browser initializes the Select2 control, wrap your code in a [`$(document).ready()`](https://learn.jquery.com/using-jquery-core/document-ready/) block.  Only one `$(document).ready()` block is needed per page.
+
 ## Multi-select boxes (pillbox)
 
 Select2 also supports multi-value select boxes. The select below is declared with the `multiple` attribute.
@@ -51,11 +56,9 @@ Select2 also supports multi-value select boxes. The select below is declared wit
   </p>
 </div>
 
-```
-<script type="text/javascript">
-$(".js-example-basic-multiple").select2();
-</script>
+**In your HTML:**
 
+```
 <select class="js-example-basic-multiple" multiple="multiple">
   <option value="AL">Alabama</option>
     ...
@@ -63,6 +66,14 @@ $(".js-example-basic-multiple").select2();
 </select>
 ```
 
+**In your Javascript (external `.js` resource or `<script>` tag):**
+
+```
+$(document).ready(function() {
+    $('.js-example-basic-multiple').select2();
+});
+```
+
 <script type="text/javascript">
   $.fn.select2.amd.require([
     "select2/core",