Include

Include lines are placeholders for cards inside other cards. They let you reuse the content of a card in multiple other cards without copying.

Furthermore, with include lines you can create loops, which can be a useful tool for composing text automatically.

Include a card

A simple include line starts with an :INCLUDE: tag followed by the unique name of a card.

In this example the include line acts as a placeholder for the card named mantra. When the card named pizza mantra is displayed, the mantra gets filled in where the include line used to be.

Workflow tip: A short tag for include lines is :INC:.

Include several cards

A single include line can also handle more than one card.

The card names on the include line should be separated with spaces. If a card name contains spaces, you will have to put it in parentheses.

The cards are included and displayed in the same order as they are written on the include line.

Workflow tip: Use parentheses for all card names on the include line to increase legibility.

Circular includes

Including a card in another card can make your source text shorter and easier to manage. Beyond that, when you include a card in itself you create a circle, or loop. This also happens when a card includes another card that includes the first one (and so on and so forth).

Loops enable you to automatically generate text. But they also add a layer of complexity: They can potentially go on forever and crash the browser.

Hypstory has certain measures in place to prevent that. But usually you will want to manage explicitely how a loop behaves.

Loop a number of times

The usual way to prevent endless loops is to create some sort of abort condition, e.g. by storing and checking a number value.

In this example there are four cards. The first three have a similar structure: They include the next card and, thus, create a chain. The fourth card, eventually, creates a loop by including the first card – but only if a certain condition is met.

That condition is a number. It gets increased by the store lines that all cards contain. While the loop goes on, the number increases up to a point where it is greater than or equal to 15. As a result, the check line that used to restart the loop fails and the loop ends.

Workflow tip: Read up on store lines and check lines in case you are unsure how they work.

Practice tip: Change the check lines inside the craving card. Try to predict the result. Then hit update and see if you were right.

Practice tip: Swap lines 16/17 with lines 18/19 and hit update. a lot of sleep. suddenly shows up three times at the end. If you know why, you really are on top of include lines and their workings.

Looping limits

Hypstory has two internal maximum values that prevent loops from going out of hand:

• a limit of 1,500 paragraphs per card and
• a limit of 1,500 includes per card.

That means, once 1,500 paragraphs have been rendered in a card, any further lines will not be rendered. That includes all lines, not only paragraphs. With this limitation you should still be able to fit an average size novel into a single card.

Also, if a card has executed 1,500 include lines, it will ignore all following include lines. Ready for a little test?

Here, a value is stored for how many pizzas have been sold. The link leads you to the sell more pizza card that includes itself under the condition that the number of sold pizzas is lower than 1500.

However, we're not done yet with our little test. You have to do two things to complete it:

1. Set the $pizzasSold value to 0, hit update and see the loop in action. It renders 1,500 paragraphs.
2. Set the number inside the check line to 2000 and hit update. Due to the 1,500 paragraphs limit there should still be 1,500 paragraphs, not 2,000.

Practice tip: Leave the two steps from the test above in place. Then, instead of linking to the sell more pizzas card inside the start card, include it and hit update. Now the loop should start immediately, but it creates only 1499 paragraphs. If you know why, you've become a true Hypstory guru. Kudos to you and godspeed.