# How to Create Guided Stories in Archify Viewer: A Complete Implementation Guide

> Learn how to create guided stories in Archify viewer with this implementation guide. Enable guided playback and enhance user experience.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-17

---

**To create guided stories in Archify viewer, set `guidedPlayback: true` in your view metadata, include the UI template from [`guide-template.html`](https://github.com/tt-a1i/archify/blob/main/guide-template.html), and instantiate the viewer with the `guided: true` option.**

A **guided story** is an interactive, step-by-step walkthrough of a visual document built from *beats*—individual view states stored in the document's metadata. The Archify viewer renders these beats through dedicated UI controls defined in the source code, enabling audiences to navigate a curated narrative.

## Prerequisites: Understanding Guided Story Architecture

Guided stories in `tt-a1i/archify` rely on three integrated components:

- **Metadata flags** that mark views as story beats
- **HTML/CSS templates** that render the story controls
- **JavaScript initialization** that activates story mode

The viewer reads story data from your document's JSON metadata (typically under `data.story`) and automatically wires navigation logic when the `guided` option is enabled.

## Step 1: Flag Views for Story Inclusion

First, annotate each view that belongs to your guided story by setting `guidedPlayback: true` in the view definition. The build script in `scripts/build-gallery.mjs` evaluates this flag during gallery generation.

According to the source code around line 308, the script automatically assigns `guidedPlayback` based on view count:

```js
// archify/scripts/build-gallery.mjs (line 308)
guidedPlayback: entry.viewCount > 0,

```

For manual control, explicitly define the flag in your view JSON:

```json
{
  "id": "view-01",
  "title": "Introduction",
  "guidedPlayback": true,
  "content": { }
}

```

## Step 2: Include the Story UI Template

The guided story interface is defined in [`scripts/guide-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html). This file contains the toolbar markup and CSS that the viewer toggles during story playback.

### Key CSS Classes in [`guide-template.html`](https://github.com/tt-a1i/archify/blob/main/guide-template.html)

| Class | Purpose |
|-------|---------|
| `.guided-view-play` | Play/pause button state |
| `.guided-view-stop` | Navigation buttons with `data-story-link` attributes |
| `.guided-story-caption` | Caption area for beat titles and descriptions |
| `.guided-view-progress` | Visual progress indicator |

The source CSS implements arrow indicators and styling states:

```css
/* archify/scripts/guide-template.html – UI styles */
.guided-view-play[aria-pressed="true"] { 
  background: var(--toolbar-hover); 
}

.guided-view-stop[data-story-link="forward"]::after { 
  content: '\2192'; 
}

.guided-story-caption strong { 
  color: var(--toolbar-text); 
  font-size: .6875rem; 
}

```

Copy this markup into your page (the viewer will unhide and populate it):

```html
<div class="guided-views" hidden>
  <button id="guided-view-prev" class="guided-view-stop" 
          data-story-link="reverse">Prev</button>
  <button id="guided-view-play" class="guided-view-play" 
          aria-pressed="false">Play</button>
  <button id="guided-view-next" class="guided-view-stop" 
          data-story-link="forward">Next</button>

  <div class="guided-view-progress"><span></span></div>
  <div class="guided-story-caption">
    <strong id="guided-caption-title"></strong>
    <small id="guided-caption-subtitle"></small>
  </div>
</div>

```

The `data-story-link` attribute accepts three values: `"forward"`, `"reverse"`, and `"multiple"` for different navigation behaviors.

## Step 3: Instantiate the Viewer with Story Mode

Initialize `ArchifyViewer` from [`archify/archify.js`](https://github.com/tt-a1i/archify/blob/main/archify/archify.js) and enable guided story mode:

```js
// Example: initialise Archify viewer with a guided story
import { ArchifyViewer } from 'archify';

const viewer = new ArchifyViewer('#archify-container', {
  // Path to the compiled document (JSON/HTML bundle)
  src: './my-project/archified.json',
  // Enable guided-story mode (automatically reads `guidedPlayback`)
  guided: true,
});

// Optionally start the story programmatically
viewer.startGuidedStory();   // plays the first beat

```

The `guided: true` option triggers the viewer to scan for `guidedPlayback` flags and activate the story navigation system.

### Auto-Start on Document Load

For immediate playback when the document is ready:

```js
<script type="module">
  import { ArchifyViewer } from './archify/archify.js';

  const viewer = new ArchifyViewer('#viewer', {
    src: 'demo/archified.json',
    guided: true          // tells the viewer to look for guided stories
  });

  // Auto-start the story when the document loads
  viewer.on('ready', () => viewer.startGuidedStory());
</script>

```

## Complete Working Example

This implementation combines all three steps in a single HTML page:

```html
<!DOCTYPE html>
<html>
<head>
  <title>Archify Guided Story</title>
  <link rel="stylesheet" href="./archify/archify.css">
</head>
<body>
  <div id="viewer"></div>

  <!-- Story UI template (from guide-template.html) -->
  <div class="guided-views" hidden>
    <button id="guided-view-prev" class="guided-view-stop" 
            data-story-link="reverse">Prev</button>
    <button id="guided-view-play" class="guided-view-play" 
            aria-pressed="false">Play</button>
    <button id="guided-view-next" class="guided-view-stop" 
            data-story-link="forward">Next</button>

    <div class="guided-view-progress"><span></span></div>
    <div class="guided-story-caption">
      <strong id="guided-caption-title"></strong>
      <small id="guided-caption-subtitle"></small>
    </div>
  </div>

  <script type="module">
    import { ArchifyViewer } from './archify/archify.js';

    const viewer = new ArchifyViewer('#viewer', {
      src: 'demo/archified.json',
      guided: true
    });

    viewer.on('ready', () => viewer.startGuidedStory());
  </script>
</body>
</html>

```

## Key Source Files Reference

| File | Function | Line Reference |
|------|----------|----------------|
| `scripts/build-gallery.mjs` | Assigns `guidedPlayback` during gallery build | Line 308 |
| [`scripts/guide-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html) | Defines story UI markup and styles | Full file |
| [`archify/archify.js`](https://github.com/tt-a1i/archify/blob/main/archify/archify.js) | Core viewer that reads `guided` flag and drives story logic | Full file |
| [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) | Complete demo implementation | Full file |

## Summary

- **Metadata**: Set `guidedPlayback: true` on views to include them as story beats
- **Template**: Include the HTML/CSS from [`guide-template.html`](https://github.com/tt-a1i/archify/blob/main/guide-template.html) for navigation controls
- **Initialization**: Pass `guided: true` to `ArchifyViewer` and call `startGuidedStory()` to begin playback
- **Navigation**: The viewer automatically wires `.guided-view-stop` buttons with `data-story-link` attributes to step through beats

## Frequently Asked Questions

### What triggers the guided story UI to appear?

The **presence of `guided: true`** in the viewer configuration and at least one view with `guidedPlayback: true` in the document metadata. When both conditions are met, the viewer unhides the `.guided-views` container and populates it with beat data from `data.story`.

### Can I customize the story navigation buttons?

Yes. The `data-story-link` attribute supports **three values**: `"forward"` and `"reverse"` for sequential navigation, and `"multiple"` for jump-to-point behavior. You can restyle buttons using the CSS custom properties defined in [`guide-template.html`](https://github.com/tt-a1i/archify/blob/main/guide-template.html) (e.g., `--toolbar-hover`, `--toolbar-text`).

### How do I add captions to each story beat?

The viewer populates `#guided-caption-title` and `#guided-caption-subtitle` from the `title` and description fields of each view's metadata. Ensure your beats include these fields in the JSON definition, and the `.guided-story-caption` element will display them automatically.

### Does the viewer support programmatic story control?

Yes. Beyond `startGuidedStory()`, the `ArchifyViewer` instance exposes methods to **pause, resume, and jump to specific beats**. These integrate with the `.guided-view-play` button state (tracked via `aria-pressed`) and the `.guided-view-progress` bar visualization.