Storybook+ v3 – Technical Docs / Specifications

version 3.4.0

Storybook Plus is a web application that uses HTML5, JavaScript, CSS3, and web storage to present multimedia presentations.

User Interface

Splash Screen

1. Title – the presentation title
2. Subtitle – an optional subtitle for the presentation
3. Author – the author of the presentation or the source that the presentation was based on.
4. Duration – approximated length of the presentation
5. Start button – starts the presentation from the beginning.
6. Resume button – starts the presentation from where it was left off. This button will not be displayed if the presentation was never viewed.
7. File download buttons – depending on the availability of files, some buttons will not be displayed.
   • The transcript is a PDF file.
   • Video is an MP4 file.
   • Audio is an MP3 file.
   • The supplement is a zip/compressed file.

Presentation Screen

8. Title – the same presentation title on the splash screen.
9. Author – the same author’s name or source on the splash screen. Click to open the author’s profile.
10. Menu button – opens up the menu, which contains the Author’s Profile, General Info,
    Settings, Help, and any other menu items.
11. Media – may contain video, audio, image, or HTML content.
12. Copy to Clipboard button – if available, copy the specified content to the computer’s clipboard.
13. Table of contents – contains sections and pages in the presentation.
14. Section – a section in a table of contents. Toggle to open or collapse pages listed under the section.
15. Slide – a slide topic in a table of contents under a section. Click to go to that slide.

16. Play, pause, or replay button – three buttons combined into one. Click to play or pause, and the icon will change respectively. The icon will change to a replay icon when the video or audio ends.
17. Skip backward 10 seconds button – click to rewind the playback by 10 seconds.
18. Skip forward 10 seconds button – click to skip ahead 10 seconds.
19. Volume control button – hover over the button to adjust the volume. Click to mute or unmute.
20. Progress/scrubber bar – indicate the progression of the video or audio. Hovering over the progress bar will display timecode tooltips. Click to scrub the progress bar. If available, specified markers will also be displayed on the progress bar.
21. Duration left timecode – indicates how long the video or audio is left to be played.
22. Playback Rate button – click to change the playback rate and hover over to select a specific rate.
23. Subtitles/Captions button – hover over to select the desired subtitle or caption.
24. Quality button – hover over to select the desired resolution of the video. This button will not be displayed when only one resolution is available.

25. Expand / Contract button – expand the media area to the full width of the player. If already expanded, contract the media area back to normal width.
26. Tabbed widget area – may contain multiple tabbed contents with proper tab labels.
27. Previous button – click to go to the previous page. If currently on the first page, it will go to the last page in the table of contents.
28. Current slide status – indicates the current slide of total slides.
29. Next button – click to go to the next page. If currently on the last page, it will go to the first page.
30. Download file button – click to open a list of files that can be downloaded. If not downloadable files are available, this button will not be displayed.

File Structure

• The index.html file is required for each presentation. It holds the HTML wrapper.
• PDF/MP4/MP3/ZIP is the downloadable file if any of them is available.
• The assets folder contains the XML data file and media files for the presentation.
  • An XML file named “sbplus.xml” is required for each presentation. It holds the context/content of the presentation.
  • The author pic can be centralized on a server with the proper configuration in the manifest and XML file. If a local copy is available in the assets directory, it will override the centralized copy. The file name for the author photo is specified in the XML.
  • Likewise, the splash image can be centralized on a server as well.
  • The pages folder is required, and it holds the image for each page in the presentation.
  • If audio or non-third-party video is used in the presentation, a folder for each media is needed and named “video” or “audio” respectively.
  • If the presentation uses images for quizzes. Create a folder named “images”. This folder is optional.
• The scripts folder contains all of the Storybook Plus core scripts. This folder can be centralized on a server, so it does not have to be included in every presentation. This folder also contains a manifest (JSON) file. The manifest file holds global configurations/settings for all of the Storybook Plus presentations that are referenced to the centralized scripts.

Manifest File (JSON)

The manifest file is a JSON file that contains global settings or configurations for all of the Storybook Plus presentations that are referenced to it.

{
    sbplus_hotjar_site_id: "",
    sbplus_google_tracking_id: "UA-########-#",
    sbplus_root_directory: "sources/",
    sbplus_program_json: "",
    sbplus_author_json: "",
    sbplus_splash_directory: "",
    sbplus_author_directory: "",
    sbplus_logo_directory: "",
    sbplus_program_themes: "",
    sbplus_program_default: "uwex",
    sbplus_default_accent: "#0c3b6b",
    sbplus_kaltura: {
        id: 0123456,
        normal: 487081,
        medium: 487061,
        low: 487041
    },
    sbplus_download_files: [ 
        
        {
            label: "Video",
            format: "mp4"
        },
        
        {
            label: "Audio",
            format: "mp3"
        },
        
        {
            label: "Transcript",
            format: "pdf"
        },
        
        {
            label: "Supplement",
            format: "zip"
        }
    ],
    sbplus_custom_menu_items: [
        
        {
            name: "Help",
            icon: "help",
            content: "information on how to get help"
        }
        
    ]
       
}

• sbplus_hotjar_site_id – the Site Id from HotJar.
• sbplus_google_tracking_id – the Google Analytics tracking ID
• sbplus_root_directory – the path to the sources directory
• sbplus_program_json – the path to a JSON file containing all the program names.
• sbplus_author_json – the path to a JSON file that contains all of the authors’ names and profiles. This is not the same JSON file for the centralized author profile.
• sbplus_splash_directory – the path to the directory that holds the splash image(s)
• sbplus_author_directory – the path to the directory that holds the author’s image and biography files.
• sbplus_logo_directory – the path to the directory that holds the logo images (displayed in the widget area when there is no widget content)
• sbplus_program_themes – the path to a JSON file that contains the copyright information and colors for each program theme.
• sbplus_program_default – the default logo file name if there is more than one logo
• sbplus_default_accent – the default accent or hexadecimal color code for buttons and hover and active states of HTML elements.
• sbplus_kaltura – specify IDs from Kaltura if used
  • id – the organization ID
  • normal – the video flavor ID for normal quality
  • medium – the video flavor ID for medium quality
  • low – the video flavor ID for low quality
• sbplus_download_files – specify downloadable file formats
  • label – the text to be displayed
  • format – the file format/extension
• sbplus_custom_menu_items – specify an array of objects that becomes a menu item under the menu
  • name – the name of the menu item
  • icon – the icon name of the menu item if applicable
  • content – the content of the menu item

Centralized Author Biography File (JSON)

Storybook Plus will always request a centralized copy of the author’s biography in JSON format. The only exception is when values are wrapped inside the author tag in sbplus.xml. The values inside the author tag will override the information from the centralized copy.

author({
    name: "Joe Doe",
    profile: "Joe Doe's info"
});

• name – the name of the author to be displayed
• profile – information about the author and HTML elements are acceptable

The index.html File

The index.html file sets references to the CSS and script files. In addition, it also contains the HTML wrapper for Storybook Plus.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Storybook+</title>
        <link id="sbplus_configs" href="sources/manifest.json" rel="manifest"/>
        <link href="sources/scripts/libs/videojs/video-js.min.css" rel="stylesheet" />
        <link href="sources/css/sbplus.css" rel="stylesheet" media="all">
        <script src="sources/scripts/libs/modernizr.js" type="text/javascript"></script>
        <script src="sources/scripts/libs/jquery.js" type="text/javascript"></script>
        <script src="sources/scripts/libs/videojs/video.js" type="text/javascript"></script>
        <script src="sources/scripts/sbplus.js" type="text/javascript"></script>
    </head>
    <body>
        
        <noscript>
    		<h1>JavaScript is required!</h1>
    		<p>In order for this application to function, please <a href="http://www.enable-javascript.com/" target="_blank">enable JavaScript</a>.</p>
    	</noscript>
        
        <div class="sbplus_wrapper"></div>
        
    </body>
</html>

The sbplus.xml File

The sbplus.xml file holds or references the contents of a Storybook Plus presentation. It should always be included inside the assets directory. The XML file contains the setting configurations, the presentation setup, and sections and pages of a particular presentation.

Settings

Right after XML declaration, <?xml version="1.0" encoding="UTF-8" ?>, is the storybook tag, the outermost tag of the XML. This storybook tag has attributes that define the settings for this particular presentation and all other tags should be nested inside.

<storybook accent="#7b3009" pageImgFormat="jpg" splashImgFormat="jpg" analytics="off" mathjax="off" xmlVersion="3.4">
    <!-- setup, sections, and pages go inside of here -->
</storybook>

• accent – accepts a hexadecimal color value that changes the color of some of the Storybook’s UI elements to match the theme or splash screen of the presentation. If left empty, it will default to the hexadecimal color value specified in the manifest file.
• pageImgFormat – specify all of the images’ file formats used for the presentation. Defaults to jpg if left empty.
• splashImgFormat – specify the splash image file format used for the presentation. Defaults to jpg if left empty.
• analytics – defines whether the presentation is tracked by Google Analytics using the tracking ID specified in the manifest file. The only acceptable value to turn on the tracking is “on“. All other values will be treated as “off.”
• mathjax – defines whether the presentation needs to render mathematic formulas or equations. The only acceptable value to turn on math equations rendering is “on“. All other values will be treated as “off.”
• xmlVersion – holds the version number of this XML that correlates with Storybook Plus. This is not the version number for the XML schema definition.

Setup

The setup tag of the sbplus.xml specifies the splash screen image, title, author, and other additional information for the presentation.

<setup program="" course="">
        
    <title>BKN315 - Chocolate Chip Cookies</title>
    <subtitle>A Sample Storybook Plus Presentation</subtitle>
    <length>7 Minutes</length>
    <author name="Bryan Bortz"></author>
    <generalInfo>
        <p>This a sample Storybook Plus presentation on chocolate chip cookies.</p>
    </generalInfo>
        
</setup>

The setup tag has two attributes currently used for specifying the path to the centralized splash image. Both attributes can be left empty, and Storybook Plus will parse the URL for the directory of where the centralized splash image is located and the name of the splash image. These two attributes will be helpful when dealing with a presentation that belongs to a group of presentations but requires a different unique splash screen.

• program – can be referred to as the directory of where the splash image resides
• course – can be referred to as the “name” of the splash image inside the directory

If no centralized splash screen will be used, place the splash image inside the assets directory and name it splash and with whatever the file format/extension. This image will override the centralized image if any.

Nested inside the setup tag:

• title – the title of the presentation; will be displayed on the splash screen and the black banner bar.
• subtitle – an optional title for the presentation; will only be displayed on the splash screen.
• length – the total approximated length or duration of the presentation; will only be displayed on the splash screen
• author – holds the author’s profile or biography. The value for this tag will override
  the centralized author’s profile or biography.
• generalInfo – an optional tag to hold information in regard to the presentation and not necessarily related to the author; this info will be displayed under the General Information menu item.

The author tag has a name attribute. This attribute holds the author’s name and will be used for naming the author’s local and centralized photo and biography files. The value will be reformatted to lowercase with space and special characters removed. For example, Bryan Bortz will be reformatted to bryanbortz. This reformatted value will be the file name that Storybook Plus will request.

Sections

A section is used to group a collection of pages. An XML can have multiple sections but must have at least one section. Each section can have multiple pages.

<section title="Chocolate Chip Cookies">
    <!-- Pages go in here -->
</section>

If there is more than one section, the section title attribute will default to “Section #”, where # is a number of a particular section. If there is only one section, the section header/title will not be displayed and can be left blank.

Pages

In the past, pages are referred to as slides. Pages in Storybook are slides, but to match the branding, slides are now called pages. Storybook Plus supports the following type of pages: image, image-audio, bundle, kaltura, video, youtube, vimeo, and html.

<page type="" src="" title="" transition="" preventAutoplay="">
    <note />
</page>

The XML attributes and basic structure for all page types, except quiz, is as follows:

• type – page type
• src – the file’s name or video ID
• title – title for the page
• transition – transition effect for the page
• preventAutoplay – this attribute is optional and only for pages that contain audio or video. Set the value to true will prevent the audio or video player from autoplaying even when the autoplay setting is turned on.
• note tag – if the page has notes, wrap the notes inside the note

Image
An image page type where there is only one image to display. The image file should be placed inside the page’s directory.

<page type="image" src="fileName" title="An Image Page" transition="">
    <note />
</page>

Image & Audio
An image and audio page type contains one image, one audio, and one WebVTT caption file if applicable.

<page type="image-audio" src="fileName" title="An Image and Audio Page" transition="" preventAutoplay="">
    <note />
</page>

The image and audio file must have the same name. The image file should be placed inside the “pages” directory, and the audio file should be inside the audio directory. If the audio has a caption file, place the WebVTT caption file with the same name as the audio file in the same directory as the audio file.

Bundle
A bundle page type where there can be multiple images displayed at different times individually within the time sequence of one audio.

<page type="bundle" src="fileName" title="Bundle" transition="" preventAutoplay="">
    <frame start="00:18"></frame>
    <frame start="00:26"></frame>
    <note />
</page>

In this bundle page type, the frame and its start attribute needs to be specified. The start attribute tells Storybook when to display the image corresponding to that timecode. The image and audio files must have the same name. However, each image file name should have a numbered post-fix. For example, fileName-1, fileName-2, fileName-3 etc. Also, fileName-1 corresponding to the first frame and so on in sequential order.

The image file should be placed inside the “pages” directory, and the audio file should be placed inside the audio directory. If the audio has a caption file, place the WebVTT caption file with the same name as the audio file in the same directory as the audio file.

Kaltura, YouTube, and Vimeo
A video page type where the video is from a third-party provider.

<page type="[kaltura/youtube/vimeo]" src="[videoID]" title="Third-Party Video" transition="" preventAutoplay="">
    <note />
</page>

The type can be kaltura, youtube, or vimeo, and the src is the video ID from the respective third-party provider.

For YouTube Video Only
To play a YouTube video in the YouTube player instead of the default player, add the following attribute and set it to false: defaultPlayer="false".

Video
A video page type where the video is placed inside the video directory, which is inside the assets directory. If the video has a WebVTT caption file, the caption file should be named the same and placed in the video directory.

<page type="video" src="fileName" title="Video" transition="" preventAutoplay="">
    <note />
</page>

HTML
An HTML page type where the content is an HTML document. The HTML document may consist of multiple files (like a webpage). All related files must be inside a directory, which must be placed inside the HTML directory in the assets directory. If you like to open the HTML page in a separate tab/window, set embed attribute value to no.

<page type="html" src="htmlDirectoryName" title="HTML" embed="yes" transition="">
    <note />
</page>

Copy to Clipboard
Each page can specify a copyableContent element to copy the specified value to the clipboard. A button will be displayed on this page. The default name of this button is “Copy to Clipboard,” but it can be renamed to something else by specifying adding the name attribute with the desired name as the value.

<page type="image-audio" src="page01" title="Page with copyable content">
    <copyableContent name="[button name]"><![CDATA[content to copy to clipboard]]></copyableContent>
    <note />
</page>

Markers
Page with audio or video can specify markers on the player’s progress bar. Those markers are interactive. When hovering over it, the marker text is displayed. When clicked, it seeks the video to that marker’s position/timecode.

<page type="[kaltura/youtube/video]" src="[sourceName/id]" title="Page with markers in player">
    <markers>
        <marker timecode="00:10" color="">Marker 1</marker>
        <marker timecode="00:20" color="#f00">Marker 2</marker>
    </markers>
</page>

Widget
Widget is new in Storybook Plus version 3.1.0. Widget is a tabbed structure and will be displayed in the notes area. Each page can have its own set of widget tabs.

<page type="image-audio" src="fileName" title="An Image and Audio Page" transition="">
    <note />
    <widget>
        <segment name="Tab One">Tab one texts here...</segment>
        <segment name="Tab Two">Tab two texts here...</segment>
     </widget>
</page>

Quiz

A quiz is a page type in Storybook Plus, and there are multiple types of a quiz: multiple choice (can also be used for true/false), multiple choice with multiple answers, fill in the blank, and short answer.

Multiple Choice / True or False

<page type="quiz" title="Question 1">
            
    <multipleChoiceSingle>
                
        <question image="" audio="">
            <![CDATA[<p><strong>I'm not sure I was clear, should you burn the butter or not?</strong></p><p><small>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</small></p>]]>
         </question>

         <choices random="">
                    
             <answer image="" audio="">
                 <value>Yes</value>
                 <feedback>Sorry, I misspoke. Don't burn the butter.</feedback>
             </answer>
                    
             <answer image="" audio="" correct="yes">
                 <value>No</value>
                 <feedback>That's right, we don't want burnt butter.</feedback>
             </answer>
                    
              <answer image="" audio="">
                  <value>It depends on personal taste</value>
                  <feedback>Personally, I don't think you should burn the butter.</feedback>
              </answer>
                    
        </choices>
                
    </multipleChoiceSingle>
            
</page>

Notice the page type is a quiz, and the following inner tag is multipleChoiceSingle. This is telling Storybook Plus that this is a quiz page with a multiple-choice question.

• question – the question to ask
  • image attribute – image file name if applicable
  • audio attribute – audio file name if applicable
• choices – holds the answer tags
  • random attribute – set to “yes” to randomly display the answer choices
• answer – an answer to the question
  • image attribute – image file name if applicable
  • audio attribute – audio file name if applicable
  • correct attribute – specify “yes” to indicate the answer is correct
  • value tag – holds the answer value
  • feedback tag – hold the feedback for that value if chosen

Multiple Choice with Multiple Answer

<page type="quiz" title="Question 1">
            
    < multipleChoiceMultiple>
                
        <question image="" audio="">What are the colors of the American's flag?</question>

         <choices random="">
                    
             <answer image="" audio="">
                 <value>Green</value>
             </answer>
                    
             <answer image="" audio="" correct="yes">
                 <value>Blue</value>
             </answer>
                    
              <answer image="" audio="" correct="yes">
                  <value>Red</value>
              </answer>

              <answer image="" audio="">
                  <value>Orange</value>
              </answer>

              <answer image="" audio="" correct="yes">
                  <value>White</value>
              </answer>
                    
        </choices>

        <correctFeedback>That's right!</correctFeedback>
        <incorrectFeedback>No, worries...</incorrectFeedback>
                
    </multipleChoiceMultiple>
            
</page>

Same with the multipleChoiceSingle quiz type, but the following inner tag is multipleChoiceMultiple. This is telling Storybook Plus that this is a quiz page with multiple-choice with multiple answers. The XML differences are that each answer tag does not have a feedback tag. However, there are two new tags right after the closing choices tag: correctFeedback and incorrectFeedback.

• question – the question to ask
  • image attribute – image file name if applicable
  • audio attribute – audio file name if applicable
• choices – holds the answer tags
  • random attribute – set to “yes” to randomly display the answer choices
• answer – an answer to the question
  • image attribute – image file name if applicable
  • audio attribute – audio file name if applicable
  • correct attribute – specify “yes” to indicate the answer is correct
  • value tag – holds the answer value
• correctFeedback – feedback for answering the question correctly
• incorrectFeedback – feedback for answering the question incorrectly

Fill in the Blank

<page type="quiz" src="slide13" title="Fill in the Blank">
    <fillInTheBlank>
        <question>256, 128, 64, 32, 16, ... what comes next?</question>
        <answer>8</answer>
        <correctFeedback>That's right. The next number can be determined by dividing the previous number by 2.</correctFeedback>
         <incorrectFeedback>No, worries. Math is hard!</incorrectFeedback>
    </fillInTheBlank>
</page>

Notice the fillInTheBlank tag. It is telling the Storybook Plus that it is a fill-in-the-blank question. The fill-in-the-blank question does not accept images and audio files for its question and answer.

• question – the question to ask
• answer – the answer to the question
• correctFeedback – feedback for answering the question correctly
• incorrectFeedback – feedback for answering the question incorrectly

Short Answer

<page type="quiz" src="slide14" title="Short Answer">
    <shortAnswer>
        <question>What are your main take aways from this presentation?</question>
        <feedback>I was hoping you would be surprised to hear how relatively young the Chocolate Chip cookie is. I am also hoping you noticed how important getting the ingredients right is to having good results.</feedback>
    </shortAnswer>
</page>

Notice the shortAnswer tag. It is telling the Storybook Plus that it is a short answer question. Short answer question does not accept images and or audio files for their question and answer. In addition, answer tag is not available.

• question – the question to ask
• feedback – feedback for answering the question whether correctly or incorrectly

Published on September 22, 2022 at 12:02:35 pm CDT. Last modified on September 22, 2022 at 2:15:16 pm CDT.