Dynamic stories: text substitution and stretchtext in Storyspace (and Tinderbox)

There are many different ways of creating dynamic text in notes (writing spaces) in Storyspace and Tinderbox. This short tutorial is aimed at those who already know the basics, and can for example create text links, and who want to make use of the new text substitution features in the latest versions. If you are still using an older version of Storyspace or Tinderbox, you will almost certainly need to update to the current release in order to be able to complete this.

When Storyspace (which will include Tinderbox, where appropriate) displays text in a writing space (note) in Read mode – the only mode available in Storyspace Reader – that text is processed to perform any substitutions, which are marked by inline commands prefaced by a carat mark ^. You can use these to display dynamic content, which can be determined by attributes, or by reader actions such as clicking on blue text links.

Create a new Storyspace document. Using the Inspector, create two user attributes:

  • theName, a string with a default value of “Me”,
  • theBoolean, a Boolean with a default value of true.

Select the start writing space, and expose those two attributes.

Simple text substitution using ^value

Replace the text in the start writing space with
This document has been personalised for ^value($theName).

This simply looks up the value of the attribute $theName, and inserts it in the text. Edit the value of $theName to your real name, and you will see it appear in the text when it is viewed in Read mode.

Including text from another writing space (unconditional)

Add a writing space named note1, containing the following text:
This text has been included from the writing space named “note1”, and will always be so included.

Then append the following to the text in start:

When you switch to Read mode, the text from note1 is inserted in the text of start.

Conditional inclusion of text

Add a writing space named note2, containing the following text:
This text has been included from the writing space named “note2” because theBoolean attribute is true.

Then append the following to the text in start:
^if($theBoolean) ^include(/note2) ^else theBoolean is set to false. ^endif

Observe that, in Read mode, the text which appears in start now varies according to whether $theBoolean is true or false. If true, then the text from note2 is included; if false, then the text given (“theBoolean is set to false.“) appears instead.


Begin by creating three additional writing spaces, and using text links to them to answer a simple three-way question. In the writing space start, enter the text
The next major version of macOS is named:
(click on the correct answer).

Then create a writing space named copperanswer, containing the response to be shown if the reader selects that, something like:
Incorrect: there has not been any version of macOS named Copper.

Create a writing space named yosemiteanswer, containing:
Incorrect: Yosemite was the name of the previous version to El Capitan, OS X 10.10.

Create a writing space named sierraanswer, containing:
Correct: macOS 10.12 is named Sierra.

Click on start again, and create text links from each of the three answers to the appropriate writing space containing the response to that answer. This is very simple to do: double-click the answer in start, e.g. Copper, to park the link text, than drag from that parked text down to copperanswer. Repeat for the other two reponses.


Now when you switch to Read mode, clicking on a blue answer will take you to the respective writing space for that answer. Check that this works for each of the three.

Switch back to Edit mode, and click on start. Now edit the three answers without altering the blue text (to preserve those text links). For each, paste
before the blue text, and type in
, copperanswer)
immediately after the blue text for the first answer, and similarly for
, yosemiteanswer)
, sierraanswer)



Save your document, switch to Read mode and click on start, and you should now be able to click on each answer and see the linked text substituted. This is stretchtext at work.


Now that we have Storyspace Reader, you should also open your document using that app, and confirm that it works properly there too. Of course in Reader you cannot directly alter the user attributes, so the values of $theName and $theBoolean are fixed. As an exercise you can extend the document so that the reader can edit their name, and change the value of $theBoolean.

My example document is here: TextSub1

Happy hypertexting!