Verwijder de voorbeeldgegevens in Joomla

De voorbeeldgegevens (sample data) van Joomla zijn nuttig voor uiteenlopende doeleinden, zoals testen, het demonstreren van functionaliteit en het voorbereiden van handleidingen. De standaard datasets die met Joomla worden meegeleverd zijn voor sommige toepassingen prima geschikt, maar niet voor allemaal. Bovendien zijn ze niet ontworpen om eenvoudig te worden verwijderd wanneer ze niet langer nodig zijn. In dit artikel beschrijf ik mijn persoonlijke aanpak voor het maken van verwijderbare voorbeeldgegevens.

Hiervoor zijn twee extensies nodig: een plugin en een module.

Ruim een jaar geleden deed Brian Teeman een voorstel: Inclusion of a Full Installable Example Website in Joomla 6, waarin een complete voorbeeldwebsite over A Travel Guide to Iceland zou worden opgenomen. Helaas is dit voorstel niet verder uitgewerkt en is de issue inmiddels gesloten.

De voorbeeldgegevens

Mijn doel was voorbeeldmateriaal te creëren dat gebruikt kan worden voor handleidingen en hulppagina's. De gegevens moesten:

• meertalig zijn;

• door gebruikers zelf kunnen worden aangemaakt.

Voor de ontwikkeling koos ik informatie over Schotse slagvelden, beschikbaar in zowel Engels als Schots-Gaelisch.

Dat lijkt misschien een merkwaardige keuze. De gegevens beperken zich echter tot een overzichtelijke historische periode, van 1296 (de Slag bij Dunbar I) tot 1746 (de Slag bij Culloden), waarvoor veel vrij beschikbare informatie bestaat. Ik heb bovendien veel van deze slagvelden zelf bezocht en enkele liggen zelfs dicht bij mijn woonplaats.

De keuze voor het Schots-Gaelisch werd ingegeven door een bezoek aan Carnasserie Castle, waar in 1567 het allereerste document in het Gaelic werd gedrukt. Hiervoor moest ik een taalpakket voor het Schots-Gaelisch ontwikkelen, maar dat is weer een heel ander verhaal. Ik spreek, lees of begrijp overigens geen woord Gaelic!
Het belangrijkste is dat het onderwerp volledig vervangbaar is. Je kunt de voorbeeldgegevens vervangen door elk gewenst onderwerp zonder de programmacode aan te passen.

Op het moment van schrijven werkt de beschreven code, maar deze is nog steeds een work in progress.

De plugin

De code van de plugin is beschikbaar op GitHub. Hier bespreek ik slechts enkele belangrijke onderdelen.

Structuur van de plugin

Onderstaande schermafbeelding toont een deel van de pluginstructuur zoals zichtbaar in VS Code.


Screenshot van de pluginstructuur in VS Code

De map en-gb bevat de voorbeeldgegevens in het Brits-Engels. De map gd-gb bevat dezelfde map- en bestandsstructuur, maar de vertaalbare inhoud is vervangen door Schots-Gaelische teksten.

Binnen iedere taalmap bevat de map articles de HTML-bestanden van de artikelen.

De afzonderlijke JSON-bestanden bevatten de specificaties van alle gegevens die moeten worden toegevoegd, zoals:

• artikelen;

• banners;

• categorieën;

• enzovoort.

De schermafbeelding toont bijvoorbeeld een deel van de specificaties voor de artikelen. Elke artikeldefinitie bevat een veld text_source, waarin wordt aangegeven waar het bijbehorende HTML-bestand zich bevindt.

Afbeeldingen worden afzonderlijk opgeslagen. De verwachting is dat foto's meestal taalonafhankelijk zijn, terwijl schermafbeeldingen juist per taal zullen verschillen.

Configuratie van de plugin

Na installatie moet de plugin worden ingeschakeld en geconfigureerd voor de gewenste talen.

Onderstaande schermafbeelding toont het configuratiescherm nadat de voorbeeldgegevens zijn geïnstalleerd.

Vóór de installatie, en opnieuw na het verwijderen van de voorbeeldgegevens, zijn alle velden leeg, behalve de specificatie van de beschikbare talen.

Screenshot van de pluginconfiguratie

De meeste waarden in de verschillende velden zijn de ID-nummers van de geïnstalleerde voorbeeldgegevens. De lege velden zijn gereserveerd voor toekomstige uitbreidingen.

De code van de plugin

Ik ga de plugincode hier niet in detail bespreken. De code bestaat uit ongeveer 3.000 regels en is grotendeels gebaseerd op de bestaande plugins voor voorbeeldgegevens die al in Joomla aanwezig zijn.

Mijn versie bevat aanzienlijk meer stappen, waarbij deze tijdens het verwijderen van de voorbeeldgegevens in omgekeerde volgorde worden uitgevoerd.

Er is één bijzondere voorziening die ik noodzakelijk vond: een controle of een stap al succesvol is uitgevoerd.

Dit blijkt vooral handig wanneer de gebruiker foutieve invoer heeft opgegeven. Nadat de invoer is gecorrigeerd, hoeft niet eerst alles handmatig ongedaan te worden gemaakt voordat de installatie opnieuw kan worden gestart.

De module

De plugin werkt niet zonder de Demodata-module.

Deze module bevat de JavaScript-code die nodig is om iedere stap van het installatie- en verwijderproces van de voorbeeldgegevens uit te voeren.

Na installatie moet de module worden toegewezen aan de positie cPanel, zodat deze zichtbaar wordt op het Home Dashboard.

Screenshot van de Demodata-module

 

Installatie van de voorbeeldgegevens

Een schone Joomla 6-installatie bevat standaard:

• geen artikelen;

• geen categorieën, behalve Uncategorized;

• geen banners;

• geen menu's of menu-items, behalve de standaarditems;

• enzovoort.

Klik op de knop Demonstration Data Install en na ongeveer vijf seconden zijn nieuwe gebruikers, artikelen, banners en andere voorbeeldgegevens toegevoegd.

Het verwijderen van de voorbeeldgegevens verloopt aanzienlijk sneller.

Onderstaande schermafbeelding toont de lijst met artikelen.

Standaard wordt deze lijst aflopend op ID gesorteerd. Omdat de Gaelische artikelen als laatste zijn geïnstalleerd, staan deze bovenaan.

Voor schermafbeeldingen stel ik de lijstweergave meestal in op maximaal vijf items.

Lijst met voorbeeldartikelen

 

Hieronder is een afzonderlijk artikel zichtbaar in de frontend.

Dit voorbeeld laat zien hoe categorieën, aangepaste velden, menu's en banners gezamenlijk worden gebruikt.


Artikel over de Slag bij Roslin

Conclusie

De Schotse geschiedenis biedt een schat aan materiaal voor populaire cultuur.

Zo speelt de Slag bij Stirling Bridge een belangrijke rol in Braveheart (1995), met Mel Gibson in de hoofdrol.

Ook de Slag bij Roslin (hierboven) vond plaats vlak bij Rosslyn Chapel, de locatie van het slot van The Da Vinci Code (2006), gebaseerd op de roman van Dan Brown en met Tom Hanks in de hoofdrol.

Dat biedt volop mogelijkheden om gebruik te maken van tags en aangepaste velden.

Op de schermafbeelding van de artikelenlijst is bovendien te zien dat ik de verwijderbare voorbeeldgegevens inmiddels test onder Joomla 7.0.0-alpha1-dev.

Dat komt doordat ik graag vooruitkijk, ook al word ik morgen tachtig jaar.

Voorlopig heb ik nog genoeg andere projecten om aan te werken. Voel je vrij om de code uit te proberen of een universeler onderwerp voor voorbeeldgegevens te bedenken.