Building Your Control Flow with Miso.Storyboard

Today we at the Miso Project are excited to release a new library, called Storyboard, our state management library for control flow of interactive interfaces.

As more and more of our code is written in an asynchronous manner, managing the flow of our code becomes more challenging. Event broadcasting and subscriptions is a common pattern for controling the flow of an application. Unfortunetly, that can become unmanageable and difficult to follow or debug when applications grow large.

Additionally, when thinking about interactive content, we often have multiple controls in a single interface that can be in different ‘states’. Take a common treemap control, for instance. It may be animating in or out, or may be showing a detail view rather than the entire treemap. Managing the switching in between these states often requires breaking encapsulation and intertwining controls.

Miso Storyboard offers a way to combat the aforementioned issues. Storyboard is a small library for a very simple idea: defining your application (or subset of your applications) as a set of ‘scenes’, each of which has enter and exit methods. When transitioning to a specific scene, the previous scene’s exit method is called and the next scene’s enter method gets invoked. These methods can serve as useful tools for organizing and managing your application’s state.

In practice, this allows you to define the states of your specific application separate from each other. For example, a single component might need to do a few things when it begins (such as rendering some UI and so on,) and when it’s ends (like remove loading messages). That same component can also be ‘updatingData’ or ‘showingDetails’. Either way, the enter method for each one of these scenes can set up the component state and the exit method can tear it down.

Miso.Storyboard is built on top of Underscore.Deferred, which allows your transitions to be asynchronous.

Enough talking… here’s what a storyboard might look like. Checkout the code on github and the (tiny) API on the Miso Project Storyboard site.

storyboard.example.js

var interactive = new Miso.Storyboard({
  // our initial state will be loading
  initial : 'loading',

  scenes : {

    loading: {
      enter : function() {
        // show that we are in a loading state
        $('#loading').show();
      },
      exit : function() {
        // This exit method is going to be asyncronous
        // so we will first declare it as such
        // by making a callback we will then need to call
        // to actually exit this scene.
        var complete = this.async();

        system.loadData({
          success : function() {

            // When our data actually loads, we can fade out the
            // loading screen (note also async!) and
            // finally call our complete method.
            $('#loading').fadeOut(function() {
              complete();
            });
          }
        })
      }
    },

    // the mainscreen scene just has our main content
    mainScreen : {
      enter : function() {
        $('#mainScreen').show();
      },
      exit : function() {
        $('#mainScreen').hide();
      }
    },

    // our details screen is for a specific element you might
    // select from the main screen
    detailScreen : {
      enter : function(datum) {
        //update the detail chart with the datum reference
      }
    }
  }
});

// Kickoff the storyboard. It will enter the initial
// scene we specified (which is loading.)
interactive.start()
  // when we're done loading, transition to the main screen
  .then(function() {
    interactive.to('mainScreen');
  }
);

// At some point, wire up a control to switch to the
// detail screen...
$('#mainScreen a.detail').click(function() {
  interactive.to('detailScreen');
});