Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!

New Sugarcube release : StoryInterface special passage

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 ?


  • There's not much to it, really.

    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:
    • Its contents are processed as regular HTML markup once at startup to initialize the UI.
    • Its contents must contain an element with the ID passages, which will be the main passage display area and whose contents will be replaced each turn.
    • The UI bar and its styles and the core display area styles are automatically removed when in use.
    For example, the most basic UI you may use is something like the following:
    <div id="passages"></div>

    That, however, is simply the bare minimum required. Your custom UI may be much more complex if desired.
  • @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 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>
    		<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>
    <div id="story" role="main">
    	<div id="passages"></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.
    #story{margin-left:20em}#ui-bar.stowed~#story{margin-left:4.5em}@media screen and (max-width:1136px){#story{margin-left:19em}#ui-bar.stowed~#story{margin-left:3.5em}}@media screen and (max-width:768px){#story{margin-left:3.5em}}#ui-bar{position:fixed;z-index:50;top:0;left:0;width:17.5em;height:100%;margin:0;padding:0;-webkit-transition:left .2s ease-in;-o-transition:left .2s ease-in;transition:left .2s ease-in}#ui-bar.stowed{left:-15.5em}#ui-bar-body{height:90%;height:calc(100% - 2.5em);margin:2.5em 0;padding:0 1.5em}#ui-bar.stowed #ui-bar-body,#ui-bar.stowed #ui-bar-history{visibility:hidden;-webkit-transition:visibility .2s step-end;-o-transition:visibility .2s step-end;transition:visibility .2s step-end}#ui-bar{background-color:#222;border-right:1px solid #444;text-align:center}#ui-bar-tray{position:absolute;top:.2em;left:0;right:0}#ui-bar a{text-decoration:none}#ui-bar hr{border-color:#444}#ui-bar-history [id|=history],#ui-bar-toggle{font-size:1.2em;line-height:inherit;color:#eee;background-color:transparent;border:1px solid #444}#ui-bar-toggle{display:block;position:absolute;top:0;right:0;border-right:none;padding:.3em .45em .25em}#ui-bar.stowed #ui-bar-toggle{padding:.3em .35em .25em .55em}#ui-bar-toggle:hover{background-color:#444;border-color:#eee}#ui-bar-history{margin:0 auto}#ui-bar-history [id|=history]{padding:.2em .45em .35em}#ui-bar-history #history-jumpto{padding:.2em .665em .35em}#ui-bar-history [id|=history]:not(:first-child){margin-left:1.2em}#ui-bar-history [id|=history]:hover{background-color:#444;border-color:#eee}#ui-bar-history [id|=history]:disabled{color:#444;background-color:transparent;border-color:#444}#ui-bar-body{line-height:1.5;overflow:auto}#ui-bar-body>:not(:first-child){margin-top:2em}#story-title{margin:0;font-size:162.5%}#story-author{margin-top:2em;font-weight:700}#menu ul{margin:1em 0 0;padding:0;list-style:none;border:1px solid #444}#menu ul:empty{display:none}#menu li{margin:0}#menu li:not(:first-child){border-top:1px solid #444}#menu li a{display:block;padding:.25em .75em;border:1px solid transparent;color:#eee;text-transform:uppercase}#menu li a:hover{background-color:#444;border-color:#eee}#menu a,#ui-bar-history [id|=history],#ui-bar-toggle{-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}#menu-core li[id|=menu-item] a:before,#ui-bar-history [id|=history],#ui-bar-toggle:before{font-family:tme-fa-icons;font-style:normal;font-weight:400;font-variant:normal;text-transform:none;line-height:1;speak:none}#ui-bar-toggle:before{content:"\e81d"}#ui-bar.stowed #ui-bar-toggle:before{content:"\e81e"}#menu-item-saves a:before{content:"\e82b\00a0"}#menu-item-settings a:before{content:"\e82d\00a0"}#menu-item-restart a:before{content:"\e82c\00a0"}#menu-item-share a:before{content:"\e82f\00a0"}

    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);
    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.

  • 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.
    • CSS. Take a look at SugarCube's CSS document—or simply go straight to the relevant CSS sources: core-display.css, for the main passage display, and ui-bar.css, for the UI bar.
Sign In or Register to comment.