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

     2 

     3 /**

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

     5 native CSS3 transitions.

     6 

     7 @module app

     8 @submodule app-transitions

     9 @since 3.5.0

    10 **/

    11 

    12 /**

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

    14 native CSS3 transitions.

    15 

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

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

    18 of an application.

    19 

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

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

    22 effects:

    23 

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

    25 

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

    27     other and both slide to the left.

    28 

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

    30     other and both slide to the right.

    31 

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

    33 `transitions` attribute.

    34 

    35 @class App.Transitions

    36 @uses App.TransitionsNative

    37 @extensionfor App

    38 @since 3.5.0

    39 **/

    40 function AppTransitions() {}

    41 

    42 AppTransitions.ATTRS = {

    43     /**

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

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

    46     `transitions` prototype property.

    47 

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

    49     browsers which support native CSS3 transitions.

    50 

    51     @attribute transitions

    52     @type Boolean|Object

    53     @default false

    54     @since 3.5.0

    55     **/

    56     transitions: {

    57         setter: '_setTransitions',

    58         value : false

    59     }

    60 };

    61 

    62 /**

    63 Collect of transitions -> fx.

    64 

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

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

    67 fx registered on `Y.Transition.fx`.

    68 

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

    70 

    71 @property FX

    72 @type Object

    73 @static

    74 @since 3.5.0

    75 **/

    76 AppTransitions.FX = {

    77     fade: {

    78         viewIn : 'app:fadeIn',

    79         viewOut: 'app:fadeOut'

    80     },

    81 

    82     slideLeft: {

    83         viewIn : 'app:slideLeft',

    84         viewOut: 'app:slideLeft'

    85     },

    86 

    87     slideRight: {

    88         viewIn : 'app:slideRight',

    89         viewOut: 'app:slideRight'

    90     }

    91 };

    92 

    93 AppTransitions.prototype = {

    94     // -- Public Properties ----------------------------------------------------

    95 

    96     /**

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

    98 

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

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

   101 

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

   103         of the application.

   104 

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

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

   107         defined in this app's `views`.

   108 

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

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

   111         this app's `views`.

   112 

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

   114     browsers which support native CSS3 transitions.

   115 

   116     @property transitions

   117     @type Object

   118     @default

   119         {

   120             navigate: 'fade',

   121             toChild : 'slideLeft',

   122             toParent: 'slideRight'

   123         }

   124     @since 3.5.0

   125     **/

   126     transitions: {

   127         navigate: 'fade',

   128         toChild : 'slideLeft',

   129         toParent: 'slideRight'

   130     },

   131 

   132     // -- Public Methods -------------------------------------------------------

   133 

   134     /**

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

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

   137 

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

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

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

   141 

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

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

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

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

   146     object passed-into this method.

   147 

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

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

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

   151 

   152     @example

   153         var app = new Y.App({

   154             views: {

   155                 usersView: {

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

   157                     type: Y.UsersView

   158                 }

   159             },

   160 

   161             transitions: true,

   162             users      : new Y.ModelList()

   163         });

   164 

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

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

   167         });

   168 

   169         app.render();

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

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

   172 

   173     @method showView

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

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

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

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

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

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

   180         properties:

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

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

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

   184             `activeView`.

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

   186         prepended instead of appended to the `viewContainer`.

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

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

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

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

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

   192         `false` for no transition.

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

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

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

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

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

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

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

   200         argument. The function will be passed the following:

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

   202     @chainable

   203     @since 3.5.0

   204     **/

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

   206 

   207     // -- Protected Methods ----------------------------------------------------

   208 

   209     /**

   210     Setter for `transitions` attribute.

   211 

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

   213     `transitions` prototype property.

   214 

   215     @method _setTransitions

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

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

   218     @protected

   219     @see App.Base.showView()

   220     @since 3.5.0

   221     **/

   222     _setTransitions: function (transitions) {

   223         var defTransitions = this.transitions;

   224 

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

   226             return Y.merge(defTransitions);

   227         }

   228 

   229         return transitions;

   230     }

   231 };

   232 

   233 // -- Namespace ----------------------------------------------------------------

   234 Y.App.Transitions = AppTransitions;

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

   236 

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

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

   239 });

   240 

   241 

   242 }, '@VERSION@', {"requires": ["app-base"]});