The Interruptable Sequence Pattern

The interruptable sequence is a web programming design pattern I recently identified and used in a site I'm developing. I tried to locate existing descriptions/definitions of this pattern with no success - I looked for 'interruptable sequence', 'tutorial pattern', 'sequence pattern', etc. without finding anything similar to what I'm about to describe, so I'm posting about it here in the hope that someone else will find it useful.

Software design patterns are an idea that's been around for quite a while... there's plenty of literature on the topic, not the least of which is 'Design Patterns: Elements of Reusable Object-Oriented Software' by the 'Gang of Four' (ISBN: 0201633612, ISBN-13: 978-0201633610). However, web-patterns are a more recent topic, and although there's a little bit of content spread around the internet, there doesn't seem to be an authoritative or even central/complete catalog. As such, I'm going to try and collect what I can here, especially since I've been very much into the software design and modeling area of study lately.

So, without further ado, the Interruptable Sequence pattern. (I've attempted to follow the same format as the pattern catalog contained in Design Patterns, so hopefully this ends up being relatively coherent and/or of a familiar format to some of you...)

Note: In the context of this (and future) articles, a 'Web Pattern' is a software pattern that applies specifically to software whose environment is the web, ie: sites or webapps...

Interruptable Sequence

Classification
A behavioral pattern with a cross-request scope.

Intent
Supports a sequence of actions as a progression of separate page requests, which can be started, stopped, resumed, exited and completed at any point throughout a user's session.

Also Known As
Tutorial Decoration

Motivation
Let's assume that you have created a site that requires a tutorial or walkthrough, to guide new users through using the basic functionality. You want the user to be able to 'follow along' with your instructions, but you also don't want them locked in to the tutorial until it's complete - they should be able to exit and resume the tutorial at will, etc.

There are some requirements for such a sequence that immediately come to mind:

• - we want the user to be able to enter and exit the sequence at will - therefore upon exit the state of the sequence should be preserved, so that on re-entry, the user is directed to the same point in the sequence where they left off.
• - we want to be able to simply 'decorate' existing functionality with messages related to the sequence - we don't want to duplicate pages/fragments for the sake of presenting them within the sequence.
  
• - the logic for a given page should know that the user is participating in a sequence (or not), and render the page (or rather, the sequence-related elements) appropriately.
• - ideally, the only customization of the sequence implementation that we would need to do each time we want to setup a sequence is to define each step in the sequence, ie: via a small set of information required for each step, such as the page uri, the sequence message, the sequence this step belongs to, and the index of the step if we're not simply appending steps in their 'native' order.

The pattern solves the problem as follows...

• - The code library for the pattern defines two main functions: sequence_manage, which is run at the beginning of every user-facing page request and sequence, which is run during every request that is part of the sequence.
  
• - sequence_manage is responsible for initializing the sequence-related data structure within the session store, and more importantly, for storing certain variables related to the state of the sequence.
• - sequence is responsible for realizing each successive step of the sequence.
• - The pattern's code library will also define an auxillary function: sequence_append_step, used to setup the sequence itself.

Applicability
Use the Interruptable Sequence when:

• - you want to define a sequence of page requests that can have auxillary information displayed with each step, and the sequence follows some kind of progression, ie: a tutorial.
• - you want the user to be able to leave and re-enter the sequence via normal navigation elements at any point.
• - you want the state of the sequence to be preserved between separate periods of the user being 'inside' the sequence

Structure
Note: diagram isn't up to snuff, this was done in a rush via Gliffy, but I'll update and post a better version eventually...





Participants

• - a session store - used to persist sequence state information across requests.
• - sequence_append_step, sequence_manage and sequence - used by the request handler at various points to execute the necessary sequence logic.

A session store is assumed to be provided already by the existing site or framework code. The other participants are provided by the implementation of the pattern... in the example below, the implementation is targeted at Ruby on Rails, and the pattern is implemented as a collection of methods in a module that is mixed in to a controller class.

Collaborations
A session store is used to store the necessary state information used by sequence_manage and sequence. sequence uses the sequence-step definitions created by sequence_append_step.

Consequences
The main consequence of this pattern is a decoupling of the components of the sequence (ie: text, sequence-specific navigation elements, logic) from the existing site components that comprise the steps of the sequence (ie: pages of a site or application). This decoupling allows us to independently vary both the sequence itself and the components that comprise the steps without affecting the other. It also allows us to re-use the components used for each step in more than one distinct sequence. Lastly, following the "don't repeat yourself" software engineering philosophy adhered to by any good object-oriented system, it removes the need for any duplicate logic or code/markup that is used to implement the sequence. We are left with a single library of functions/code that allows us to create a sequence, and the only per-sequence coding that needs to be done is to define the steps of the sequence itself and the content of each sequence step (ie: the text that decorates an existing component when displayed as part of a sequence).

Implementation
To implement the pattern, there are a few pieces of data that we need to store in a session:

• - the current step of the sequence (ie: sequence index)
• - the name of the sequence that's currently being followed
  
• - whether or not the sequence is currently active
• - the uri that acts as a referrer for the sequence - this is the last uri that was visited by a user before (re-)entering the sequence
• - the current uri, to be accessed on the next request as the last uri (Note: this data is almost always available via the server-side environment as the HTTP_REFERRER. However, to remove such a dependency, we include code to explicitly store this value in the sample implementation below, instead of relying on the environment of the application/site to provide it implicitly).
  

Next, we need to write a few main functions to implement the sequence pattern:

1. A sequence_append_step function that is used by the site/application to define the steps of the sequence. The sequence is treated as a stack of items - each item corresponds to a step in the sequence, and the first item in the sequence 'stack' corresponds to the first step in the sequence. This function will need to take a few arguments: the name of the sequence we're appending this step to, the uri of the step that's being appended, and any other data needed to implement the step... in the example below under Sample Code, the last argument is the name of a template that's rendered as the decoration for this sequence step. The method, timing and location used for storing the data for each step is irrelevant to the pattern itself; as such, either persisting this data between requests somehow (session, rdbms, etc) or calling the step-defining code on every request is a valid answer to this question, the storage method most appropriate will depend on the programmer's specific requirements for speed or storage optimization, etc.
   
2. A sequence_manage function that is called at or near the beginning of every request. It's main responsibility is to determine whether we are currently following a sequence or not. It does this by checking if either the previous uri (ie: the referrer, the uri that redirected us here) or the current uri corresponds to a sequence uri. If not, it stores the current uri as the sequence referrer uri, and explicitly disables the sequence (via a sequence_active flag stored in the session), since we're not currently following a sequence. The sequence referrer is used to return the user to the place from which they entered the sequence, once the sequence has been completed. Additionally, this function is responsible for storing the current uri in the session, to be accessed in in the next call to sequence_manage as the last_uri mentioned above.
3. A sequence function - this is generally activated by visiting a sequence-specific uri, ie: by clicking 'next step' in a sequence or a navigation link that targets (the beginning of) a sequence. The sequence function needs to be passed the sequence step to 'execute', as well as the name of the sequence we're executing, if not already known (ie: when starting a 'new' sequence). This function is responsible for the bulk of the sequence logic... 1) if the named sequence doesn't exist, or if the sequence step being executed corresponds to 'finish', then finish the sequence (reset the sequence step to zero, disable the sequence, and return the user to the sequence_referrer uri), 2) otherwise, explicitly enable the sequence (it may not already be active), set the current sequence step if a step value is passed and redirect the user to the uri corresponding to the (first) current step in the tutorial.
   

Sample Code

The following is a bare-bones implementation of the pattern written in Ruby, for the Rails web application framework.

We already have session and redirect support, which are the main requirements/dependencies for this implementation of the pattern.

First, the pattern 'library':

module InterruptableSequence

  def sequence_append_step(sequence_name, sequence_uri, sequence_data)

    # initialize our local sequence data structure(s), if necessary...

    if @sequences.nil?
      @sequences = {}
    end

    if @sequences[sequence_name].nil?
      @sequences[sequence_name] = {}

      @sequences[sequence_name]['uris'] = []
      @sequences[sequence_name]['data'] = []
    end

    # append the step to the sequence...

    @sequences[sequence_name]['uris'].push sequence_uri
    @sequences[sequence_name]['data'].push sequence_data
  end


  def sequence_manage

    # initialize the session-based sequence data if necessary, as a hash
    # so that the only pollution of the session namespace we're doing is adding
    # one new name ('sequences')

    if session['sequences'].nil?
      session['sequences'] = {}
    end

    # check if we need to store the referrer and disable the sequence

    # note: this implementation assumes that the controller action for a
    # sequence step is 'sequence', which is how we identify if this request
    # is for a sequence page or not

    if session['sequences']['last_uri'] \
    and session['sequences']['last_uri'].match('^/[^/]+/sequence($|\?)').nil? \
    and request.request_uri.match('^/[^/]+/sequence($|\?)').nil?

      # this is currently NOT a sequence-step request... store the sequence referrer

      session['sequences']['sequence_referrer'] = request.request_uri

      # turn off the sequence

      session['sequences']['active'] = false
    end

    # store the request uri, to be used during the next request as the referrer

    session['sequences']['last_uri'] = request.request_uri
  end


  def sequence

    # read arguments from request parameters, if present

    if ! params[:step].nil?
      session['sequences']['step'] = params[:step]
    elseif session['sequences']['step'].nil?
      session['sequences']['step'] = 0
    end

    if ! params[:name].nil?
      session['sequences']['name'] = params[:name]
    end

    # check if we're 'finishing' the sequence

    if -1 == session['sequences']['step'] \
    or @sequences[session['sequences']['name']].nil?
      session['sequences']['step'] = 0
      session['sequences']['active'] = false

      redirect_to session['sequences']['sequence_referrer']
    else
      session['sequences']['active'] = true

      redirect_to @sequences[session['sequences']['name']]['uris'][session['sequences']['step']]
    end
  end

end

Next, we make use of the pattern library in our main ApplicationController class:

class ApplicationController < ActionController::Base
  include InterruptableSequence

  ...

  before_filter :sequence_manage

  ...

  def initialize
    sequence_append_step('my tutorial', '/orders/create', 'my_tutorial_step_one')
    sequence_append_step('my tutorial', '/orders/edit', 'my_tutorial_step_two')
  end
end

In this example implementation, sequence_manage is being called on every request via the installed before_filter in the ApplicationController class, from which all other controllers (request handler classes) inherit. The sequence is defined in the constructor of the ApplicationController class, so it will be available in all controllers. sequence_append_step, used to define the sequence, stores all sequence-specific data in @sequences, which is an instance variable of whatever controller object the request is being handled by. Since we're including the InterruptableSequence module in the main ApplicationController class, any controller can call sequence (ie: by visiting /controller_name/sequence) to start/resume a sequence.

The page rendering code can examine session['sequences']['active'] to check if a sequence is currently active... if so, it can use session['sequences']['step'] to pull the sequence-step data value from @sequences, which in this case is the name of a template to render within the page that's being used as part of a sequence.

The same code also uses the step index to construct sequence-specific navigation elements such as 'next' or 'previous'... if we're on the last step, a 'next' link would pass '-1' as the step index to the next request, which would signal the sequence logic to 'finish' the sequence and redirect the user back to where they were when they started the sequence.

Note that the above implementation has been simplified for demonstration purposes - it's lacking some important error checking, etc. Also, certain functionality which is supported by the pattern may not be illustrated above, such as multiple sequence usage, etc.

Known Uses
As already discussed, a website usage tutorial is a good example of a candidate for using the Interruptable Sequence. Another example of an application for this pattern would be an online shopping cart checkout process, whose steps are comprised of cart functionality that already stands on it's own, ie: using the independent 'update shipping address' page within the checkout flow. Alternately, this pattern could be applied to a situation where only part of the sequence is made up of pre-existing functionality, with the balance being created specifically for the sequence (ie: a variation of the online shopping cart example above, where portions of the checkout process (ie: 'enter shipping address') are re-used from existing pages unrelated to the checkout process itself.

Related Patterns
Unknown