Thème Joomla Websource SEO — référence développeur

Vue d'ensemble

• Template de site websource (templates/websource, média dans media/templates/site/websource), déclaré inheritable : les templates enfants sont pris en charge, toutes les ressources se résolvent d'abord dans l'enfant puis dans le parent.
• Classes dans src/, espace de noms Websource\Template, chargées par src/autoload.php (JLoader::registerNamespace, pas de Composer).
• CSS : Tailwind v4 compilé en fichiers statiques. theme.css (socle) est chargé partout, plus une seule feuille pages/<type>.css selon le type de page. Aucun CSS n'est généré à l'exécution.
• JavaScript sans jQuery : theme.js (recherche mobile, menu push et filtres push, compteur du panier), product.js (détails de la fiche).
• HikaShop est facultatif. Toutes les méthodes de Websource\Template\Shop répondent sans erreur quand il est absent.
• Les feuilles de style du template sont placées après celles que les extensions ajoutent par Document::addStyleSheet() (HikaShop le fait) : à spécificité égale, le template l'emporte.

Types de page

Websource\Template\Theme::pageType() renvoie l'un de : home, shop, product, cart, checkout, account, blog, post, page, search, 404. La valeur donne la classe wsx-page-<type> de <body> et la feuille de style chargée.

Positions de modules

24 positions : banner, topbar-left, topbar-right, header-search, header-actions, header-menu, drawer, wrapper-top, breadcrumbs, home, shop-sidebar, sidebar, product-reassurance, product-footer, cart-footer, wrapper-bottom, footer-before, footer-1, footer-2, footer-3, footer-after, debug, error-404, error-403.

Habillages de module (html/layouts/chromes) : websource (titre + contenu, sans cadre) et card (carte arrondie).

Dispositions de module livrées :

Variables CSS

Les variables sont déclarées sur :root dans theme.css. Les réglages du template et l'évènement onWebsourceTemplateTokens ajoutent une règle :root{…} en ligne qui ne contient que les valeurs modifiées.

Alias courts, à utiliser dans une extension avec une valeur de repli : --wst-brand, --wst-brand-light, --wst-brand-dark, --wst-brand-soft, --wst-brand-on, --wst-secondary, --wst-accent, --wst-highlight, --wst-ink, --wst-line, --wst-page, --wst-surface, --wst-footer, --wst-footer-ink, --wst-radius, --wst-radius-lg, --wst-font, --wst-font-head, --wst-container.

.mon-module { border: 1px solid var(--wst-line, #d9e6e4); border-radius: var(--wst-radius, 1rem); color: var(--wst-ink, #14282b); }

Évènements

Le template déclenche des évènements Joomla\Event\Event sur le répartiteur de l'application. Un plugin les écoute et modifie les arguments avec setArgument().

Un plugin doit implémenter Joomla\Event\SubscriberInterface. Avec un plugin à l'ancienne (méthodes on… sans SubscriberInterface), Joomla ne transmet l'évènement que si la méthode a un seul paramètre nommé $event et typé Joomla\Event\EventInterface ; sinon elle reçoit des copies des arguments et ne peut rien modifier.

namespace Acme\Plugin\System\Boutique\Extension;

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\EventInterface;
use Joomla\Event\SubscriberInterface;

final class Boutique extends CMSPlugin implements SubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return ['onWebsourceTemplateTokens' => 'tokens', 'onWebsourceTemplateSettings' => 'settings'];
    }

    public function tokens(EventInterface $event): void
    {
        $tokens = $event->getArgument('tokens');
        $tokens['--wst-brand'] = '#b45309';   // reconstruit toute l'échelle --color-brand-*
        $tokens['--radius-xl'] = '.5rem';
        $event->setArgument('tokens', $tokens);
    }

    public function settings(EventInterface $event): void
    {
        $settings = $event->getArgument('settings');
        $settings['footer_style'] = 'light';
        $event->setArgument('settings', $settings);
    }
}

Fonctions publiques

Charger les classes depuis un module ou une surcharge :

require_once JPATH_THEMES . '/websource/src/autoload.php';

use Websource\Template\Shop;
use Websource\Template\Theme;

Point d'entrée AJAX

Le template n'ajoute pas de route d'API. Il expose une méthode par com_ajax.

Exemple de requête :

curl -b cookies.txt 'https://exemple.test/index.php?option=com_ajax&template=websource&method=cart&format=json'

Exemple de réponse :

{"success":true,"message":null,"messages":null,"data":{"items_count":2}}

theme.js appelle cette adresse après les évènements HikaShop cart.updated, checkout.cart.updated, cart.empty et wishlist.updated, puis met à jour tous les éléments [data-wsx-cart-count]. L'adresse est fournie à la page par Joomla.getOptions('websource').cartUrl.

Attributs JavaScript

Assets déclarés

joomla.asset.json déclare : template.websource.base (style), template.websource.page.<type> (un style par type de page), template.websource.offline, template.websource (script), template.websource.product (script), template.active, template.active.language, template.user, et le préréglage template.websource.

template.user charge css/user.css et js/user.js s'ils existent dans media/templates/site/websource (ou dans le template enfant). Le template ne livre pas ces fichiers.

En-tête SEO

Avec Balises de référencement sur Oui, Seo::head() écrit robots (noindex,follow sur la recherche, le panier, la commande et le compte), canonical, Open Graph et twitter:card. Une balise déjà présente dans le document n'est pas réécrite ; le canonical posé par HikaShop est repris. Sur une fiche produit, les liens rel="next" et rel="prev" ajoutés par les listes de modules sont retirés.

Avec Données structurées sur Oui, les nœuds sont écrits à la compilation du <head>. Quand le plugin schema.org de Joomla a déjà écrit son graphe pour la page (articles), le template n'ajoute que BreadcrumbList et ItemList. Le nœud Product vient de HikaShop.

Surcharges livrées

Le panier, les étapes de commande, les listes de commandes et d'adresses gardent les vues d'origine de HikaShop : elles sont habillées par CSS (assets/src/hikashop-checkout.css, assets/src/pages/account.css).

Template enfant

Créer l'enfant depuis Système > Templates de site > Websource > Créer un template enfant. Un fichier placé dans templates/websource_<nom>/html/… remplace celui du parent ; Theme::layout() cherche d'abord dans l'enfant. Les réglages du style enfant sont indépendants.

Build CSS

nice npm install
nice npm run build     # media/css/theme.css + media/css/pages/<type>.css
nice npm run watch
bash scripts/build-zip.sh   # dist/tpl_websource-<version>.zip

• scripts/pages.config.mjs associe à chaque type de page ses sources (assets/src/…) et les gabarits analysés par Tailwind.
• Ce qui se trouve déjà dans theme.css est retiré des fichiers de page.
• Les CSS de composants sont hors @layer : ils doivent l'emporter sur les CSS non stratifiés du cœur et de HikaShop.
• Une classe utilitaire n'existe que si elle figure dans un gabarit analysé : relancer le build après tout ajout.