upjs-rails 0.4.4 → 0.5.0

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

@@ -15,6 +15,7 @@ We need to work on this page:
 - Demo the built-in animations and transitions
 - Examples for defining your own animations and transitions
 - Explain ghosting
+- Explain how many elements accept arguments for animation.
 
   
 @class up.motion
@@ -43,38 +44,76 @@ up.motion = (->
     u.extend(config, options)
   
   ###*
-  Animates an element.
-  
-  If the element is already being animated, the previous animation
-  will instantly jump to its last frame before the new animation begins. 
-  
-  The following animations are pre-registered:
-  
-  - `fade-in`
-  - `fade-out`
-  - `move-to-top`
-  - `move-from-top`
-  - `move-to-bottom`
-  - `move-from-bottom`
-  - `move-to-left`
-  - `move-from-left`
-  - `move-to-right`
-  - `move-from-right`
-  - `none`
-  
+  Applies the given animation to the given element:
+
+      up.animate('.warning', 'fade-in');
+
+  You can pass additional options:
+
+      up.animate('warning', '.fade-in', {
+        delay: 1000,
+        duration: 250,
+        easing: 'linear'
+      });
+
+  \#\#\#\# Named animations
+
+  The following animations are pre-defined:
+
+  | `fade-in`          | Changes the element's opacity from 0% to 100% |
+  | `fade-out`         | Changes the element's opacity from 100% to 0% |
+  | `move-to-top`      | Moves the element upwards until it exits the screen at the top edge |
+  | `move-from-top`    | Moves the element downwards from beyond the top edge of the screen until it reaches its current position |
+  | `move-to-bottom`   | Moves the element downwards until it exits the screen at the bottom edge |
+  | `move-from-bottom` | Moves the element upwards from beyond the bottom edge of the screen until it reaches its current position |
+  | `move-to-left`     | Moves the element leftwards until it exists the screen at the left edge  |
+  | `move-from-left`   | Moves the element rightwards from beyond the left edge of the screen until it reaches its current position |
+  | `move-to-right`    | Moves the element rightwards until it exists the screen at the right edge  |
+  | `move-from-right`  | Moves the element leftwards from beyond the right  edge of the screen until it reaches its current position |
+  | `none`             | An animation that has no visible effect. Sounds useless at first, but can save you a lot of `if` statements. |
+
+  You can define additional named animations using [`up.animation`](#up.animation).
+
+  \#\#\#\# Animating CSS properties directly
+
+  By passing an object instead of an animation name, you can animate
+  the CSS properties of the given element:
+
+      var $warning = $('.warning');
+      $warning.css({ opacity: 0 });
+      up.animate($warning, { opacity: 1 });
+
+  \#\#\#\# Multiple animations on the same element
+
+  Up.js doesn't allow more than one concurrent animation on the same element.
+
+  If you attempt to animate an element that is already being animated,
+  the previous animation will instantly jump to its last frame before
+  the new animation begins.
+
   @method up.animate
   @param {Element|jQuery|String} elementOrSelector
+    The element to animate.
   @param {String|Function|Object} animation
-  @param {Number} [options.duration]
-  @param {String} [options.easing]
-  @param {Number} [options.delay]
+    Can either be:
+    - The animation's name
+    - A function performing the animation
+    - An object of CSS attributes describing the last frame of the animation
+  @param {Number} [opts.duration=300]
+    The duration of the animation, in milliseconds.
+  @param {Number} [opts.delay=0]
+    The delay before the animation starts, in milliseconds.
+  @param {String} [opts.easing='ease']
+    The timing function that controls the animation's acceleration.
+    See [W3C documentation](http://www.w3.org/TR/css3-transitions/#transition-timing-function)
+    for a list of pre-defined timing functions.
   @return {Promise}
     A promise for the animation's end.
   ###
   animate = (elementOrSelector, animation, options) ->
     $element = $(elementOrSelector)
     finish($element)
-    options = u.options(options, config)
+    options = animateOptions(options)
     if u.isFunction(animation)
       assertIsDeferred(animation($element, options), animation)
     else if u.isString(animation)
@@ -83,6 +122,22 @@ up.motion = (->
       u.cssAnimate($element, animation, options)
     else
       u.error("Unknown animation type %o", animation)
+
+  ###*
+  Extracts animation-related options from the given options hash.
+  If `$element` is given, also inspects the element for animation-related
+  attributes like `up-easing` or `up-duration`.
+
+  @protected
+  @method up.motion.animateOptions
+  ###
+  animateOptions = (allOptions, $element = null) ->
+    allOptions = u.options(allOptions)
+    options = {}
+    options.easing = u.option(allOptions.easing, $element?.attr('up-easing'), config.easing)
+    options.duration = Number(u.option(allOptions.duration, $element?.attr('up-duration'), config.duration))
+    options.delay = Number(u.option(allOptions.delay, $element?.attr('up-delay'), config.delay))
+    options
       
   findAnimation = (name) ->
     animations[name] or u.error("Unknown animation %o", animation)
@@ -99,7 +154,7 @@ up.motion = (->
     # $old should take up space in the page flow until the transition ends
     $old.css(visibility: 'hidden')
     
-    newCssMemo = u.temporaryCss($new, display: 'none')
+    showNew = u.temporaryCss($new, display: 'none')
     promise = block($oldGhost, $newGhost)
     $old.data(GHOSTING_PROMISE_KEY, promise)
     $new.data(GHOSTING_PROMISE_KEY, promise)
@@ -113,7 +168,7 @@ up.motion = (->
       # Since we expect $old to be removed in a heartbeat,
       # $new should take up space
       $old.css(display: 'none')
-      newCssMemo()
+      showNew()
 
     promise
       
@@ -121,7 +176,7 @@ up.motion = (->
   Completes all animations and transitions for the given element
   by jumping to the last animation frame instantly. All callbacks chained to
   the original animation's promise will be called.
-  
+
   Does nothing if the given element is not currently animating.
   
   @method up.motion.finish
@@ -145,18 +200,24 @@ up.motion = (->
       u.error("Did not return a promise with .then and .resolve methods: %o", origin)
 
   ###*
-  Performs a transition between two elements.
-  
-  The following transitions  are pre-registered:
-  
-  - `cross-fade`
-  - `move-up`
-  - `move-down`
-  - `move-left`
-  - `move-right`
-  - `none`
+  Performs an animated transition between two elements.
+  Transitions are implement by performing two animations in parallel,
+  causing one element to disappear and the other to appear.
+
+  \#\#\#\# Named transitions
+
+  The following transitions are pre-defined:
+
+  | `cross-fade` | Fades out the first element. Simultaneously fades in the second element. |
+  | `move-up`    | Moves the first element upwards until it exits the screen at the top edge. Simultaneously moves the second element upwards from beyond the bottom edge of the screen until it reaches its current position. |
+  | `move-down`  | Moves the first element downwards until it exits the screen at the bottom edge. Simultaneously moves the second element downwards from beyond the top edge of the screen until it reaches its current position. |
+  | `move-left`  | Moves the first element leftwards until it exists the screen at the left edge. Simultaneously moves the second element leftwards from beyond the right  edge of the screen until it reaches its current position. |
+  | `move-right` | Moves the first element rightwards until it exists the screen at the right edge. Simultaneously moves the second element rightwards from beyond the left edge of the screen until it reaches its current position. |
+  | `none`       | A transition that has no visible effect. Sounds useless at first, but can save you a lot of `if` statements. |
+
+  You can define additional named transitions using [`up.transition`](#up.transition).
   
-  You can also compose a transition from two animation names
+  You can also compose a transition from two [named animations](#named-animations).
   separated by a slash character (`/`):
   
   - `move-to-bottom/fade-in`
@@ -166,15 +227,20 @@ up.motion = (->
   @param {Element|jQuery|String} source
   @param {Element|jQuery|String} target
   @param {Function|String} transitionOrName
-  @param {Number} [options.duration]
-  @param {String} [options.easing]
-  @param {Number} [options.delay]
+  @param {Number} [opts.duration=300]
+    The duration of the animation, in milliseconds.
+  @param {Number} [opts.delay=0]
+    The delay before the animation starts, in milliseconds.
+  @param {String} [opts.easing='ease']
+    The timing function that controls the transition's acceleration.
+    See [W3C documentation](http://www.w3.org/TR/css3-transitions/#transition-timing-function)
+    for a list of pre-defined timing functions.
   @return {Promise}
     A promise for the transition's end.
   ###  
   morph = (source, target, transitionOrName, options) ->
     if up.browser.canCssAnimation()
-      options = u.options(config)
+      options = animateOptions(options)
       $old = $(source)
       $new = $(target)
       finish($old)
@@ -216,6 +282,29 @@ up.motion = (->
   ###*
   Defines a named animation.
 
+  Here is the definition of the pre-defined `fade-in` animation:
+
+      animation('fade-in', ($ghost, options) ->
+        $ghost.css(opacity: 0)
+        animate($ghost, { opacity: 1 }, options)
+      )
+
+  It is recommended that your definitions always end by calling
+  calling [`up.animate`](#up.animate) with an object argument, passing along
+  the `options` that were passed to you.
+
+  If you choose to *not* use `up.animate` and roll your own
+  animation code instead, your code must honor the following contract:
+
+  1. It must honor the passed options.
+  2. It must not remove the passed element from the DOM.
+  3. It returns a promise that is resolved when the animation ends
+  4. The returned promise responds to a `resolve()` function that
+     instantly jumps to the last animation frame and resolves the promise.
+
+  Calling [`up.animate`](#up.animate) with an object argument
+  will take care of all these points.
+
   @method up.animation
   @param {String} name
   @param {Function} animation
@@ -369,6 +458,7 @@ up.motion = (->
     
   morph: morph
   animate: animate
+  animateOptions: animateOptions
   finish: finish
   transition: transition
   animation: animation

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

@@ -105,10 +105,10 @@ up.popup = (->
     $popup.hide()
     $popup
     
-  updated = ($link, $popup, origin, animation) ->
+  updated = ($link, $popup, origin, animation, animateOptions) ->
     $popup.show()
     position($link, $popup, origin)
-    up.animate($popup, animation)
+    up.animate($popup, animation, animateOptions)
     
   ###*
   Opens a popup overlay.
@@ -118,6 +118,13 @@ up.popup = (->
   @param {String} [options.url]
   @param {String} [options.origin='bottom-right']
   @param {String} [options.animation]
+    The animation to use when opening the popup.
+  @param {Number} [opts.duration]
+    The duration of the animation. See [`up.animate`](/up.motion#up.animate).
+  @param {Number} [opts.delay]
+    The delay before the animation starts. See [`up.animate`](/up.motion#up.animate).
+  @param {String} [opts.easing]
+    The timing function that controls the animation's acceleration. [`up.animate`](/up.motion#up.animate).
   @param {Boolean} [options.sticky=false]
     If set to `true`, the popup remains
     open even if the page changes in the background.
@@ -133,14 +140,14 @@ up.popup = (->
     animation = u.option(options.animation, $link.attr('up-animation'), config.openAnimation)
     sticky = u.option(options.sticky, $link.is('[up-sticky]'))
     history = if up.browser.canPushState() then u.option(options.history, $link.attr('up-history'), false) else false
+    animateOptions = up.motion.animateOptions(options, $link)
 
     close()
     $popup = createHiddenPopup($link, selector, sticky)
     
     up.replace(selector, url,
       history: history
-      # source: true
-      insert: -> updated($link, $popup, origin, animation) 
+      insert: -> updated($link, $popup, origin, animation, animateOptions)
     )
     
   ###*

data/lib/upjs/rails/version.rb

@@ -1,5 +1,5 @@
 module Upjs
   module Rails
-    VERSION = '0.4.4'
+    VERSION = '0.5.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: upjs-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.5.0
 platform: ruby
 authors:
 - Henning Koch
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-23 00:00:00.000000000 Z
+date: 2015-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails