Storybook+ v3 – Technical Docs / Specifications

version 3.1.0

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

 

User Interface

Splash Screen
Storybook Plus Splash Screen UI

  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 button will not be displayed.
    • Transcript is a PDF file.
    • Video is a MP4 file.
    • Audio is a MP3 file.
    • Supplement is a zip/compressed file.
The splash screen image and button color may change depending on the context of the presentation.

Presentation Screen
Storybook Plus Presentation Screen UI

  1. Title – the same presentation title on the splash screen.
  2. Author – the same author’s name or source on the splash screen. Click to open author’s profile.
  3. Menu button – opens up the menu, which contain the Author’s Profile, General Info,
    Settings, Help, and any other menu items.
  4. Media – may contain a video, audio, image, or HTML content.
  5. Table of contents – contains sections and pages in the presentation.
  6. Section – a section in a table of contents. Toggle to open or collapse pages listed under the section.
  7. Page – a page in a table of contents under a section. Click to go to that page.
If there is only one section in the table of contents, the section label will not be displayed, and pages can not be collapsed. The color indicator may change depending on the context of the presentation.
  1. Play, pause, and 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 video or audio ended.
  2. Volume control button – hover over the button to adjust the volume. Click to mute or un-mute.
  3. 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.
  4. Duration left timecode – indicates how long the video or audio is left to be played.
  5. Playback Rate button – click to change playback rate and hover over to select a specific rate.
  6. Quality button – hover over to select the desired resolution of the video. This button will not be displayed when only one resolution is available.
  7. Subtitles/Captions button – hover over to select desired subtitle or caption to be displayed.
Items 15 to 21 are display only when the media is a video or audio.
  1. Tabbed widget area – may contains multiple tabbed contents with proper tab labels.
  2. 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.
  3. Next button – click to go to the next page. If currently on the last page, it will go to the first page.
  4. Page status – indicates current page of how many pages.
  5. 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.
  6. Toggle widget button – click to show or hide the tabbed widget area. The media area will expand vertically. If there are contents in the hidden tabbed widget area, a red triangle will be displayed on the button to indicates there are contents in the widget area.
  7. Toggle table of contents button – click to show or hide the table of contents. The media area will expand horizontally.

File Structure

Storybook Plus Splash 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 one 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 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.
    • Like wise, 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 presentation that is referenced to the centralized scripts.
The scripts folder does not have to be centralized. However, if that is the case, each presentation will need a copy of the scripts folder included in the root directory, and the manifest (JSON) file and the index.html file should be properly referenced to the local copy.

Manifest File (JSON)

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

  • sbplus_google_tracking_id – the Google Analytic tracking ID
  • sbplus_root_directory – the path to the sources directory
  • 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 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_logo_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_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 centralized copy of author biography in JSON file format. The only exception is when there are values wrapped inside the author tag in sbplus.xml. The values inside the author tag will override the information from the centralized copy.

  • name – the name of the author to be displayed
  • profile – information about the author and HTML elements are acceptable
Please refer to the setup section under sbplus.xml for naming centralized photo and biography files.

The index.html File

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

This file must be included for each Storybook Plus presentation, because this is the page that the web browser will load. Do not attempt to modify the HTML structure unless you are familiar with HTML and the Storybook Plus process.

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.

  • 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 defaults to the hexadecimal color value specified in the manifest file.
  • pageImgFormat – specify all of the images’ file format that will be used for the presentation. Defaults to jpg if left empty.
  • splashImgFormat – specify the splash image file format that will be used for the presentation. Defaults to jpg if left empty.
  • analytics – defines whether the presentation is tracked by Google Analytics using the tracking ID that was 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 versions number of this XML that correlates with Storybook Plus. This is not the version number for the XML schema definition.
Do not turn on MathJax if the presentation does not contain complex mathematic formulas or equations. MathJax is a heavy library and will slow down Storybook Plus’s load time.

Setup

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

The setup tag has two attributes that are 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 of that belong to a group of presentations but requires a different unique splash screen.

  • program – can be refer to as the directory of where the splash image resides
  • course – can be refer 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.

These two attributes were named program and course because they follow the naming convention and directory structure that was used by the Media Team.

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 name of the author 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 be will the file name that Storybook Plus will be requesting.

Sections

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

If there are more than one section, the section title attribute will default to “Section #”, where # is 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.

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

  • type – page type
  • src – file name or video ID
  • title – title for the page
  • transition – transition effect for the page
  • note tag – if the page has notes, wrap the notes inside the note
The values or transition effects for the transition attribute can be obtained from Animate.css. The value is case sensitive and should be entered as shown on the Animate.css website. For example, to use rubberBand effect, enter rubberBand as-is.
If there is no notes, the note tag can be written as <note />, which is called a self closing tag. This can also be applied to all other empty tags.

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

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

The image and audio file must have the same name. 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.

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

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 correspond 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 correspond to the first frame and so on in sequential order.

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 video is from a third-party provider.

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

Video
A video page type where video is place 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 as well.

HTML
A HTML page type where the content is a HTML document. The HTML document may be made up of multiple file (like a webpage). All related files must be inside directory, and that directory must be placed inside the html directory in assets directory. If you like to open the HTML page in a separate tab/window, set embed attribute value to no.

Widget

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

Like the note tag, widget is not available for any quiz type pages.

Quiz

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

Multiple Choice / True or False

Notice the page type is 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

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 a multiple choice with multiple answer. 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

Notice the fillInTheBlank tag. It is telling the Storybook Plus that it is a fill-in-the-blank question. Fill-in-the-blank question does not accept images and or 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

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 its question and answer. In addition, answer tag is no available.

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

Published on July 07, 2016 at 4:18:59 pm CDT. Last modified on January 23, 2019 at 9:05:10 am CDT.