This is some documentation from an old wiki. We should put this in the new site somewhere.

Why Sequences

Sequencing was created because we had a document creation process that required a user to follow a certain order of pages within one or more zones. There were multiple places that needed to lead to this process. So we made sequences that would order the pages, and then at the end of the process, send the user back to whatever page he had started on. In addition, we sometimes had pages in different orders based on where they came from.

As you might imagine, this led to some very complicated, bug-prone conditional navigation code. So to deal with this, we made an xml-based sequence engine. The idea is that you define how to make an url for a zone, any sequences of pages that a user might travel through for that zone, and then you specify sequences of zones that you will be using. Then inside the code for each zone, you can ignore navigation completely.

As an example, imagine you had something like a forum. You have a "register" process that takes a few page views to complete(because you require their SSN for some silly reason, and their address, and all kinds of things). You want to send them back to wherever they came from. Without sequences, this could be resolved by just saving the url where they clicked register, and returning to it when the register process is completed. However, in addition, you want to reuse the register pages so that registered users can edit their information. Without sequences, you now have to have some kind of logic that stores whether I'm registering or not, and then some logic at the end of each page that does different navigation.

The XML side

The XML used is better documented at SequenceXmlDoc.
With the sequence component, you can instead specify some xml:

<sequences>
  <zone name="userInfo">
    <param name="userId"/>
    <url>
      <link name="userInfo"/>
    </url>
    <pagesequence name="register">
      <step name="basicInfo"/>
      <step name="extendedInfo"/>
      <step name="loginInfo"/>
    </pagesequence>
    <pagesequence name="edit">
      <step name="viewInfo"/>
        <action name="basic" page="basicInfo"/>
        <action name="extended" page="extendedInfo"/>
        <action name="login" page="loginInfo"/>
      </step>
      <freepage name="basicInfo">
        <action name="back" page="viewInfo"/>
      </freepage>
      <freepage name="extendedInfo"/>
        <action name="back" page="viewInfo"/>
      </freepage>
      <freepage name="loginInfo"/>
        <action name="back" page="viewInfo"/>
      </freepage>
    </pagesequence>
  </zone>
  <zonesequence name="register">
    <param name="userId" value="new"/>
    <step zone="userInfo" pagesequence="register"/>
  </zonesequence>
  <zonesequence name="editUserInfo">
    <param name="userId"/>
    <step zone="userInfo" pagesequence="edit"/>
  </zonesequence>
</sequences>

The PHP side

When you want to jump into a sequence, you just create a ZoneSequence object, set the parameters for it, and then getUrl from the object, and it's all taken care of for you.

For the example above, you have some code to enter the sequence like:

$seq = &new ZoneSequence('register');
redirect($seq->getUrl());

$seq = &new ZoneSequence('editUserInfo');
$seq->setParam('userId', $userId);
redirect($seq->getUrl());

Now, in your post functions, you don't have any navigation code at all.

Performance

To address concerns about performance, you can rest assured that when you are not using sequences, it doesn't decrease performance at all. When you are, I can only say that the code is all really fast. No complex algorithms in it, and I have not found any human perceptible decreases in performance. It's in use on a heavy production site, without a significant increase in load.

Code Efficiency

As far as using 3 lines of code... If you can use 3 lines of code, I would suggest that you do that. Sequences is really only meant to help in more complex situations. If you think that sequences is too complex for your usage, it probably is. And I will also admit that there is some redundancy in simple situations in the xml. If I get time, I might make it more friendly to simple situations.