Storybook – Assembly

Project Structure

When you are finished creating all of the images, videos, and audio that will be used in a Storybook Presentation you are ready to assemble it all into a project that will be uploaded to the web server. Storybook Projects are comprised of a specific structure of folders, asset files, XML, and HTML. It is important to get all of the structure, naming, and XML code exactly correct for the Project to load and run properly.

The Structure of a Storybook Project:

1 Project Folder
This folder contains all of the parts of a Storybook Project. It is named according to the Titling and File Naming guidelines. This folder is what will be uploaded to the web server.
Typically the only things in the root of the Project Folder are the assets folder 2, index.html file 3, and the transcript 4 for the presentation. Where appropriate, the downloadable video 5 and audio versions 6 may be included. Or a supplementary archive of files in .zip format.
2 assets
This is where all of the components that are loaded and displayed in a Storybook Presentation are stored.
7 audio

All audio files should be stored inside of this folder. This includes narration for image + audio pages, and audio files for quiz items.

It is best practice to name the audio files sequentially, but because you program in the specific name of the audio files into the XML you can technically name them whatever you want. The filename minus the extension is shared with the image when used on pages. (Eg. page457.mp3, page457.svg)

All references to audio files in the XML assume they are stored in this folder.

8 pages
This is where all images should be stored that are for standard image or image + audio pages. They can be SVG, JPG, or PNG. The file names used here are shared with the associated audio file, minus the extension. (Eg. page02.jpg, page02.mp3)
9 video
Videos that are not hosted on Kaltura, YouTube or Vimeo are stored inside of this folder in .mp4 format. They are referenced in the XML just like images and audio are. (Eg. page13.mp4)
10 html
Videos that are not hosted on Kaltura, YouTube or Vimeo are stored inside of this folder in .mp4 format. They are referenced in the XML just like images and audio are. (Eg. page13.mp4)
11 sbplus.xml
This is the XML file that configures and structures a Storybook Presentation.

Assembly

Get all of your audio and image files placed in their corresponding folders and named appropriately. Then open up the sbplus.xml file in a text editor to begin writing the XML.

Writing the XML

Begin by reviewing the Storybook attributes on the opening <storybook> tag.

Accent
Set this to a color that compliments the aesthetic of the presentation’s theme.
pageImgFormat
This can be SVG, JPG, or PNG. Generally it will be either JPG or SVG.
Analytics
Analytics for the presentation can be set to “on” or “off.” The default is on.
xmlVersion
This is currently set to 3. The xmlVersion tells the storybook version how it should parse your xml.

Then move on to configuring the <setup> tag.

course
The course number of the course the presentation is associated with
Title
The title of the presentation, see the File Names and Titling documentation for more information on writing a presentation title.
Subtitle
The subtitle of the presentation, not the title – Optional.
Length
The overall length of the presentation written out. Eg. 45 Minutes
Author name
The name of the author without titles or punctuation. This name is used to load the author profile from a centrally stored profile.
generalInfo
This block of text is displayed in the menu of the Storybook presentation and is useful for disclaimers, attribution or other supporting information that is not instructional content
Profile
Enter an author bio here to override the centrally stored author file

Now we move on to creating the XML that describes the Pages of the Storybook Presentation. We start by opening a new <section title=””> tag. Every presentation needs at least one section tag that encompasses all of the slides. Section tags enclose all of the pages that appear in that section. A section title is optional but recommended. If there is only one section it will not display in the presentation for the end user.

To create the pages of the storybook presentation we create page tags. There is a page tag for each page that appears in the presentation. They are structured as follows:

Example Page Tag

Storybook Page Tags

Type:
The type of Storybook page. This can be either image, image-audio, bundle, video, kaltura, youtube, vimeo, quiz, or html
src:
the asset or resource ID being loaded. For images, audio files, and video files stored in the video folder it is the filename minus the extension. For Kaltura, YouTube and Vimeo videos it is the applicable resource ID.
title:
the title of the Storybook page. This will appear in the table of contents navigation
Note:
This tag holds the text or html that will appear in the notes widget below the content area of a Storybook Page. Keep in mind that the text/html needs to be placed inside of the CDATA tag. <![CDATA[ ALL TEXT/HTML HERE ]]>

Page Type: Image + Audio

The src=”” tag references the image file and the audio file. You enter the filename minus the extension. Both assets share the same filename except for having differing file extensions. For example:
/assets/pages/page03.jpg
/assets/pages/page03.mp3


Page Type: Image

The src=”” tag references just an image file in the pages folder for Storybook pages that only contain an image. It is the filename of the image minus the extension.


Page Type: Video

The src=”” tag references just a video file in the video folder. This is only for videos hosted inside of the project and not externally on places like Katura, YouTube or Vimeo. It is the filename of the video minus the extension.


Page Type: Kaltura

For videos hosted on Kaltura, you will set the type to Kaltura and the src to the video ID for the Katura video. It can be found in the Kaltura KMC backend.


Page Type: YouTube

For videos hosted on Kaltura, you will set the type to Kaltura and the src to the video ID for the Katura video. It can be found in the video’s URL.


Page Type: Vimeo

For videos hosted on Vimeo, you will set the type to Vimeo and the src to the video ID for the Vimeo video. It is the numeric code in the video’s URL.


Page Type: Quiz

Quizzes have the most things to configure in the sbplus.xml file. Every quiz will have the type set to quiz and have a title. Note that they do not have an src. The type of quiz is determined by the tag that holds the quizzes questions, answers, and feedback. What follows is a list of the different quizzes that Storybook v3 supports and the tag structure each uses. Note that each question, answer, and feedback tag supports attaching an image or audio file. These are stored in the images or audio folders inside of the assets folder.

Multiple Choice Single Answer

Multiple Choice Single Answer is probably the most commonly used quiz question type. Note that the correct=”yes” is placed on a single correct answer. This question type is also used for true/false questions because of the shared logic. Just type in “True” or “False” in the answer tags. Each answer tag represents a single answer. There is not a limit to how many answers you can put in one quiz page.

Multiple Choice Multiple Answer

Multiple Choice Multiple Answer differs in that it allows for more than one correct=”yes” tag and it has feedback for only two states, correct and incorrect. This is due to not being able to easily accommodate all possible combinations of answers with customized feedback.

Short Answer

Short answer is the simplest quiz to implement. It has just a question tag and a feedback tag. There is no answer tag or any sort of logic to test what the student enters. It is intended to be used for self-reflection and assessment.

Fill in the Blank

FIll in the Blank is similar to Short Answer, but what the student enters in response is checked against a correct answer and feedback is shown based on if it matches or not. Multiple answers or spellings/forms of the same answer can be entered in the answer field separated by commas.


Bundles

Bundles in a Storybook presentation are Pages that contain both an audio file and a set of images that are timed to the audio. See the section on Bundles in the Slide Formatting portion of this document for more information on creating the assets for a bundle.

Bundles work just like image-audio pages except for additional <frame> tags. First frame of the bundle always starts at 00:00, so it is not specified in the xml. Each frame tag specifies when a frame starts being displayed. The start time is formatted as minutes:seconds.


HTML

For special situations where you need to create an interactive element such a custom learning object or you need to display content that works on the web but is otherwise not directly supported in Storybook you can use the HTML Storybook page type.

The type is set to html and the src is set to the name of the folder inside of the html folder in your assets folder that contains the index.html that will be used on the Storybook page.

Notes

The notes section is an area intended for information that supports the content area and the narration. It is an area that supports most basic HTML and CSS including text formatting, images, and links.

The notes area scrolls, so a fair amount of content can be put in it. With that said, please use good judgment and do not fill it with pages of content. If you are requested to put a large amount of content in the notes area, consider alternative methods to deliver it.

Common uses for the notes area:

  • Clickable versions of links that are on the slide
  • Supporting links that are not on the slide
  • Citations on information or image sources
  • Additional supplementary text
  • Computer code for copying and pasting
  • Instructions for activities relating to the slide

The <note> tag is usable on all slides except for the quiz as the quiz takes up the full height of the player.

Links and Citations

Links and citations should be placed in the notes area. Please refer to the Links and Citations documentation page for more information on how to format them.

Centralized Assets

To help with updating assets that are used across presentations, and to save a bit of space on the server, we centralize some assets used in Storybook Presentations. We currently centralize the text and photo of the author profile and the splash image.

All centralized assets are sent through Bryan Bortz for installation on the web server. This is to ensure consistency in implementation, and structure. These assets should be delivered through Pulse. If Bryan is not available, contact Ethan Lin.

Author Profile

The author profile is comprised of two parts, the author’s photo, and a short text biography/profile.

Photo

This is a photograph of the author in portrait style and orientation. It is recommended that it be at least 900px tall when possible. Formatting, scaling and resizing can be taken care of by Bryan when

Profile

This should be delivered as plain text without major formatting. It should include the following:

  • Author Name
  • Affiliated campus or affiliated organization
  • A short profile/description of the author
Splash

The splash image for the Storybook Presentation is the background that appears on the title/splash screen when the presentation is first loaded. The image is in vector format, has an aspect ratio of 10×7 and should adhere to the following specifications:

  • Format: SVG
  • Width: 900px
  • Height: 630px
  • File Size: under 250kb

Creation of a splash image should be done in Adobe Illustrator. The amount of fine detail included in the design should be kept to a minimum to make sure the resulting SVG comes in under 250kb.

The splash image should also coordinate with the Course Theme that has been created for the course the Storybook presentation is part of.

Math

Some of our programs have courses that use Math equations that are beyond the basics. These are supported throughout Storybook in the interface, quiz questions, and notes areas by a javascript library called MathJax. We write out the math equations in a format called LaTeX (pronounced Lay-Tech).

LaTeX is an extensive and deep form of what is called a document preparation system. This means it is a series of characters that are written out to then be interpreted and displayed in a different but intended structure.

Writing LaTeX

Because the use of LaTeX is an edge case process we don’t deal with a lot, it is not expected that you learn how to write it. But you will need to either look at examples and adapt the equations to it, or you will delegate this part of the work to someone who can sort it out.

Using an online LaTeX editor such as the one located at latex4technics.com will allow you to write LaTeX and get instant previews of how it will look when rendered. For the most part, by referencing examples and through trial and error you should be able to sort out how to render most of the equations you may run into in our courses.

LaTeX has a wide scope beyond what we will be using it for, our focus is on displaying inline math. These two documents should give an idea of the basics:

Using LaTeX with MathJax in Storybook Presentations

Use of LaTeX math equations works in the following places of a Storybook Presentation:

  • Title and Subtitle
  • Section Titles
  • Storybook Page Titles
  • Notes
  • Widgets

Formatting LaTeX so it renders with MathJax
Our MathJax install is configured to use \(…\) for indicating LaTeX blocks. The block starts with a backslash and an opening parenthesis has the LaTeX in the middle and ends with a backslash followed by a closing parenthesis. Examples:

  • \(\frac{a^b+2}{2+1}=\)
  • \(\begin{aligned} \dot{x} & = \sigma(y-x)\)
  • \(r = 0.731\)

Audio Editing Transcript Production

Published on April 24, 2017 at 3:28:25 pm CDT. Last modified on June 06, 2018 at 12:13:49 pm CDT.