[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 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.17.2', {"requires": ["app-base"]});