Porting from WordPress to Storyspace, 2: links and stretchtext

In the first article in this series, I started importing the HTML and images from my series on the history of oil painting, to assemble them into hypertext to be accessed from Storyspace Reader. In this article, I will progress to composing the images and text within the linked writing spaces which make up the spine of the hypertext.

If you want to visit earlier tutorials to remind yourself how to use features of Storyspace, you’ll find links to all my other tutorials on Storyspace in this index.

Those writing spaces which make up the spine will each use the Milestone prototype, which is intended to contain the text and images for each milestone event in the history, and has $StartDate and $EndDate as key attributes, so that it will appear on the timeline.


I have separated out the paintings (with their captions) used to illustrate each of the milestones so that I can use them with several different writing spaces. For example, this image shows what is probably the earliest oil painting in Europe; not only will it need to appear in the relevant milestone in the spine, but it will need to be included in a more detailed account of early oil painting materials and techniques.

This large version, with a maximum dimension of 1024 pixels, is just over 250 KB in size. If I keep embedding it in different writing spaces, it will steadily increase the size of the Storyspace document, which is inefficient. I want just a single copy there, and one of its smaller version, which has a maximum dimension of 512 pixels and only takes up 77 KB. These are not large files, but I have a lot of them, so eliminating duplication is important.

There are several ways of avoiding such duplication in Storyspace. I could fetch the images from online storage here, perhaps, which works fine when readers have a web connection, but lets them down when they don’t. I could put all the images in a single folder, perhaps somewhere in /Library/Application Support, and open them in Preview. But to implement that in a friendly way, I would need to provide a proper installer, and I’d like to make the document file complete in itself, if possible.

I have also already mentioned the importance of showing the images in the context provided by the text, so I need to use code expressions for text substitution.


I use the most basic of these, ^include(), to call in the smaller image in its appropriate context. Because I am storing all the images (within writing spaces) in the Gallery container, I have to refer to them using the ‘path’ beginning /Gallery. For best style, I should really put the entire path in quotation marks, as
^include("/Gallery/Tingelstad Altar Frontal")
However, as this expression has only the one variable passed to it, and that is enclosed within parentheses, there is no scope for confusion. There is, though, scope for error if you do use quotation marks: they must be plain marks such as “” and not the ‘pretty’ typographic version of “” which are so often substituted when you press the normal key. To enforce plain quotes, you need to press Control-Shift-” rather than just Shift-“.


The moment that we switch from Edit to Read mode, that expression brings in the image and caption from the small painting writing space, showing the Tingelstad painting.

When you switch back to Edit mode, the included content is replaced by the ^include() expression again.


The other expression for text substitution which I will use here is stretchtext, using ^stretch(). I have recently looked in detail at stretchtext, and this is an almost perfect example of its use, to open the large version of the image. The expression here is fairly simple,
^stretch("Large image of the Tingelstad Altar Frontal","/Gallery/Tingelstad Large")
to use best style by putting both the anchor and the path in quotes.

As with ^include(), when in Edit mode all you see is the expression.


Switch to Read mode, and the anchor text appears, distinguished in blue. The reader will thus initially see this writing space with just its small captioned image, and the anchor below that.


Only when they click/tap on the blue anchor text, in Read mode, is the large image (and caption) fetched from the referenced writing space.

The use of ^include() and ^stretch() expressions ensures that the images are displayed in the original context. The reader only needs to scroll through that content to be able to read the text and refer to the image, and vice versa. They do not need to juggle windows, tabbed views, or go back and fore through the writing spaces.

In this case, I want the reader to be able to see both the smaller and large images simultaneously, in context, when they wish. In other circumstances, you might want the reader to choose whether to view only smaller images or larger ones. You could then use the ^if() … ^else … ^endif expression in conjuction with a boolean User attribute. Indeed another ingenious and flexible solution might be to combine that with stretchtext, in
^if($ShowLarge) ^stretch("Large image of the Tingelstad Altar Frontal", "/Gallery/Tingelstad Large") ^else ^include("/Gallery/Tingelstad Altar Frontal") ^endif

When the User attribute $ShowLarge is true, the stretchtext will appear, requiring the reader to click on the blue anchor text to reveal the large image; otherwise, when that attribute is false, the smaller image will be substituted without the stretchtext feature. This gives you an idea of how flexible these code expressions can be for building content.


The reader’s progress through these milestones is intended to be linear, with time, so I have added the next milestone, Layers and Glazes, and you here see it with the included text and stretchtext both brought in, and the milestones linked together using plain links. At this stage, there are no text links to take you away from the spine along limbs which go into each milestone in more detail: those will come later.

So far, I have been working in the Map view, and with the content of writing spaces, and have not even looked at the Timeline view. Now that I have three milestone and two paintings in place, I will take a moment to look at how it is shaping up in the Timeline. Before doing so, I need to focus the Timeline on the period in which I am interested, so that it captures the milestones better.

To do that, I open the Inspector, select the document tab, and set two Events attributes to the start and end of the Timeline window: I set $TimelineStart to 01/01/1000, and $TimelineEnd to 01/01/2010.


When I then switch to a Timeline view, I can see the milestones and individual paintings shown correctly. For next to no effort at all, Storyspace is happily plotting my content on that Timeline.

My next task is to complete the spine of milestones, and then look at how best to incorporate additional detail, including Vasari’s account, and other linked narratives.

Happy hypertexting!