Read-Along Web Component

This is a web component for embedding read-along, audio/text aligned content in your website or hybrid app.

Basic use

The simplest way to use the web component is to generate a read along using the ReadAlongs Studio web app. Once you've create a readalong, you can download the Web Bundle.

You can also use the ReadAlongs Studio CLI. Its align command will output the bundle in a folder.

Whether you're using the web app or the CLI, the bundle will contain the read-along XML file (.readalong), the other assets, and a minimal HTML index page, which you can view with python -m http.server, for example, or deploy on a web server.

The rest of this readme is intended for users who want to customize their readalongs or contribute to the development of this web component.

Installation

For now, just clone the repo, make sure you have node 6+, and run npm install from the project root. Then you can run npm start and a minimal website containing only the webcomponent will be served at localhost:3333. Any changes you make to /src will be automatically shown in the browser.

Properties

| Property | Attribute | Description | Type | Default | | ---------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------- | | audio | audio | URL of the audio file | string | undefined | | autoPauseAtEndOfPage | auto-pause-at-end-of-page | Auto Pause at end of every page | boolean | false | | cssUrl | css-url | Optional custom Stylesheet to override defaults | string | undefined | | displayTranslation | display-translation | Show text translation on at load time | boolean | true | | href | href | URL of the aligned text as readalong XML | string | undefined | | imageAssetsFolder | image-assets-folder | Define a path for where the image assets are located This should be used instead of use-assets-folder. Defaults to 'assets/'. The empty string means that image paths will not have a prefix added to them. Use of the forward slash is optional. | string | "assets/" | | language | language | Language of the interface. In 639-3 code. Options are "eng" (English), "fra" (French) or "spa" (Spanish) | "eng" \| "fra" \| "spa" | "eng" | | mode | mode | Choose mode of ReadAlong - either view (default) or edit | "EDIT" \| "VIEW" | "VIEW" | | pageScrolling | page-scrolling | Toggles the page scrolling from horizontal to vertical. Defaults to horizontal | "horizontal" \| "vertical" | "horizontal" | | playbackRateRange | playback-rate-range | Control the range of the playback rate: allow speeds from 100 - playback-rate-range to 100 + playback-rate-range. | number | 15 | | scrollBehaviour | scroll-behaviour | Select whether scrolling between pages should be "smooth" (default nicely animated, good for fast computers) or "auto" (choppy but much less compute intensive) | "auto" \| "smooth" | "smooth" | | svgOverlay | svg-overlay | Overlay This is an SVG overlay to place over the progress bar | string | undefined | | theme | theme | Theme to use: ['light', 'dark'] defaults to 'dark' | string | "light" | | useAssetsFolder | use-assets-folder | DEPRECATED Toggle the use of an assets folder. Defaults to undefined. Previously (<1.2.0) defaulted to 'true'. .readalong files should just contain base filenames not the full paths to the images. | boolean | undefined |

IMAGES

You have three options:

• put images in "assets/" and provide relative links
• provide full paths
• put them in a custom relative folder and make sure to add image-assets-folder="path/to/images/folder" attribute to the read-long component

Images can be inserted in a read-along interactively using the web app.

If you're using the CLI, images are normally inserted in a read-along by specifying them in the config.json file provided to readalongs align, which will then attempt to generate and populate the assets folder automatically. See the readalongs CLI user guide for details.

Test with your site

You can either modify the /src/index.html or after running npm start you can copy out the www/build folder and add the following script import in your own index.html page:

<script
  type="module"
  src="https://unpkg.com/@readalongs/web-component@^1.4.0/dist/web-component/web-component.esm.js"
></script>

Then, you can add as many read-along components to your page as you like simply by adding <read-along> elements with arguments for where to find your text, alignments and audio file. These files can be generated using the ReadAlongs Studio web app or the ReadAlongs Studio CLI.

<read-along
  href="assets/my-story.readalong"
  audio="assets/my-story.wav"
  css-url="assets/custom.css"
  image-assets-folder="assets/"
></read-along>

Loading as a single file

By default, Stencil (the tool used to build this web component) uses lazy loading. However, some use cases for this web component might involve running the component as a single file, without access to the internet. A single-file script of this web component is therefore made available at https://unpkg.com/@readalongs/web-component@^1.4.0/dist/bundle.js although we recommend using the default imports using the unpkg content delivery network (cdn) described above.

Theming

There are two themes out-of-the-box: light and dark. You set them as a property on the <read-along> web component element. If you want to add your own theme, it's as easy as adding your colour palette to the $ui-themes variable in src/components/read-along-component/scss/utilities/_colors.scss. Note you will have to rebuild the web component from source to do this, or submit your theme as a pull-request!

$ui-themes: (
  light: (
    primary: $white,
    secondary: darken($white, 50%),
    accent: darken($white, 60%),
    text: $black,
    text--secondary: $white,
    text--accent: $white,
  ),
  dark: (
    primary: lighten($black, 30%),
    secondary: darken($white, 35%),
    accent: $white,
    text: $white,
    text--secondary: $white,
    text--accent: $black,
  ),
);

Slots

Slots allow you to add custom html into specific "slots" within the web component. For example, to add an optional header and subheader to the <read-along> element, you would write:

<read-along>
  <span slot="read-along-header">Hello World!</span>
  <span slot="read-along-subheader">Read by I-travelled Around-the-world</span>
</read-along>

| Slot | Description | Suggested Element | | ---------------------- | ---------------------- | ----------------- | | read-along-header | The read along header | span | | read-along-subheader | Subheader (ie authors) | span |

Page layout

By default, the pages are two column layout with images on the left and text on the right. You can force any page to one column layout by setting the class of the page to one-column-layout-page in the .readalong file.

<div type="page" class="one-column-layout-page">
  ...
</div>

The default layout auto adjusts without restrictions. To force a 40-60 split between the image and the text use the two-column-layout-page class for the page.

<div type="page" class="two-column-layout-page">
  ...
</div>

Hide page number

You can hide the page number for any page by specifying the class hide-page-counter on its <div type="page"> element in the .readalong file.

Assets folder

By defaults the image assets will be resolved to ./assets/ relative to the index.html file. You can override this behaviour by using this attribute on the <read-along> element in your .html file: images-assets-folder="path/to/assets". The web component will resolve urls for images by prepending the specified path to image paths. Specifying "" disables this behaviour.

CSS customization

You can override the default style of the component. This option is best used anyone does not want to clone this project and modify only the UI. Use the web inspector of your browser to find the classes you wish to override.

/* change the font size and color of the text */
.sentence__word.theme--light {
  color: #64003c;
  font-size: 1.8rem;
}

/* change the background color of the text being read */
.sentence__word.theme--light.reading {
  background-color: #64003c;
}

Here is a list of classes you want to override:

• .sentence__word.theme--light
• .sentence__word.theme--light.reading
• .sentence__text.theme--light
• .sentence__translation
• .sentence
• .paragraph
• .page__container.theme--light (to set page background)

XML customizations

You can add classes to the xml tags in the .readalong XML file. When coupled with the custom css, it will produce most of the visual effect you want in your read along. E.g. <s class="sentence__translation">

Built-in translation class

The default css class provided for translations should be added to the XML <s> tag. Here is a sample:

<p id="t0b0d1p0">
  <s id="t0b0d1p0s0">
    <w id="t0b0d1p0s0w0">...</w>
    <w id="t0b0d1p0s0w1">...</w>
    <w id="t0b0d1p0s0w2">...</w>
  </s>
  <s id="t0b0d1p0s1" class="sentence__translation">This is a translation</s>
</p>

The default style:

.sentence__translation {
  color: #777;
  font-style: italic;
  font-size: 95%;
}

Visual alignment

You can force the visual alignment of sentences within a paragraph by adding class="visually_aligned" to the <p> tag of xml. Here is a sample

<p id="t0b0d1p0" class="visually_aligned">
  <s id="t0b0d1p0s0">
    <w id="t0b0d1p0s0w0">...</w>
    <w id="t0b0d1p0s0w1">...</w>
    <w id="t0b0d1p0s0w2">...</w>
  </s>
  <s id="t0b0d1p0s1" class="sentence__translation ">This is a translation</s>
</p>

MIND THE GAP: When you visually align a paragraph please triple check the spacing and punctuation between elements because the visual alignment is white-space sensitive

SIDE EFFECT: This feature disables auto-wrapping of the words in the paragraph

For developers of the component

We use Cypress (instead of Jest+Puppeteer) to do integration/end-to-end testing.

How to run the tests

Since this package is part of a monorepo, all the following commands must be run at the root of the monorepo, not in this directory.

First, start the two test servers, by using this command:

npx nx run-many --targets=serve-test-data,serve --projects=web-component

Or you can run each test server separately:

npx nx serve web-component
npx nx serve-test-data web-component

Run the full test suite automatically using this command:

npx nx test:once web-component

Alternatively, this command will launch Cypress so that you can run the tests interactively:

npx nx test:open web-component

Interactively testing your local copy

If you want to use your local copy of the Web Component instead of the version published at unpkg, change the two script lines in your HTML and set the module URL to your localhost. See for example the unit testing file test-data/ej-fra/index.html, which assumes this Stencil component is being served on port 3333, the default when running locally.