#Ajouter un thème au catalogue

Le catalogue, ce sont les thèmes d’origine : ceux qu’un client trouve dans Site web → Installer un thème — Aplomb, Cadence, Épure, Forge, Origo, Piazza, Scène et Vela. Ils vivent dans le dépôt du CMS, sous Git, et se déploient avec lui. Ce guide dit comment en ajouter un — et pourquoi l’étape de compilation, qui a l’air d’une formalité, est celle qui casse la production quand on l’oublie.

#Un seul catalogue, deux surfaces d’installation

Le CMS et store.webcosa.com proposent les mêmes thèmes. src/lib/store/themes-liquid.ts ne contient aucun thème : il dérive les fiches du magasin de THEMES_ORIGINE, le module compilé depuis themes/.

Les deux appellent installerThemeOrigine. Ajouter un thème au Store, c’est donc exactement ce que décrit cette page : créer le dossier sous themes/, puis recompiler.

#Le parcours

1. Créer le dossier

   Le nom du dossier est l’identifiant du thème. Il voyage : c’est lui qui est enregistré dans la colonne origine de chaque thème installé, et c’est lui qui sert à ne pas proposer deux fois le même à l’installation. Choisis-le court, en minuscules, et ne le renomme plus ensuite.

   $mkdir -p themes/atelier/{layout,sections,snippets,assets,config,templates}

   Les six dossiers, et rien d’autre. La compilation descend récursivement mais le format ne connaît que deux segments : un fichier plus profond serait embarqué dans le module et refusé à l’installation, ce qui ferait échouer le thème entier chez le premier client qui l’essaie.

2. Écrire les trois fichiers indispensables

   Sans eux, l’installation est refusée : POST /api/themes répond 400 avec {"error":"fichier_requis_manquant"}.

   layout/theme.liquidrequis

   La coquille HTML de toutes les pages, avec content_for_layout. Un thème publié qui la perd est purement ignoré : le site repart sur l’ancien moteur, sans une erreur. Voir La coquille.

   templates/index.jsonrequis

   La composition de la page d’accueil. C’est le thème qui compose l’accueil — un site n’a pas besoin d’avoir créé une page pour qu’elle rende.

   config/settings_schema.jsonrequis

   Les réglages globaux, déclarés. Un tableau de groupes, chacun avec un name et des settings.

   Le plus rapide, et de loin : partir d’un thème existant.

   $cp -R themes/forge/. themes/atelier/

3. Renseigner config/theme.json

   C’est ce fichier qui donne au thème son identité dans l’écran d’installation.

   themes/atelier/config/theme.jsonjson

   {
     "nom": "Atelier",
     "version": "1.0.0",
     "pour": "Robuste et net, pour les métiers de la main. Traits épais, titres en capitales, aucune ombre.",
     "metiers": ["artisan", "batiment", "services"],
     "traits": [
       "Prestations numérotées, séparées par des filets",
       "Réalisations en grille asymétrique, la première en grand",
       "Téléphone dans l'en-tête, cliquable sur mobile"
     ]
   }

   nomchaînerequis

   Le nom affiché partout : la carte d’installation, la liste des thèmes du site, lister du CLI. Sans lui, la compilation retombe sur l’identifiant du dossier — ce qui se voit, et c’est le but.

   versionchaînedéfaut : 1.0.0

   Recopiée dans la ligne du thème installé. Elle ne bouge pas toute seule : c’est une étiquette, pas un mécanisme de mise à jour. Un thème installé ne se met jamais à jour depuis le catalogue.

   pourchaîne

   Une phrase : à qui il va, et pourquoi. Affichée sous le nom, sur la carte d’installation. C’est elle qui décide du clic — écris-la comme une réponse à « pourquoi celui-là plutôt qu’un autre ».

   traitschaîne[]

   Trois traits, affichés sur la fiche du thème sur le Store, dans la colonne « Ce qui distingue ce thème » — la carte d’installation, elle, ne les montre pas. Dis ce qui distingue réellement le thème, pas ce que tous ont : « Horaires affichés dans l’en-tête, pas cachés dans le pied » vaut mieux que « Design responsive ».

   metierschaîne[]

   Les familles de métiers visées — les identifiants de src/lib/metiers.ts : batiment, artisan, beaute, sante, sport, conseil, juridique, image, restauration, commerce, services, formation, autre.

   L’ordre compte : c’est celui de la pertinence. Le sélecteur de métier de l’aperçu, sur la fiche du Store, propose d’abord ceux que tu déclares ici, dans cet ordre — et l’aperçu s’ouvre donc sur le premier. Les autres suivent, aucun n’est caché : un thème refusé parce qu’on n’a pas pu essayer son métier est un thème perdu.

   editionsobjet[]

   Plusieurs habillages complets du même thème — ce que le Theme Store de Shopify appelle « presets ». Détaillé juste en dessous.

   #Les éditions, et pourquoi le métier les commande

   Une édition ne pose que des valeurs de réglages : couleurs, polices, densité, arrondis, forme des boutons, allure de l’en-tête. Jamais une structure, jamais une section, jamais un gabarit. C’est cette contrainte qui la rend sans danger — en changer ne peut pas casser une page déjà composée.

   themes/atelier/config/theme.jsonjson

   {
     "editions": [
       {
         "id": "chantier",
         "nom": "Chantier",
         "pour": "Le bâtiment. Angles droits, filets épais, ocre sur ardoise.",
         "metiers": ["batiment"],
         "settings": {
           "arrondi": 0,
           "boutons": "droit",
           "accent": "#b4541c",
           "sections": { "entete": { "settings": { "allure": "barre" } } }
         }
       }
     ]
   }

   settings est fusionné en profondeur par-dessus config/settings_data.json. C’est ce qui permet à sections.entete.settings.allure de remplacer la pilule flottante par une barre pleine largeur sans effacer les textes de l’annonce et du pied — une fusion plate remplacerait tout l’objet sections, et l’aperçu montrerait un bandeau vide qu’on prendrait pour un bug de section.

   metiers est ce qui relie l’habillage au contenu. L’aperçu du Store affiche sept boutons — Charpente, Ébénisterie, Coiffure, Kinésithérapie, Restaurant, Photographie, Salle de sport. Chacun peuple la page d’une entreprise fictive et applique l’édition qui déclare son métier. Et ce qu’on installe est ce qu’on regardait : le bouton du Store transporte l’édition affichée.

   Attention

   Chacun des sept métiers de démonstration doit être réclamé par exactement une édition. Un métier oublié retombe sur la première du thème, et deux boutons du Store rendent alors la même page — ce qui détruit la seule chose que cet écran doit démontrer. node scripts/verifier-theme.mjs <id> le refuse, en même temps qu’il relit chaque valeur contre settings_schema.json : un réglage mal nommé, une option de select inventée ou un nombre hors bornes sont ignorés en silence par le moteur, et l’édition semble alors « ne rien faire ».

   Si le thème déclare un réglage edition et le pose en data-edition sur <html>, chaque édition doit y écrire son propre identifiant, et la feuille de style doit porter la règle correspondante. Sinon l’interrupteur ne branche rien : le client tourne le bouton dans son panneau, et rien ne bouge.

   Note

   Un theme.json illisible n’arrête pas la compilation : le thème part avec son identifiant comme nom et 1.0.0 comme version. C’est délibéré — un JSON cassé ne doit pas empêcher les autres thèmes de se compiler — mais le défaut se voit à l’écran, et c’est ainsi qu’on l’attrape.

4. Compiler le catalogue

   $node scripts/compiler-themes.mjs9 thèmes, 308 fichiers → src/lib/liquid/catalogue.ts

   Le script parcourt themes/, embarque tout fichier en .liquid, .json, .css ou .svg, et écrit un module TypeScript généré. Les autres extensions sont ignorées : un README.md ou une capture d’écran posée dans le dossier ne partira pas au catalogue.

   Relis le compte affiché. Si le nombre de thèmes n’a pas augmenté, le dossier n’est pas là où tu crois.

5. Vérifier en installant

   Lance le CMS, ouvre Site web sur un site de test, et regarde la section Installer un thème.

   Ce que tu dois voir : une carte « Atelier » — une vignette du thème rendu, son nom, puis sa phrase pour sur deux lignes. Les traits, eux, se lisent sur la fiche du Store. Clique Installer : le message « « Atelier » est installé, en brouillon. » doit apparaître, et la carte disparaître de la liste — on ne propose pas deux fois le même thème au même site.

   C’est le seul test qui vaille : l’installation passe les fichiers par la même validation que l’import d’une archive extérieure. Nos propres thèmes n’y ont aucun privilège, et c’est voulu — un thème d’origine mal formé doit être arrêté ici plutôt que découvert par un client.

   Attention

   Sur l’action « installer », l’API répond {"error":"…","message":"…"} et le toast affiche la phrase : c’est le cas des quatre premières causes ci-dessous. theme_inconnu fait exception — il ne figure pas dans MESSAGES_REFUS_THEME, donc l’écran retombe sur le libellé générique « L’opération n’a pas abouti. » et la cause ne se lit que dans le corps de la réponse. Pour celui-là seulement, ouvre l’onglet réseau avant de cliquer.

   Ce que répond POST /api/themes	Ce qu’il faut corriger
   fichier_requis_manquant	il manque layout/theme.liquid, templates/index.json ou config/settings_schema.json
   chemin_invalide	un fichier à plus de deux segments, ou une extension refusée dans son dossier
   fichier_trop_gros	un fichier au-dessus de 512 Ko
   trop_de_fichiers	plus de 120 fichiers
   theme_inconnu	l’identifiant envoyé n’existe pas dans le module compilé — presque toujours une compilation oubliée

6. Commiter le module généré

   $git add themes/atelier src/lib/liquid/catalogue.ts

   src/lib/liquid/catalogue.ts est versionné. C’est ce qui rend l’oubli visible : un git status qui montre themes/atelier/ sans catalogue.ts dit que la compilation n’a pas été relancée. Prends l’habitude de regarder les deux ensemble.

#Pourquoi la compilation n’est pas optionnelle

C’est la question qu’on se pose en voyant un script de génération, et la réponse mérite d’être connue avant de proposer de le supprimer.

Un thème est fait de fichiers, et on veut les éditer comme des fichiers : coloration syntaxique, recherche, diff lisible en revue. Les écrire dans des chaînes TypeScript rendrait chaque accolade Liquid pénible à taper et chaque revue illisible.

Mais le rendu ne peut pas les relire depuis le disque. Sur Vercel, seul ce que l’empaqueteur a vu est embarqué dans la fonction. Un readFileSync sur themes/ marcherait parfaitement en développement — le dossier est là, à côté — et rendrait « fichier introuvable » en production.

Corollaire pratique : une modification dans themes/ n’existe pour personne tant que compiler-themes.mjs n’a pas tourné. Ni pour le CMS local, ni pour le déploiement. Il n’y a pas de rechargement à chaud sur ce chemin.

#Ce que le catalogue ne fait pas

Trois propriétés contre-intuitives, et elles découlent toutes de la même décision : l’installation copie.

#Le pont, et il est manuel

Faire d’un thème travaillé sur un site un thème de catalogue demande de le rapatrier soi-même. C’est le seul chemin, et il n’y en aura pas d’autre tant que personne n’aura décidé qui, du disque ou de la base, fait autorité.

1. Récupérer le thème dans themes/

   $node scripts/theme.mjs recuperer --theme=Atelier --dossier=themes/atelier

   Le CLI avertit au passage :

   Sortie du CLI

   ! themes/atelier est sous le `themes/` du dépôt — celui des thèmes d'ORIGINE,
     compilé dans le catalogue. Préfère `--dossier=` ailleurs.

   Cet avertissement n’est pas là pour t’arrêter ici : il est là pour que ce soit une décision, et non le résultat d’un --dossier mal choisi un soir de fatigue. Un thème récupéré là finirait au catalogue, proposé à tous les sites, sans que personne l’ait voulu.

2. Nettoyer ce qui ne doit pas partir

   recuperer pose un .webcosa.json dans le dossier : il nomme le site et le thème d’où vient la copie. Il n’a rien à faire dans le catalogue.

   $rm themes/atelier/.webcosa.json

   Relis aussi config/settings_data.json : ce sont les valeurs de ce client-là — son téléphone, son adresse, ses horaires. Elles deviendraient les valeurs par défaut de tous les sites qui installent le thème.

3. Compiler et vérifier

   $node scripts/compiler-themes.mjs

   Puis installe-le sur un site de test, comme plus haut. Un thème qui vient d’un site réel a souvent accumulé des fichiers que le format tolère mal — c’est le moment de s’en apercevoir.

#Retirer un thème du catalogue

Supprime le dossier, recompile. Le thème disparaît de l’écran d’installation.

Les sites qui l’avaient installé, eux, ne perdent rien : leurs fichiers sont en base, indépendants. La seule trace qui reste est la valeur de leur colonne origine, qui pointe désormais vers un identifiant sans modèle — sans conséquence, puisqu’elle ne sert qu’à filtrer la liste des thèmes proposés.

#La suite