Storyspace 3: structuring hypertext using rules instead of links

There are times when even Storyspace’s sophisticated links are too constraining. This brief tutorial looks at one way of using Rules to allow the reader to visit writing spaces in a way that is structured by time and space, rather than links. It is based on an article here about paintings made of Piazza San Marco (Saint Mark’s Square) in Venice.


My aim is to present the reader with an interactive map of the Piazza, in which each painting is placed according to the location from which it was painted. However, as there are quite a lot of paintings, and most readers will also be interesting in how those paintings changed over time, I am going to structure this in time too.

The idea is, therefore, to allow the reader to select a time period, and to show only those paintings made in that selected period.




I therefore need two prototype writing spaces: one for the time periods (1500-1700, then by century up to 1900-1940) which will act primarily as radio buttons, the other to represent paintings.

There are several different ways in which we can control the selection of period buttons, and determine which of the painting writing spaces are visible.

One might be to have a Boolean user attribute IsSelected, and to search through all the writing spaces using the special designator find(). A snag with that is that all references to attributes within find() are to the local attribute: there does not appear to be any way of comparing a local attribute with that of the writing space calling the find(). So this action would have to use hard-coded values along the lines of
$IsSelected( find($Era=18))=true
which gets messy.

The solution which I have arrived at has a user attribute Era, a number ranging from 16 to 19, to indicate which time period is selected. The global value which applies at any time is that in the start writing space. Clicking on one of the radio buttons sets $Era(start) to the value associated with that button.

Each writing space then has a Rule which compares its own value for Era against $Era(start), and responds accordingly. The selected button’s value will match that of start, so it will be highlighted. Other buttons will not match, so will not be highlighted. Paintings whose Era attribute matches that of start will be visible, and those whose Era is different will be invisible (almost).


With a new document, create a writing space to be the prototype for those which will function as radio buttons. Double-click in the Map view to create a new writing space, and name it button. Using the Document Inspector, create a new user attribute named Era, to contain a number with the default value of 18.


Using the + button at the upper right of the Outline view, expose the User/Era, Storyspace/OnVisit, and Appearance/Color attributes.


Then select the start writing space, and expose its User/Era attribute. Select the button writing space again, and in the Prototype tab of the Properties Inspector, make it a prototype. Then add the following script to its OnVisit action:
so that visiting (clicking) it will set $Era(start) to the local value of the Era attribute.


Now, with the button prototype writing space still selected, add the Rule which will set the button’s appearance according to whether $Era(start) is the same as its value of $Era:
if($Era(start)=$Era) {$Color="red"} else {$Color="warm gray dark"}


Create four new writing spaces to represent the four radio buttons, named 1500-1700, 1700-1800, 1800-1900, and 1900-1940. Set each to use the button prototype, and set their Era attributes to 16, 17, 18, and 19 respectively.


Test the four buttons out now: click on one and it should be highlighted in red, and the others set back to dark grey.

Now create the prototype writing space for paintings, which will be placed over a plan of the Piazza. Double-click in the Map view as usual, name the prototype painting, and expose the attributes User/Era, Appearance/Color, Appearance/Opacity, and Appearance/Shadow. Turn Shadow off, set Color to red, and in the Action Inspector add the Rule
if($Era(start)=$Era) {$Opacity=100;} else {$Opacity=0}


This simply ‘hides’ the writing space in the Map view if it is not in the selected Era. Finally, make this a prototype in the Properties Inspector.

Test this out by creating several writing spaces which use painting as their prototype, and giving them different values for the Era attribute: they should appear and disappear according to which of the radio buttons is selected.

To finish off, I have dragged and dropped my plan of the Piazza into the Map view, resized it with the Shift key held to retain its proportions, then added some appropriate content, and some example paintings for you to try out. These are included in the copy of the Storyspace 3 document which you can download here: PiazzaSMarco