unpoly-rails 0.28.1 → 0.29.0

data/lib/assets/javascripts/unpoly/modal.js.coffee

@@ -2,28 +2,40 @@
 Modal dialogs
 =============
 
-Instead of [linking to a page fragment](/up.link), you can choose
-to show a fragment in a modal dialog. The existing page will remain
-open in the background and reappear once the modal is closed.
+Instead of [linking to a page fragment](/up.link), you can choose to show a fragment
+in a modal dialog. The existing page will remain open in the background.
 
-To open a modal, add an [`up-modal` attribute](/up-modal) to a link,
-or call the Javascript functions [`up.modal.follow`](/up.modal.follow)
-and [`up.modal.visit`](/up.modal.visit).
-  
-For smaller popup overlays ("dropdowns") see [up.popup](/up.popup) instead.
+To open a modal, add an [`up-modal`](/up-modal) attribute to a link:
+
+    <a href="/blogs" up-modal=".blog-list">Switch blog</a>
+
+When this link is clicked, Unpoly will request the path `/blogs` and extract
+an element matching the selector `.blog-list` from the response. The matching element
+will then be placed in a modal dialog.
+
+
+\#\#\# Closing behavior
+
+By default the dialog automatically closes
+*when a link inside a modal changes a fragment behind the modal*.
+This is useful to have the dialog 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`](/up-modal#up-sticky) attribute:
 
 
-\#\#\#\# Customizing the dialog design
+\#\#\# Customizing the dialog design
 
-Loading the Unpoly stylesheet will give you a minimal dialog design:
+Dialogs have a minimal default design:
 
-- Dialog contents are displayed in a white box that is centered vertically and horizontally.
-- There is a a subtle box shadow around the dialog
+- Contents are displayed in a white box with a subtle box shadow
 - The box will grow to fit the dialog contents, but never grow larger than the screen
-- The box is placed over a semi-transparent background to dim the rest of the page
+- The box is placed over a semi-transparent backdrop to dim the rest of the page
 - There is a button to close the dialog in the top-right corner
 
-The easiest way to change how the dialog looks is by overriding the [default CSS styles](https://github.com/unpoly/unpoly/blob/master/lib/assets/stylesheets/up/modal.css.sass).
+The easiest way to change how the dialog looks is by overriding the
+[default CSS styles](https://github.com/unpoly/unpoly/blob/master/lib/assets/stylesheets/up/modal.css.sass).
 
 By default the dialog uses the following DOM structure:
 
@@ -32,28 +44,15 @@ By default the dialog uses the following DOM structure:
       <div class="up-modal-viewport">
         <div class="up-modal-dialog">
           <div class="up-modal-content">
-            ...
+            <!-- the matching element will be placed here -->
           </div>
           <div class="up-modal-close" up-close>X</div>
         </div>
       </div>
     </div>
 
-If you want to change the design beyond CSS, you can
-configure Unpoly to [use a different HTML structure](/up.modal.config).
-
-
-\#\#\#\# Closing behavior
-
-By default the dialog automatically closes
-*when a link inside a modal changes a fragment behind the modal*.
-This is useful to have the dialog 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-modal=".options" up-sticky>Settings</a>
+You can change this structure by setting [`up.modal.config.template`](/up.modal.config#config.template) to a new template string
+or function.
 
 
 @class up.modal
@@ -69,7 +68,7 @@ up.modal = (($) ->
   @param {String} [config.history=true]
     Whether opening a modal will add a browser history entry.
   @param {Number} [config.width]
-    The width of the dialog as a CSS value like `'400px'` or `50%`.
+    The width of the dialog as a CSS value like `'400px'` or `'50%'`.
 
     Defaults to `undefined`, meaning that the dialog will grow to fit its contents
     until it reaches `config.maxWidth`. Leaving this as `undefined` will
@@ -562,7 +561,7 @@ up.modal = (($) ->
   ###*
   Register a new modal variant with its own default configuration, CSS or HTML template.
 
-  \#\#\#\# Example
+  \#\#\# Example
 
   Let's implement a drawer that slides in from the right:
 
@@ -670,11 +669,12 @@ up.modal = (($) ->
 
   # Close the modal when someone clicks outside the dialog
   # (but not on a modal opener).
-  up.on('click', 'body', (event, $body) ->
+  up.on('click', (event) ->
     return unless state.closable
 
     $target = $(event.target)
     unless $target.closest('.up-modal-dialog').length || $target.closest('[up-modal]').length
+      up.bus.consumeAction(event)
       closeAsap()
   )
 
@@ -706,10 +706,11 @@ up.modal = (($) ->
   up.on('click', '[up-close]', (event, $element) ->
     if contains($element)
       closeAsap()
-      # Only prevent the default when we actually closed a modal.
-      # This way we can have buttons that close a modal when within a modal,
-      # but link to a destination if not.
-      event.preventDefault()
+      # If the user closes the modal by clicking on the background, we want to halt the event chain here.
+      # The event should not trigger anything else. The user needs to click again for another interaction.
+      # Also only prevent the default when we actually closed a modal.
+      # This way we can have buttons that close a modal when within a modal, but link to a destination if not.
+      up.bus.consumeAction(event)
   )
 
   # The framework is reset between tests

data/lib/assets/javascripts/unpoly/motion.js.coffee

@@ -2,35 +2,32 @@
 Animation
 =========
   
-Whenever you update a page fragment (through methods like
-[`up.replace`](/up.replace) or UJS attributes like [`up-target`](/up-target))
-you can animate the change.
+Whenever you [update a page fragment](/up-link) you can animate the change.
 
-For instance, when you replace a selector `.list` with a new `.list`
-from the server, you can add an `up-transition="cross-fade"` attribute
-to smoothly fade out the old `.list` while fading in the new `.list`:
+Let's say you are using an [`up-target`](/a-up-target) link to update an element
+with content from the server. You can add an attribute [`up-transition`](/a-up-target#up-transition)
+to smoothly fade out the old element while fading in the new element:
 
     <a href="/users" up-target=".list" up-transition="cross-fade">Show users</a>
 
-Transitions vs. animations
---------------------------
+\#\#\# Transitions vs. animations
 
-When we morph between an old an new element, we call it a *transition*.
+When we morph between an old and a new element, we call it a *transition*.
 In contrast, when we animate a new element without simultaneously removing an
 old element, we call it an *animation*.
 
-An example for an animation is opening a new dialog, which we can animate
-using the `up-animation` attribute:
+An example for an animation is opening a new dialog. We can animate the appearance
+of the dialog by adding an [`up-animation`](/up-modal#up-animation) attribute to the opening link:
 
     <a href="/users" up-modal=".list" up-animation="move-from-top">Show users</a>
 
-Predefined animations and transitions
--------------------------------------
+\#\#\# Which animations are available?
 
-Unpoly ships with a number of predefined [animations](/up.animate#named-animation)
-and [transitions](/up.morph#named-animation).
-You can also easily [define your own animations](/up.animation)
-or [transitions](/up.transition) using Javascript or CSS.
+Unpoly ships with a number of [predefined transitions](/up.morph#named-transitions)
+and [predefined animations](/up.animate#named-animations).
+
+You can define custom animations using [`up.transition`](/up.transition) and
+[`up.animation`](/up.animation).
 
 @class up.motion
 ###
@@ -95,7 +92,7 @@ up.motion = (($) ->
   ###*
   Applies the given animation to the given element.
 
-  \#\#\#\# Example
+  \#\#\# Example
 
       up.animate('.warning', 'fade-in');
 
@@ -107,7 +104,7 @@ up.motion = (($) ->
         easing: 'linear'
       });
 
-  \#\#\#\# Named animations
+  \#\#\# Named animations
 
   The following animations are pre-defined:
 
@@ -125,7 +122,7 @@ up.motion = (($) ->
 
   You can define additional named animations using [`up.animation`](/up.animation).
 
-  \#\#\#\# Animating CSS properties directly
+  \#\#\# Animating CSS properties directly
 
   By passing an object instead of an animation name, you can animate
   the CSS properties of the given element:
@@ -134,7 +131,7 @@ up.motion = (($) ->
       $warning.css({ opacity: 0 });
       up.animate($warning, { opacity: 1 });
 
-  \#\#\#\# Multiple animations on the same element
+  \#\#\# Multiple animations on the same element
 
   Unpoly doesn't allow more than one concurrent animation on the same element.
 
@@ -312,7 +309,7 @@ up.motion = (($) ->
   Note that the transition does not remove any elements from the DOM.
   The first element will remain in the DOM, albeit hidden using `display: none`.
 
-  \#\#\#\# Named transitions
+  \#\#\# Named transitions
 
   The following transitions are pre-defined:
 
@@ -331,7 +328,7 @@ up.motion = (($) ->
   - `move-to-bottom/fade-in`
   - `move-to-left/move-from-top`
 
-  \#\#\#\# Implementation details
+  \#\#\# Implementation details
 
   During a transition both the old and new element occupy
   the same position on the screen.

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

@@ -2,12 +2,36 @@
 Navigation bars
 ===============
 
-Unpoly automatically marks up link elements with classes indicating that
-they are currently loading (class `up-active`) or linking
-to the current location (class `up-current`).
+Unpoly automatically adds CSS classes to links while they are
+currently loading ([`.up-active`](/up-active)) or
+pointing to the current location ([`.up-current`](/up-current)).
+
+By styling these classes with CSS you can provide instant feedback to user interactions.
+This improves the perceived speed of your interface.
+
+\#\#\# Example
+
+Let's say we have an navigation bar with two links, pointing to `/foo` and `/bar` respectively:
+
+    <a href="/foo" up-follow>Foo</a>
+    <a href="/bar" up-follow>Bar</a>
+
+If the current URL is `/foo`, the first link is automatically marked with an [`up-current`](/up-current) class:
+
+    <a href="/foo" up-follow class="up-current">Foo</a>
+    <a href="/bar" up-follow>Bar</a>
+
+When the user clicks on the `/bar` link, the link will receive the [`up-active`](/up-active) class while it is waiting
+for the server to respond:
+
+    <a href="/foo" up-follow class="up-current">Foo</a>
+    <a href="/bar" up-follow class="up-active">Bar</a>
+
+Once the response is received the URL will change to `/bar` and the `up-active` class is removed:
+
+    <a href="/foo" up-follow>Foo</a>
+    <a href="/bar" up-follow class="up-current">Bar</a>
 
-This dramatically improves the perceived speed of your user interface
-by providing instant feedback for user interactions.
 
 @class up.navigation
 ###
@@ -96,20 +120,64 @@ up.navigation = (($) ->
         $section.removeClass(klass)
 
   ###*
-  @function findClickArea
+  @function findActionableArea
   @param {String|Element|jQuery} elementOrSelector
-  @param {Boolean} options.enlarge
-    If `true`, tries to find a containing link that has expanded the link's click area.
-    If we find one, we prefer to mark the larger area as active.
   @internal
   ###
-  findClickArea = (elementOrSelector, options) ->
+  findActionableArea = (elementOrSelector) ->
     $area = $(elementOrSelector)
-    options = u.options(options, enlarge: false)
-    if options.enlarge
-      u.presence($area.parent(SELECTOR_SECTION)) || $area
-    else
-      $area
+    if $area.is(SELECTOR_SECTION)
+      # Try to enlarge links that are expanded with [up-expand] on a surrounding container.
+      $area = u.presence($area.parent(SELECTOR_SECTION)) || $area
+    $area
+
+  ###*
+  Marks the given element as currently loading, by assigning the CSS class [`up-active`](/up-active).
+
+  This happens automatically when following links or submitting forms through the Unpoly API.
+  Use this function if you make custom network calls from your own Javascript code.
+
+  If the given element is a link within an [expanded click area](/up-expand),
+  the class will be assigned to the expanded area.
+
+  \#\#\# Example
+
+      var $button = $('button');
+      $button.on('click', function() {
+        up.navigation.start($button);
+        up.ajax(...).always(function() {
+          up.navigation.stop($button);
+        });
+      });
+
+  Or shorter:
+
+      var $button = $('button');
+      $button.on('click', function() {
+        up.navigation.start($button, function() {
+          up.ajax(...);
+        });
+      });
+
+  @method up.navigation.start
+  @param {Element|jQuery|String} elementOrSelector
+    The element to mark as active
+  @param {Function} [action]
+    An optional function to run while the element is marked as loading.
+    The function must return a promise.
+    Once the promise resolves, the element will be [marked as no longer loading](/up.navigation.stop).
+  @internal
+  ###
+  start = (elementOrSelector, action) ->
+    $element = findActionableArea(elementOrSelector)
+    $element.addClass(CLASS_ACTIVE)
+    if action
+      promise = action()
+      if u.isPromise(promise)
+        promise.always -> stop($element)
+      else
+        up.warn('Expected block to return a promise, but got %o', promise)
+      promise
 
   ###*
   Links that are currently loading are assigned the `up-active`
@@ -119,7 +187,7 @@ up.navigation = (($) ->
   The `up-active` class will be removed as soon as another
   page fragment is added or updated through Unpoly.
 
-  \#\#\#\# Example
+  \#\#\# Example
 
   We have a link:
 
@@ -138,25 +206,22 @@ up.navigation = (($) ->
   @selector .up-active
   @stable
   ###
-  markActive = (elementOrSelector, options) ->
-    $element = findClickArea(elementOrSelector, options)
-    $element.addClass(CLASS_ACTIVE)
 
-  unmarkActive = (elementOrSelector, options) ->
-    $element = findClickArea(elementOrSelector, options)
-    $element.removeClass(CLASS_ACTIVE)
+  ###*
+  Marks the given element as no longer loading, by removing the CSS class [`up-active`](/up-active).
+
+  This happens automatically when network requests initiated by the Unpoly API have completed.
+  Use this function if you make custom network calls from your own Javascript code.
 
-  withActiveMark = (elementOrSelector, args...) ->
-    block = args.pop()
-    options = u.options(args.pop())
-    $element = $(elementOrSelector)
-    markActive($element, options)
-    promise = block()
-    if u.isPromise(promise)
-      promise.always -> unmarkActive($element, options)
-    else
-      up.warn('Expected block to return a promise, but got %o', promise)
-    promise
+  @function up.navigation.stop
+  @param {jQuery} event.$element
+    The link or form that has finished loading.
+  @internal
+  ###
+  stop = (elementOrSelector) ->
+    $element = findActionableArea(elementOrSelector)
+    up.emit('up:navigated', $element: $element, message: false)
+    $element.removeClass(CLASS_ACTIVE)
 
   ###*
   Links that point to the current location are assigned
@@ -176,7 +241,7 @@ up.navigation = (($) ->
         <a href="/bar">Bar</a>
       </nav>
 
-  \#\#\#\# What's considered to be "current"?
+  \#\#\# What's considered to be "current"?
 
   The current location is considered to be either:
 
@@ -222,8 +287,7 @@ up.navigation = (($) ->
 
   config: config
   defaults: -> up.fail('up.navigation.defaults(...) no longer exists. Set values on he up.navigation.config property instead.')
-  markActive: markActive
-  unmarkActive: unmarkActive
-  withActiveMark: withActiveMark
+  start: start
+  stop: stop
 
 )(jQuery)

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

@@ -10,7 +10,7 @@ or call the Javascript function [`up.popup.attach`](/up.popup.attach).
 
 For modal dialogs see [up.modal](/up.modal) instead.
 
-\#\#\#\# Customizing the popup design
+\#\#\# Customizing the popup design
 
 Loading the Unpoly stylesheet will give you a minimal popup design:
 
@@ -26,7 +26,7 @@ By default the popup uses the following DOM structure:
       ...
     </div>
 
-\#\#\#\# Closing behavior
+\#\#\# Closing behavior
 
 The popup closes when the user clicks anywhere outside the popup area.
 
@@ -176,14 +176,22 @@ up.popup = (($) ->
   Emits events [`up:popup:open`](/up:popup:open) and [`up:popup:opened`](/up:popup:opened).
 
   @function up.popup.attach
-  @param {Element|jQuery|String} elementOrSelector
+  @param {Element|jQuery|String} anchor
+    The element to which the popup will be attached.
   @param {String} [options.url]
+    The URL from which to fetch the popup contents.
+
+    If omitted, the `href` or `up-href` attribute of the anchor element will be used.
+
+    Will be ignored if `options.html` is given.
   @param {String} [options.target]
     A CSS selector that will be extracted from the response and placed into the popup.
   @param {String} [options.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`.
+  @param {String} [options.html]
+    A string of HTML from which to extract the popup contents. No network request will be made.
   @param {String} [options.confirm]
     A message that will be displayed in a cancelable confirmation dialog
     before the modal is being opened.
@@ -382,29 +390,30 @@ up.popup = (($) ->
 
   @stable
   ###
-  up.link.onAction('[up-popup]', ($link) ->
+  up.link.onAction '[up-popup]', ($link) ->
     if $link.is('.up-current')
       closeAsap()
     else
       attachAsap($link)
-  )
 
-  # Close the popup when someone clicks outside the popup
-  # (but not on a popup opener).
-  up.on('mousedown', 'body', (event, $body) ->
+  # We close the popup when someone clicks on the document.
+  # We also need to listen to up:action:consumed in case an [up-instant] link
+  # was followed on mousedown.
+  up.on 'click up:action:consumed', (event) ->
     $target = $(event.target)
+    # Don't close when the user clicked on a popup opener.
     unless $target.closest('.up-popup, [up-popup]').length
       closeAsap()
-  )
-  
-  up.on('up:fragment:inserted', (event, $fragment) ->
+      # Do not halt the event chain here. The user is allowed to directly activate
+      # a link in the background, even with a (now closing) popup open.
+
+  up.on 'up:fragment:inserted', (event, $fragment) ->
     if contains($fragment)
       if newSource = $fragment.attr('up-source')
         state.url = newSource
     else if contains(event.origin)
       autoclose()
-  )
-  
+
   # Close the pop-up overlay when the user presses ESC.
   up.bus.onEscape(closeAsap)
 
@@ -422,14 +431,13 @@ up.popup = (($) ->
   @selector [up-close]
   @stable
   ###
-  up.on('click', '[up-close]', (event, $element) ->
+  up.on 'click', '[up-close]', (event, $element) ->
     if contains($element)
       closeAsap()
       # Only prevent the default when we actually closed a popup.
       # This way we can have buttons that close a popup when within a popup,
       # but link to a destination if not.
-      event.preventDefault()
-  )
+      up.bus.consumeAction(event)
 
   # The framework is reset between tests
   up.on 'up:framework:reset', reset