StoryTeller Repository

Manages stories via manual sequencing and page-note queries

Quick Status

Code functions correctly

- Works correctly for FireFox & Chrome
- Styling problems with Safari and Edge
- CSS validates as correct using W3C validator

Demonstration code

yes

Documentation

yes

Test cases

Static library

none planned

Planned design changes

- Attempt to find stylings that work for all
browsers
- Add Local StoryTeller that uses JavaScript
messages

Fig 1. StoryTeller UI

1.0 Concept

A story is a linked sequence of resources, mostly HTML pages, all focused on a common theme. You will find, in the documentation site, links to a StoryTeller that has, at this time, five stories:

Rust Story
Rust Bite by Byte
C++ Story
∞ Data Library
MLiPS
Site Story
Test Story

When the StoryTeller is opened, a list of available stories is presented for selection. A user may then navigate through the story using links or key presses.

All of the stories listed above don't need the services of StoryTeller. They work fine using the standard menus with its "Prev" and "Next" links. StoryTeller was designed to allow a page to be used in more than one story. That means there needs to be another way of defining the page sequence since a page link is a permanent link to one other page.

That's what the StoryTOC does, as shown in Figure 2. The design worked well enough, but was a bit less ergonomic than navigating the conventional stories. For that reason I don't plan to continue this development.

Fig 1. StoryTeller Callgraph

2.0 Design - Note: see status below

StoryTeller provides an iframe that fills most of the available browser view, and a set of navigation buttons that invoke JavaScript functions for navigation and query.

For security reasons, iframes are not allowed to directly interact with host code. However, the host needs to figure out how to link story pages. The way that is done is:

The StoryTeller host page loads a list of available stories. When a user clicks on a link to one of the stories, a story Table of Contents page is loaded. As part of the loading, that page analyzes its own links and text immediately below a link, and writes that information into localStorage.
The StoryTeller host reads localStorage to extract all the story information so it can build a timeline - an array of JavaScript objects, each having a url, name, and page-notes. It also builds a Table of Contents for the story, as a dropdown list, and provides buttons for manually steping through story content.

It took quite a bit of JavaScript and CSS styling, and some fairly intricate event processing to get all this to work, but it does!

3.0 Build

StoryTeller was built with Visual Studio Community Edition - 2019, and tested on Windows 10.

3.0 Status

The design of StoryTeller is still evolving. I've refactored its JavaScript, and converted from localStorage events to iframe onLoad events, but am still using localStorage to hold story information. The current version, StoryTeller_LocalStorage, uses iframe onLoad event exclusively. This version works well for FireFox and Chrome, when using https:// or http:// protocols.

Both Edge and Safari are able to use StoryTeller to step through stories, but both of them have CSS placement artifacts that make that a less than perfect experience. I will be looking at that soon. In the meantime you can use either FireFox or Chrome on any of the major platforms. Using current versions, StoryTelling works fine on Windows 10, Ubuntu 18.04, and macOS Mohave. You can download either from their websites (to be sure you get a recent version). The installers for each platform work with no problems.

Running StoryTeller locally from a machine drive uses the file:// protocol. There are variations in how all of these browsers treat localStorage for the file:// protocoal. Edge, for example, doesn't define local storage for file://. Neither FireFox nor Chrome will display stories locally due to CORS security settings (browsers treat each file as a unique domain).

I'm working on a version, StoryTeller_Messages, that uses JavaScript messages to use with the file:// protocol. That should work for all the major browsers. That work has just started, been put on hold for other things, but will make an appearance soon.

3.1 Current Status of this repository

StoryTeller_LocalStorage.html is the current version hosted by this site. It can present any story that has a Story TOC page, as described above. Here's an Example. Look at the page source to get an idea of how things work.

The next update will also provide StoryTeller_Message.html, which should work for the file:// protocol with all three browsers.

3.2 Late Breaking Status Update

Several months ago I made a breaking code change and have not fixed that yet. Eventually I will implement the StoryTeller_Messages version. While that design is interesting, its implementation has a low priority because of the ergonomic issues cited at the end of the Concept section.