Frontend-architectuur¶
De frontend van IntroVox is een Vue-3-single-page-app gebundeld met webpack, geïntegreerd in Nextcloud als vier entry-points: de tour-runtime, de admin-instellingen-pagina, de persoonlijke-instellingen-pagina en de tourlijst die andere apps kunnen tonen.
Entry-points¶
| Entry | Output-bundle | Geladen op |
|---|---|---|
src/main.js |
js/main.js |
Elke Nextcloud-pagina (via LoadScripts-listener) |
src/admin.js |
js/admin.js |
Admin-instellingen → IntroVox |
src/personal.js |
js/personal.js |
Persoonlijke instellingen → IntroVox |
src/embed/embed.js |
js/introvox-embed.js |
Een pagina van een andere app die <introvox-tour-list> toont (zie De tourlijst insluiten) |
main.js is een kleine bootstrap, omdat elke ingelogde pagina hem laadt. De tour-code zelf (WizardManager, Shepherd.js, Vue en css/wizard.css) is een eigen chunk, src/runtime/tour.js → js/tour.<hash>.js plus gedeelde vendor-chunks, die met een dynamische import() alleen geladen wordt op een pagina waar een tour draait. Chunk-namen hebben een content-hash (chunkFilename: '[name].[contenthash:8].js'), omdat chunks zonder Nextclouds ?v=-parameter laden. De bootstrap zet __webpack_nonce__ op het request-token in base64, zodat Nextclouds CSP de script-tag van de chunk toelaat. Zie Tour-runtime.
Component-boom¶
Elke pagina (src/main.js, de bootstrap)
└── chooseTour() ← src/runtime/chooseTour.mjs: welke tour, als er een is
└── tour-chunk (src/runtime/tour.js, alleen geladen als er een tour draait)
└── WizardManager.vue ← Shepherd.js-tour-levenscyclus, welkomsttour en tours voor apps
├── (Shepherd-managed step-DOM, geen Vue-componenten)
└── PWA-installatie-instructies (~50 strings, v1.6.0+)
Admin-instellingen-pagina (src/admin.js)
└── AdminApp.vue ← de rij panelen, de lijst met tours, een tour openen, de beheerderstour
├── SettingsPane.vue ← Tours for everyone, Show Tours in the user menu
│ └── ChecklistSettings.vue ← de checklist op het Dashboard: aan/uit, de taken, eigen taken, op elk Dashboard
│ └── ChecklistTaskDialog.vue ← "New task" / "Edit task": titel, korte tekst, pagina
├── Paneel Tours
│ ├── ToursList.vue ← de tours: schakelaar, Edit steps, ⋯ (Preview, Copy link, Export tour, Show again to everyone, Delete), New tour, Import tour
│ │ (de acties: useTours.js)
│ ├── NewTourDialog.vue ← "New tour" en "Tour settings"
│ └── TourEditor.vue ← de stappen van één tour: talen, toevoegen, bewerken, verwijderen, herordenen (slepen of Move step up / Move step down), reset/import/export per taal
│ ├── AssistantDialog.vue ← "Translate with AI" / "Write steps with AI" (de taken: useAssistant.js)
│ ├── StepWizard.vue ← dialoog "New step" / "Edit step"
│ │ ├── StepTextEditor.vue ← het veld Text: opmaakbalk, emoji, Edit as HTML (regels in stepTextHtml.mjs)
│ │ ├── StepMediaBlock.vue ← Image or video: uploaden, kiezen uit Bestanden, een schermafbeelding plakken; beschrijving, grootte, ondertitels
│ │ └── ElementPicker.vue ← "Pick element" (src/picker/)
│ └── TourPreview.vue ← "Preview tour" / "Test this step" (src/preview/)
│ beide in NextcloudFrame.vue (src/frame/): Nextcloud in een iframe
├── StatisticsPane.vue ← TourStatistics.vue (één tour: gestart, afgerond, overgeslagen, hoe ver mensen komen), instance-informatie, telemetrie (TelemetryLists.vue)
├── SupportSettings.vue ← het paneel Support (src/components/)
└── TelemetryQuestion.vue ← de vraag na de beheerderstour (TelemetryLists.vue, telemetry.js)
Persoonlijke-instellingen-pagina (src/personal.js)
└── PersonalApp.vue ← Start tours by themselves
└── TourList.vue ← Restart tour now, de lijst Tours met Start (src/components/)
Pagina van een andere app (src/embed/embed.js)
└── <introvox-tour-list> ← custom element
└── EmbeddedTourList.vue ← laadt de lijst (GET /personal/settings)
└── TourLinks.vue ← een link per tour, zonder stijl: de host stijlt hem
In AdminApp.vue heet het paneel Tours intern nog steps. TourEditor werkt op één tour (AdminApp maakt er één per geopende tour, met het id als key) en geeft het id daarvan als tour mee aan elke aanroep voor stappen, overrides, import en export. AdminApp mag twee functies ervan aanroepen: addStep(), voor de eerste stap van een nieuwe tour, en ready(), waar de beheerderstour op wacht voordat hij naar de editor wijst.
Picker en voorbeeld¶
Beide tonen een live Nextcloud-pagina in een iframe van dezelfde origin, zodat de admin-pagina de DOM ervan direct kan lezen en aansturen. De naam van het frame (src/frame/frameNames.js) vertelt main.js in het frame waarvoor het dient: in de picker start geen tour, in het voorbeeld wacht WizardManager in voorbeeldmodus op stappen van de admin-pagina (window.introVoxPreview.run()) en registreert niets (geen telemetrie, geen voltooiing, geen localStorage). De selector-logica van de picker staat in src/picker/selector.mjs, getest in tests-js/picker-selector.test.js.
De tourlijst insluiten¶
Een andere app kan de tours tonen die een gebruiker kan starten, als het custom element <introvox-tour-list>: een link voor de welkomsttour, en dan een link voor elke tour die deze gebruiker mag krijgen, met het icoon van de app en de naam. IntroVox bepaalt per gebruiker welke tours erin staan, met dezelfde regels als overal (aan/uit, groepen, toegang tot de app van de tour), dus de lijst is altijd actueel. De vormgeving is van de host: het element levert kale markup zonder stijl, en de host stijlt die met de klassenamen hieronder. Een custom element in plaats van een Vue-component, net als <metavox-metadata-form> van MetaVox: de host hangt niet af van de Vue-versie van IntroVox, of van Vue überhaupt.
Laad de bundle tijdens het renderen van de pagina. IntroVox is optioneel voor de host, dus bewaak de aanroep:
if (class_exists(\OCA\IntroVox\Embed\TourListEmbed::class)) {
\OCP\Server::get(\OCA\IntroVox\Embed\TourListEmbed::class)->load();
}
isAvailable($userId) zegt of IntroVox voor een gebruiker aanstaat.
Plaats daarna het element:
Het neemt geen attributen. Elke link is de deellink van de tour (/apps/introvox/tour/<id>, /apps/introvox/tour/welcome voor de welkomsttour), die de pagina van de tour opent en de tour daar met de hand start. Staat Tours for everyone uit, dan blijft het element leeg; anders staat de link van de welkomsttour er altijd in.
De markup, binnen het element:
| Klasse | Op |
|---|---|
introvox-tour-list__items |
de lijst (ul) |
introvox-tour-list__item |
elk item (li) |
introvox-tour-list__link |
de link (a); --welcome voor de welkomsttour, --seen als de gebruiker de tour gezien heeft |
introvox-tour-list__icon |
het icoon (een SVG van 20 px); --app voor het icoon van een app (een img, licht zoals in het app-menu, dus een lichte pagina keert het om, bijvoorbeeld met filter: var(--background-invert-if-bright)) |
introvox-tour-list__name |
de naam van de tour; "Welcome tour" voor de welkomsttour, vertaald door IntroVox |
Events bubbelen vanaf het element:
| Event | Detail |
|---|---|
introvox:loaded |
{ tours, welcome }: de getoonde tours, en of de link van de welkomsttour er staat. tours leeg en welcome false: tours staan voor iedereen uit, er valt niets te starten, dus een host kan zijn eigen kader verbergen |
introvox:error |
{ message }: IntroVox staat niet aan voor deze gebruiker, of gaf geen antwoord |
De tagnaam, TourListEmbed met load() en isAvailable(), de klassenamen en de twee events zijn een vaste interface; tests-js/embed-contract.test.js faalt als een ervan verandert.
Tour-runtime¶
src/main.js (de bootstrap)¶
Bij DOMContentLoaded doet elke pagina dit:
- Bepaalt in wat voor frame hij zit (
frameKind()): een eigen pagina, de element-picker van de beheerder, het voorbeeld van de beheerder, of een same-origin-frame van iemand anders. De frame-namen tellen alleen binnen een same-origin-parent, zodat een andere website geen tabblad met zo'n naam kan openen om de tour tegen te houden. In het voorbeeld-frame zet hijwindow.introVoxPreviewklaar en stopt. - Definieert
window.introVoxmetstart()(laadt de chunk en start de welkomsttour met de hand),reset()(wist de localStorage-markeringen van de welkomsttour) enisCompleted(). WizardManager vervangt dit door zijn eigen versie zodra hij draait. - Haalt het
?introvox-tour=<id>van een deellink uit het adres (history.replaceState()), en houdt het alleen als het een tour-id is; heeft een app het adres al veranderd (Deck gaat naar Upcoming cards), dan gebruikt hij delinkdie de server bij de pagina las. Net zo?introvox-check=<id>, een eigen taak van de checklist op het Dashboard die vanuit de lijst geopend is: een eigen chunk (src/runtime/checklist.js) meldt die. - Roept
chooseTour()aan met wat de pagina al heeft: de lazy initial stateintrovox/runtimevanLoadScripts(zie Backend Architecture, in het Engels), de link, sessionStorage, localStorage en het pad. Daar is geen request voor nodig. - Haalt een start-verzoek weg zodra het gebruikt is, en laadt de tour-chunk alleen als er een tour gekozen is.
src/runtime/chooseTour.mjs¶
Gewone data erin, gewone data eruit, getest zonder browser (tests-js/choose-tour.test.js). De regels, op volgorde; de eerste die geldt, beslist:
- In de element-picker of een same-origin-frame van iemand anders: geen tour
- Een deellink start zijn tour op de pagina die hij opende (niet op de beheerpagina van IntroVox), ook boven een tour die bezig was: wie een link volgt, vraagt om die tour, en wie midden in een tour een pagina verlaat (door de link te typen bijvoorbeeld) laat een resume-entry achter, die de bootstrap dan wist
- Een tour die bezig is (een resume-entry, jonger dan 10 minuten) gaat verder op de pagina die zijn volgende stap opende, of na herladen op de pagina waar hij was (een entry met
staygaat alleen op die pagina verder,resumesHere(), zodat de tour niemand volgt die ergens anders heen ging); anders een start-verzoek uit de persoonlijke instellingen (jonger dan 2 minuten): de welkomsttour op de eerstvolgende pagina, een tour voor een app op zijn eigen pagina. Een link en een start met de hand werken ook als Start tours by themselves uit staat en buiten de datums van een tour; de server controleert nog steeds of de gebruiker de tour mag krijgen - Op de eigen beheerpagina van IntroVox: geen tour (daar draait de beheerderstour)
- Geen runtime-state op de pagina: de tour-code vraagt het de server, zoals vóór deze state bestond
- Tours for everyone uit, of Start tours by themselves uit: geen tour
- De welkomsttour gaat voor: tenzij hij in de lijst met tours uit staat of klaar is voor deze gebruiker (
wizard_disabled), draait hij als deze browser hem niet als voltooid heeft gemarkeerd, of bij een anderewizard_versiondan die van de server - Er is minder dan 2 minuten geleden een tour geëindigd in dit tabblad: geen tour, zodat er nooit twee tours vlak na elkaar draaien
- De eerste tour voor een app of pagina die hier aan de beurt is; een tour die overal start is op elke pagina aan de beurt. "Aan de beurt" bepaalt de server (
TourStateService::due()): beschikbaar, niet gezien bij deze versie, het publiek, en zijn tijd (TourSchedule)
Browser-opslag die hij leest:
| Key | Opslag | Betekenis |
|---|---|---|
introvox_completed, introvox_version |
localStorage | De welkomsttour is in deze browser afgerond, gesloten of overgeslagen, bij die wizard_version |
introvox_tour_resume |
sessionStorage | Een tour die bezig is en naar een andere pagina ging, of waarvan de pagina op een andere manier verlaten werd, zoals door herladen ({ tourId, stepId, at }, plus stay: de pagina waar hij was) |
introvox_start_tour |
sessionStorage | Een start met de hand uit de persoonlijke instellingen ({ tourId, page, at }; de welkomsttour heeft geen pagina) |
introvox_tour_ended |
sessionStorage | Wanneer er in dit tabblad voor het laatst een tour eindigde |
introvox_preview_resume |
sessionStorage | De eigen resume-entry van het voorbeeld van de beheerder |
src/runtime/tour.js¶
De ingang van de chunk: mount WizardManager met de keuze van de bootstrap (startTour()), voor een start met de hand (startManually()) of in voorbeeldmodus (mountPreview()). Hij importeert ook de CSS van Shepherd en css/wizard.css, zodat die met de chunk mee laden.
Kern-bestanden¶
src/components/WizardManager.vue¶
Beheert de Shepherd.js-tour:
- Krijgt de keuze van de bootstrap als prop
start: welke tour, en of hij verdergaat of met de hand gestart is - Welkomsttour: laadt
GET /api/steps, hangt gedrag aan de client-kant weer aan de stappen op id (enrichSteps()), terwijl hij op het app-menu wacht (en tot de eerste-start-wizard van Nextcloud dicht is), en start zodra er geen dialoog open is - Tour voor een app of pagina: laadt
GET /api/steps?tour=<id>(een 404 of geen stappen: er start niets), wacht tot de app klaar is (het element van de eerste stap of de inhoud van de app, geen dialoog van de app open, het tabblad in beeld; hoogstens 15 seconden), en stuurt danPOST /api/tours/{id}/eventmetstart. Hij toont de tour alleen als dit de eerste start bij deze versie was, of als de tour met de hand gestart is. De knop in de eerste stap is Skip in plaats van Skip and don't show again - Instantiëert
new Shepherd.Tour({...})en registreert Next/Back/Done/Skip-handlers - Welkomsttour: vuurt telemetrie-events via
axios.post('/api/wizard/...'), updatet localStorage bij close/complete/skip, en roeptPOST /personal/settingsaan metwizardDisabled: truebij Skip en Done - Tour voor een app: stuurt
completeofskipnaarPOST /api/tours/{id}/event; niets in localStorage - Elke tour, tijdens een run die vanzelf startte: elke stap verder dan deze run al kwam, gaat naar
POST /api/tours/{id}/reached(id van de stap en plek in de run), voor How far people get. Een start met de hand (window.introVox.start(), Start in de persoonlijke instellingen) en een voorbeeld tellen nooit; een app-tour telt alleen als zijnstartde eerste was. Of een run telt, gaat mee in de resume-entry als de tour van pagina wisselt
src/components/wizardSteps.js¶
Definities aan de client-kant van de ingebouwde stappen van de welkomsttour, gewrapped in t('introvox', ...), met wat de server niet kan opslaan: lazy attachTo, menu's die eerst open moeten, beforeShowPromise. Gebruikt:
- Door
enrichSteps(), die dat gedrag op id weer aanhangt aan de stappen dieGET /api/stepsteruggeeft - Als volledige terugval (
getWizardSteps()) als de server geen stappen stuurt of niet bereikbaar is
Tours voor een app of pagina gebruiken het niet.
Sinds v1.6.0 gebruiken alle 16 default-stap-titels en -teksten Engelse source-strings als Transifex-msgids in plaats van opaque step_welcome_title-achtige keys.
Media en tekst van een stap¶
StepMediaBlock.vue voegt de afbeelding, GIF of video van een stap toe via POST /admin/media of /admin/media/from-files en bewerkt het blok media van de stap. In de tour bouwt src/utils/stepMedia.js (buildStepMedia()) de afbeelding of video met DOM-API's uit dat blok, nooit via HTML, controleert het bestands-id opnieuw en laadt het bestand van GET /media/{file}; alles wat beweegt krijgt een pauzeknop en staat stil bij verminderde beweging. Zie Media in tour steps (in het Engels).
StepTextEditor.vue bewerkt de tekst van een stap met een TipTap-editor die beperkt is tot de tags die de tour toont (EDITOR_TAGS in src/admin/stepTextHtml.mjs, dezelfde allowlist als src/utils/stepHtml.js). Teksten worden nog steeds als HTML opgeslagen.
src/components/SupportSettings.vue¶
Het paneel Support: dat IntroVox vrij en open source is zonder limieten, links naar de andere apps, naar een issue melden en naar de broncode, en Show the admin tour again. De abonnementssleutel en de stap-tellers per taal die het vóór 1.7.7 had, zijn weg.
src/utils/deviceDetection.js (v1.6.0+)¶
OS-/browser-detectie gebruikt door de PWA-installatie-stap. Alle ~40 gebruikers-strings zijn gewrapped in t() (gefixt in v1.6.0 — voorheen waren ze hardcoded Nederlands).
State-management¶
IntroVox gebruikt geen Vuex of Pinia. Staat blijft lokaal per component:
- Of er een tour draait — per paginalading beslist door
chooseTour()uit de initial stateintrovox/runtimeen browser-opslag, voordat er tour-code laadt - Stap-lijst — eenmalig per pagina geladen via
GET /api/steps(met?tour=<id>voor een tour voor een app), gehouden in de reactive state vanWizardManager.vue - Admin-tours —
GET /admin/toursinuseTours.js, gebruikt doorAdminApp.vue; aan/uit, opnieuw tonen, verwijderen, exporteren en importeren gaan naar/admin/tours/… - Admin-stap-bewerking — lokale component-state in
TourEditor.vue, voor de tour die daarin open is; elke wijziging (opslaan in de editor, verwijderen, herordenen, aan/uit) wordt direct viaPOST /admin/stepsmet het id van die tour opgeslagen, na elkaar in een wachtrij zodat snelle wijzigingen nooit in de verkeerde volgorde aankomen - Gebruikers-voltooiings-staat — welkomsttour: browser-localStorage plus de server-voorkeur
wizard_disabled; tours voor een app: alleen op de server (tour_<id>_seen,_completed,_skipped); hoe ver een tour kwam:tour_<id>_reached; Start tours by themselves: de server-voorkeurtours_disabled - Taal-selectie (admin) — lokale staat; wisselen met niet-opgeslagen wijzigingen triggert een bevestigings-dialoog
Tour-engine: Shepherd.js¶
IntroVox wrapt Shepherd.js voor tour-rendering:
- Elke stap wordt geregistreerd als
tour.addStep({...}) - Element-markering (
.shepherd-target-click-disabled) wordt overschreven zodat gebruikers nog steeds op gemarkeerde elementen kunnen klikken - Custom styling overschrijft Shepherd's default-classes om Nextcloud's thema-variabelen te matchen (zie Thema-ondersteuning)
Bug-fixes gerelateerd aan Shepherd-integratie¶
- v1.6.1 —
.nextcloud-wizard-step[hidden] { display: none }toegevoegd om te voorkomen dat Shepherd-verborgen stappen zichtbaar stapelen achter de actieve stap (werd veroorzaakt door.nextcloud-wizard-step { display: flex }die de browser-default overschreef) - v1.5.0 —
max-heighten interne body-scrolling toegevoegd zodat lange mobiele stappen navigeerbaar blijven - v1.4.2 — fallback-CSS-selectors en 10s-timeout toegevoegd aan de app-menu-readiness-check
- 2.0.0 — een stap waarvan het element er nog niet is, wacht opzij in een hoek, laat de pagina bruikbaar en schuift naar het element zodra het verschijnt; dit verving de gecentreerde weergave van v1.4.1
- v1.4.1 — stappen met ontbrekende doel-elementen vielen terug op gecentreerde weergave in plaats van stil te worden overgeslagen
Build-configuratie¶
npm run build— productie-build (geminified, geen source-maps)npm run watch— watch-modus voor actieve ontwikkeling
Bundle-outputs gaan naar js/. De src/-directory is niet opgenomen in App-Store-tarballs — alleen gecompileerde assets.
Vertaal-flow¶
- Vue-componenten en JS gebruiken
t('introvox', '<Engelse bron>')uit@nextcloud/l10n python3 scripts/po2l10n.pyzettranslationfiles/<lang>/introvox.po(uittx pull) om naarl10n/<lang>.jsenl10n/<lang>.json, zoals de Transifex-bot van Nextcloud dat doet: Nextcloud laadt de.jsin de browser (OC.L10N.register) en de.jsonop de serverOCP\L10N\IFactory::getLanguages()levert display-namen voor de taal-picker (v1.6.0+)
Zie Transifex-integratie voor de volledige vertaal-workflow.
Zie ook¶
- Architectuur-overzicht
- Backend-architectuur
- Geleide tours — Shepherd-levenscyclus
- Thema-ondersteuning — CSS-variabele-overerving