Skip to content
This repository

Simple Backbone extension library providing alternative mechanism to navigate/route between application views.

branch: master
README.md

What is BackStack?

BackStack is a JavaScript component/extension for Backbone.js that allows you to create nice view transitions in your HTML5 apps. By default it comes with an implementation of mobile-style slide transitions, fade transitions, and no-effect transitions.

It is conceptually based on the ViewNavigator API from the mobile SDK of the Apache Flex framework. It enables developers to manage a stack of views that can be pushed, popped, or replaced.

Why should I use it?

Although you can use it for web development (as I did to create this site) it is especially useful when building mobile apps with PhoneGap/Cordova framework. Of course, if you are using one of the dozen or so available mobile UI frameworks like jQuery Mobile, Sencha Touch, or jQTouch you don't need it.

Are there other alternatives?

You can use the ViewNavigator implementation from the app-UI framework built by fellow Adobe Evangelist Andy Trice. Alternatively, you can build the transitions yourself; it is not really hard! Or, use one of the frameworks mentioned above.

How was it built?

This may not be particularly interesting to everyone but I used the almond library to develop/package BackStack. Almond is a replacement AMD loader for RequireJS. It is a smaller "shim" loader, providing a minimal AMD API footprint that includes loader plugin support.

Where can I find more info about it?

Here is a demo site that is actually built with BackStack. Be aware of a disclaimer that I only tested it with WebKit based browsers as I mainly used it for mobile apps development. So if you are on IE this site many not work for you, sorry for that ;)

You can also checkout this simple example that is available on jsFiddle.

Watch an intro on YouTube with step-by-step instructions how to get started: http://www.youtube.com/watch?v=sm5DI-iYark

BackStack.StackNavigator class API

Constructor

  • options - Backbone view options hash.
    • options.popTransition - default transition effect object to be used during pop operations.
    • options.pushTransition - default transition effect object to be used during push operations.

Events

BackStack.StackNavigator eventing model is based on Backbone's events implementation.

  • StackNavigator#viewChanging - It's triggered just before view on the stack is changed. This event is cancelable and the view change can be stopped using event.preventDefault() function.

    Event object properties:

    • action - this property can have following values: push, pop, popAll, replace and replaceAll.
    • fromViewClass - class of a from view.
    • fromView - instance of a from view.
    • toViewClass - class of a to view.
    • toView - instance of a to view.
  • StackNavigator#viewChanged - It's triggered after view on the stack is changed. This event cannot be canceled.

    Event object properties:

    • target - Instance of BackStack.StackNavigator that triggered this event.
  • Backbone.View#viewActivate - This event is triggered when view is activated on the stack.

    Event object properties:

    • target - Instance of a view that was activated.
  • Backbone.View#viewDeactivate - This event is triggered when view is deactivated on the stack. Either it was popped or it was covered by another view.

    Event object properties:

    • target - Instance of a view that was deactivated.

Fields

  • StackNavigator.viewsStack - An array with all the view refs on the stack.
  • StackNavigator.activeView - View on top of the stack.
  • StackNavigator.defaultPushTransition - Default push transition effect.
  • StackNavigator.defaultPopTransition - Default pop transition effect.

Functions

  • StackNavigator.popAll(transition) - Pops all views from a stack and leaves empty stack.

    Parameters:

    • {Effect} transition Transition effect to be played when popping views.
  • StackNavigator.popView(transition) - Pops an active view from a stack and displays one below.

    Parameters:

    • {Effect} transition Transition effect to be played when popping new view.
  • StackNavigator.pushView(view, viewOptions, transition) - Pushes new view to the stack.

    Parameters:

    • {Backbone.View || Backbone.ViewClass} view View class or view instance to be pushed on top of the stack.
    • {Object} viewOptions Options to be passed if view is constructed by StackNavigator.
    • {Effect} transition Transition effect to be played when pushing new view.
  • StackNavigator.replaceAll(view, viewOptions, transition) - Replaces all of the views on the stack, with the one passed as a view param.

    Parameters:

    • {Backbone.View || Backbone.ViewClass} view View class or view instance to be pushed on top of the stack.
    • {Object} viewOptions Options to be passed if view is constructed by StackNavigator.
    • {Effect} transition Transition effect to be played when replacing views.
  • StackNavigator.replaceView(view, viewOptions, transition) - Replaces view on top of the stack, with the one passed as a view param.

    Parameters:

    • {Backbone.View || Backbone.ViewClass} view View class or view instance to be pushed on top of the stack instead of current one.
    • {Object} viewOptions Options to be passed if view is constructed by StackNavigator.
    • {Effect} transition Transition effect to be played when replacing view.
Something went wrong with that request. Please try again.