API Docs for: 3.8.0
Show:

App.Transitions Class

Uses
Defined in: app/js/app-extensions/app-transitions.js:10
Module: app-transitions
Parent Module: app

Available since 3.5.0

Y.App extension that provides view transitions in browsers which support native CSS3 transitions.

View transitions provide an nice way to move from one "page" to the next that is both pleasant to the user and helps to communicate a hierarchy between sections of an application.

When the "app-transitions" module is used, it will automatically mix itself into Y.App and transition between activeView changes using the following effects:

  • fade: Cross-fades between the old an new active views.

  • slideLeft: The old and new active views are positioned next to each other and both slide to the left.

  • slideRight: The old and new active views are positioned next to each other and both slide to the right.

Note: Transitions are an opt-in feature and are enabled via an app's transitions attribute.

Methods

_dequeueActiveView

() protected

Inherited from App.TransitionsNative: app/js/app-extensions/app-transitions-native.js:61

Available since 3.5.0

Dequeues any pending calls to _uiTransitionActiveView().

Note: When there is more than one queued transition, only the most recent activeView change will be visually transitioned, while the others will have their transition option overridden to false.

_getFx

(
  • newView
  • oldView
  • [transition]
)
Object protected

Inherited from App.TransitionsNative: app/js/app-extensions/app-transitions-native.js:90

Available since 3.5.0

Returns an object containing a named fx for both viewIn and viewOut based on the relationship between the specified newView and oldView.

Parameters:

  • newView View

    The view being transitioned-in.

  • oldView View

    The view being transitioned-out.

  • [transition] String optional

    The preferred transition to use.

Returns:

Object: An object containing a named fx for both viewIn and viewOut.

_queueActiveView

() protected

Inherited from App.TransitionsNative: app/js/app-extensions/app-transitions-native.js:126

Available since 3.5.0

Queues calls to _uiTransitionActiveView() to make sure a currently running transition isn't interrupted.

Note: This method prevents the default _uiSetActiveView() method from running.

_setTransitions

(
  • transitions
)
Mixed protected

Defined in app/js/app-extensions/app-transitions.js:207

Available since 3.5.0

Setter for transitions attribute.

When specified as true, the defaults will be use as specified by the transitions prototype property.

Parameters:

  • transitions Boolean | Object

    The new transitions attribute value.

Returns:

Mixed: The processed value which represents the new state.

_uiTransitionActiveView

(
  • newView
  • [oldView]
  • [options]
)
protected

Inherited from App.TransitionsNative: app/js/app-extensions/app-transitions-native.js:149

Available since 3.5.0

Performs the actual change of this app's activeView by visually transitioning between the newView and oldView using any specified options.

The newView is attached to the app by rendering it to the viewContainer, and making this app a bubble target of its events.

The oldView is detached from the app by removing it from the viewContainer, and removing this app as a bubble target for its events. The oldView will either be preserved or properly destroyed.

Note: This method overrides _uiSetActiveView() and provides all of its functionality plus supports visual transitions. Also, the activeView attribute is read-only and can be changed by calling the showView() method.

Parameters:

  • newView View

    The View which is now this app's activeView.

  • [oldView] View optional

    The View which was this app's activeView.

  • [options] Object optional

    Optional object containing any of the following properties:

    • [callback] Function optional

      Optional callback function to call after new activeView is ready to use, the function will be passed:

      • view View
        A reference to the new activeView.
    • [prepend=false] Boolean optional

      Whether the view should be prepended instead of appended to the viewContainer.

    • [render] Boolean optional

      Whether the view should be rendered. Note: If no value is specified, a view instance will only be rendered if it's newly created by this method.

    • [transition] Boolean | String optional

      Optional transition override. A transition can be specified which will override the default, or false for no transition.

    • [update=false] Boolean optional

      Whether an existing view should have its attributes updated by passing the config object to its setAttrs() method. Note: This option does not have an effect if the view instance is created as a result of calling this method.

showView

(
  • view
  • [config]
  • [options]
  • [callback]
)
chainable

Defined in app/js/app-extensions/app-transitions.js:132

Available since 3.5.0

Sets which view is active/visible for the application. This will set the app's activeView attribute to the specified view.

The view will be "attached" to this app, meaning it will be both rendered into this app's viewContainer node and all of its events will bubble to the app. The previous activeView will be "detached" from this app.

When a string-name is provided for a view which has been registered on this app's views object, the referenced metadata will be used and the activeView will be set to either a preserved view instance, or a new instance of the registered view will be created using the specified config object passed-into this method.

A callback function can be specified as either the third or fourth argument, and this function will be called after the new view becomes the activeView, is rendered to the viewContainer, and is ready to use.

Parameters:

  • view String | View

    The name of a view defined in the views object, or a view instance which should become this app's activeView.

  • [config] Object optional

    Optional configuration to use when creating a new view instance. This config object can also be used to update an existing or preserved view's attributes when options.update is true.

  • [options] Object optional

    Optional object containing any of the following properties:

    • [callback] Function optional

      Optional callback function to call after new activeView is ready to use, the function will be passed:

      • view View
        A reference to the new activeView.
    • [prepend=false] Boolean optional

      Whether the view should be prepended instead of appended to the viewContainer.

    • [render] Boolean optional

      Whether the view should be rendered. Note: If no value is specified, a view instance will only be rendered if it's newly created by this method.

    • [transition] Boolean | String optional

      Optional transition override. A transition can be specified which will override the default, or false for no transition.

    • [update=false] Boolean optional

      Whether an existing view should have its attributes updated by passing the config object to its setAttrs() method. Note: This option does not have an effect if the view instance is created as a result of calling this method.

  • [callback] Function optional

    Optional callback Function to call after the new activeView is ready to use. Note: this will override options.callback and it can be specified as either the third or fourth argument. The function will be passed the following:

    • view View

      A reference to the new activeView.

Example:

var app = new Y.App({
    views: {
        usersView: {
            // Imagine that Y.UsersView has been defined.
            type: Y.UsersView
        }
    },

    transitions: true,
    users      : new Y.ModelList()
});

app.route('/users/', function () {
    this.showView('usersView', {users: this.get('users')});
});

app.render();
app.navigate('/uses/');
// => Creates a new Y.UsersView and transitions to it.

Properties

_transitioning

Boolean protected

Inherited from App.TransitionsNative: app/js/app-extensions/app-transitions-native.js:28

Available since 3.5.0

Whether this app is currently transitioning its activeView.

Default: false

_viewTransitionQueue

Array protected

Inherited from App.TransitionsNative: app/js/app-extensions/app-transitions-native.js:38

Available since 3.5.0

A queue that holds pending calls to this app's _uiTransitionActiveView() method.

Default: []

FX

Object static

Defined in app/js/app-extensions/app-transitions.js:60

Available since 3.5.0

Collect of transitions -> fx.

A transition (e.g. "fade") is a simple name given to a configuration of fx to apply, consisting of viewIn and viewOut properties who's values are names of fx registered on Y.Transition.fx.

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

transitions

Object

Defined in app/js/app-extensions/app-transitions.js:94

Available since 3.5.0

Default transitions to use when the activeView changes.

The following are types of changes for which transitions can be defined that correspond to the relationship between the new and previous activeView:

  • navigate: The default transition to use when changing the activeView of the application.

  • toChild: The transition to use when the new activeView is configured as a child of the previously active view via its parent property as defined in this app's views.

  • toParent: The transition to use when the new activeView is configured as the parent of the previously active view as defined in this app's views.

Note: Transitions are an opt-in feature and will only be used in browsers which support native CSS3 transitions.

Default: { navigate: 'fade', toChild : 'slideLeft', toParent: 'slideRight' }

Attributes

transitions

Boolean | Object

Defined in app/js/app-extensions/app-transitions.js:41

Available since 3.5.0

Whether or not this application should use view transitions, and if so then which ones or true for the defaults which are specified by the transitions prototype property.

Note: Transitions are an opt-in feature and will only be used in browsers which support native CSS3 transitions.

Default: false

Fires event transitionsChange

Fires when the value for the configuration attribute transitions is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.