Guided tours: a page shows a user where things are, one highlighted element at a time, with a popover telling about it -- and the ? button of the top bar, which offers the page's tours and the guides' articles.
MMO.guide = {…}
Namespace
MMO
A tour comes from the page or from an element:
- a page's is a `.tour.json` written beside its `.phtml` (`declaration.phtml` → `declaration.tour.json`), which the
server filters (the steps the user may not see) and hands to `register` (`Guide`);
- an element's is given by its script to `add` (`<mmo-page-editor>`'s, one per display level).
```json
{
"id": "AccidentTravail-declaration", //where it is remembered as seen: `guides/{id}`
"title": "Declare a work accident",
"article": "guide/declare-accident", //optional: the page of the guide about the same task
"autostart": true, //shown once, the first time the user meets it
"allowed": "data#create", //optional: the scope the user needs (a page's tour, server side)
"level": "standard", //optional: from this display level up (MMO.modes)
"levels": ["simple"], //optional: at these display levels only
"steps": [
{
"title": "The path",
"text": "Plain text: a blank line starts a new paragraph.",
"target": "#workflow #stepper li", //css; `host >>> inner` looks inside host's shadow root
"contains": "Identification", //optional: the first target whose text contains this
"placement": "right", //optional: bottom (default), top, left, right
"optional": true, //optional: skipped when the target is not on the page
"wait": 8000, //optional: how long to wait for the target to show (ms)
"level": "expert", "levels": [...] //optional: as a tour's
}
]
}
```
A step without a target, or whose target never shows up, is shown in the middle of the screen. A tour only shows:
the page under it cannot be clicked while it runs, so a tour never saves, creates or sends anything. A tour is
started by the `?` menu, by itself the first time (`autostart`), or by `?guide={id}` (`?guide=1`) in the page's url.
Where a user left it (`done`, `skipped`, at which step) is saved in their config (mmo.oauth's `MMO.user`), and in
the browser.
Put the spotlight on the target and the popover beside it: on the side the step asks for when it fits, on the side with the most room when it does not.
Add a tour to the page's: offered by the ? menu, and started if it was asked for (?guide={id}) or is autostart and was never seen. A tour of another display level than the one shown is left out.
add(tour, first = false)
tour
Object
first = false
boolean
- true: the page's own, first in the menu
returns
boolean
whether it is one of the page's (not left out by its level, nor without steps)
Put the spotlight on the target and the popover beside it: on the side the step asks for when it fits, on the side with the most room when it does not. A phone shows the popover as a sheet at the bottom (css).
Show a page of the guides in the shell's side panel, beside the page the user is working on. The panel then browses the guides by itself (panelClick). The article is the site's own page: its .guide-article (else its main), read from its html without its scripts.
A click in the guide's panel: a page of the guides opens in the panel, the tour of the page the user is on starts right there. Any other link, or a ctrl/cmd/shift-click, goes where it says.