Embed Chapters on Your Page
Put the chapters of a work one by one on your own page — for example a course with text, images and quizzes in between. Each chapter becomes its own player that loads when the reader scrolls near it and autoplays only while it is on screen.
Some works are best read in steps: a training course, a lesson series, a story told between articles. Chapter embeds put each chapter of a work on your own page as its own player, with your content in between. Every player shows only its chapter — readers cannot skip ahead into the next one — and loads only when the reader scrolls close to it, so a page with many chapters stays fast.
Chapter embeds use the open-source PanelWave Player and work on any web page: plain HTML, WordPress, a learning platform's HTML block. You paste one script tag and one placeholder per chapter.
Create the snippets
Open Work Properties → Publishing
In My Works, open the work's More actions menu (⋮), choose Properties and switch to the Publishing tab. Embed chapters sits below the reader links.
Pick where the player comes from
- Hosted on PanelWave plays the public version at read.panelwave.org. Publish the work publicly first.
- Self-hosted package plays a Package with player that you uploaded to your own web space. Enter the folder of the unzipped package relative to your page, for example
./first-aid/.
Choose the chapters
| Column | What it does | Saved with the work |
|---|---|---|
| Include | The chapter is part of the generated set | yes |
| Autoplay on scroll | The chapter plays by itself while it is on screen | yes |
| Poster | The image readers see before the player loads (self-hosted package; default: the first panel) | yes |
| Copy | Copies the script tag and this one chapter | — |
Set the page options (optional)
Language, how the players load, their shape (16:9, A4 portrait, …), the toolbar, the cover, and the seconds per panel for autoplay. These shape the generated code only.
Paste the code into your page
Click Copy all and paste: the <script> tag once (in the page's <head> or before the first chapter), then each <div class="panelwave-embed" …> where that chapter belongs. Download example page gives you a complete HTML page to start from.
The generated code looks like this:
<script src="https://read.panelwave.org/embed.js" defer></script>
<h2>1. Arrival</h2>
<p>Your lesson text …</p>
<div class="panelwave-embed" data-src="https://read.panelwave.org/acme/first-aid"
data-chapter="0d3a5c1e-…" data-title="1. Arrival" data-autoplay="true"></div>
<h2>2. The accident</h2>
<p>A quiz, a video …</p>
<div class="panelwave-embed" data-src="https://read.panelwave.org/acme/first-aid"
data-chapter="7c1e8b2f-…" data-title="2. The accident"></div>
data-chapter is the chapter's permanent id: reordering or renaming chapters later does not break your page.
How readers experience it
- Lazy loading. The first chapter loads with the page; every other one shows its poster and title until the reader scrolls within about one screen of it. Only then is its player loaded.
- One chapter per player. Next and previous stop at the chapter's first and last panel, the table of contents lists only that chapter, and links into other chapters do nothing. Preflight points such links out as Link into another chapter (info).
- Autoplay on scroll. A chapter with autoplay starts when at least half of it is on screen, pauses when the reader scrolls away or switches tabs, continues when they come back, and stops at the chapter's end. If the reader switches autoplay off in the toolbar, it stays off.
- Sound. Browsers allow sound only after the reader interacted with the page. The first click or key press anywhere on your page counts for every chapter player.
- Keyboard. Arrow keys and shortcuts go to the chapter the reader clicked into, never to all players at once.
Options for developers
Each placeholder accepts these attributes:
| Attribute | Default | Meaning |
|---|---|---|
data-src | required | The work's reader address, or a package's index.html |
data-chapter | required | Chapter id (the generated code uses the permanent one) |
data-autoplay | false | Autoplay while on screen |
data-loading | auto | auto (first at once, the rest when near), lazy, eager or click (on tap only) |
data-poster | — | Image shown before the player loads |
data-title | — | Caption on the poster and the player's accessible name |
data-aspect | 16/9 | Shape of the player box, e.g. 4/3 or 210/297 |
data-locale | the reader's | Start language, e.g. de-DE |
data-toolbar | true | false hides the player toolbar |
data-cover | false | true starts on the work's cover |
data-seconds-per-panel | 5 | Autoplay time of panels without their own timing |
data-max-live | 3 | How many players stay loaded at once; farther ones return to their poster |
data-exclusive-audio | off | Mute chapters that are off screen |
The loader fires DOM events on each placeholder — panelwave:ready, panelwave:panelchange, panelwave:chaptercomplete, panelwave:autoplaychange, panelwave:error and more — so your page can, for example, unlock the next lesson when a chapter is complete:
document.addEventListener('panelwave:chaptercomplete', (event) => {
console.log('Finished', event.target.dataset.chapter, event.detail);
});
window.PanelWaveEmbed offers scan() (for placeholders added later, e.g. in single-page apps), mount(el), unmount(el) and get(el) with navigate(panelId), setOptions({ … }), getState() and destroy(). The protocol behind it is documented in the player repository (docs/EMBED_PROTOCOL.md, docs/MULTI_CHAPTER_EMBED.md). From player 1.10.0 (protocol v3) a host can also restyle the content widgets live with { type: 'setTheme', theme } and receives reader actions on them as pw:event widgetEvent; plain CSS on the page works too (--pw-theme-*, see Widget theme).
Self-hosted packages
A package exported with Add a chapter-embed example page (on by default) contains embed-example.html: every included chapter with its poster and autoplay setting, loaded by player/panelwave-embed.js from the package. Copy its script tag and chapter blocks into your own page and adjust the paths to where the package folder lives. Embedding from another website needs no extra server settings.
Analytics
Reads inside chapter embeds count like any other read of the published work. Under Analytics → Audience, Read on shows how many sessions came from the PanelWave reader and how many from each site that embeds the work.