Backbone.Manager

Goals

Intuitive state change description
Differentiate between pageload and triggered changes
Remove temptation of view<->router relationships
Easily keep view swaps within a SPA
Allow anchors to indirectly trigger a state change
Conventional state change from anchor href's
Programmatic state change ability
Lots of bullet points for a presentation

Managing State

Router Managing State Changes

UsersRouter = Backbone.Router.extend
  routes:
    users: 'showUsers'
    'users/:uuid': 'showUser'

  initialize: (options) ->
    _.bindAll @, 'switchToUsers', 'switchToUser'

    @listenTo Backbone, 'showUsers', @switchToUsers
    @listenTo Backbone, 'showUser', @switchToUser

Manager Managing (haHA!) State Changes

UsersManager = Backbone.Manager.extend
  states:
    'users.detail':
      url: 'users/:id'
      loadMethod: 'showUser'
      transitionMethod: 'switchToUser'

Manager Details

Backbone.Manager =
  states: # the foundation

    users.detail:  # state name

      url: 'users/:id' # (optional) used in History matching and updating
                       # will update browser url on state transition

      loadMethod: 'showUser' # (optional) name of pageload callback
                             # url must be defined to activate

      transitionMethod: 'switchUser' # name of state change callback

  # Arguments are built from url params
  showUser: (id) ->

  # all of Arguments except Options are either provided by automatic
  # trigger if url is defined, or passed through directly from go() call
  #
  # Options currently only contain the filled in url, so in this case:
  # Options = {url: 'users/1'}
  switchUser: (id, options) ->

App Structure

Manager StructUre

State Flow

State Change Triggers

Three Ways

1. navigate to a state's url

2. Backbone.Manager.go()

3. click on < a data-bb-state = "" />

Backbone.Manager.go

The Programmatic Option

events:
  'click dd': 'showUser'
showUser: ->
  Backbone.Manager.go('users.detail', {id:1})

params:

state name
args: [] or {}

passed into transitionMethod as Arguments

uses values of [] or _.values of {}

order important only in [] for optional state url

[1, 2] for url '/u/:a/p/:b' = /u/1/p/2
{b : 2, a : 1 ] for url '/u/:a/p/:b' = /u/1/p/2

data-bb-state

The Automatic Option

<a data-bb-state='users.detail([1])'/>
<a data-bb-state='users.detail({id:1})'/>
<a data-bb-state='' href='/users/1'/>

All match to users.detail state name

All trigger users.detail.transitionMethod on click

Params work the same as .go() 's args

HREF Parsing Convention

Auto url -> state translation examples:

/users -> users
/users/1 -> users.detail
/users/1/favs -> users.detail.favs
/users/1/favs/2 -> users.detail.favs.detail
/books/1/2 -> books.detail.2 (not good)

use data-bb-state='books.detail.chapter([1,2])' instead

The * State

 Backbone.Manager.extend
  states:
    '*':
      url: '*url'
      transitionMethod: 'defaultTransition'

* is triggered by the data-bb-state watcher if the conventional state it creates from href doesn't exist

Order is important...

should be declared before any other states

Order Matters

Backbone.Router limitations...

Manager integrates with a router, inserting routes based on states, starting at the top. So... last declared url is first to match .

states:
  a:
    url: 'a/:id'
  b: 
    url: '*'

a.url will never be matched by router

states:
  b:
    url: '*'
  a:
    url: 'a/:id'

now a.url matches first, with b.url as proper fallback

Manager Events

pre-load = incoming page load call for all states
pre-load:[state] (args) = incoming page load call for the state
post-load = incoming page load call completed for all states
post-load:[state] (args) = incoming page load call completed for the state

pre-transition = incoming transition call for all states
pre-transition:[state] = incoming transition call for the state
post-transition = transition call completed for all states
post-transition:[state] = transition call completed for the state