#Anatomie d’un thème

Un thème Webcosa est un ensemble de fichiers texte, rangés par dossier, rendus par Liquid au moment où un visiteur demande une page. Il n’y a rien d’autre : pas de compilation, pas d’étape de construction, pas de paquet npm. Un fichier que tu enregistres est un fichier que le serveur lit.

Cette page dit ce que ce format est, d’où il vient, et où il s’arrête.

#Le format est celui de Shopify, à la lettre

Les mêmes noms de dossiers, la même syntaxe de {% schema %}, les mêmes templates/*.json, le même {{ content_for_layout }}. Un thème Shopify posé tel quel dans Webcosa rend, tant qu’il ne parle pas de boutique.

C’est délibéré, et la raison tient en trois points :

• le format est documenté depuis dix ans. Tout ce qui n’est pas dans cette documentation, quelqu’un l’a déjà écrit ailleurs ;
• des milliers de gens le connaissent. Un intégrateur Shopify est productif sur Webcosa en une heure, pas en une semaine ;
• les outils existent déjà. Coloration syntaxique Liquid dans tous les éditeurs, extensions, exemples, formations.

Un format maison aurait obligé à tout réexpliquer, pour aucun gain fonctionnel. Le langage lui-même est Liquid, exécuté par LiquidJS — la même grammaire, portée en JavaScript. Écrire notre propre interpréteur aurait coûté des semaines pour obtenir moins sûr et moins complet.

#Ce que Webcosa n’expose pas, et pourquoi

Il n’y a ni product, ni cart, ni collection, ni customer, ni checkout. Webcosa fait des sites vitrines : un artisan, un cabinet, un restaurant. Pas de panier, pas de commande, pas de stock.

L’alternative aurait été d’exposer ces objets vides, pour « la compatibilité ». C’est pire que de ne rien exposer : on écrirait des thèmes contre une API qui ne rend jamais rien, et on découvrirait le vide en production, sur le site d’un client. Un objet absent lève une question à l’écriture ; un objet vide ne lève rien du tout.

Ce qu’un thème peut lire est une liste fermée, et c’est un contrat : ce qui y figure devra continuer d’exister sous ce nom tant que des thèmes s’en servent.

La page Objets les détaille champ par champ, et Les absents explique par quoi remplacer ce qui manque.

#Les trois fichiers indispensables

Un thème doit contenir ces trois fichiers. Ils sont vérifiés à l’installation et à l’import, et l’éditeur de code refuse de les supprimer.

#Ce qui se passe quand l’un manque

Les trois cas sont différents, et il vaut la peine de les distinguer : le premier est silencieux, les deux autres sont bruyants.

Sans template applicable, la page rend une chaîne vide, accompagnée de l’erreur Aucun template pour « <nom> ». Comme templates/index.json sert de dernier recours à toutes les pages, ce cas ne se produit en pratique que s’il a été supprimé ou si son JSON est cassé.

Sans config/settings_schema.json, le thème ne s’installe pas : l’ensemble est refusé avec fichier_requis_manquant, avant même d’écrire une ligne en base. Le fichier n’est en revanche lu par personne au rendu — ce sont les valeurs de config/settings_data.json qui alimentent settings. Son contenu minimal, parfaitement valable, est donc :

[]

Un tableau, jamais un objet : c’est la seule différence de forme avec le {% schema %} d’une section, et c’est la faute qu’on fait une fois. Voir Réglages globaux.

#Ce qu’un thème n’est pas

Ce n’est pas une application. Pas de JavaScript de thème, pas de fetch, pas de service worker. Le dossier assets/ n’accepte que .css et .svg, et cette liste est fermée pour des raisons de sécurité détaillées dans Assets.

Ce n’est pas un dépôt de contenu. Le nom du site, le menu, les articles et les demandes de contact viennent du CMS. Un thème qui écrit ses propres liens de navigation oblige le client à les tenir à jour à deux endroits — les quatre thèmes d’origine lisent tous menu, et aucun ne déclare de liens.

Ce n’est pas un programme. Liquid n’a ni eval, ni appel de fonction, ni accès au disque. C’est ce qui permet de faire tourner le thème d’un client sur le serveur qui rend aussi ceux des autres. Voir Le bac à sable.

#Le trajet d’une page, du domaine au HTML

Utile à avoir en tête : la moitié des questions « pourquoi ça ne s’affiche pas » se répond en sachant à quelle étape ça coince.

1. Le site a-t-il un thème publié ?

   Une seule ligne peut porter le rôle publie par site. Sinon, le rendu passe par l’ancien moteur et le thème n’est jamais consulté.

2. Les fichiers sont chargés

   Tous les fichiers du thème sont lus en une requête et posés dans une carte en mémoire — c’est ce que voient le moteur, {% render %} et {% section %}. Pas de disque, jamais.

3. Les réglages globaux sont lus

   config/settings_data.json est analysé. Sa clé current donne settings ; sa sous-clé current.sections donne les valeurs des sections que la coquille pose. Un JSON cassé ici ne casse rien : on repart sur les valeurs par défaut des schémas.

4. Le template est résolu

   templates/<nom>.json, sinon templates/page.json, sinon templates/index.json. Trois niveaux, dans cet ordre.

5. Les sections sont rendues, puis la coquille

   Chaque section du template est rendue avec son contexte propre. Les résultats sont concaténés, et cette chaîne devient content_for_layout dans layout/theme.liquid.

Une section qui échoue ne fait pas tomber la page : elle est remplacée par un commentaire HTML. C’est un choix, et il se défend — un thème en cours d’édition contient forcément des erreurs passagères, et une page blanche à chaque virgule mal placée rendrait l’édition impossible.

#Deux endroits où un thème peut vivre

Ils ne se confondent pas, et rien ne circule automatiquement de l’un à l’autre.

Le catalogue — themes/<id>/ dans le dépôt, compilé en un module TypeScript par node scripts/compiler-themes.mjs. Ce sont les thèmes d’origine, proposés à l’installation à tous les sites. Ils vivent sous Git et se déploient avec le CMS.

La base — le thème installé sur un site. C’est ce qu’édite l’éditeur de code du CMS, et ce que pousse le CLI. Corriger un thème du catalogue ne corrige aucun site déjà installé : l’installation copie les fichiers, et le site garde ensuite sa copie.

#Pages voisines