How Using State Diagrams Can Make You a Better Web Coder

One tool that should be in your web coding arsenal is the state diagram. A state diagram shows the various "states" (reactions) that your application (e.g., web site) can be in, as well as what action or input (from the user) is necessary to get to a specific state. A state diagram helps to make concrete in your mind all of the possible user/application interactions. This increases the chances that you'll at least consider coding for all possibilities simply because you now know them all - which reduces the chances that you have buggy code or worse, forgot to handle specific functionality.

Why Use a State Diagram?

A state diagram consists of two components: circles to represent states (application reactions/ output) and arrows to represent transitions (user actions/ input). State diagrams are very handy for complex and not so complex computer applications of any sort. However, when it comes to website development, state diagrams are not always of use:

If you have a static website where the navigation guarantees that every single page links to every other page, then a state diagram is redundant. (In the branch of mathematics called Graph Theory, this situation is known as a "fully connected graph". A graph is a set of edges and nodes - i.e., transitions and states.)
If you have a dynamic website running on a CMS (Content Management System) - which includes blog platforms - then so much of the state transitions are already coded into your site. So once again, a state diagram is not of much use.

On the other hand, if you are building a website where you have to handle special transitions, then a state diagram can be of great benefit:

Handling special user input, where what they select decides the next state. (E.g., forms or menus that have drop-down or dynamic lists.)
AJAX-y sites where even after a significant user action, the URL does not change. (Content does, URL doesn't.)

How Do You Create State Diagrams?

The surprising thing is that state diagrams are not all that complicated to produce. Yet in my experience, they are not used all that often by most programmers, despite the benefits (deeper understanding of user interactions; cohesion of coding effort). I swear by them - or did when I was coding every day in various jobs.

It's recommended that you do produce state diagrams on paper first, then transfer them to a digital copy if and only if that's necessary. (There's something about the tactility of sketching input/display relationships on paper that makes them more concrete in your mind, making it easier to accomodate all possible interactions and thus reduce bugs in your applications.)

A state diagram consists of:

Labeled arrow lines to show user input/action (transition).
Labeled circles to show the resulting display of content (application state).
Start state with a double-border circle.
End states (but not when the application is web-based. See below for an explanation.)

You can see a simple example directly below - which will be expanded on later in this article:

Here are the steps for creating state diagrams (with a leaning towards website-based applications):

Make a list of all possible inputs by the application user, from every single state.
Draw the Start state - a double-border circle labeled with "S". With a web site, the start state is the home page and its default display.
Draw circles for possible unique state or sub-state. For static sites, each web page is a separate state. If for your web app can have different sub-states for the same URL, then you need to draw separate state circles.
For each possible action from the start state, draw labeled arrows (transitions) to the next possible state's circle.
Repeat this from each state until you have a full state diagram for the application.
Don't forget about circular transitions. E.g., from one state back to itself (possibly because of re-clicking the same link twice).
Repetitive transitions from a cluster of related states can be represented with some short form, as will be discussed below.
State diagrams for non-Web applications almost always have an "End" state. However, the Web is said to be "stateless" because in a web browser, every single state is an end state. You can take an action and leave, or take another action and then leave, etc. So for web applications, there's no need to draw the End state.

To expand on #7 above, keep in mind that with websites, there could be a lot of repetition of actions. For example if every page includes the same navigation menu, there's no need to show those transitions over and over and clutter up the state diagram. Just represent clustered actions with some short-form notation/ symbol.

(It's far easier to understand a state diagram if you are the person drawing it, one step at a time. If you are a person looking at a completed state diagram, it might be intimidating. For this reason, state diagrams often live only paper - assuming you use them.

How Do State Diagrams Apply to Website-based Applications?

For a static website that uses no AJAX-y features (i.e., any feature where the URL does not change), a state diagram is fairly easy to produce but generally unnecessary. For example, a static website in which every page is connected to every other page results in a state diagram that is sometimes referred to as a "fully-connected" graph. Such state diagrams are usually pointless because there's no special handling to visualize. Every state is connected to every other state)

Where state diagrams are most handy is for dynamic sites - especiall those with AJAX-y features (such as drop menus, sliders, accordions, galleries, etc.). In the latter case, the URL in the browser might not change but the page content does so partially. It's harder to visualize all possible states and transitions (actions) because a "page" can have multiples sub-states.

A state diagram (or set of increasingly detailed diagrams) comes in very handy in this case - especially if there are a team of coders (and sometimes designers) to work with.

An Example of State Diagram Use

In an upcoming tutorial I'm going to show you how to code the jQuery for two effects I'm using in my AboutMe template. The live page has a few CSS glitches that need to be ironed out first. I'd also like to add some more jQuery-based features if there's enough time. These additional features will be the subject of our example.

In the future, this template will turn into a free WordPress theme aimed at freelancers that want to showcase their work (gigs) experience. For now, I want to show how state diagrams can help you understand the necessary cause/reactions (aka input/transitions) for the "Current Gigs" gallery seen above. Understanding the necessary transitions helps you to code more confidently, and it's all coding language-independent. So you can decide on code library/language after creating the state diagram.

Desired Application Features

If you look at the "Current Gigs" gallery at the center left of the image above, or on the live page, you'll see that this is essentially the same concept as an image gallery. Click a link and details of that "gig" will appear. However, when I built the live page, there were no jQuery tutorials on how to throw text into the mix, for each "frame" of the showcase. I had to come up with my own code.

To do that, I had to first understand all possible user interactions. A state diagram is ideal for this. Let's up the ante, though. What I really wanted is a showcase area that shows both Current Gigs and Past Gigs. It's sort of like a visual C.V. (Curriculum Vitae, aka "resume"), showing a gallery of work experience. Each gig's frame contains a screen snap of the associated site's home page, along with some text giving details of the work I did/ am doing there.

For now, the page only has "Current Gigs", but should have "Past Gigs" as well. Here is a list of the functional requirements for what the showcase area should have:

Tabbed jQuery interface, but "invisible". Instead of using regular tabs, use mini-banners similar to the "Current Gigs" graphic.
When a "tab" is clicked (Current Gigs, Past Gigs), the appropriate gig list is shown, along with the frame (details) of the first item.
The default showcase is "Current Gigs".
When someone clicks "Past Gigs", then the past gigs list must show, along with the details frame of the first item in that list.
Gigs lists. Each "tab" will provide a list of gigs positioned to the left using a Blueprint CSS grid.
The gig list items will be text links.
Each showcase will have entirely different links (past and present work). So a "job experience" can only appear in one showcase at a time.
When an item in a gig list is clicked, the gig's details "frame" will appear. Each frame will show a screen snap (previously saved) and the associated job description. The Blueprint CSS grid framework will be used to position the showcase elements. (This isn't necessary, but that's what I'm aiming for.)

So to reiterate, the goal is to have a tabbed interface where the tabs are labelled "Current Gigs" and "Past Gigs". This allows for more tabs later, limited only by the width of each label and the width of the showcase space (590 pixels). But I want the tabs to be "invisible", as mentioned. Instead of the typical tabs in a tab interface, I want to use mini-banners. If you look at the live test page, there's a mini-banner labeled "Current Gigs", and another labeled "Past Gigs". Those will be the tabs. Here is a closeup screen snap of what the final showcase area might look like, with default settings.

Creating the State Diagram

To create the state diagram, we first have to enumerate every possible unique state, input and action:

Start state: Upon load of the home page:
1. Hide (non-display) all gig frames using CSS.
2. Present "Current Gigs" showcase as default.
3. Within the default showcase, present the frame for the 1st item in gig list as the default. So whenever someone clicks the Current Gigs "tab", the showcase will reset itself.
Possible generic actions from the Start state:
1. Click on "tab". Reaction/ transition: render the showcase corresponding to the tab clicked.
2. Click on a gig list item. Reaction/ transition: render the corresponding gig item frame.
Possible generic actions from other states: exactly the same. We're fortunate in this case, because this makes the state diagram so much simpler.

Note: At this point, we're only concerned with what's happening in the C.V. showcase. In the state diagram, we don't care about actions that affect other parts of the web page. We're only showing actions/ reactions that affect the C.V. showcase.

Here is a sample state diagram for the above functionality.

A few notes about this diagram:

For the purposes of this discussion, it's not all that important what each label actually is. Here, each one represents a website that I am either writing for now or used to write for.
It's not as complicated as it looks. Just focus on one transition at a time and it'll be clear what's going on. [Here, the action labels are the same as the state labels. That's not always the case.] It's usually a lot clearer when you draw the diagram yourself, adding new state circles and transition arrows one at a time.
Transitions, aka user actions, are represented by labelled arrows. (Normally the labels would be full text, not the short forms used here.)
States, aka reactions, are represented by circles. The start state is always marked with a double circle and an "S".
Short forms are used for both types of labels, to keep the diagram less cluttered.
The states and sub-states are color-coded based on whether they are primary or secondary in nature. For example, blue represents primary states (and transitions). You can go from Start state to any blue state with a single click on the appropriate link. You cannot go to a purple (secondary) state from Start without first passing through a primary state.
Because there is a lot of repetitive transition (i.e., from any gig item to another), groups of transitions are shown with one of the thick outlined arrows (blue or purple fill). For example, while you're viewing the FF (FreelanceFolder) gig details, you can click on any of the gig items listed for the CG (Current Gigs) showcase, including FF itself. Or you can click on the CG "tab" and reset the showcase. You cannot go from a "current" gig frame to a "past" gig frame, nor vice versa.
The short, outlined blue arrow includes transitions back to CG's default state. The short, outlined purple arrow does not include transitions back to PG's default state. (That's because those transitions are already shown explicitly. They were not for CG because the diagram would be way too cluttered.)

Expanding on point #5 above, the rule of thumb is that if there are multiple repetitive transitions from a related cluster of states, you can annotate the transitions with some sort of short form. You simply want to get a sense of the important transitions so that they are foremost in your mind. Another approach is to take a complex diagram and split into parts: main overview, then "exploded" versions of transition clusters.

For example, the diagram above could have had a main state diagram containing the nodes S, CG and PG. Then there would be two detailed diagrams. One would have S, CG, and the corresponding sub-states representing various gigs. The other detailed diagram would have S, PG, and the corresponding gig sub-states.

Final Thoughts

Overall, you should now have a clearer mental picture of how the showcase section functions. I'm not going to get into how to move from a state diagram to actual code. That should become evident once you understand all the user interactions. State diagrams - and your understanding of them should help you to write more cohesive code, reducing the chances of a buggy application. Your coding technique does not change.