lib/yui/3.5.0/build/app-transitions/app-transitions-debug.js

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