Een Hyvä-childthema op de juiste manier bouwen

Bijna elke Hyvä-webshop begint met dezelfde beslissing: het standaardthema direct aanpassen, of er een childthema bovenop bouwen. Het antwoord is altijd een childthema. Hoe je het bouwt, bepaalt of Hyvä-updates een middag of een week kosten.

Deze gids legt uit hoe we Hyvä-childthema's opzetten voor klantwebshops en voor onze eigen demowebshop. Hij behandelt de bestanden die je nodig hebt, wat je overschrijft, wat je met rust laat en de fouten die we het vaakst zien bij webshops die bij ons komen voor een Hyvä-project.

Waarom een childthema, en geen kopie

Hyvä levert zijn standaardthema als Composer-package. Als Hyvä een fix of verbetering uitbrengt, werkt Composer dat package in de vendor-map bij.

Pas je die bestanden direct aan, dan verdwijnen je wijzigingen bij de volgende update. Kopieer je het hele thema naar je eigen map, dan houd je je wijzigingen, maar mis je elke toekomstige verbetering, omdat niets meer van het origineel erft.

Een childthema zit daartussenin. De theme fallback van Magento kijkt eerst in jouw thema en valt voor alles wat je niet hebt overschreven terug op het parent theme. Jij beheert je eigen afwijkingen, Hyvä blijft de rest beheren.

• Updates van het parent theme komen automatisch in je webshop terecht.
• Je diff blijft klein, dus een update beoordelen gaat snel.
• Developers zien in één oogopslag wat maatwerk is en wat standaard.

De minimale bestanden

Een Hyvä-childthema is een normaal Magento 2-thema. Het staat in app/design/frontend/Vendor/theme en heeft twee kleine bestanden nodig om zich te registreren.

Het eerste is theme.xml, waarin de parent staat:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Vendor Default</title>
    <parent>Hyva/default</parent>
</theme>

Het tweede is registration.php:

<?php
use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::THEME,
    'frontend/Vendor/default',
    __DIR__
);

Daarna volgt de map web/tailwind . De documentatie van Hyvä zegt dat je die uit het parent theme moet kopiëren, omdat elk thema zijn eigen stylesheet bouwt. Deze map bevat de Tailwind-configuratie, de bron-CSS en de package.json met de buildscripts.

Voer daarna bin/magento setup:upgradeuit, wijs het thema toe aan je store view onder Content > Design > Configuration en build de CSS één keer. Je hebt nu een werkend childthema dat er precies zo uitziet als Hyvä default.

Overschrijf zo weinig mogelijk

Het probleem dat we het vaakst zien, is een childthema dat de helft van de parent bevat. Iemand moest één regel in de header aanpassen en kopieerde daarom de hele Magento_Theme -templatemap. Twee jaar later weet niemand meer welke van die bestanden echt zijn gewijzigd.

Onze regel is simpel: één overschreven template betekent één gekopieerd bestand. Voordat we een template kopiëren, kijken we of een kleinere wijziging volstaat.

1. Eerst layout-XML. Blokken verplaatsen, verwijderen of toevoegen is een layoutwijziging, geen templatewijziging. Een default.xml of paginaspecifiek layoutbestand in je thema kan het meeste hiervan doen zonder ook maar één .phtml -bestand aan te raken.
2. Daarna Tailwind-classes. Veel visuele wijzigingen zijn gewoon andere kleuren, witruimte of lettertypes. Die horen in de Tailwind-configuratie, niet in gekopieerde templates.
3. Als laatste een template-override. Moet de markup zelf veranderen, kopieer dan alleen die ene template naar hetzelfde pad in je thema en pas haar daar aan.

Als we toch een template kopiëren, zetten we bovenaan een kort commentaar met wat er is gewijzigd en waarom. Dat kost tien seconden en scheelt veel giswerk bij de volgende update.

Laat Tailwind naar de parent blijven kijken

Tailwind genereert alleen CSS voor classes die het in je bronbestanden vindt. Daarom zijn Hyvä-stylesheets klein: ongebruikte utilities komen nooit in de build terecht.

De keerzijde is dat Tailwind elke template moet scannen die je webshop rendert. Dat zijn de templates in je childthema én de templates die nog uit het parent theme in de vendor-map komen. De Tailwind-configuratie die je van Hyvä hebt gekopieerd, wijst al naar het parent theme, en dat pad moet je behouden als je haar aanpast.

Hyvä-compatibele modules kunnen ook hun eigen templates en Tailwind-bronnen meebrengen. Hyvä biedt daarvoor een commando, bin/magento hyva:config:generate, dat een lijst van die modulepaden wegschrijft zodat de build ze oppikt. Voer het uit telkens als je een Hyvä-compatibele module toevoegt of verwijdert.

Werkt een class in development maar verdwijnt ze in productie, dan is een ontbrekend content path meestal de oorzaak. We leggen de volledige build uit in ons artikel over Tailwind design tokens en de build-pipeline.

Vertalingen, assets en thema-instellingen

Nog een paar dingen horen in het childthema en worden makkelijk vergeten.

• Vertalingen. Teksten op themaniveau horen in i18n/de_DE.csv en vergelijkbare bestanden in je thema. Formuleringen per store view waren een van de valkuilen die we tegenkwamen in onze meertalige demowebshop, dus test elke store view, niet alleen de standaard.
• Afbeeldingen en lettertypes. Thema-afbeeldingen, zoals tegels op de homepage, horen in de web -map van het thema. In onze demowebshop zijn ze WebP, 720 pixels breed en gecomprimeerd op ongeveer kwaliteit 72.
• Kleuren die je team misschien wil aanpassen. We maken header- en merkkleuren beschikbaar in Stores > Configuration, zodat een marketingteam ze zonder developer kan aanpassen. De Tailwind-tokens worden bij de deploy opnieuw opgebouwd uit config- en themabestanden.

Over lettertypes nog een korte opmerking. Eén lettertypefamilie met een klein aantal gewichten zelf hosten is meestal lichter dan er meerdere laden via een externe dienst.

Build de CSS bij elke deploy

De gecompileerde stylesheet is een build-artefact. Die moet tijdens de deployment worden gegenereerd, niet met de hand worden aangepast en niet worden gecommit nadat iemand een build op een laptop heeft gedraaid.

Een typische deploystap ziet er zo uit:

bin/magento hyva:config:generate
npm --prefix app/design/frontend/Vendor/default/web/tailwind ci
npm --prefix app/design/frontend/Vendor/default/web/tailwind run build-prod
bin/magento setup:static-content:deploy -f en_GB de_DE

De exacte naam van het buildscript hangt af van je Hyvä-versie, dus controleer de package.json in je thema. Op onze eigen stack draaien we Magento in production mode met static content deploy, dus de CSS-build draait altijd voordat de statische content wordt gegenereerd.

Veelgemaakte fouten die we herstellen

Dit zijn de problemen die we het vaakst tegenkomen als we een bestaande Hyvä-webshop beoordelen.

De derde rij is het belangrijkst voor de snelheid. Eén oude extensie die haar Luma-JavaScript laadt, kan veel van de winst van Hyvä tenietdoen. Daarom controleren we elke extensie vóór een migratie.

Veelgestelde vragen

Kan ik meer dan één childthema hebben?

Ja. Magento ondersteunt ketens van thema's, dus je kunt een basis-childthema hebben voor gedeeld werk en daarbovenop een tweede thema per merk of store view. Houd de keten kort, want elk niveau maakt debuggen net wat lastiger.

Moet ik beginnen met Hyvä default of met Hyvä UI?

Hyvä default is altijd het parent theme. Hyvä UI is een bibliotheek met kant-en-klare componenten die je naar behoefte in je thema kopieert. Beide aanpakken eindigen op dezelfde plek: een childthema van Hyva/default met je eigen templates.

Heb ik een childthema nodig als ik alleen kleuren aanpas?

Ja. Ook kleine wijzigingen hebben een plek nodig die updates overleeft. Een childthema met alleen een Tailwind-configuratie en geen templates is volkomen geldig, en het is het makkelijkst te onderhouden.

Wil je een Hyvä-thema dat makkelijk te updaten blijft? Bekijk hoe we werken op onze pagina over Hyvä-thema-ontwikkeling, of neem contact op om over je webshop te praten.