1 /*

     2 YUI 3.10.3 (build 2fb5187)

     3 Copyright 2013 Yahoo! Inc. All rights reserved.

     4 Licensed under the BSD License.

     5 http://yuilibrary.com/license/

     6 */

     7 

     8 YUI.add('app-transitions', function (Y, NAME) {

     9 

    10 /**

    11 `Y.App` extension that provides view transitions in browsers which support

    12 native CSS3 transitions.

    13 

    14 @module app

    15 @submodule app-transitions

    16 @since 3.5.0

    17 **/

    18 

    19 /**

    20 `Y.App` extension that provides view transitions in browsers which support

    21 native CSS3 transitions.

    22 

    23 View transitions provide an nice way to move from one "page" to the next that is

    24 both pleasant to the user and helps to communicate a hierarchy between sections

    25 of an application.

    26 

    27 When the `"app-transitions"` module is used, it will automatically mix itself

    28 into `Y.App` and transition between `activeView` changes using the following

    29 effects:

    30 

    31   - **`fade`**: Cross-fades between the old an new active views.

    32 

    33   - **`slideLeft`**: The old and new active views are positioned next to each

    34     other and both slide to the left.

    35 

    36   - **`slideRight`**: The old and new active views are positioned next to each

    37     other and both slide to the right.

    38 

    39 **Note:** Transitions are an opt-in feature and are enabled via an app's

    40 `transitions` attribute.

    41 

    42 @class App.Transitions

    43 @uses App.TransitionsNative

    44 @extensionfor App

    45 @since 3.5.0

    46 **/

    47 function AppTransitions() {}

    48 

    49 AppTransitions.ATTRS = {

    50     /**

    51     Whether or not this application should use view transitions, and if so then

    52     which ones or `true` for the defaults which are specified by the

    53     `transitions` prototype property.

    54 

    55     **Note:** Transitions are an opt-in feature and will only be used in

    56     browsers which support native CSS3 transitions.

    57 

    58     @attribute transitions

    59     @type Boolean|Object

    60     @default false

    61     @since 3.5.0

    62     **/

    63     transitions: {

    64         setter: '_setTransitions',

    65         value : false

    66     }

    67 };

    68 

    69 /**

    70 Collect of transitions -> fx.

    71 

    72 A transition (e.g. "fade") is a simple name given to a configuration of fx to

    73 apply, consisting of `viewIn` and `viewOut` properties who's values are names of

    74 fx registered on `Y.Transition.fx`.

    75 

    76 By default transitions: `fade`, `slideLeft`, and `slideRight` have fx defined.

    77 

    78 @property FX

    79 @type Object

    80 @static

    81 @since 3.5.0

    82 **/

    83 AppTransitions.FX = {

    84     fade: {

    85         viewIn : 'app:fadeIn',

    86         viewOut: 'app:fadeOut'

    87     },

    88 

    89     slideLeft: {

    90         viewIn : 'app:slideLeft',

    91         viewOut: 'app:slideLeft'

    92     },

    93 

    94     slideRight: {

    95         viewIn : 'app:slideRight',

    96         viewOut: 'app:slideRight'

    97     }

    98 };

    99 

   100 AppTransitions.prototype = {

   101     // -- Public Properties ----------------------------------------------------

   102 

   103     /**

   104     Default transitions to use when the `activeView` changes.

   105 

   106     The following are types of changes for which transitions can be defined that

   107     correspond to the relationship between the new and previous `activeView`:

   108 

   109       * `navigate`: The default transition to use when changing the `activeView`

   110         of the application.

   111 

   112       * `toChild`: The transition to use when the new `activeView` is configured

   113         as a child of the previously active view via its `parent` property as

   114         defined in this app's `views`.

   115 

   116       * `toParent`: The transition to use when the new `activeView` is

   117         configured as the `parent` of the previously active view as defined in

   118         this app's `views`.

   119 

   120     **Note:** Transitions are an opt-in feature and will only be used in

   121     browsers which support native CSS3 transitions.

   122 

   123     @property transitions

   124     @type Object

   125     @default

   126         {

   127             navigate: 'fade',

   128             toChild : 'slideLeft',

   129             toParent: 'slideRight'

   130         }

   131     @since 3.5.0

   132     **/

   133     transitions: {

   134         navigate: 'fade',

   135         toChild : 'slideLeft',

   136         toParent: 'slideRight'

   137     },

   138 

   139     // -- Public Methods -------------------------------------------------------

   140 

   141     /**

   142     Sets which view is active/visible for the application. This will set the

   143     app's `activeView` attribute to the specified `view`.

   144 

   145     The `view` will be "attached" to this app, meaning it will be both rendered

   146     into this app's `viewContainer` node and all of its events will bubble to

   147     the app. The previous `activeView` will be "detached" from this app.

   148 

   149     When a string-name is provided for a view which has been registered on this

   150     app's `views` object, the referenced metadata will be used and the

   151     `activeView` will be set to either a preserved view instance, or a new

   152     instance of the registered view will be created using the specified `config`

   153     object passed-into this method.

   154 

   155     A callback function can be specified as either the third or fourth argument,

   156     and this function will be called after the new `view` becomes the

   157     `activeView`, is rendered to the `viewContainer`, and is ready to use.

   158 

   159     @example

   160         var app = new Y.App({

   161             views: {

   162                 usersView: {

   163                     // Imagine that `Y.UsersView` has been defined.

   164                     type: Y.UsersView

   165                 }

   166             },

   167 

   168             transitions: true,

   169             users      : new Y.ModelList()

   170         });

   171 

   172         app.route('/users/', function () {

   173             this.showView('usersView', {users: this.get('users')});

   174         });

   175 

   176         app.render();

   177         app.navigate('/uses/');

   178         // => Creates a new `Y.UsersView` and transitions to it.

   179 

   180     @method showView

   181     @param {String|View} view The name of a view defined in the `views` object,

   182         or a view instance which should become this app's `activeView`.

   183     @param {Object} [config] Optional configuration to use when creating a new

   184         view instance. This config object can also be used to update an existing

   185         or preserved view's attributes when `options.update` is `true`.

   186     @param {Object} [options] Optional object containing any of the following

   187         properties:

   188       @param {Function} [options.callback] Optional callback function to call

   189         after new `activeView` is ready to use, the function will be passed:

   190           @param {View} options.callback.view A reference to the new

   191             `activeView`.

   192       @param {Boolean} [options.prepend=false] Whether the `view` should be

   193         prepended instead of appended to the `viewContainer`.

   194       @param {Boolean} [options.render] Whether the `view` should be rendered.

   195         **Note:** If no value is specified, a view instance will only be

   196         rendered if it's newly created by this method.

   197       @param {Boolean|String} [options.transition] Optional transition override.

   198         A transition can be specified which will override the default, or

   199         `false` for no transition.

   200       @param {Boolean} [options.update=false] Whether an existing view should

   201         have its attributes updated by passing the `config` object to its

   202         `setAttrs()` method. **Note:** This option does not have an effect if

   203         the `view` instance is created as a result of calling this method.

   204     @param {Function} [callback] Optional callback Function to call after the

   205         new `activeView` is ready to use. **Note:** this will override

   206         `options.callback` and it can be specified as either the third or fourth

   207         argument. The function will be passed the following:

   208       @param {View} callback.view A reference to the new `activeView`.

   209     @chainable

   210     @since 3.5.0

   211     **/

   212     // Does not override `showView()` but does use `options.transitions`.

   213 

   214     // -- Protected Methods ----------------------------------------------------

   215 

   216     /**

   217     Setter for `transitions` attribute.

   218 

   219     When specified as `true`, the defaults will be use as specified by the

   220     `transitions` prototype property.

   221 

   222     @method _setTransitions

   223     @param {Boolean|Object} transitions The new `transitions` attribute value.

   224     @return {Mixed} The processed value which represents the new state.

   225     @protected

   226     @see App.Base.showView()

   227     @since 3.5.0

   228     **/

   229     _setTransitions: function (transitions) {

   230         var defTransitions = this.transitions;

   231 

   232         if (transitions && transitions === true) {

   233             return Y.merge(defTransitions);

   234         }

   235 

   236         return transitions;

   237     }

   238 };

   239 

   240 // -- Namespace ----------------------------------------------------------------

   241 Y.App.Transitions = AppTransitions;

   242 Y.Base.mix(Y.App, [AppTransitions]);

   243 

   244 Y.mix(Y.App.CLASS_NAMES, {

   245     transitioning: Y.ClassNameManager.getClassName('app', 'transitioning')

   246 });

   247 

   248 

   249 }, '3.10.3', {"requires": ["app-base"]});