From b4fdf27023b4d3f0329c7e4c9ea0778695ae8cf9 Mon Sep 17 00:00:00 2001
From: Samuel Georges <sam@daftspunk.com>
Date: Sat, 26 Sep 2015 08:24:16 +1000
Subject: [PATCH] Tidy up popups docs

---
 modules/system/assets/ui/docs/popup.md | 71 ++++++++++++++++++++++----
 1 file changed, 62 insertions(+), 9 deletions(-)

diff --git a/modules/system/assets/ui/docs/popup.md b/modules/system/assets/ui/docs/popup.md
index 682a6b885..4c33c5549 100644
--- a/modules/system/assets/ui/docs/popup.md
+++ b/modules/system/assets/ui/docs/popup.md
@@ -1,13 +1,17 @@
 # Popups
 
-Displays a modal popup
+Displays a modal popup, based on the Bootstrap modal implementation.
 
-# Example
+- [Examples](#examples)
+- [Inline popups](#inline-popups)
+- [Remote popups](#remote-popups)
 
-    <!-- Basic Popup -->
-    <a data-toggle="modal" href="#content-basic" class="btn btn-primary btn-lg">Launch basic content</a>
+<a name="examples"></a>
+## Examples
 
-    <div class="control-popup modal fade" id="content-basic" tabindex="-1" role="dialog">
+    <a data-toggle="modal" href="#contentBasic" class="btn btn-primary btn-lg">Launch basic content</a>
+
+    <div class="control-popup modal fade" id="contentBasic" tabindex="-1" role="dialog">
         <div class="modal-dialog">
             <div class="modal-content">
                 <div class="modal-body">
@@ -18,8 +22,6 @@ Displays a modal popup
         </div>
     </div>
 
-
-    <!-- Confirmation Popup -->
     <a data-toggle="modal" href="#content-confirmation" class="btn btn-primary btn-lg">Launch Confirmation dialog</a>
 
     <div class="control-popup modal fade" id="content-confirmation" tabindex="-1" role="dialog">
@@ -41,5 +43,56 @@ Displays a modal popup
         </div>
     </div>
 
-    <!-- Ajax Popup -->
-    <a data-control="popup" data-ajax="popup-content.htm" href="javascript:;" class="btn btn-primary btn-lg">Launch Ajax Form</a>
+<a name="inline-popups"></a>
+## Inline popups
+
+An inline popup places the popup content inside the current page, hidden from the view. For example, this container will not be visible on the page.
+
+```html
+<div class="control-popup modal fade" id="contentBasic">
+    <div class="modal-dialog">
+        <div class="modal-content">
+            <div class="modal-body">
+                <button type="button" class="close" data-dismiss="modal">&times;</button>
+                <p>This is a very basic example of a popup...</p>
+            </div>
+        </div>
+    </div>
+</div>
+```
+
+Use the `data-toggle="modal"` HTML attribute to launch this container as a popup.
+
+```html
+<a data-toggle="modal" href="#contentBasic" class="btn btn-primary btn-lg">
+    Launch basic content
+</a>
+```
+
+<a name="remote-popups"></a>
+## Remote popups
+
+Content for the popup can be loaded remotely using an AJAX request. Use the `data-handler` attribute to populate a popup with the contents of an AJAX handler.
+
+```html
+<a
+    data-control="popup"
+    data-handler="onLoadContent"
+    href="javascript:;"
+    class="btn btn-primary btn-lg">
+    Launch Ajax Form
+</a>
+```
+
+Using the `data-ajax` attribute you can refer to an external file or URL directly.
+
+```html
+<a
+    data-control="popup"
+    data-ajax="popup-content.htm"
+    href="javascript:;"
+    class="btn btn-primary btn-lg">
+    Launch Ajax Form
+</a>
+```
+