This tutorial follows on from my initial article about Storyspace 3, and the first and introductory tutorial. Here I develop non-linear hypertext in a chapter, and start using guards to provide different readings for different readers. It begins with the project file which I ended up with last time: TreesInTheLandscape.tbx

Free reading form

The first chapter is going to continue with an introductory survey of paintings through the ages. For each of these, you will need three versions of each image:

• standard size, at something around 1000 x 1000 pixels, for detailed viewing,
• a small view at no more than 512 x 512, for ordinary looking,
• a thumbnail at no more than 128 x 128.

Create a new writing space by double-clicking in the Map view, and name it Rubens 1. Paste the text content in, then drag and drop the small view of the painting into that window, above the text. This forms the basic narrative writing space.

There are two further writing spaces which the more inquisitive reader may want: one of the painting at standard size, and its full caption information. Create those by double-clicking, then adding their content, the text by copy and paste, the painting by drag and drop.

In the basic narrative writing space for the painting, we want to offer the reader two options: to view the painting at full size, or to view fuller details about the painting. Create these as text links from that writing space. For the full-sized painting, drag the image to the blue button to create a text link, and link that to the full size painting writing space.

For the full caption, add a line containing the text Details at the top of the text body, select that, and make a text link from that to the writing space containing the detailed caption. Then for the full size painting writing space and the caption writing space, link them back to the Rubens 1 basic narrative writing space.

Now test that out, by switching to Read mode. Start at the basic narrative writing space, click the painting or Details text, then click again or press Return and check that you end up in the basic narrative writing space again.

Next add some more basic narrative writing spaces to complete more of this chapter. For speed and simplicity, I have not placed any images in them, nor the linked writing spaces out to full size images and captions.

The root chapter writing space comes next. Put the paintings with thumbnails in the sequence which you intend them to be viewed. Then add a final line to review them in full.

Connect each painting using a text link to its basic narrative writing space, returning from that back to the root chapter writing space.

Once happy, switch to Read mode and check that it is all wired up correctly.

Structured reading form

This provides the general reader with complete flexibility to meander through the book as they wish. But this book will also be used for teaching purposes, for which flow through the contents is to be more controlled and pedagogic. In that case, we would not give the students free access to the full-size view of each painting, or its full details, until they had completed reading the basic narrative writing spaces, and we want them to read those in order. This is achieved using guards.

We first want a boolean (true-false) attribute which can be set to determine whether the reader is free to read non-sequentially, or is constrained. Select the Trees in the Landscape writing space, where the attribute will be stored, and click on the + button at the upper right to open the attributes. In the General list, select the Checked attribute, and it will then be listed in the Outline view.

Now we will use that attribute setting – referred to as $Checked(/Trees in the Landscape) – to determine whether the full image and detailed information about a painting can be viewed when reading the chapter. The Rubens 1 writing space has two text links going out from it, to those detailed writing spaces. Click on the Rubens 1 writing space to select it, then on the ⓘ (i) on one of those two outgoing links. The link editor pane appears, and in the Guard textbox, enter
$Checked(/Trees in the Landscape)

Repeat this on the other outgoing link. Then switch to Read mode to test how the guard works. When the Checked attribute in the title writing space is checked, the links appear and work; when it is not checked, they are disabled, and the text remains black.

Better guard logic

We need more sophisticated guards than this, which will build in the logic to ensure that the links in Chapter 1 are followed in sequence. This is accomplished by using guards predicated on which writing spaces have been visited. The logic is simple: the first link out to Rubens 1 can always be followed. Each link out thereafter can only be followed if the previous link has been followed, and that writing space has been visited. So for the link to Rubens 2, the basic guard condition would read
visited("Rubens 1")

However, we also want to enable the link if $Checked(/Trees in the Landscape) has been set: logically, this is an or condition, so the full guard should read
$Checked(/Trees in the Landscape) | visited("Rubens 1")

The guard for the link to Poussin 1 should then read
$Checked(/Trees in the Landscape) | visited("Rubens 2")
and so on.

To make it easier to identify the links to have guards applied, spread the writing spaces out in the Map view, then add the guards to the outbound text links from chapter 1.

Before you can test them, you will need to reset the visit counts for each of the writing spaces to zero, as these are persistent. There may be an easier way to do this, but for now the best way is to select the writing space in the Map view, and use the Get info… command in the Note menu. In the pane which appears, select attributes at the far left, then Storyspace in the next column. You will then see the Visits attribute, and can double-click on the value and enter 0, pressing Return.

When you are happy, switch to Read mode and test them, first in textbook mode with the Checked attribute false (unchecked), and then in free reading mode, with it checked (true).

The final step for now is to enable the two outgoing links from the Rubens 1 writing space, so that a student can view the detailed image and full caption once they have worked through the whole of the pedagogic material. Do this by selecting the Rubens 1 writing space, then editing the guards on its two outgoing links to read
$Checked(/Trees in the Landscape) | visited("Gainsborough")

My example Storyspace 3 file is here: TreesInTheLandscape2