upjs-rails 0.12.1 → 0.12.2

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

@@ -16,9 +16,7 @@ We need to work on this page:
 - Explain that the server needs to send `X-Up-Location` and `X-Up-Method` headers
   if an successful form submission resulted in a redirect
 - Examples
-  
 
-  
 @class up.form
 ###
 up.form = (($) ->
@@ -66,15 +64,15 @@ up.form = (($) ->
     The transition to use when a failed form submission updates the `options.failTarget` selector.
     Defaults to the form's `up-fail-transition` attribute, or to `options.transition`, or to `'none'`.
   @param {Number} [options.duration]
-    The duration of the transition. See [`up.morph`](/up.motion#up.morph).
+    The duration of the transition. See [`up.morph`](/up.morph).
   @param {Number} [options.delay]
-    The delay before the transition starts. See [`up.morph`](/up.motion#up.morph).
+    The delay before the transition starts. See [`up.morph`](/up.morph).
   @param {String} [options.easing]
-    The timing function that controls the transition's acceleration. [`up.morph`](/up.motion#up.morph).
+    The timing function that controls the transition's acceleration. [`up.morph`](/up.morph).
   @param {Element|jQuery|String} [options.reveal]
     Whether to reveal the target element within its viewport.
   @param {Boolean} [options.restoreScroll]
-    If set to `true`, this will attempt to [`restore scroll positions`](/up.layout#up.restoreScroll)
+    If set to `true`, this will attempt to [`restore scroll positions`](/up.restoreScroll)
     previously seen on the destination URL.
   @param {Boolean} [options.cache]
     Whether to force the use of a cached response (`true`)
@@ -153,7 +151,7 @@ up.form = (($) ->
   For instance, the following would submit the form whenever the
   text field value changes:
 
-      up.observe('input', { change: function(value, $input) {
+      up.observe('input[name=query]', { change: function(value, $input) {
         up.submit($input)
       } });
 
@@ -170,8 +168,8 @@ up.form = (($) ->
   \#\#\#\# Throttling
 
   If you are concerned about fast typists causing too much
-  load on your server, you can use a `delay` option to wait before
-  executing the callback:
+  load on your server, you can use a `delay` option to wait
+  a few miliseconds before executing the callback:
 
       up.observe('input', {
         delay: 100,
@@ -269,7 +267,7 @@ up.form = (($) ->
 
   ###*
   Submits the form through AJAX, searches the response for the selector
-  given in `up-target` and replaces the selector content in the current page:
+  given in `up-target` and [replaces](/up.replace) the selector content in the current page:
 
       <form method="post" action="/users" up-target=".main">
         ...
@@ -278,11 +276,16 @@ up.form = (($) ->
   @method form[up-target]
   @ujs
   @param {String} up-target
-    The selector to replace if the form submission is successful (200 status code).
+    The selector to [replace](/up.replace) if the form submission is successful (200 status code).
   @param {String} [up-fail-target]
+    The selector to [replace](/up.replace) if the form submission is not successful (non-200 status code).
+    If omitted, Up.js will replace the `<form>` tag itself, assuming that the
+    server has echoed the form with validation errors.
   @param {String} [up-transition]
+    The animation to use when the form is replaced after a successful submission.
   @param {String} [up-fail-transition]
-  @param {String} [up-history]
+    The animation to use when the form is replaced after a failed submission.
+  @param {String} [up-history='true']
   @param {String} [up-method]
     The HTTP method to be used to submit the form (`get`, `post`, `put`, `delete`, `patch`).
     Alternately you can use an attribute `data-method`

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

@@ -34,8 +34,8 @@ up.history = (($) ->
   Returns the previous URL in the browser history.
 
   Note that this will only work reliably for history changes that
-  were applied by [`up.history.push`](#up.history.replace) or
-  [`up.history.replace`](#up.history.replace).
+  were applied by [`up.history.push`](/up.history.replace) or
+  [`up.history.replace`](/up.history.replace).
 
   @method up.history.previousUrl
   @protected

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

@@ -1,5 +1,5 @@
 ###*
-Viewport scrolling
+Application layout
 ==================
 
 This modules contains functions to scroll the viewport and reveal contained elements.
@@ -35,10 +35,10 @@ up.layout = (($) ->
     See [W3C documentation](http://www.w3.org/TR/css3-transitions/#transition-timing-function)
     for a list of pre-defined timing functions.
   @param {Number} [config.snap]
-    When [revealing](#up.reveal) elements, Up.js will scroll an viewport
+    When [revealing](/up.reveal) elements, Up.js will scroll an viewport
     to the top when the revealed element is closer to the top than `config.snap`.
   @param {Number} [config.substance]
-    A number indicating how many top pixel rows of an element to [reveal](#up.reveal).
+    A number indicating how many top pixel rows of an element to [reveal](/up.reveal).
   ###
   config = u.config
     duration: 0
@@ -134,7 +134,7 @@ up.layout = (($) ->
       u.resolvedDeferred()
 
   ###*
-  @method up.viewport.finishScrolling
+  @method up.layout.finishScrolling
   @private
   ###
   finishScrolling = (elementOrSelector) ->
@@ -143,7 +143,7 @@ up.layout = (($) ->
         existingScrolling.resolve()
 
   ###*
-  @method up.viewport.anchoredRight
+  @method up.layout.anchoredRight
   @private
   ###
   anchoredRight = ->
@@ -172,8 +172,8 @@ up.layout = (($) ->
   element are visible for the user.
 
   By default Up.js will always reveal an element before
-  updating it with Javascript functions like [`up.replace`](/up.flow#up.replace)
-  or UJS behavior like [`[up-target]`](/up.link#up-target).
+  updating it with Javascript functions like [`up.replace`](/up.replace)
+  or UJS behavior like [`[up-target]`](/up-target).
 
   \#\#\#\# How Up.js finds the viewport
 
@@ -183,7 +183,7 @@ up.layout = (($) ->
   - the currently open [modal](/up.modal)
   - an element with the attribute `[up-viewport]`
   - the `<body>` element
-  - an element matching the selector you have configured using `up.viewport.config.viewports.push('my-custom-selector')`
+  - an element matching the selector you have configured using `up.layout.config.viewports.push('my-custom-selector')`
 
   \#\#\#\# Fixed elements obstruction the viewport
 
@@ -192,8 +192,8 @@ up.layout = (($) ->
 
   To make `up.aware` of these fixed elements you can either:
 
-  - give the element an attribute [`up-fixed="top"`](#up-fixed-top) or [`up-fixed="bottom"`](up-fixed-bottom)
-  - [configure default options](#up.layout.config) for `fixedTop` or `fixedBottom`
+  - give the element an attribute [`up-fixed="top"`](/up-fixed-top) or [`up-fixed="bottom"`](up-fixed-bottom)
+  - [configure default options](/up.layout.config) for `fixedTop` or `fixedBottom`
 
   @method up.reveal
   @param {String|Element|jQuery} element
@@ -338,9 +338,13 @@ up.layout = (($) ->
 
   ###*
   Saves the top scroll positions of all the
-  viewports configured in [`up.layout.config.viewports`](#up.layout.config).
-  The saved scroll positions can be restored by calling
-  [`up.layout.restoreScroll()`](#up.layout.restoreScroll).
+  viewports configured in [`up.layout.config.viewports`](/up.layout.config).
+
+  The scroll positions will be associated with the current URL.
+  They can later be restored by calling [`up.layout.restoreScroll()`](/up.layout.restoreScroll)
+  at the same URL.
+
+  Up.js automatically saves scroll positions whenever a fragment was updated on the page.
 
   @method up.layout.saveScroll
   @param {String} [options.url]
@@ -354,8 +358,11 @@ up.layout = (($) ->
     lastScrollTops.set(url, tops)
 
   ###*
-  Restores the top scroll positions of all the
-  viewports configured in [`up.layout.config.viewports`](#up.layout.config).
+  Restores [previously saved](/up.layout.saveScroll) scroll positions of viewports
+  viewports configured in [`up.layout.config.viewports`](/up.layout.config).
+
+  Up.js automatically restores scroll positions when the user presses the back button.
+  You can disable this behavior by setting [`up.history.config.restoreScroll = false`](/up.history.config).
 
   @method up.layout.restoreScroll
   @param {jQuery} [options.around]
@@ -405,8 +412,11 @@ up.layout = (($) ->
 
 
   ###*
-  Marks this element as a scrolling container. Apply this ttribute if your app uses
-  a custom panel layout with fixed positioning instead of scrolling `<body>`.
+  Marks this element as a scrolling container ("viewport").
+
+  Apply this attribute if your app uses a custom panel layout with fixed positioning
+  instead of scrolling `<body>`. As an alternative you can also push a selector
+  matching your custom viewport to the [`up.layout.config.viewports`](/up.layout.config) array.
 
   [`up.reveal`](/up.reveal) will always try to scroll the viewport closest
   to the element that is being revealed. By default this is the `<body>` element.

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

@@ -101,7 +101,7 @@ up.link = (($) ->
   @param {String} [options.target='body']
     The selector to replace.
   @param {Object} options
-    See options for [`up.replace`](/up.flow#up.replace)
+    See options for [`up.replace`](/up.replace)
   ###
   visit = (url, options) ->
     options = u.options(options)
@@ -109,7 +109,7 @@ up.link = (($) ->
     up.replace(selector, url, options)
 
   ###*
-  Follows the given link via AJAX and replaces a CSS selector in the current page
+  Follows the given link via AJAX and [replaces](/up.replace) a CSS selector in the current page
   with corresponding elements from a new page fetched from the server.
 
   Any Up.js UJS attributes on the given link will be honored. E. g. you have this link:
@@ -122,7 +122,7 @@ up.link = (($) ->
       up.follow($link);
 
   @method up.follow
-  @param {Element|jQuery|String} link
+  @param {Element|jQuery|String} linkOrSelector
     An element or selector which resolves to an `<a>` tag
     or any element that is marked up with an `up-href` attribute.
   @param {String} [options.target]
@@ -132,23 +132,23 @@ up.link = (($) ->
   @param {Function|String} [options.transition]
     A transition function or name.
   @param {Number} [options.duration]
-    The duration of the transition. See [`up.morph`](/up.motion#up.morph).
+    The duration of the transition. See [`up.morph`](/up.morph).
   @param {Number} [options.delay]
-    The delay before the transition starts. See [`up.morph`](/up.motion#up.morph).
+    The delay before the transition starts. See [`up.morph`](/up.morph).
   @param {String} [options.easing]
-    The timing function that controls the transition's acceleration. [`up.morph`](/up.motion#up.morph).
+    The timing function that controls the transition's acceleration. [`up.morph`](/up.morph).
   @param {Element|jQuery|String} [options.reveal]
     Whether to reveal the target  element within its viewport before updating.
   @param {Boolean} [options.restoreScroll]
-    If set to `true`, this will attempt to [`restore scroll positions`](/up.layout#up.restoreScroll)
+    If set to `true`, this will attempt to [`restore scroll positions`](/up.restoreScroll)
     previously seen on the destination URL.
   @param {Boolean} [options.cache]
     Whether to force the use of a cached response (`true`)
     or never use the cache (`false`)
     or make an educated guess (`undefined`).
   ###
-  follow = (link, options) ->
-    $link = $(link)
+  follow = (linkOrSelector, options) ->
+    $link = $(linkOrSelector)
 
     options = u.options(options)
     url = u.option($link.attr('up-href'), $link.attr('href'))
@@ -164,10 +164,18 @@ up.link = (($) ->
     up.replace(selector, url, options)
 
   ###*
+  Returns the HTTP method that should be used when following the given link.
+
+  Looks at the link's `up-method` or `data-method` attribute.
+  Defaults to `get`.
+
   @protected
   @method up.link.followMethod
+  @param linkOrSelector
+  @param options.method {String}
   ###
-  followMethod = ($link, options) ->
+  followMethod = (linkOrSelector, options) ->
+    $link = $(linkOrSelector)
     options = u.options(options)
     u.option(options.method, $link.attr('up-method'), $link.attr('data-method'), 'get').toUpperCase()
 
@@ -304,7 +312,7 @@ up.link = (($) ->
       <a href="/users" up-follow>User list</a>
 
   To only update a fragment instead of the entire page,
-  see [`up-target`](#up-target).
+  see [`up-target`](/up-target).
 
   \#\#\#\# Turn any element into a link
 
@@ -345,7 +353,7 @@ up.link = (($) ->
       </div>
 
   In the example above, clicking anywhere within `.notification` element
-  would [follow](#up-follow) the *Close* link.
+  would [follow](/up.follow) the *Close* link.
 
   `up-expand` honors all the UJS behavior in expanded links
   (`up-target`, `up-instant`, `up-preload`, etc.).
@@ -372,9 +380,9 @@ up.link = (($) ->
   Marks up the current link to be followed *as fast as possible*.
   This is done by:
   
-  - [Following the link through AJAX](/up.link#up-target) instead of a full page load
-  - [Preloading the link's destination URL](/up.proxy#up-preload)
-  - [Triggering the link on `mousedown`](/up.link#up-instant) instead of on `click`
+  - [Following the link through AJAX](/up-target) instead of a full page load
+  - [Preloading the link's destination URL](/up-preload)
+  - [Triggering the link on `mousedown`](/up-instant) instead of on `click`
   
   Use `up-dash` like this:
   

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

@@ -21,15 +21,36 @@ up.magic = (($) ->
   DESTROYABLE_CLASS = 'up-destroyable'
   DESTROYER_KEY = 'up-destroyer'
 
+  liveDescriptions = []
+  defaultLiveDescriptions = null
+
   ###*
-  Binds an event handler to the document, which will be executed whenever the
-  given event is triggered on the given selector:
+  # Convert an Up.js style listener (second argument is the event target
+  # as a jQuery collection) to a vanilla jQuery listener
+  ###
+  upListenerToJqueryListener = (upListener) ->
+    (event) ->
+      $me = event.$element || $(this)
+      upListener.apply($me.get(0), [event, $me, data($me)])
+
+  ###*
+  Listens to an event on `document`.
+
+  The given event listener which will be executed whenever the
+  given event is [triggered](/up.emit) on the given selector:
 
       up.on('click', '.button', function(event, $element) {
         console.log("Someone clicked the button %o", $element);
       });
 
-  This is roughly equivalent to binding a jQuery element to `document`.
+  This is roughly equivalent to binding an event listener to `document`:
+
+      $(document).on('click', '.button', function(event) {
+        console.log("Someone clicked the button %o", $(this));
+      });
+
+  Other than jQuery, Up.js will silently discard event listeners
+  on [browsers that it doesn't support](/up.browser.isSupported).
 
 
   \#\#\#\# Attaching structured data
@@ -81,18 +102,6 @@ up.magic = (($) ->
   @return {Function}
     A function that unbinds the event listeners when called.
   ###
-  liveDescriptions = []
-  defaultLiveDescriptions = null
-
-  ###*
-  # Convert an Up.js style listener (second argument is the event target
-  # as a jQuery collection) to a vanilla jQuery listener
-  ###
-  upListenerToJqueryListener = (upListener) ->
-    (event) ->
-      $me = event.$element || $(this)
-      upListener.apply($me.get(0), [event, $me, data($me)])
-
   live = (args...) ->
     # Silently discard any event handlers that are registered on unsupported
     # browsers and return a no-op destructor
@@ -112,12 +121,26 @@ up.magic = (($) ->
 
     # Return destructor
     -> $document.off(description...)
-  
+
+
   ###*
   Registers a function to be called whenever an element with
-  the given selector is inserted into the DOM through Up.js.
+  the given selector is inserted into the DOM.
+
+      $('.action').compiler(function($element) {
+        // your code here
+      });
 
-  This is a great way to integrate jQuery plugins.
+  Compiler functions will be called on matching elements when
+  the page loads, or whenever a matching fragment is [updated through Up.js](/up.replace)
+  later.
+
+  If you have used Angular.js before, this resembles [Angular directives](https://docs.angularjs.org/guide/directive).
+
+
+  \#\#\#\# Integrating jQuery plugins
+
+  `up.compiler` is a great way to integrate jQuery plugins.
   Let's say your Javascript plugin wants you to call `lightboxify()`
   on links that should open a lightbox. You decide to
   do this for all links with an `[rel=lightbox]` attribute:
@@ -131,14 +154,10 @@ up.magic = (($) ->
         $element.lightboxify();
       });
 
-  Note that within the compiler, Up.js will bind `this` to the
-  native DOM element to help you migrate your existing jQuery code to
-  this new syntax.
-
 
   \#\#\#\# Custom elements
 
-  You can also use `up.compiler` to implement custom elements like this:
+  You can use `up.compiler` to implement custom elements like this:
 
       <clock></clock>
 
@@ -214,12 +233,28 @@ up.magic = (($) ->
       });
 
 
-  \#\#\#\# Migrating jQuery event handlers to `up.on`
+  \#\#\#\# Migrating jQuery event handlers to `up.compiler`
 
   Within the compiler, Up.js will bind `this` to the
   native DOM element to help you migrate your existing jQuery code to
   this new syntax.
 
+  So if you had this before:
+
+      $(function() {
+        $('.action').on('click', function() {
+          $(this).something();
+        });
+      });
+
+  ... you can reuse the event handler like this:
+
+      $('.action').compiler(function($element) {
+        $element.on('click', function() {
+          $(this).something();
+        });
+      });
+
   
   @method up.compiler
   @param {String} selector
@@ -238,7 +273,7 @@ up.magic = (($) ->
     object before it is removed from the DOM. The destructor is supposed to
     clear global state such as time-outs and event handlers bound to the document.
     The destructor is *not* expected to remove the element from the DOM, which
-    is already handled by [`up.destroy`](/up.flow#up.destroy).
+    is already handled by [`up.destroy`](/up.destroy).
   ###
   compilers = []
   defaultCompilers = null
@@ -295,11 +330,11 @@ up.magic = (($) ->
 
   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.magic#up.magic.compiler) handlers.
+  [`up.compiler`](/up.magic.compiler) handlers.
 
   Similarly, when an event is triggered on an element annotated with
   [`up-data`], the parsed object will be passed to any matching
-  [`up.on`](/up.magic#up.on) handlers.
+  [`up.on`](/up.on) handlers.
 
   @ujs
   @method [up-data]
@@ -315,7 +350,7 @@ up.magic = (($) ->
 
   ###*
   Makes a snapshot of the currently registered event listeners,
-  to later be restored through [`up.bus.reset`](/up.bus#up.bus.reset).
+  to later be restored through [`up.bus.reset`](/up.bus.reset).
   
   @private
   @method up.magic.snapshot
@@ -343,16 +378,21 @@ up.magic = (($) ->
   into the DOM. This causes Up.js to compile the fragment (apply
   event listeners, etc.).
 
-  This method is called automatically if you change elements through
-  other Up.js methods. You will only need to call this if you
-  manipulate the DOM without going through Up.js.
+  **As long as you manipulate the DOM using Up.js, you will never
+  need to call this method.** You only need to use `up.hello` if the
+  DOM is manipulated without Up.js' involvement, e.g. by plugin code that
+  is not aware of Up.js:
+
+      // Add an element with naked jQuery, without going through Upjs:
+      $element = $('<div>...</div>').appendTo(document.body);
+      up.hello($element);
 
   @method up.hello
   @param {String|Element|jQuery} selectorOrElement
   ###
   hello = (selectorOrElement) ->
     $element = $(selectorOrElement)
-    up.bus.emit('up:fragment:inserted', $element: $element)
+    up.emit('up:fragment:inserted', $element: $element)
     $element
 
   onEscape = (handler) ->