popup.js.coffee in upjs-rails-0.12.5

- old
+ new

@@ -1,59 +1,89 @@
 ###*
 Pop-up overlays
 ===============
 
-Instead of linking to another page fragment, you can also choose
-to "roll up" any target CSS selector in a popup overlay. 
-Popup overlays close themselves if the user clicks somewhere outside the
-popup area. 
-  
+Instead of [linking to a page fragment](/up.link), you can choose
+to show a fragment in a popup overlay.
+
+To open a popup, add an [`up-popup` attribute](/a-up-popup) to a link,
+or call the Javascript function [`up.popup.attach`](/up.popup.attach).
+
 For modal dialogs see [up.modal](/up.modal) instead.
-  
-\#\#\# Incomplete documentation!
-  
-We need to work on this page:
 
-- Show the HTML structure of the popup elements, and how to style them via CSS
-- Explain how to position popup using `up-position`
-- Explain how dialogs auto-close themselves when a fragment changes behind the popup layer
-- Document method parameters
+
+\#\#\#\# Customizing the popup design
+
+Loading the Up.js stylesheet will give you a minimal popup design:
+
+- Popup contents are displayed in a white box
+- There is a a subtle box shadow around the popup
+- The box will grow to fit the popup contents
+
+The easiest way to change how the popup looks is by overriding the [default CSS styles](https://github.com/makandra/upjs/blob/master/lib/assets/stylesheets/up/popup.css.sass).
+
+By default the popup uses the following DOM structure:
+
+    <div class="up-popup">
+      ...
+    </div>
+
+
+\#\#\#\# Closing behavior
+
+The popup closes when the user clicks anywhere outside the popup area.
+
+By default the popup also closes
+*whenever a page fragment below the popup is updated*.
+This is useful to have the popup interact with the page that
+opened it, e.g. by updating parts of a larger form or by signing in a user
+and revealing additional information.
+
+To disable this behavior, give the opening link an `up-sticky` attribute:
+
+    <a href="/settings" up-popup=".options" up-sticky>Settings</a>
+
   
-  
 @class up.popup
 ###
 up.popup = (($) ->
 
   u = up.util
 
   ###*
   Returns the source URL for the fragment displayed
   in the current popup, or `undefined` if no  popup is open.
 
-  @method up.popup.url
+  @function up.popup.url
   @return {String}
     the source URL
   ###
   currentUrl = undefined
 
   ###*
   Returns the URL of the page or modal below the popup.
 
-  @method up.popup.coveredUrl
+  @function up.popup.coveredUrl
   @return {String}
   @protected
   ###
   coveredUrl = ->
     $popup = $('.up-popup')
     $popup.attr('up-covered-url')
 
   ###*
-  @method up.popup.config
-  @property
-  @param {String} [config.openAnimation]
-  @param {String} [config.closeAnimation]
-  @param {String} [config.position]
+  Sets default options for future popups.
+
+  @property up.popup.config
+  @param {String} [config.openAnimation='fade-in']
+    The animation used to open a popup.
+  @param {String} [config.closeAnimation='fade-out']
+    The animation used to close a popup.
+  @param {String} [config.position='bottom-right']
+    Defines where the popup is attached to the opening element.
+
+    Valid values are `bottom-right`, `bottom-left`, `top-right` and `top-left`.
   ###
   config = u.config
     openAnimation: 'fade-in'
     closeAnimation: 'fade-out'
     position: 'bottom-right'
@@ -135,11 +165,11 @@
     up.animate($popup, animation, animateOptions)
     
   ###*
   Attaches a popup overlay to the given element or selector.
   
-  @method up.popup.attach
+  @function up.popup.attach
   @param {Element|jQuery|String} elementOrSelector
   @param {String} [options.url]
   @param {String} [options.position='bottom-right']
   @param {String} [options.animation]
     The animation to use when opening the popup.
@@ -176,11 +206,11 @@
     
   ###*
   Closes a currently opened popup overlay.
   Does nothing if no popup is currently open.
   
-  @method up.popup.close
+  @function up.popup.close
   @param {Object} options
     See options for [`up.animate`](/up.animate).
   ###
   close = (options) ->
     $popup = $('.up-popup')
@@ -221,12 +251,11 @@
   if a page fragment below the popup overlay updates:
 
       <a href="/decks" up-popup=".deck_list">Switch deck</a>
       <a href="/settings" up-popup=".options" up-sticky>Settings</a>
 
-  @method a[up-popup]
-  @ujs
+  @selector a[up-popup]
   @param [up-sticky]
   @param [up-position]
   ###
   up.on('click', 'a[up-popup]', (event, $link) ->
     event.preventDefault()
@@ -257,11 +286,10 @@
 
   ###*
   When an element with this attribute is clicked,
   a currently open popup is closed. 
   
-  @method [up-close]
-  @ujs
+  @selector [up-close]
   ###
   up.on('click', '[up-close]', (event, $element) ->
     if $element.closest('.up-popup').length
       close()
       # Only prevent the default when we actually closed a popup.