Joomla! code, HTMLHelper voor het laden van media bestanden

Als je zelf extensies bouwt, is de HTMLHelper een tool die je veel werk kan besparen. De HTMLHelper is een hulpbestand in Joomla dat het onder andere makkelijk maakt om mediabestanden zoals JavaScript en CSS te laden. Er kan nog veel meer mee maar in dit verhaal blijven we bij mediabestanden.

Bij mediabestanden kun je denken aan CSS, JavaScript en afbeeldingen. Vandaag de dag is er nagenoeg geen website meer die niet van één van deze onderdelen gebruik maakt. Wat nog veel voorkomt bij zelfgebouwde extensies is dat we zelf deze bestanden gaan inladen in plaats van deze taak over te laten aan Joomla. Dat is best wel gek omdat Joomla hier goede ondersteuning voor biedt.

We maken in de voorbeelden gebruik van de extensie com_foo. Die bestaat natuurlijk niet; binnen het programmeren wordt “foo” vaak als voorbeeld gebruikt. Vervang com_foo dus door de naam van je eigen extensie.

CSS

Het laden van CSS zonder Joomla ziet er vaak zo uit:

<link href="/media/com_foo/css/notify.min.css" rel="stylesheet" />

Je zou toch zeggen: dat ziet er goed uit. Dat ziet het ook wel maar toch kan het beter. Wat we bijvoorbeeld missen is een versienummer. Hiermee wordt het makkelijker voor de browser om te weten welk bestand het is en of het in de cache staat. Je moet bij bovenstaande regel ook precies weten welk pad het is. We kijken nu eens naar de Joomla manier:

\Joomla\CMS\HTML\HTMLHelper::stylesheet('com_foo/notify.min.css', ['version' => 'auto', 'relative' => true]);

Dit stuk code breken we op in een paar stukken:

• \Joomla\CMS\HTML\HTMLHelper
• stylesheet
• com_foo/notify.min.css
• ['version' => 'auto', 'relative' => true]

HTMLHelper

De HTMLHelper is een Joomla helper die allerlei HTML zaken kan regelen. Het stuk code hierboven geeft Joomla al een hoop informatie.

Stylesheet

Hiermee geven we aan dat het om een CSS bestand gaat.

com_foo/notify.min.css

Dit is de locatie van het CSS bestand. In plaats van het hele pad uit te schrijven kan er met HTMLHelper volstaan worden door alleen maar aan te geven om welke extensie het gaat en wat de naam van het bestand is. Joomla vogelt zelf uit wat het volledige pad is.

['version' => 'auto', 'relative' => true]

Dit bestaat uit 2 onderdelen, namelijk de versie en het relatieve pad. Door hier op te geven dat versiebeheer automatisch is zal Joomla achter de bestandsnaam een code plakken, zoals bijvoorbeeld ?bed16ef69496696827df9134e02d31f9. Wijzigt de versie van Joomla, dan krijg je een andere code. Dit vertelt de browser: let op, er is een nieuw bestand. De browser zal het bestand dan opnieuw downloaden. Gebruikers krijgen dan meteen de aanpassingen te zien en hoeven niet te wachten tot de cache tijd verlopen is.

Het relatieve pad vertelt Joomla dat het niet naar de locatie com_foo/notify.min.css moet kijken maar in de map media/com_foo/css/notify.min.css. Automagisch plakt Joomla de juiste mappen er tussen.

notify.min.css en notify.css

Het is gangbaar om geminimaliseerde bestanden de extensie .min mee te geven. Daardoor weet je dat dit een bestand is dat niet normaal gelezen kan worden.

Als je aan het testen bent wil je wel graag een leesbaar bestand zien. Je kunt de code aanpassen door te zeggen: nu moet je notify.css laden en niet notify.min.css. Dat is omslachtig en er zal zeker een keer vergeten worden om dit terug te zetten. Daar komt de HTMLHelper ook van pas. Als je in Joomla de debug modus aanzet, zal Joomla kijken of het bestand notify-uncompressed.css bestaat, zo niet dan wordt het bestand notify.css genomen. Automatisch wordt dit bestand dan geladen en niet notify.min.css. Dat maakt ontwikkeling een stuk makkelijker.

JavaScript

Bij JavaScript is het verhaal zoals bij CSS eigenlijk hetzelfde, alleen vervangen we 2 zaken:

• Het type bestand dat geladen wordt
• De bestandsnaam die geladen wordt

Zoals in het voorbeeld bij het CSS bestand, ziet het JavaScript bestand er standaard zo uit:

<script src="/media/com_foo/js/notify.min.js"></script>

Met de HTMLHelper ziet het er zo uit:

\Joomla\CMS\HTML\HTMLHelper::script('com_foo/notify.min.js', ['version' => 'auto', 'relative' => true]);

Hierbij is stylesheet vervangen door script en .css vervangen door .js.

Hiermee is het laden van zowel CSS als Javascript bestanden uniform en dat biedt veel meer mogelijkheden dan op de traditionele manier.

Afbeeldingen

Als laatste hebben we nog de afbeeldingen, dit gaat net als CSS en JavaScript met de HTMLHelper. Een afbeelding in HTML opmaak ziet er zo uit:

<img src="/media/com_foo/images/notify.png" alt="Notification" />

De opbouw van het HTMLHelper commando is iets anders:

\Joomla\CMS\HTML\HTMLHelper::image('com_foo/notify.png', 'Notification', 'class="image"', true));

Laten we deze code ook opbreken in een paar stukken:

• \Joomla\CMS\HTML\HTMLHelper
• image
• com_foo/notify.png
• Notification
• class="image"
• true

HTMLHelper

Dit is de inmiddels bekende HTMLHelper.

Image

Hiermee geven we aan dat het om een afbeelding gaat.

com_foo/notify.png

Net als bij het CSS en JavaScript bestand, is dit de locatie van de afbeelding.

Notification

Dit is de alt tag van de afbeelding, die wordt gebruikt voor gebruikers die hulpmiddelen gebruiken om de website te zien.

class="image"

Dit is een attribuut dat we meegeven aan de afbeelding. In dit voorbeeld gebruiken we een class, maar het mogen ook andere attributen zijn. Denk hierbij aan een data attribuut zoals data-type="image". Meerdere attributen kunnen achter elkaar gezet worden. Indien er geen attributen zijn om mee te geven zet dan het woord null zodat Joomla weet dat er geen attributen zijn.

True

Hiermee geven we aan dat de afbeelding relatief is. Net als bij de CSS en JavaScript bestanden zal Joomla de afbeelding dan in de media map zoeken.

Het uiteindelijke pad wordt dan media/com_foo/images/notify.png

HTMLHelper afkorting

In de voorbeelden komt iedere keer de volledige naam van de HTMLHelper voorbij, namelijk \Joomla\CMS\HTML\HTMLHelper. Het is niet nodig om altijd de volledige naam te gebruiken. Om het makkelijker te maken kunnen we het volgende doen. Bovenaan het bestand zetten we:

use \Joomla\CMS\HTML\HTMLHelper;

Nu kunnen we HTMLHelper gebruiken in plaats van de volledige naam.

Conclusie

De HTMLHelper is een handig hulpbestand met veel mogelijkheden. We hebben nu drie  mogelijkheden bekeken maar er zijn er veel meer. Denk hierbij aan:

• HTMLHelper::calendar()
• HTMLHelper::iframe()
• HTMLHelper::date()
• HTMLHelper::link()
• en nog veel meer.

Je weet nu wat de beste manier is om CSS, JavaScript en afbeeldingen in te laden in jouw eigen extensie(s). Door deze standaard te volgen kunnen ook andere extensies overweg met jouw bestanden.