#Depuis un thème Shopify

Le format est le même : mêmes dossiers, même langage, mêmes schémas, mêmes templates JSON. Ce qui n’est pas le même, c’est ce qu’un thème peut lire — Webcosa fait des sites vitrines, pas des boutiques. Ce guide dit exactement ce qui se transpose, ce qui se réécrit, ce qui disparaît, et dans quel ordre s’y prendre.

#Le tableau, en un coup d’œil

Le reste de cette page reprend les trois colonnes, une par une.

#Ce qui se transpose tel quel

#L’arborescence

Copie les dossiers. Il n’y a rien à renommer.

layout/theme.liquid            .liquid
sections/<type>.liquid         .liquid
snippets/<nom>.liquid          .liquid
assets/theme.css               .css .svg
config/theme.json              .json
config/settings_schema.json    .json
config/settings_data.json      .json
templates/index.json           .json

Une seule règle, mais elle est stricte : un chemin de thème a exactement deux segments. Pas de sections/blocks/…, pas de templates/customers/…, pas de sous-dossier dans assets/. Tout ce qui est plus profond est refusé à l’entrée. Voir Arborescence.

#Le langage

C’est du Liquid, exécuté par LiquidJS — la même grammaire, portée en JavaScript. Les tags de contrôle, d’affectation et d’inclusion se comportent comme chez Shopify : if / elsif / unless, case / when, for avec break et continue, tablerow, cycle, assign, capture, increment, liquid, echo, raw, comment, et surtout render en portée isolée contre include en portée partagée. Le contrôle des espaces ({%- et -%}) est identique.

Voir Tags pour la liste exacte, et Filtres pour les filtres.

#Les schémas de section

Aucun changement d’écriture. Le bloc {% schema %} est du JSON pur posé à la fin du fichier, extrait par une expression régulière — exactement comme chez Shopify.

{% schema %}
{
  "name": "Avis clients",
  "settings": [
    { "type": "text", "id": "titre", "label": "Titre", "default": "Ce qu'ils en disent" }
  ],
  "blocks": [
    {
      "type": "avis",
      "name": "Avis",
      "settings": [
        { "type": "textarea", "id": "citation", "label": "Citation" },
        { "type": "text", "id": "auteur", "label": "Auteur" }
      ]
    }
  ],
  "max_blocks": 6
}
{% endschema %}

#Les templates JSON

Même forme, mêmes clés : sections (chaque entrée porte un type, des settings, des blocks et un block_order) et order.

L’ordre de résolution est aussi celui de Shopify, avec un niveau de moins : templates/<nom>.json, puis templates/page.json, puis templates/index.json. Le nom du template suit le slug de la page — une page « tarifs » cherche templates/tarifs.json. Voir Les templates.

#La coquille

layout/theme.liquid, content_for_layout, et {% section 'entete' %} pour les sections posées hors template. Leurs valeurs vivent dans config/settings_data.json, sous current.sections — comme chez Shopify.

Ce qui n’a pas d’équivalent : content_for_header. Webcosa n’injecte rien dans le head ; ce qui doit y être, le thème l’écrit.

#Ce qui change de forme

Sept réécritures, et elles reviennent souvent. Passe-les en recherche-remplacer avant tout le reste.

#Le formulaire de contact, sans {% form %}

C’est la réécriture la plus visible, et elle est plus simple qu’attendu : un <form> ordinaire qui poste vers la route du CMS.

<form method="post" action="/api/contacts">
  <label class="champ">
    <span>Votre nom</span>
    <input type="text" name="nom" required>
  </label>
  <label class="champ">
    <span>Votre e-mail</span>
    <input type="email" name="email" required>
  </label>
  <label class="champ">
    <span>Votre projet</span>
    <textarea name="message" required></textarea>
  </label>
  <button type="submit" class="bouton">{{ section.settings.bouton }}</button>
</form>

Le retour se lit dans page.demande, qui vaut merci ou erreur après l’envoi et reste vide sinon — de quoi remercier sans une ligne de JavaScript :

{%- if page.demande == 'merci' -%}
  <p class="message message-ok" role="status">
    Merci, votre message est bien arrivé. Nous vous répondons vite.
  </p>
{%- elsif page.demande == 'erreur' -%}
  <p class="message message-ko" role="alert">
    Le message n'a pas pu être envoyé. Vérifiez votre e-mail, puis réessayez.
  </p>
{%- endif -%}

#Ce qui n’existe pas

#Les objets du commerce

Ni product, ni collection, ni cart, ni customer, ni order. Exposer des objets vides serait 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.

La liste de ce qu’un thème peut lire est fermée, et c’est un contrat : site, page, settings, section, menu, articles, annee, theme_base. Rien d’autre. Voir Objets et Les absents.

#Les tags absents

Un tag inconnu, lui, ne passe pas silencieusement : c’est une erreur d’analyse. La section entière est remplacée par un commentaire HTML dans la page rendue, et le CLI refuse le fichier à l’écriture.

Remplacements : un <form> nu pour form, un <style> dans la coquille pour style, assets/theme.css pour stylesheet, et {% section %} un par un pour sections.

#Les traductions

Il n’y a pas de locales/, donc pas de {{ 'general.title' | t }}. Les textes s’écrivent en clair dans le thème, en français, et ce qui doit varier d’un site à l’autre devient un réglage. Un thème Webcosa sert un site, dans une langue.

#Le JavaScript

Pas de .js dans assets/, et l’extension est refusée à l’entrée, pas ignorée au rendu :

! ignoré : assets/menu.js — extension non admise dans ce dossier

Ce n’est pas du rangement, c’est de la sécurité. Un thème s’exécute sous le domaine du client, avec ses cookies ; un .js déposé dans assets/ serait du script exécuté chez tous ses visiteurs. Le JavaScript de thème viendra quand on saura le relire.

#Les bornes du bac à sable

Elles n’ont pas d’équivalent visible chez Shopify, et un gros thème peut les toucher.

C’est la dernière ligne qui arrête les portages : un thème Shopify complet dépasse allègrement 120 fichiers. Voir Le bac à sable.

#La méthode de reprise

Dans cet ordre. Chaque étape se vérifie avant la suivante, et l’ordre n’est pas indifférent : on veut voir une page rendre le plus tôt possible, quitte à ce qu’elle soit laide.

1. Trier le thème d’origine

   Ouvre sections/ et range chaque fichier dans une des trois colonnes du tableau du haut. Tout ce qui parle de produit, de panier, de collection, de recherche, de compte client ou de paiement part à la poubelle maintenant — pas « on verra plus tard ». Compte ce qui reste : si tu passes sous 120 fichiers au total, le portage est viable.

   Ce que tu dois voir : une liste de sections dont chacune tient debout avec site, page, settings, section, menu et articles, et rien d’autre.

2. Partir d’un thème d’origine, pas d’un dossier vide

   Installe Origo sur un site de préproduction et récupère-le. Tu obtiens une coquille qui fonctionne, un settings_schema.json valide, un index.json valide, et un .webcosa.json déjà réglé.

   $node scripts/theme.mjs recuperer --theme=Origo --dossier=~/webcosa/portage$cd ~/webcosa/portage

   Partir de zéro coûte une demi-journée à retrouver ce que les trois fichiers indispensables doivent contenir. Voir Créer son premier thème.

3. Porter la feuille de style d’abord

   Copie le CSS de l’ancien thème dans assets/theme.css. C’est la partie qui se transpose le mieux et qui donne le plus de résultat visible : la mise en page, la typographie, les couleurs.

   Deux choses à corriger au passage : les url() qui pointaient vers des images du thème (elles doivent devenir des adresses absolues) et les @font-face qui chargeaient un .woff2 local.

   $node scripts/theme.mjs pousser ↑ modifié assets/theme.css ✓ 1 modifié, 22 inchangés

4. Porter la coquille

   layout/theme.liquid. Retire content_for_header, corrige les asset_url, remplace {% sections 'header-group' %} par des {% section %} un par un.

   Ce que tu dois voir : la page rend, avec l’en-tête et le pied de l’ancien thème. Vérifie dans le code source que le <link rel="stylesheet"> pointe sur /theme-assets/<id>/theme.css et que la feuille répond bien 200 — c’est le piège asset_url, et il ne se signale pas autrement.

5. Porter les sections, une par une

   Une section, un pousser, un rechargement. Pas dix d’un coup : quand quelque chose ne rend pas, on veut savoir quoi.

   Pour chacune : remplacer les objets absents par des réglages, réécrire les sept filtres du tableau, et laisser le schéma tel quel — il passe presque toujours.

6. Porter les templates

   templates/index.json en dernier, parce qu’il référence les sections. Les clés et l’ordre viennent de l’ancien thème ; les settings de chaque entrée sont à relire, puisque des réglages ont disparu en route.

   Ajoute templates/page.json si l’ancien thème avait un gabarit de page générique : sans lui, toute page sans template dédié retombe sur index.json, c’est-à-dire affiche la page d’accueil entière sous un autre titre.

7. Relire le rendu, pas seulement le code

   Ouvre le code source de chaque page — pas l’inspecteur, qui ne montre pas toujours les commentaires — et cherche <!-- section. Chaque commentaire est une section qui a échoué en silence.

   Rendu de la pagehtml

   <!-- section produits : tag "paginate" not found -->
   <!-- section absente : header-group -->

8. Chercher les vides

   Les objets absents rendent du vide sans rien dire. Passe le thème au peigne :

   $grep -rnE "product|collection|cart|customer|metafield|routes\.|shop\." sections snippets layout

   Chaque occurrence est un trou dans la page, qui ne se signalera jamais tout seul.

#Ce qu’on gagne au change

La liste des absents est longue, alors il faut dire l’autre moitié : ce format donne des choses que Shopify ne donne pas à un site vitrine.

• menu vient du CMS, pas d’une liste écrite dans le thème. Le client gère sa navigation dans Site web → Navigation, et le thème l’affiche. Un thème qui déclare ses propres liens oblige à les tenir à jour à deux endroits.
• page.demande rend le remerciement de formulaire trivial, sans JavaScript et sans page dédiée.
• teinte évite les vingt sélecteurs de couleur que personne ne remplit.
• Le formulaire survit au changement de thème : il poste vers le CMS, pas vers le thème.

#La suite