Navstack

Manage a stack of multiple views. Perfect for tabs, navigation stacks, and similar. Inspired by iOS's UINavigationController.

• Framework-agnostic: made to play fair with Backbone, Ractive, React.js and more. Can even work with plain old jQuery.

• Router-friendly: made to be able to work with pushstate routers (like page.js), giving you back/forward button support.

• Mobile-like transitions: buttery-smooth transitions are available out of the box, modeled after iOS7.

Installation

Navstack is a JS + CSS bundle.

• navstack.js
• navstack.css

Or get it via Bower or NPM:

$ npm install --save navstack
$ bower install --save navstack

Then use it:

<script src="navstack.js"></script>
<link rel="stylesheet" href="navstack.css">

Getting started

Create your stack by instanciating Navstack. Pass a jQuery object or a DOM node to el.

stage = new Navstack({
  el: $('#stage')
});

Adding panes

Use .push() to create your panes. It takes 2 arguments:

• name (string): the ID of the pane. This will the unique identifier that will identify your pane.
• initializer (function): a function to return the pane's contents.

// Navigate to new pages using push.
stage.push('/home', function() {
  return $("<div class='full-screen'>This is the home screen</div>");
});
 
// The first parameter is an ID for the pane to be pushed.
// This will animate the stage to slide into the new view.
stage.push('/task/1', function() {
  return $("<div class='full-screen'>Task #1 details: ...</div>");
});

Libraries support: The initializer can return jQuery elements, Backbone views, Ractive instances, or React.js components.

stage.push('task:1', function() {
  /* Backbone: */
  return new Backbone.View({ ... });
 
  /* Ractive: */
  return new Ractive({ template: '...' });
 
  /* React.js: */
  var MyComponent = React.createClass({ ... });
  return new MyComponent({ name: "John" });
});

Returning back: Calling .push() again with a pane that is already part of the stack will make the stage will animate backwards (slide left) to that old pane. If the pane is recent (ie, last 5 panes used or so), the pane's DOM element is previously hidden and will be made visible. If it's an old pane, it will be recreated based on the initializer first passed onto .push().

stage.push('/home', function() { ... });
 
stage.push('/task/1', function() { ... });
 
// this will slide left into the first screen.
stage.push('/home', function() { ... });

Groups & modal dialogs

Group panes together by passing the { group: 'groupname' } option to push().

This allows you to create logical sections of your app UI. Panes of the same group will slide left-and-right by default, while panes of a different group will pop up like modal dialogs.

In this example below, the settings pages will pop up in a modal:

stage = new Navstack({ el: ... });
 
// Use no group names for the main parts of your app.
stage.push('home', function () { ... });
stage.push('messages', function () { ... });
stage.push('message/user1', function () { ... });
 
// this will pop up the `config` settings dialog with a modal popup animation.
// the next one, `account` settings, will animate by sliding to the right,
// since it's in the same group as the previous pane.
stage.push('config',  {group: 'settings'}, function () { ... });
stage.push('account', {group: 'settings'}, function () { ... });
 
// by going back to `home`, there will be a modal exit animation, since you're 
// transitioning from one group to another.
stage.push('home', function () { ... });

Prefixes: You can also prefix names with groupname! (eg, settings!account) -- this accomplishes the same thing.

// these two are equivalent
stage.push('config',  {group: 'settings'}, function () { ... });
stage.push('settings!config', function () { ... });

Sleeping and waking

When a view is about to be hidden, a navstack:sleep event is called. When a view is about to be shown, a navstack:wake event is called. These are triggered as jQuery, Backbone, Ractive or React events, depending on what your pane is.

var $box = $("<div>hello</div>");
$box.on('navstack:sleep', function () { ... });
$box.on('navstack:wake', function () { ... });
 
stage.push('home', function () {
  return $box;
});

Use with routers

To take full advantage of Navstack, it's recommended to use it with a router to manage browser history states (read: makes the browser "Back" button work). Here's an example usage of Navstack with page.js:

var stack = new Navstack();
 
page('/home', function (ctx) {
  stack.push(ctx.canonicalPath, function () {
    return $("<div>...</div>");
  });
});
 
page('/book/:id', function (ctx) {
  stack.push(ctx.canonicalPath, function () {
    return $("<div>...</div>");
  });
});
 
document.body.appendChild(stack.el);

Or with Backbone.Router:

var stack = new Navstack();
 
App.Router = Backbone.Router.extend({
  routes: {
    '': 'home',
    'book/:id': 'showBook'
  },
 
  home: function () {
    stack.push('home', function () {
      return new HomeView(...);
    });
  },
 
  showBook: function (id) {
    stack.push('book:' + id, function () {
      var book = new Book(id: id);
      return new BookView(book);
    });
  }
});
 
$(function () {
  $(stack.el).appendTo('body');
  Backbone.history.start();
});

Navstack

new Navstack(options)

Instanciates a new Navstack stage that manages multiple panes.

stage = new Navstack({
  el: '#stack'
});

You may pass any of these options below. All of them are optional.

• el — a selector, a jQuery object, or a DOM element.
• transition — a string of the transition name to use.
• groupTransition — a string of the transition to use in between groups.

You'll then use push to add panes into the stage.

stage.push('home', function () {
  return $("<div>Hello</div>");
});

Attributes

panes

Index of panes that have been registered with this Navstack. Object with pane names as keys and Pane instances as values.

stage.push('home', function () { ... });
 
stage.panes['home']
stage.panes['home'].name   //=> 'home'
stage.panes['home'].el     //=> DOMElement
stage.panes['home'].view

active

A reference to the active pane. This is a Navstack.Pane instance.

stage.push('home', function() { ... });
 
// later:
stage.active.name   //=> 'home'
stage.active.el     //=> DOMElement
stage.active.view

It is a pointer to the active pane in the panes object.

stage.push('home', function() { ... });
 
// later:
stage.active === stage.panes['home']

stack

Ordered array of pane names of what are the panes present in the stack. When doing push(), you are adding an item to the stack.

stage.push('home', function() { ... });
stage.stack
=> ['home']
 
stage.push('timeline', function() { ... });
stage.stack
=> ['home', 'timeline']

transition

The transition name to be used. Defaults to "slide". This can either be a String (a transition name), a Function, or false (no animations).

stage = new Navstack({
  transition: 'slide',
  groupTransition: 'modal'
});
 
// the second push here will use the slide animation.
stage.push('home', function() { ... });
stage.push('mentions', function() { ... });
 
// this will use the modal transition, as its in a different group.
stage.push('auth!login', function() { ... });

groupTransition

Pane transition to use in between groups. Defaults to "modal". See transition for more details.

el

The DOM element of the stack. You may specify this while creating a Navstack instance. When no el is given, it will default to creating a new <div> element.

stage = new Navstack({
  el: document.getElementById('#box')
});

You may also pass a jQuery object here for convenience.

stage = new Navstack({
  el: $('#box')
});

You can access this later in the Navstack instance:

$(stage.el).show()

Methods

push

.push(name, [options], [fn])

Registers a pane with the given name.

The function will specify the initializer that will return the view to be pushed. It can return a DOM node, a jQuery object, a Backbone view, Ractive instance, or a React component.

stage.push('home', function() {
  return $("<div>...</div>");
});

You can specify a pane's group by prefixing the name with the group name and a bang.

stage.push('modal!form', function() {
  return $("<div>...</div>");
});

You can specify options.

stage.push('home', { group: 'root' }, function() {
  return $("<div>...</div>");
});

Available options are (all are optional):

• group (String) — the group name that the pane should belong to.
• transition (String) — the name of the transition to use. See Navstack.transitions.

init

Constructor. You may override this function when subclassing via Navstack.extend to run some code when subclassed stack is instanciated.

var MyStack = Navstack.extend({
  init: function() {
    // initialize here
  }
});

goNow

.goNow(name, [options])

Performs the actual moving, as delegated to by .go(), which is then delegated from .push().

For external API, Use .push() instead.

remove

Destroys the Navstack instance, removes the DOM element associated with it.

stage = new Navstack({ el: '#stack' });
stage.remove();

This is also aliased as .teardown(), following Ractive's naming conventions.

ready

ready(fn)

Runs a function fn when transitions have elapsed. If no transitions are happening, run the function immediately.

nav = new Navstack();
nav.push('home', function () { ... });
nav.push('messages', function () { ... });
 
nav.ready(function () {
  // gets executed only after transitions are done
});

Events

A stack may emit events, which you can listen to via [on()].

stage = new Navstack();
 
stage.on('push', function (e) {
  e.direction  // 'forward' or 'backward'
  e.current    // current pane
  e.previous   // previous pane
});
 
// to listen for a specific pane:
stage.on('push:NameHere', function (e) {
  ...
});

Available events are:

• push -- called after a push() succeeds
• push:NAME -- called after a pane with the name NAME is pushed
• purge -- called when a pane is purged from being obsolete
• purge:NAME -- called when pane NAME is purged
• remove -- called when removing the stack

on

.on(event, function)

Binds an event handler.

stage.on('remove', function() {
  // do things
});

off

.off(event, callback)

Removes an event handler.

stage.off('remove', myfunction);

one

.one(event, callback)

Works like .on, except it unbinds itself right after.

Navstack.Pane

Panes are accessible via navstack.panes['name'] or navstack.active.

stage = new Navstack();
pane = stage.active;
 
pane.name
pane.initializer  // function
pane.el
pane.view

You'll find these properties:

• name (String) — the identifier for this pane as passed onto push().
• parent — a reference to the Navstack instance.
• el — DOM element.
• view — the view instance created by the initializer passed onto push().
• adaptor — a wrapped version of view (internal).

Static members

These are static members you can access from the global Navstack object.

Navstack.extend

extend(prototype)

Subclasses Navstack to create your new Navstack class. This allows you to create 'presets' of the options to be passed onto the constructor.

var Mystack = Navstack.extend({
  transition: 'slide'
});
 
// doing this is equivalent to passing `transition: 'slide'` to the
// options object.
var stack = new Mystack({ el: '#stack' });

Navstack.transitions

The global transitions registry. It's an Object where transition functions are stored.

Available transitions are:

• default — show new panes immediately, no animation
• slide — slides the new panes horizontally like iOS7
• modal — slides the new panes vertically

Whenever a transition is used on a Navstack (eg, with new Navstack({ transition: 'slide' })), it is first looked up in the stack's own registry (stage.transitions). If it's not found there, it's then looked up in the global transitions registry, Navstack.transitions.

You can define your own transitions via:

Navstack.transitions.foo = function (direction, current, previous) {
 
  // this function should return an object with 3 keys: `before`,
  // `run`, and `after`. Each of them are asynchronous functions
  // that will perform different phases of the transition.
  //
  // you can use the arguments:
  //
  //   direction - this is either "first", "forward", or "backward".
  //   previous  - the previous pane. This an instance of [Pane].
  //   current   - the pane to transition to.
 
  return {
    before: function (next) {
      // things to perform in preparation of a transition,
      // such as hide the current pane.
      // invoke next() after it's done.
 
      if (current) $(current.el).hide();
      next();
    },
 
    run: function (next) {
      // run the actual transition.
      // invoke next() after it's done.
 
      if (current)  $(current.el).show();
      if (previous) $(previous.el).hide();
      next();
    },
 
    after: function (next) {
      // things to perform after running the transition.
      // invoke next() after it's done.
      next();
    }
  }
};

Navstack.jQuery

Pointer to the instance of jQuery to optionally use. Set this if you would like Navstack to utilize [jQuery.queue].

Navstack.jQuery = jQuery;

Cheat sheet

// Basic usage
stage = new Navstack();
 
// All options are optional
stage = new Navstack({
  el: 'body', /* selector, or jQuery object */
 
  adapt: ['backbone'],
  adaptors: { backbone: ... },
 
  transition: 'slide' | 'modal',
  transitions: { slide: ... }, /* custom transitions */
});
 
stage.push('pane_id', function () {
  return $("<div>...</div>");
  return new Ractive(...);
  return new ReactComponent(...);
});
 
// Return to old pane
stage.push('pane_id');
 
// The main element
stage.el;           //=> <div>
 
// Access the active pane
stage.active;
stage.active.el;    //=> <div>
stage.active.view;  //=> whatever's returned in the initializer
stage.active.name;  //=> "home"
 
// Access the stack
stage.stack;
stage.stack['pane_id'].view;
stage.stack.length;
 
// Global repositories
Navstack.adaptors = {...};
Navstack.transitions = {...};

Thanks

Navstack © 2014+, Rico Sta. Cruz. Released under the MIT License.
Authored and maintained by Rico Sta. Cruz with help from contributors.

ricostacruz.com  ·  GitHub @rstacruz  ·  Twitter @rstacruz