Overlays

Tour

Point at parts of a page one after the other, with a short text for each.

A three-step tour

HTML

<button class="pw-btn pw-btn--primary" id="demo-tour-start">Start the tour</button>
<input class="pw-input" id="demo-tour-search" placeholder="Search orders" style="max-width:200px" aria-label="Search orders">
<button class="pw-btn" id="demo-tour-export">Export</button>

JavaScript

var tour = Partwise.tour([
  { element: '#demo-tour-search', title: 'Search', text: 'Find an order by its number or by a customer name.' },
  { element: '#demo-tour-export', title: 'Export', text: 'Download what you see as a CSV file.', placement: 'top' },
  { title: 'That is all', text: 'You can start this tour again at any time.' }
]);
document.getElementById('demo-tour-start').addEventListener('click', function () { tour.start(); });

From HTML

Write the steps in a hidden element and start them with a button.

New

HTML

<button class="pw-btn" data-pw-tour-start="#demo-steps">Start</button>
<span class="pw-badge pw-badge--info" id="demo-tour-badge">New</span>

<div id="demo-steps" hidden>
  <div data-element="#demo-tour-badge" data-title="A badge">Steps can point at any element.</div>
  <div data-title="Done">A step without an element sits in the middle.</div>
</div>

How to use it

Each step has element (a selector, optional), title, text and placement (top, bottom, left, right).

Options

Set them as attributes on the element.

Attribute	Default	What it does
`key`		Script option. Remembers in the browser that this visitor finished or skipped the tour. Use it with `startOnce()`.
`labels`		Script option: `{ next, back, done, skip }` for your own words.
`onEnd`		Script option: a function called with `finished` or `skipped`.

Events

Listen with addEventListener. Details are in event.detail.

Event	When
`pw:tour-step`	On `document`, with `index` and `step`.
`pw:tour-end`	On `document`, with `reason`.

From your script

var tour = Partwise.tour(steps, { key: 'welcome' });
tour.startOnce();   // only for people who have not seen it
tour.start(); tour.next(); tour.back(); tour.end();
tour.reset();       // forget that it was seen

Keyboard

Key	Action
`Right` `Left`	Next and previous step
`Enter`	Press the button that has the focus
`Esc`	Skip the tour

Good to know

The page scrolls to each element. A step whose element is not on the page is shown in the middle.
The page behind cannot be clicked while a tour runs.
Keep tours short. Three to five steps is plenty.

Files

Everything is in dist/partwise.css and dist/partwise.js. To load only this component, use src/css/00-base.css and src/js/00-core.js plus: css/40-code-tour.css, js/41-tour.js.