How to add the "history-backward" and "history-forward" buttons to the ui using StoryInterface?

Question

Hello community, 

I am attempting to built a custom user interface using the StoryInterface special passage. I am stuck with the mime of the backward and forward buttons, like the ones with chevron icons built-in in the default Sugarcube ui bar. At the moment I am doing this test for the backward button, having the Homepage tag in the main/initial passage:

<<if (!tags().contains("Homepage"))>>
<button id="history-backward"><<back>></button>
<<else>>
<button id="history-backward"></button>
<</if>>

which works, but then two questions:

- How to implement the same for the forward button (linking to the viewed passage which is ahead of the current position)?

- How can be the resulting back text for the macro (eg from <<back>>) can be substitute by an icon?

Thank you very much!

 

Answer 1

NOTE: You don't state which means you are using to build/compile your story HTML file (Twine 1, Twine 2, TweeGo, etc) so the following instructions will assume you are using the Twine 2.x application, if you are using a command line compiler like TweeGo then the following CSS needs to be placed within a stylesheet tagged Passage and the Javascript within a script tagged one.

The following answer is heavily based on the SugarCube 2.x source code originally written by Thomas Michael Edwards (aka TheMadExile), so all credit for it should be given to him, and all blame for any bugs and/or errors that have been introduced in the following examples should be assigned to me.
It shows how to use code found within SugarCube's uiBarInit() and uiBarStart() functions, and its default UIBar related CSS to re-implement the main functionality of story format's Back & Forward buttons,

1. Add the 'history' related HTML elements to the StoryInterface special passage of your project.
(The default Left and Right arrows glyph of the standard UI layout are actually characters stored within SugarCube's special tme-fa-icons font, this is why HTML Character Escaping is used within the button elements.)

<div id="ui-bar-history">
	<button id="history-backward" tabindex="0">&#xE821;</button>
	<button id="history-forward" tabindex="0">&#xE822;</button>
</div>
<div id="passages"></div>

2. Add the following CSS to your project's Story Stylesheet area.
It allocates the default styling used to show the Left & Right arrows as well as that used to disable them as necessary.

#ui-bar-history [id|=history] {
    font-family: tme-fa-icons;
    font-style: normal;
    font-weight: 400;
    font-variant: normal;
    text-transform: none;
    line-height: 1;
    speak: none;
}
#ui-bar-history [id|=history]:disabled {
    color: #444;
    background-color: transparent;
    border-color: #444;
}

3. Add the following Javascript to your project's Story Javascript area.
It uses jQuery to set up the event handlers required to determine when each of the two buttons should be enabled as well as what to do when each button is selected. The code makes use of the State API to determine how many total Moments are currently within the story's History and how many of them are in the past, and it makes use of the Engine API to navigate between the Moments of the story History.
note: The following code listens for a special (undocumented?) :historyupdate event which is sent by the engine whenever the story's History has been updated, this is how we know when to check the enabled/disabled state of the buttons.

/* Set up a handler for the enabling and disabling of the history-backward/-forward buttons. */
jQuery(document)
	.on(':historyupdate.ui-bar',
		(function ($backward, $forward) {
			return function () {
				$backward.prop('disabled', State.length < 2);
				$forward.prop('disabled', State.length === State.size);
			};
		})(jQuery('#history-backward'), jQuery('#history-forward'))
	);

/* Set up a handler for the selection of the history-backward button. */
jQuery('#history-backward')
	.prop('disabled', State.length < 2)
	.ariaClick({
		label : L10n.get('uiBarBackward')
	}, function () {
		Engine.backward()
	});

/* Set up a handler for the selection of the history-forward button. */
jQuery('#history-forward')
	.prop('disabled', State.length === State.size)
	.ariaClick({
		label : L10n.get('uiBarForward')
	}, function () {
		Engine.forward()
	});

Obviously you will need to alter the above HTML, CSS, and Javascript to suit the needs of your particular project.

Comments

Clear, complete and working answer for this topic question. I've just discovered the fantastic Engine API, Thank you!

Answer 2

You can use "Engine.forward()" and "Engine.backward()" to control moving forwards or backwards (see here for full details on those functions).

As for adding an icon, just get rid of the "<<back>>" and then have those functions triggered on the button click using SugarCube's button macro with an image in it.  For example:

<<button [img[images\BackIcon.png]]>><<run Engine.backwards()>><</button>>

You can use "State.length" to determine if the back button should be enabled, and "State.size - State.length" to determine if the forward button should be enabled (see a bit below here).

Hope that helps!  :-)

Comments

Typo ^.^

<<button [img[images\BackIcon.png]]>><<run Engine.backward()>><</button>> // (Without the s)
<<button [img[images\ForwardIcon.png]]>><<run Engine.forward()>><</button>>