Thanks a lot Thomas, for your last release of Sugarcube 2.18.0.
I'm a little bit puzzled with the new StoryInterface special passage. Could you give us a little practical example on how to use it ?
@TheMadExile, if, for reasons of practice and learning, I want to replicate SugarCube's standard UI (along with the sidebar) with StoryInterface, what would I put in it?
You would need to do a lot more that just placing a HTML structure in the StoryInterface special passage to simulate the standard UI.
1. Side-bar and main passage HTML structure.
The core HTML elements that make up these two parts of the screen are dynamically added to the page at startup, this allows the engine to use things like the Configuration system to influence the core content of the structure being generated.
You could use HTML like the following in a StoryInterface passage to approximate the standard structure.
<div id="ui-bar">
<div id="ui-bar-tray">
<button id="ui-bar-toggle" tabindex="0" title="Toggle the UI bar" aria-label="Toggle the UI bar" type="button"></button>
<div id="ui-bar-history">
<button id="history-backward" tabindex="0" title="Go backward within the game history" aria-label="Go backward within the game history" disabled="" type="button"></button>
<button id="history-forward" tabindex="0" title="Go forward within the game history" aria-label="Go forward within the game history" disabled="" type="button"></button>
</div>
</div>
<div id="ui-bar-body">
<header id="title" role="banner">
<div id="story-banner"></div>
<h1 id="story-title"></h1>
<div id="story-subtitle"></div>
<div id="story-title-separator"></div>
<p id="story-author"></p>
</header>
<nav id="menu" role="navigation">
<ul id="menu-core">
<li id="menu-item-saves"><a tabindex="0">Saves</a></li>
<li id="menu-item-restart"><a tabindex="0">Restart</a></li>
</ul>
</nav>
</div>
</div>
<div id="story" role="main">
<div id="passages"></div>
</div>
2. Styling of the Side-bar.
Added a StoryInterface passage to your story causes the standard style-ui-bar related CSS to be removed from the generated page, this means that you will need to add your own copy of that CSS to your story's Story Stylesheet area. It would look something like the following.
3. Associating the ID'ed HTML elements in the structure with their related special passages.
You will need to use the setPageElement() function to associate special passages (like StoryTitle, StoryAuthor, StoryCaption, etc...) with the HTML elements in the generated page so that their content will automatically appear the the relevant area of the screen. You may be able to use a Task Object like the following to do this although there may be issues doing it this way, code like this would need to placed in your Story Javascript area.
postrender["Associate Special Passages"] = function (content, taskName) {
setPageElement("story-title", "StoryTitle", Story.title);
setPageElement("story-banner","StoryBanner");
setPageElement("story-subtitle","StorySubtitle");
setPageElement("story-author","StoryAuthor");
setPageElement("story-caption","StoryCaption");
}
note: I am unsure the above will work with the StoryMenu special passage.
4. Implementing the ability to select the standard buttons on the side-bar.
I don't have an example of how to do that, but if it is possible then it would require adding custom code to the Story Javascript area to do it.
First. Let me define what I consider to be SugarCube's default UI: the main passage display area and the UI bar. Parts of the extended UI not covered in that: the loading screen and dialogs—both the builtins and the dialog system in general.
You cannot replicate the default UI with StoryInterface alone, since that would only cover the markup. There is, obviously, quite a bit of CSS involved, to say nothing of the requisite JavaScript making things work behind the scenes. Well, for the UI bar anyway, the main passage display area is a fairly simple affair.
That said, I can point you to reasonable overviews of the markup and CSS involved.
Markup. Take a look at SugarCube's HTML document—the two <div> elements you want to look at are: <div id="story" role="main">, for the main passage display, and <div id="ui-bar">, for the UI bar. Note: While shown for the sake of completeness, the main passage display does not actually include the passage element—it's injected into the #passages element by the renderer.
Comments
The StoryInterface special passage allows developers to easily replace SugarCube's default UI—since that seems like a popular thing to do now a days.
Things to know about it:
That, however, is simply the bare minimum required. Your custom UI may be much more complex if desired.
1. Side-bar and main passage HTML structure.
The core HTML elements that make up these two parts of the screen are dynamically added to the page at startup, this allows the engine to use things like the Configuration system to influence the core content of the structure being generated.
You could use HTML like the following in a StoryInterface passage to approximate the standard structure.
2. Styling of the Side-bar.
Added a StoryInterface passage to your story causes the standard style-ui-bar related CSS to be removed from the generated page, this means that you will need to add your own copy of that CSS to your story's Story Stylesheet area. It would look something like the following.
3. Associating the ID'ed HTML elements in the structure with their related special passages.
You will need to use the setPageElement() function to associate special passages (like StoryTitle, StoryAuthor, StoryCaption, etc...) with the HTML elements in the generated page so that their content will automatically appear the the relevant area of the screen. You may be able to use a Task Object like the following to do this although there may be issues doing it this way, code like this would need to placed in your Story Javascript area. note: I am unsure the above will work with the StoryMenu special passage.
4. Implementing the ability to select the standard buttons on the side-bar.
I don't have an example of how to do that, but if it is possible then it would require adding custom code to the Story Javascript area to do it.
5. Anything else I didn't think of.
You cannot replicate the default UI with StoryInterface alone, since that would only cover the markup. There is, obviously, quite a bit of CSS involved, to say nothing of the requisite JavaScript making things work behind the scenes. Well, for the UI bar anyway, the main passage display area is a fairly simple affair.
That said, I can point you to reasonable overviews of the markup and CSS involved.