Rwt-storyboard NPM

Premium DOM Component

Storyboard

Multi-panel story with cool effects

Motivation

The rwt-storyboard DOM component is intended for use on web pages where the author wants to grab the reader's attention and funnel them towards a particular action.

The component has these features:

Each panel may contain any arbitrary content and styling.
Each panel may be transitioned to visibility using it's own effect.
The first panel can be shown with an initial delay before the sequencing begins.
The last panel can be shown with a final hold time before restarting the full sequence.
Sequencing occurs only when the component is fully visible within the browser's viewport. It is suspended when the component is hidden or only partially visible.
The user may suspend the auto-sequencing by clicking anywhere within the component's frame, and may resume the auto-sequencing by clicking the component a second time.
Round buttons along the bottom of the storyboard allow the user to override the auto-sequencing to display a particular panel.

In the wild

To see an example of this component in use, visit the READ WRITE STACK website. Each page uses this component to tell a user story about apps, plugins and DOM components. To understand what's going on under the hood, use the browser's inspector to view the HTML source code and network activity, and follow along as you read this documentation.

Installation

Prerequisites

The rwt-storyboard DOM component works in any browser that supports modern W3C standards. Templates are written using BLUE PHRASE notation, which can be compiled into HTML using the free Read Write View desktop app. It has no other prerequisites. Distribution and installation are done with either NPM or via Github.

Download

Using the DOM component

After installation, you need to add two things to your HTML page to make use of it.

Add a script tag to load the component's rwt-storyboard.js file:

<script src='/node_modules/rwt-storyboard/rwt-storyboard.js' type=module></script>

Add the component tag somewhere on the page with these two attributes:
- Apply a sourceref attribute with a reference to an HTML file containing the panels. See details below.
- Optional. For WAI-ARIA accessibility apply a role=contentinfo attribute.

Here's an example:

<rwt-storyboard sourceref='/five-panel-story.html' role=contentinfo></rwt-storyboard>

Panel template

The sourceref file should contain valid HTML consisting of two or more section elements. The contents of each section is treated as a panel.

Transition effects are declared by adding the two special attributes data-next and data-prev to each section. In this example (shown using BLUE PHRASE notation for clarity), each panel will transition to visibility using fade-in and transition to hidden using fade-out:

section *data-next='fade-in' *data-prev='fade-out' {
    Ask a leading question
}
section *data-next='fade-in' *data-prev='fade-out' {
    Pose a suggested answer
}
section *data-next='fade-in' *data-prev='fade-out' {
    State the product's feature 
}
section *data-next='fade-in' *data-prev='fade-out' {
    Assert that user needs the product
}
section *data-next='fade-in' *data-prev='fade-out' {
    Give user easy way to get it
}

The possible transition values are:

Customization

Dimensions

The width and height of the storyboard are set using the CSS variables --width and --height.

Adjust the --font-basis to shrink or grow the entire storyboard.

rwt-storyboard {
    --font-basis: 1.0;
    --width: calc(10rem * var(--font-basis));
    --height: calc(40rem * var(--font-basis));
}

Color scheme

The default color palette for the storyboard uses a dark mode theme. You can use CSS to override the variables' defaults:

rwt-storyboard {
    --color: var(--white);
    --background: var(--black);
    --button-color: var(--pure-white);
}

Important: the content of each panel can be customized with any CSS you want, but that CSS must be included in the sourceref template file together with the panel's HTML declarations. CSS that is outside the component is firewalled and will not pierce the document/component barrier.

Threshold

Panels will only transition when visible. When the document is scrolled outside the user's viewport, the transitioning effect is suspended. The component can be customized to suspend/resume transitions when only a portion of the full storyboard is visible. The threshold for this is a value between 0.0 and 0.99.

rwt-storyboard {
    --threshold: 0.95;
}

Timing variables

The sequencing of panel transitions is controlled by CSS variables. Each variable may specify values in units of seconds (s) or milliseconds (ms).

--duration-in is the duration for a new panel to become fully visible.
--duration-out is the duration for the previous panel to become completely hidden.
--delay-in is the amount of time to wait before starting a panel's transition from hidden to visible.
--delay-out is the amount of time to wait before starting a panel's transition from visible to hidden.
--initial-delay is the initial amount of time to show the first panel, before beginning the transition to the second panel.
--sequence-time is the total time from one panel to the next. Normally this should be equal to --duration-in + --duration-out + --delay-in + --delay-out.
--hold-time is the final amount of time to show the last panel, before restarting the full sequence.

rwt-storyboard {
    --duration-in: 2s;
    --duration-out: 2s;
    --delay-in: 0s;
    --delay-out: 0s;
    --initial-delay: 6s;
    --sequence-time: 4s;
    --hold-time: 6s;
}

Life-cycle events

The component issues life-cycle events.

Reference

License

The rwt-storyboard DOM component is not freeware. After evaluating it and before using it in a public-facing website, eBook, mobile app, or desktop application, you must obtain a license from Read Write Tools .

Activation

To activate your license, copy the rwt-registration-keys.js file to the root directory of your website, providing the customer-number and access-key sent to your email address, and replacing example.com with your website's hostname. Follow this example: