Link behavior objects/Syntactic sugar for phrase-cycling links.

[NQNStudios]

What happened

When I was doing a lot of Twine work, one of the most common design patterns I used was a link that would start as one word, and clicking it would change the link through a series of alternate words/phrases. An excellent example is from Why I Run, where it's used as a kind of gender/avatar selection tool:

Implementing this kind of thing in Twine was always an ungodly mess.

Feature proposal

I just thought of what might be the snazziest syntactic sugar we could add to make this common task simple/beautiful in Fractive:

[text1/text2/text3]

to produce a link that starts by saying 'text1' and reveals the next phrase in the cycle whenever clicked. Or, to make a more extensible framework for links that transform their own text:

[text1/text2/text3]({!Core.CycleText}) where ! marks a link behavior macro that has both an initial condition (i.e. displaying only text1), and an event for being clicked (i.e. switching through the remaining options). Core.CycleText would be an object with an init() function as well as an onClick() function. And we could define more such macros in the Core, and also allow users to implement their own more complicated link behaviors that involve more than just onClick.

[NQNStudios]

Gonna spit some more design thoughts here, with an eye out for potential gotcha's:

Link syntax is extended generally like so:

[Links whose destination follows this syntax are complex links.]({!LinkClassName})

Their class name corresponds to a JavaScript class that implements the ComplexLink interface. When the player visits a section with one or more complex links, a ComplexLink object of the specifically declared type will be instantiated for each complex link. ComplexLink instances are deleted when the current section changes, but there are good arguments on both sides for whether these instances should be deleted when the current section gets refreshed. Maybe that's determined per each link type by implementing a RefreshWithSection(): boolean method in the ComplexLink interface.

ComplexLinks are all wrappers of an array of text. This text is declared in markdown by using the | character in the link text:

[Here's a link|with multiple texts|declared in it]({!SomeLinkType})

(Hence there will need to be a way to escape a | and have it not be interpreted as complex link syntax)

All ComplexLink objects are created with a list of the texts that the link was declared in Markdown with. The interface is like so:

class ComplexLink
{
    Init(); // Do something such as adopt the first text in the array as the one to be displayed
    OnClick(); // Do something that will modify the text being displayed, such as cycling through the text array, or choosing randomly between one of the texts after the first one.
}

[NQNStudios]

Note to self: related to #51

[NQNStudios]

It struck me today that we already have a form of customized link behavior: inline links. And the most internally consistent way to implement this, would be to refactor so anything in a link following the : character can be registered as a special link behavior, inline included.

• {@SectionLink:inline} invokes the built-in inline behavior.
• {$arrayLink:cycle} to invokes a built-in cycle behavior like I described in the first post.
• {@SectionLink:expandAndCollapse} invokes a built-in behavior where the section is expanded but can be collapsed by clicking again.
• {#FunctionLink:customWhatever} invokes a custom behavior implemented by the story developer