Guided Tours in Joomla

2. Anatomie van een tour en een stap

Voordat je iets bouwt, helpt het om elk veld te kennen, want elk veld komt rechtstreeks overeen met een databasekolom die je later kunt tegenkomen.

2.1 De velden van een tour

2.2 De velden van een stap

Een stap hoort altijd bij een tour via zijn tour_id, en zijn plek in de reeks komt uit de waarde ordering die je instelt door rijen te slepen in de stappenlijst.

4. Staptypes en interactieve stappen

Elke stap heeft een type dat bepaalt hoe de gebruiker verdergaat. Joomla slaat dit op als een klein geheel getal, en de drie waarden liggen vast in het onderdeel.

4.1 De drie staptypes

Gebruik Next voor "kijk hier"-stappen. Gebruik Redirect wanneer een tour meer dan een scherm beslaat, bijvoorbeeld van de artikellijst naar het bewerkscherm van een artikel. Gebruik Interactive wanneer je een hands-on tutorial wilt waarin de gebruiker zelf typt, klikt of iets selecteert.

4.2 De interactieve types

Wanneer een stap interactief is, geeft een tweede veld, Interactief type, precies aan wat de gebruiker moet doen. Joomla definieert er zes:

Voor een Text Field- of Select-stap kun je in de parameters van de stap een vereiste waarde instellen. De tour wacht dan tot de gebruiker precies die waarde invoert of selecteert voordat de knop Volgende ontgrendelt. Zo kan een tour iemand begeleiden bij het correct invullen van een formulier, niet alleen erover laten lezen.

6. Autostart en gebruikersstatus

Tours kunnen vanzelf starten, maar slechts een keer. Joomla onthoudt wat elke gebruiker deed, zodat een tour niet eindeloos blijft zeuren. Dit is het lastigste deel van de functie, dus het loont om het te begrijpen.

6.1 De autostart-vlag

Als een tour Autostart aan heeft, zoekt Joomla ernaar wanneer de gebruiker het bijbehorende scherm bereikt. Als de gebruiker hem nog niet heeft gezien, start hij automatisch. Er is ook een globale schakelaar onder Gebruikers → Guided Tours → Options met de naam Allow Tour Auto Start; zet die uit en geen enkele tour start nog automatisch, ongeacht de vlag per tour.

6.2 De drie statussen

Wanneer een gebruiker een automatisch startende tour afrondt of stopt, slaat Joomla een van drie statussen op in zijn gebruikersprofiel:

Het "tijdje" voor een uitgestelde tour komt uit de optie Delayed Time, die standaard 60 minuten is. Na die periode kan de tour weer automatisch starten, wat handig is voor een gebruiker die hem sloot omdat hij druk was, niet omdat hij klaar was.

6.3 Waar de status wordt bewaard

De status wordt per gebruiker opgeslagen in de tabel #__user_profiles, onder een sleutel zoals guidedtour.id.5 voor de tour met id 5. Omdat het bij de gebruiker hoort, valt een tour die jij hebt voltooid je niet meer lastig, maar ziet een gloednieuwe redacteur hem alsnog vers. Wil je autostart herhaaldelijk testen, verwijder dan die profielrij voor je account, of test met een andere gebruiker.

8. Onder de motorkap (ontwikkelaarsblik)

Nu de technische laag. Guided Tours is een mooi voorbeeld van een modern Joomla-onderdeel plus een systeemplugin, en het is klein genoeg om op een middag door te lezen.

8.1 De twee tabellen

Alles zit in twee databasetabellen:

#__guidedtours        een rij per tour
#__guidedtour_steps   een rij per stap, gekoppeld via tour_id

De belangrijkste kolommen van #__guidedtours:

id           primaire sleutel
title        titel van de tour (of een taalsleutel)
uid          unieke tekst-identifier, bv. joomla-guidedtours
description  HTML van de intro-pop-over (of een taalsleutel)
url          relatieve URL van de pagina waarop de tour draait
extensions   JSON-lijst van onderdelen, bv. ["com_content"]
autostart    0 of 1
access       toegangsniveau voor weergave
language     taalcode of *
published    publicatiestatus

De belangrijkste kolommen van #__guidedtour_steps:

id                primaire sleutel
tour_id           de bovenliggende tour
title             kop van de pop-over
description       body-HTML van de pop-over
position          top / bottom / left / right / center
target            CSS-selector van het gemarkeerde element
type              0 = next, 1 = redirect, 2 = interactive
interactive_type  1..6 (alleen bij type = 2)
url               redirect-doel (alleen bij type = 1)
ordering          volgorde van de stap binnen de tour
params            JSON, bv. {"required":1,"requiredvalue":"Hello"}
language          taalcode of *

8.2 De systeemplugin en Shepherd.js

Het zichtbare deel van een tour komt volledig uit de plugin System - Guided Tours in plugins/system/guidedtours/. Die doet twee taken via geabonneerde events:

Het tekenen zelf gebruikt Shepherd.js, meegeleverd onder media/vendor/shepherdjs/ en ingepakt door media/plg_system_guidedtours/js/guidedtours.js. Shepherd tekent de pop-over, dimt de rest van de pagina en plaatst de markering over het target-element. Wanneer de plugin een tour verwerkt, zet hij de integer-types om naar de strings die Shepherd begrijpt, bijvoorbeeld staptype 2 wordt interactive en interactief type 6 wordt select.

8.3 Status opslaan via AJAX

Wanneer de gebruiker een automatisch startende tour voltooit, annuleert of overslaat, roept de browser de taak AjaxController::fetchUserState() van het onderdeel aan met drie waarden: tid (tour-id), sid (stapnummer) en context (een van tour.complete, tour.cancel, tour.skip). De controller zet de context om naar een status (completed, delayed of skipped) en slaat die op, maar alleen voor tours die daadwerkelijk automatisch starten.

Rond dat opslaan worden twee events afgevuurd waar eigen plugins naar kunnen luisteren:

onBeforeTourSaveUserState   vuurt af voordat de status wordt geschreven
onAfterTourSaveUserState    vuurt af daarna en kan het antwoordbericht overschrijven

Dit is de hook die je zou gebruiken om bijvoorbeeld het voltooien van een tour naar je eigen analytics te loggen, of om een badge toe te kennen wanneer een gebruiker een onboarding-tour afrondt.

8.4 Tours meeleveren met je extensie

Omdat een tour gewoon rijen in twee tabellen is, kan een extensie-ontwikkelaar kant-en-klare tours meeleveren in een extensiepakket. De gebruiker installeert je onderdeel, module of plugin, en de tours verschijnen zonder handmatige instellingen. Er zijn twee gangbare manieren om dit te doen.

De eerste is een install-SQL-script. Joomla draait bij de installatie de SQL-bestanden die in je manifest staan, dus daar zet je de inserts:

INSERT INTO `#__guidedtours`
  (`title`, `uid`, `description`, `url`, `extensions`,
   `autostart`, `access`, `language`, `published`)
VALUES
  ('COM_MYEXT_TOUR_INTRO_TITLE', 'mycompany-myext-intro',
   'COM_MYEXT_TOUR_INTRO_DESC',
   'index.php?option=com_myext&view=items',
   '["com_myext"]', 1, 1, '*', 1);

INSERT INTO `#__guidedtour_steps`
  (`tour_id`, `title`, `description`, `target`, `position`,
   `type`, `ordering`, `language`, `published`)
VALUES
  (LAST_INSERT_ID(), 'COM_MYEXT_TOUR_INTRO_STEP1_TITLE',
   'COM_MYEXT_TOUR_INTRO_STEP1_DESC', '#toolbar-new', 'bottom',
   0, 1, '*', 1);

Let op twee dingen die de tour schoon houden. De waarde extensions is een JSON-array, dus die moet geldige JSON zijn binnen de SQL-string. En de velden title en description bevatten taalsleutels, geen letterlijke tekst, zodat je dezelfde tour vertaald in meerdere talen kunt leveren (zie hoofdstuk 7.3). Lever de bijpassende strings in de taalbestanden van je extensie.

De tweede manier is een installer-script. Heb je logica nodig, bijvoorbeeld om dubbele inserts bij herinstallatie te voorkomen of om bestaande tours bij een upgrade bij te werken, zet het werk dan in de methoden install, update en postflight van je script.php in plaats van in platte SQL. Daar kun je com_guidedtours booten en zijn model gebruiken, dat ook de UID- en validatielogica van de tabel voor je uitvoert:

$factory = Factory::getApplication()
    ->bootComponent('com_guidedtours')
    ->getMVCFactory();

$model = $factory->createModel('Tour', 'Administrator', ['ignore_request' => true]);
$model->save([ /* tour-velden, zoals in hoofdstuk 9 */ ]);

Welke route je ook kiest, geef elke meegeleverde tour een onderscheidende uid (bijvoorbeeld mycompany-myext-intro) zodat hij nooit botst met kerntours of de tours van een andere extensie, en zodat je update-script hem later kan terugvinden en verversen.

10. SEO en vindbaarheid

Guided Tours is een onboarding-tool voor de backend, geen publieke inhoud, dus het heeft geen directe SEO-voetafdruk. Een tour verschijnt nooit in je sitemap, wordt nooit door Google geindexeerd en levert geen publieke URL op. Verwacht niet dat je ergens op scoort omdat je tours hebt gebouwd.

Het beinvloedt wel een ander soort vindbaarheid, de soort die binnen je eigen admin telt:

• Goede tours maken functies vindbaar voor je klanten, wat supportvragen vermindert.
• Het veld URL van de tour is het dichtst bij routing: het bepaalt bij welk scherm een tour hoort, dus stel het nauwkeurig in.
• Bouw je een frontend-tour (stel de extensies breed in en richt je op frontend-elementen), houd de pop-overtekst dan kort; lange pop-overs schaden de ervaring op mobiel.

Kortom, zie Guided Tours als interne documentatie die staat waar het werk gebeurt, niet als een marketing- of zoekmiddel.

12. Best practices

Als je maar een paar dingen uit dit artikel onthoudt, onthoud dan deze:

• Houd tours kort: vijf tot acht stappen winnen het van een marathon van twintig.
• Richt je op een id of stabiele class, nooit op fragiele diepe selectors die bij een upgrade breken.
• Stel altijd de URL en Extensies van de tour in zodat de tour alleen verschijnt waar hij hoort.
• Gebruik Autostart spaarzaam, en alleen voor echte eerste-keer-onboarding.
• Test autostart met een nieuwe gebruiker, want je eigen profiel onthoudt voltooide tours.
• Controleer je tours opnieuw na elke Joomla-update, want adminmarkup kan verschuiven.
• Gebruik toegangsniveaus om redacteuren en beheerders op dezelfde site verschillende tours te geven.

14. Samenvatting

Guided Tours maakt van Joomla een zelfonderwijzend CMS. Met niets meer dan de backend kun je interactieve onboarding bouwen die de juiste knoppen markeert, de juiste velden uitlegt en zelfs wacht tot gebruikers een actie uitvoeren voordat het verdergaat.

De essentie om mee te nemen:

• Een tour is een container; zijn stappen zijn pop-overs, en beide zijn gewoon databaserijen die je in de admin bewerkt.
• Stappen komen in drie types (Next, Redirect, Interactive) met zes interactieve varianten voor hands-on tutorials.
• Targets zijn CSS-selectors; stabiele id's maken betrouwbare tours.
• Autostart plus de status per gebruiker in #__user_profiles betekent dat een tour nieuwe gebruikers een keer begroet zonder te blijven zeuren.
• Het geheel wordt getekend door de plugin System - Guided Tours met Shepherd.js, en er is geen publieke REST API.

Goed gebouwd kan een handvol korte tours stil de meest voorkomende "hoe doe ik…"-vragen van je klanten wegnemen. Wil je geleide onboarding over een Joomla-site uitrollen, of heb je tours die na een upgrade kapot gingen en een vaste hand nodig hebben om de selectors te herstellen, dan loont het om iemand te hebben die weet waar elk van deze onderdelen zit.