upjs-rails 0.12.4 → 0.12.5

data/lib/assets/javascripts/up/navigation.js.coffee

@@ -18,8 +18,7 @@ up.navigation = (($) ->
   ###*
   Sets default options for this module.
 
-  @method up.navigation.config
-  @property
+  @property up.navigation.config
   @param {Number} [config.currentClasses]
     An array of classes to set on [links that point the current location](/up-current).
   ###
@@ -126,8 +125,7 @@ up.navigation = (($) ->
 
       <a href="/foo" up-follow up-current>Foo</a>
 
-  @ujs
-  @method [up-active]
+  @selector [up-active]
   ###
   sectionClicked = ($section) ->
     unmarkActive()
@@ -189,8 +187,7 @@ up.navigation = (($) ->
 
       <a href="/reports" up-alias="/reports/*">Reports</a>
 
-  @method [up-current]
-  @ujs
+  @selector [up-current]
   ###
   up.on 'up:fragment:inserted', ->
     # If a new fragment is inserted, it's likely to be the result

data/lib/assets/javascripts/up/popup.js.coffee

@@ -2,22 +2,46 @@
 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
 ###
@@ -29,7 +53,7 @@ up.popup = (($) ->
   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
   ###
@@ -38,7 +62,7 @@ up.popup = (($) ->
   ###*
   Returns the URL of the page or modal below the popup.
 
-  @method up.popup.coveredUrl
+  @function up.popup.coveredUrl
   @return {String}
   @protected
   ###
@@ -47,11 +71,17 @@ 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'
@@ -137,7 +167,7 @@ up.popup = (($) ->
   ###*
   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']
@@ -178,7 +208,7 @@ up.popup = (($) ->
   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).
   ###
@@ -223,8 +253,7 @@ up.popup = (($) ->
       <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]
   ###
@@ -259,8 +288,7 @@ up.popup = (($) ->
   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

data/lib/assets/javascripts/up/proxy.js.coffee

@@ -18,8 +18,9 @@ the user performs the click.
 Spinners
 --------
 
-You can listen to [framework events](/up.bus) to implement a spinner
-(progress indicator) that appears during a long-running request,
+You can [listen](/up.on) to the [`up:proxy:busy`](/up:proxy:busy)
+and [`up:proxy:idle`](/up:proxy:idle) events  to implement a spinner
+that appears during a long-running request,
 and disappears once the response has been received:
 
     <div class="spinner">Please wait!</div>
@@ -31,8 +32,8 @@ Here is the Javascript to make it alive:
       show = function() { $element.show() };
       hide = function() { $element.hide() };
 
-      showOff = up.on('proxy:busy', show);
-      hideOff = up.on('proxy:idle', hide);
+      showOff = up.on('up:proxy:busy', show);
+      hideOff = up.on('up:proxy:idle', hide);
 
       hide();
 
@@ -44,9 +45,9 @@ Here is the Javascript to make it alive:
 
     });
 
-The `proxy:busy` event will be emitted after a delay of 300 ms
+The `up:proxy:busy` event will be emitted after a delay of 300 ms
 to prevent the spinner from flickering on and off.
-You can change (or remove) this delay like this:
+You can change (or remove) this delay by [configuring `up.proxy`](/up.proxy.config) like this:
 
     up.proxy.config.busyDelay = 150;
 
@@ -63,8 +64,7 @@ up.proxy = (($) ->
   busyEventEmitted = undefined
 
   ###*
-  @method up.proxy.config
-  @property
+  @property up.proxy.config
   @param {Number} [config.preloadDelay=75]
     The number of milliseconds to wait before [`[up-preload]`](/up-preload)
     starts preloading.
@@ -100,25 +100,26 @@ up.proxy = (($) ->
 
   ###*
   @protected
-  @method up.proxy.get
+  @function up.proxy.get
   ###
   get = cache.get
 
   ###*
   @protected
-  @method up.proxy.set
+  @function up.proxy.set
   ###
   set = cache.set
 
   ###*
   @protected
-  @method up.proxy.remove
+  @function up.proxy.remove
   ###
   remove = cache.remove
 
   ###*
-  @protected
-  @method up.proxy.clear
+  Removes all cache entries.
+
+  @function up.proxy.clear
   ###
   clear = cache.clear
 
@@ -165,7 +166,7 @@ up.proxy = (($) ->
   Once the response is received, a `proxy:receive` event will
   be emitted.
   
-  @method up.proxy.ajax
+  @function up.proxy.ajax
   @param {String} request.url
   @param {String} [request.method='GET']
   @param {String} [request.selector]
@@ -222,7 +223,7 @@ up.proxy = (($) ->
   The proxy will also emit an `proxy:idle` [event](/up.bus) if it
   used to busy, but is now idle.
 
-  @method up.proxy.idle
+  @function up.proxy.idle
   @return {Boolean} Whether the proxy is idle
   ###
   idle = ->
@@ -235,7 +236,7 @@ up.proxy = (($) ->
   The proxy will also emit an `proxy:busy` [event](/up.bus) if it
   used to idle, but is now busy.
 
-  @method up.proxy.busy
+  @function up.proxy.busy
   @return {Boolean} Whether the proxy is busy
   ###
   busy = ->
@@ -245,6 +246,8 @@ up.proxy = (($) ->
     wasIdle = idle()
     pendingCount += 1
     if wasIdle
+      # Since the emission of up:proxy:busy might be delayed by config.busyDelay,
+      # we wrap the mission in a function for scheduling below.
       emission = ->
         if busy() # a fast response might have beaten the delay
           up.emit('up:proxy:busy')
@@ -254,19 +257,66 @@ up.proxy = (($) ->
       else
         emission()
 
+  ###*
+  This event is [emitted]/(up.emit) when [AJAX requests](/up.proxy.ajax)
+  are taking long to finish.
+
+  By default Up.js will wait 300 ms for an AJAX request to finish
+  before emitting `up:proxy:busy`. You can configure this time like this:
+
+      up.proxy.config.busyDelay = 150;
+
+  Once all responses have been received, an [`up:proxy:idle`](/up:proxy:idle)
+  will be emitted.
+
+  Note that if additional requests are made while Up.js is already busy
+  waiting, **no** additional `up:proxy:busy` events will be triggered.
+
+  @event up:proxy:busy
+  ###
+
   loadEnded = ->
     pendingCount -= 1
     if idle() && busyEventEmitted
       up.emit('up:proxy:idle')
       busyEventEmitted = false
 
+  ###*
+  This event is [emitted]/(up.emit) when [AJAX requests](/up.proxy.ajax)
+  have [taken long to finish](/up:proxy:busy), but have finished now.
+
+  @event up:proxy:busy
+  ###
+
   load = (request) ->
     u.debug('Loading URL %o', request.url)
     up.emit('up:proxy:load', request)
     promise = u.ajax(request)
-    promise.always -> up.emit('up:proxy:receive', request)
+    promise.always -> up.emit('up:proxy:received', request)
     promise
 
+  ###*
+  This event is [emitted]/(up.emit) before an [AJAX request](/up.proxy.ajax)
+  is starting to load.
+
+  @event up:proxy:load
+  @protected
+  @param event.url
+  @param event.method
+  @param event.selector
+  ###
+
+  ###*
+  This event is [emitted]/(up.emit) when the response to an [AJAX request](/up.proxy.ajax)
+  has been received.
+
+  @event up:proxy:received
+  @protected
+  @param event.url
+  @param event.method
+  @param event.selector
+  ###
+
   isIdempotent = (request) ->
     normalizeRequest(request)
     u.contains(SAFE_HTTP_METHODS, request.method)
@@ -286,7 +336,9 @@ up.proxy = (($) ->
 
   ###*
   @protected
-  @method up.proxy.preload
+  @function up.proxy.preload
+  @param {String|Element|jQuery}
+    The element whose destination should be preloaded.
   @return
     A promise that will be resolved when the request was loaded and cached
   ###
@@ -310,12 +362,11 @@ up.proxy = (($) ->
   response will already be cached when the user performs the click,
   making the interaction feel instant.   
 
-  @method [up-preload]
+  @selector [up-preload]
   @param [up-delay=75]
     The number of milliseconds to wait between hovering
     and preloading. Increasing this will lower the load in your server,
     but will also make the interaction feel less instant.
-  @ujs
   ###
   up.on 'mouseover mousedown touchstart', '[up-preload]', (event, $element) ->
     # Don't do anything if we are hovering over the child

data/lib/assets/javascripts/up/syntax.js.coffee

@@ -155,7 +155,7 @@ up.syntax = (($) ->
       });
 
   
-  @method up.compiler
+  @function up.compiler
   @param {String} selector
     The selector to match.
   @param {Boolean} [options.batch=false]
@@ -204,7 +204,7 @@ up.syntax = (($) ->
         else
           $matches.each -> applyCompiler(compiler, $(this), this)
 
-  destroy = ($fragment) ->
+  runDestroyers = ($fragment) ->
     u.findWithSelf($fragment, ".#{DESTROYABLE_CLASS}").each ->
       $element = $(this)
       destroyer = $element.data(DESTROYER_KEY)
@@ -220,14 +220,15 @@ up.syntax = (($) ->
   we can support getting or setting individual keys.
 
   @protected
-  @method up.syntax.data
+  @function up.syntax.data
   @param {String|Element|jQuery} elementOrSelector
-  ###
+  @return
+    The JSON-decoded value of the `up-data` attribute.
 
+    Returns an empty object (`{}`) if the element has no (or an empty) `up-data` attribute.
   ###
-  Looks for an `up-data` attribute on the given element, then parses
-  its value as JSON and returns the JSON object.
 
+  ###
   If an element annotated with [`up-data`] is inserted into the DOM,
   Up will parse the JSON and pass the resulting object to any matching
   [`up.compiler`](/up.syntax.compiler) handlers.
@@ -236,13 +237,9 @@ up.syntax = (($) ->
   [`up-data`], the parsed object will be passed to any matching
   [`up.on`](/up.on) handlers.
 
-  @ujs
-  @method [up-data]
-  @param {JSON} [up-data]
-  @return
-    The JSON-decoded value of the `up-data` attribute.
-
-    Returns an empty object (`{}`) if the element has no (or an empty) `up-data` attribute.
+  @selector [up-data]
+  @param {JSON} up-data
+    A serialized JSON string
   ###
   data = (elementOrSelector) ->
     $element = $(elementOrSelector)
@@ -284,7 +281,10 @@ up.syntax = (($) ->
       $element = $('<div>...</div>').appendTo(document.body);
       up.hello($element);
 
-  @method up.hello
+  This function emits the [`up:fragment:inserted`](/up:fragment:inserted)
+  event.
+
+  @function up.hello
   @param {String|Element|jQuery} selectorOrElement
   ###
   hello = (selectorOrElement) ->
@@ -292,9 +292,24 @@ up.syntax = (($) ->
     up.emit('up:fragment:inserted', $element: $element)
     $element
 
+  ###*
+  When a page fragment has been [inserted or updated](/up.replace),
+  this event is [emitted](/up.emit) on the fragment.
+
+  \#\#\#\# Example
+
+      up.on('up:fragment:inserted', function(event, $fragment) {
+        console.log("Looks like we have a new %o!", $fragment);
+      });
+
+  @event up:fragment:inserted
+  @param {jQuery} event.$element
+    The fragment that has been inserted or updated.
+  ###
+
   up.on 'ready', (-> hello(document.body))
   up.on 'up:fragment:inserted', (event) -> compile(event.$element)
-  up.on 'up:fragment:destroy', (event) -> destroy(event.$element)
+  up.on 'up:fragment:destroy', (event) -> runDestroyers(event.$element)
   up.on 'up:framework:boot', snapshot
   up.on 'up:framework:reset', reset