lib/yuilib/3.7.2/build/app-transitions/app-transitions.js

   1 /*
   2 YUI 3.7.2 (build 5639)
   3 Copyright 2012 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7 YUI.add('app-transitions', function (Y, NAME) {
   8
   9 /**
  10 `Y.App` extension that provides view transitions in browsers which support
  11 native CSS3 transitions.
  12
  13 @module app
  14 @submodule app-transitions
  15 @since 3.5.0
  16 **/
  17
  18 /**
  19 `Y.App` extension that provides view transitions in browsers which support
  20 native CSS3 transitions.
  21
  22 View transitions provide an nice way to move from one "page" to the next that is
  23 both pleasant to the user and helps to communicate a hierarchy between sections
  24 of an application.
  25
  26 When the `"app-transitions"` module is used, it will automatically mix itself
  27 into `Y.App` and transition between `activeView` changes using the following
  28 effects:
  29
  30   - **`fade`**: Cross-fades between the old an new active views.
  31
  32   - **`slideLeft`**: The old and new active views are positioned next to each
  33     other and both slide to the left.
  34
  35   - **`slideRight`**: The old and new active views are positioned next to each
  36     other and both slide to the right.
  37
  38 **Note:** Transitions are an opt-in feature and are enabled via an app's
  39 `transitions` attribute.
  40
  41 @class App.Transitions
  42 @uses App.TransitionsNative
  43 @extensionfor App
  44 @since 3.5.0
  45 **/
  46 function AppTransitions() {}
  47
  48 AppTransitions.ATTRS = {
  49     /**
  50     Whether or not this application should use view transitions, and if so then
  51     which ones or `true` for the defaults which are specified by the
  52     `transitions` prototype property.
  53
  54     **Note:** Transitions are an opt-in feature and will only be used in
  55     browsers which support native CSS3 transitions.
  56
  57     @attribute transitions
  58     @type Boolean|Object
  59     @default false
  60     @since 3.5.0
  61     **/
  62     transitions: {
  63         setter: '_setTransitions',
  64         value : false
  65     }
  66 };
  67
  68 /**
  69 Collect of transitions -> fx.
  70
  71 A transition (e.g. "fade") is a simple name given to a configuration of fx to
  72 apply, consisting of `viewIn` and `viewOut` properties who's values are names of
  73 fx registered on `Y.Transition.fx`.
  74
  75 By default transitions: `fade`, `slideLeft`, and `slideRight` have fx defined.
  76
  77 @property FX
  78 @type Object
  79 @static
  80 @since 3.5.0
  81 **/
  82 AppTransitions.FX = {
  83     fade: {
  84         viewIn : 'app:fadeIn',
  85         viewOut: 'app:fadeOut'
  86     },
  87
  88     slideLeft: {
  89         viewIn : 'app:slideLeft',
  90         viewOut: 'app:slideLeft'
  91     },
  92
  93     slideRight: {
  94         viewIn : 'app:slideRight',
  95         viewOut: 'app:slideRight'
  96     }
  97 };
  98
  99 AppTransitions.prototype = {
 100     // -- Public Properties ----------------------------------------------------
 101
 102     /**
 103     Default transitions to use when the `activeView` changes.
 104
 105     The following are types of changes for which transitions can be defined that
 106     correspond to the relationship between the new and previous `activeView`:
 107
 108       * `navigate`: The default transition to use when changing the `activeView`
 109         of the application.
 110
 111       * `toChild`: The transition to use when the new `activeView` is configured
 112         as a child of the previously active view via its `parent` property as
 113         defined in this app's `views`.
 114
 115       * `toParent`: The transition to use when the new `activeView` is
 116         configured as the `parent` of the previously active view as defined in
 117         this app's `views`.
 118
 119     **Note:** Transitions are an opt-in feature and will only be used in
 120     browsers which support native CSS3 transitions.
 121
 122     @property transitions
 123     @type Object
 124     @default
 125         {
 126             navigate: 'fade',
 127             toChild : 'slideLeft',
 128             toParent: 'slideRight'
 129         }
 130     @since 3.5.0
 131     **/
 132     transitions: {
 133         navigate: 'fade',
 134         toChild : 'slideLeft',
 135         toParent: 'slideRight'
 136     },
 137
 138     // -- Public Methods -------------------------------------------------------
 139
 140     /**
 141     Sets which view is active/visible for the application. This will set the
 142     app's `activeView` attribute to the specified `view`.
 143
 144     The `view` will be "attached" to this app, meaning it will be both rendered
 145     into this app's `viewContainer` node and all of its events will bubble to
 146     the app. The previous `activeView` will be "detached" from this app.
 147
 148     When a string-name is provided for a view which has been registered on this
 149     app's `views` object, the referenced metadata will be used and the
 150     `activeView` will be set to either a preserved view instance, or a new
 151     instance of the registered view will be created using the specified `config`
 152     object passed-into this method.
 153
 154     A callback function can be specified as either the third or fourth argument,
 155     and this function will be called after the new `view` becomes the
 156     `activeView`, is rendered to the `viewContainer`, and is ready to use.
 157
 158     @example
 159         var app = new Y.App({
 160             views: {
 161                 usersView: {
 162                     // Imagine that `Y.UsersView` has been defined.
 163                     type: Y.UsersView
 164                 }
 165             },
 166
 167             transitions: true,
 168             users      : new Y.ModelList()
 169         });
 170
 171         app.route('/users/', function () {
 172             this.showView('usersView', {users: this.get('users')});
 173         });
 174
 175         app.render();
 176         app.navigate('/uses/');
 177         // => Creates a new `Y.UsersView` and transitions to it.
 178
 179     @method showView
 180     @param {String|View} view The name of a view defined in the `views` object,
 181         or a view instance which should become this app's `activeView`.
 182     @param {Object} [config] Optional configuration to use when creating a new
 183         view instance. This config object can also be used to update an existing
 184         or preserved view's attributes when `options.update` is `true`.
 185     @param {Object} [options] Optional object containing any of the following
 186         properties:
 187       @param {Function} [options.callback] Optional callback function to call
 188         after new `activeView` is ready to use, the function will be passed:
 189           @param {View} options.callback.view A reference to the new
 190             `activeView`.
 191       @param {Boolean} [options.prepend=false] Whether the `view` should be
 192         prepended instead of appended to the `viewContainer`.
 193       @param {Boolean} [options.render] Whether the `view` should be rendered.
 194         **Note:** If no value is specified, a view instance will only be
 195         rendered if it's newly created by this method.
 196       @param {Boolean|String} [options.transition] Optional transition override.
 197         A transition can be specified which will override the default, or
 198         `false` for no transition.
 199       @param {Boolean} [options.update=false] Whether an existing view should
 200         have its attributes updated by passing the `config` object to its
 201         `setAttrs()` method. **Note:** This option does not have an effect if
 202         the `view` instance is created as a result of calling this method.
 203     @param {Function} [callback] Optional callback Function to call after the
 204         new `activeView` is ready to use. **Note:** this will override
 205         `options.callback` and it can be specified as either the third or fourth
 206         argument. The function will be passed the following:
 207       @param {View} callback.view A reference to the new `activeView`.
 208     @chainable
 209     @since 3.5.0
 210     **/
 211     // Does not override `showView()` but does use `options.transitions`.
 212
 213     // -- Protected Methods ----------------------------------------------------
 214
 215     /**
 216     Setter for `transitions` attribute.
 217
 218     When specified as `true`, the defaults will be use as specified by the
 219     `transitions` prototype property.
 220
 221     @method _setTransitions
 222     @param {Boolean|Object} transitions The new `transitions` attribute value.
 223     @return {Mixed} The processed value which represents the new state.
 224     @protected
 225     @see App.Base.showView()
 226     @since 3.5.0
 227     **/
 228     _setTransitions: function (transitions) {
 229         var defTransitions = this.transitions;
 230
 231         if (transitions && transitions === true) {
 232             return Y.merge(defTransitions);
 233         }
 234
 235         return transitions;
 236     }
 237 };
 238
 239 // -- Namespace ----------------------------------------------------------------
 240 Y.App.Transitions = AppTransitions;
 241 Y.Base.mix(Y.App, [AppTransitions]);
 242
 243 Y.mix(Y.App.CLASS_NAMES, {
 244     transitioning: Y.ClassNameManager.getClassName('app', 'transitioning')
 245 });
 246
 247
 248 }, '3.7.2', {"requires": ["app-base"]});