This set of macros/functions aim to provide an easy way to set up content which is revealed bit-by-bit via user interaction.

Using nested <<linkreplace>> and <<linkappend>> works, but gets tedious and is often prone to errors. The CTP (Click To Proceed: original-est name ever) macros make it a bit easier by turning them into blocks instead of nests.

If using the Twine desktop/web app, copy contents of CTP.js to Story JavaScript, and contents of CTP.css to Story Stylesheet.

If using a compiler like Tweego, drop CTP.js and CTP.css to your source folder.

<<ctp "testID">>
  This is the first string.
<<ctpNext clear>>
  Second! It cleared the first one out!
<<ctpNext nobr>>
  Third, but with nobr...
<<ctpNext t8n>>
  And the final one. With a transition!
<</ctp>>

<<button>>
  <<ctpAdvance "testID">>
<</button>>

NOTE: Avoid usage of passage navigation macros until the end of the entire chain. To free up memory when not required anymore, CTP objects created via the macros are deleted once they reach the end. If the passage changes before that happens, then the object will stay in memory and bloat the State (and affect performance; and the size of save files) unnecessarily.

• id: (string) Unique ID to be used to identify the chain of content. Naming rule follows the same as those of SugarCube variable names (learn more here).

Example:

<<ctp "ID_of_the_year">>
  Bare minimum...
<</ctp>>

To be used inside <<ctp>> to separate the content into blocks.

• keywords: (optional|string) The following keywords can be used to alter behavior of the macro:
  • clear: Clears content of previous block. Use for replacing.
  • nobr: Appends content in the same line as last block instead of going to a new line.
  • t8n or transition: Custom CSS animation based transition (250ms fade-in by default).

Example:

<<ctp "fancyCTP">>
  One.
<<ctpNext clear>>
  Two with clear.
<<ctpNext nobr>>
  Three on the same line.
<<ctpNext t8n>>
  Fading four.
<</ctp>>

The 'proceed' part of Click To Proceed... Used to move the train forward and show the next blocks.

• id: (string) Unique ID which was set up in <<ctp>>.

NOTE: Use with user interaction (inside a <<link>> or <<button>>) or inside a <<timed>> macro to ensure the DOM is loaded and has the element on page for the macro to target.

Example:

<<ctp "ID_of_the_year_once_again">>
  <!-- stuff -->
<</ctp>>

<<link "Next">>
  <<ctpAdvance "ID_of_the_year_once_again">>
<</link>>

The CTP custom object is set up as follows:

id: (string) Unique ID.

selector: (string) CSS selector to target to output to. When used by the macro, this is the slugified form of id.

Example:

var ctpTest = new CTP({
  id: "ctpTest",
  selector: "#ctp-test-id"
});

Other properties which are used under the hood:

stack: (array) Contains the content of all blocks.

log: (object) Keeps track of blocks amd their behaviors:

• index: (whole number) Current index of block (zero-based).
• clear: (array) Indices of blocks at which to clear the output element before appending new content.
• nobr: (array) Indices of blocks where no <br> is added.
• transition: (array) Indices of blocks which have the CSS transition (Target the class .macro-ctp-entry-t8n to customize).

Object methods:

Adds content to the end of the stack and returns the CTP object for chaining.

• content: (string) The actual content in the block.
• keywords: (string) Space-separated list of keywords (clear, nobr, t8n, transition) to modify behavior of the blocks.

Example:

ctpTest
  .add("This is the first string.")
  .add("Second! It cleared the first one out!", "clear")
  .add("Third, but with nobr...", "nobr")
  .add("And the final one. With a transition!", "t8n");

Does the same as <<ctpAdvance>>, moving to the next block. Returns the CTP object for chaining.

Example:

ctpTest.advance();

Returns the html output for a single block at the index passed into it.

• index: (whole number) Index of block to return.

Example:

ctpTest.ctpEntry(2);

// Assuming ctpTest is the same as in the previous examples, this returns:
// <span class="macro-ctp-entry macro-ctp-entry-index-2">Third, but with nobr...</span>

Returns the html output for entire chain from the last 'clear' to the current index.

Example:

// Assuming current index is 3
ctpTest.out()

/* Returns:
 *
 * <span class="macro-ctp-entry macro-ctp-entry-index-1">Second! It cleared the first one out!</span>
 * <span class="macro-ctp-entry macro-ctp-entry-index-2">Third, but with nobr...</span>
 * <br>
 * <span class="macro-ctp-entry macro-ctp-entry-index-3">And the final one. With a transition!</span>
 */

Complete usage:

JavaScript:

State.variables.ctpTest = new CTP({
  id: "ctpTest",
  selector: "#ctp-test-id"
});

State.variables.ctpTest
  .add("This is the first string.")
  .add("Second! It cleared the first one out!", "clear")
  .add("Third, but with nobr...", "nobr")
  .add("And the final one. With a transition!", "t8n");

In Passage:

<div id="#ctp-test-id">
  <<= $ctpTest.out()>>
</div>

<<link "Advance">>
  <<run $ctpTest.advance()>>
  <!--Because $ctpTest was created manually, using the <<ctpAdvance>> macro won't work. To be able to use <<ctpAdvance>>, the CTP object needs to be set as a property of State.variables.macroCTP as that is what is used internally to store CTP objects created via the macros. -->
<</link>>

Add css time delays before next one appears Interactive skip keyword skip - if current entry has interactive elements, you can skip their use and move on.