Aller au contenu
Webcosa Développeurs
RessourcesOuvrir le CMS

#Thèmes

Un thème Webcosa est un dossier de fichiers texte, rendus par Liquid, qui décide de tout ce qu’un visiteur voit. Cette section décrit le format en entier : les six dossiers, la coquille, les sections et leurs schémas, les treize types de réglage, les templates, et les bornes dans lesquelles tout cela s’exécute.

Le format est celui de Shopify, à la lettre. Ce n’est pas une coïncidence et ce n’est pas de la paresse : c’est un format documenté depuis dix ans, que des milliers de gens connaissent déjà, et pour lequel les outils existent — coloration syntaxique, éditeurs, tutoriels. Un format maison aurait obligé à tout réexpliquer, pour aucun gain. Ce qui diffère, et pourquoi, est le sujet de Anatomie d’un thème.

#Un thème en trente secondes

Trois fichiers suffisent à faire rendre un site. Les voici, dans leur forme la plus courte qui fonctionne.

layout/theme.liquidliquid
<!doctype html>
<html lang="fr">
  <head>
    <meta charset="utf-8">
    <title>{{ page.titre }} — {{ site.nom }}</title>
    {{ 'theme.css' | asset_url | stylesheet_tag }}
  </head>
  <body>{{ content_for_layout }}</body>
</html>
templates/index.jsonjson
{
  "sections": { "accueil": { "type": "hero" } },
  "order": ["accueil"]
}
sections/hero.liquidliquid
<section class="hero">
  <h1>{{ section.settings.titre }}</h1>
</section>

{% schema %}
{
  "name": "Bandeau d'accueil",
  "settings": [
    { "type": "text", "id": "titre", "label": "Titre", "default": "Bonjour" }
  ]
}
{% endschema %}

Il manque config/settings_schema.json pour que le thème soit installable — un tableau vide [] suffit. Le reste de cette section explique ce qu’on met dedans, et pourquoi.

#Les douze pages

Anatomie d'un thèmeCe qu'est un thème Webcosa, ce qu'il n'est pas, et ce qui le sépare d'un thème Shopify.ArborescenceLes six dossiers reconnus, les extensions admises dans chacun, et les trois fichiers sans lesquels rien ne rend.La coquille`layout/theme.liquid` : le HTML qui entoure toutes les pages, et le point d'insertion du contenu.Écrire une sectionUn fichier de `sections/`, son balisage, ses réglages, et la façon dont il est rendu.Le bloc schemaLa déclaration `{% schema %}` : ce qu'elle contient, ce que l'éditeur en fait, ce qu'elle refuse.Les types de réglageLes treize types admis dans un schéma, un par un, avec ce que chacun rend dans l'éditeur.Les blocsLes éléments répétables d'une section : déclaration, limites, et ordre d'affichage.Les templates`templates/*.json` : composer une page à partir de sections, et l'ordre dans lequel Webcosa les résout.Réglages globaux`settings_schema.json` et `settings_data.json` : les réglages qui valent pour tout le thème.SnippetsLes fragments réutilisables de `snippets/`, et le tag `{% render %}` qui les appelle.AssetsLe dossier `assets/` : CSS et SVG, l'adresse qu'ils reçoivent, et pourquoi le JavaScript en est exclu.Le bac à sableLes bornes dans lesquelles un thème s'exécute : temps, taille, imbrication, et ce qui est hors de portée.

#Dans quel ordre les lire

Elles se suivent, et l’ordre n’est pas alphabétique : il va du contenant au contenu, puis du contenu à ses réglages.

  1. Comprendre ce qu’est un thème

    Anatomie puis Arborescence : ce que le format est, ce qu’il n’est pas, et où chaque fichier se range. Une demi-heure, et on ne se trompe plus de dossier.

  2. Écrire du HTML qui rend

    La coquille, Écrire une section, Les templates. À la fin de ces trois pages, on sait composer une page entière.

  3. Le rendre modifiable

    Le bloc schema, Les types de réglage, Les blocs, Réglages globaux. C’est ici qu’un thème cesse d’être une maquette figée.

  4. Ranger et durcir

    Snippets, Assets, Le bac à sable. Les fragments réutilisables, les feuilles de style, et les bornes qu’on ne franchit pas.

Astuce

Si tu préfères apprendre en faisant, saute directement à Créer son premier thème : c’est le même contenu, dans l’ordre d’un projet réel, et il renvoie ici quand il faut un détail.

#Quatre thèmes complets à lire

Le dépôt embarque quatre thèmes d’origine, terminés et en production. Tous les exemples de cette documentation en sont tirés — jamais inventés.

ThèmeCe qu’il montre de mieux
origoTrente-quatre sections, sept gabarits de page, trois snippets. Le plus complet.
forgeUn thème sobre et anguleux, avec une barre d’annonce en group: "header".
velaPeu de sections, très réglées. Bon exemple de paragraph en note d’éditeur.
piazzaLe plus court. Utile pour voir le format sans le bruit.

Ils vivent dans themes/<id>/ à la racine du dépôt. Un thème du catalogue n’est pas un thème installé : voir Ajouter un thème au catalogue pour la différence, qui compte.

#Ce qu’un thème ne peut pas faire

Autant le dire avant de commencer, ça évite d’écrire trois cents lignes pour rien :

  • pas de product, cart, collection — Webcosa fait des sites vitrines. Voir Les absents ;
  • pas de JavaScript dans assets/ — la liste des extensions est fermée, et c’est une mesure de sécurité. Voir Assets ;
  • pas d’accès au disque, au réseau, ni aux variables d’environnement — {% render %} ne voit qu’une carte en mémoire. Voir Le bac à sable ;
  • pas d’appel de fonction, pas d’eval — c’est Liquid, et c’est la raison d’être du langage.

#Pour aller plus loin

LiquidLa référence du langage tel que Webcosa l'exécute : objets exposés, filtres, tags, et absences assumées.CLIL'outil en ligne de commande : éditer un thème sur sa machine, le pousser, le publier.Créer son premier thèmeDu dossier vide à une page qui rend, pas à pas, avec les trois fichiers minimaux.Depuis un thème ShopifyCe qui se transpose tel quel, ce qui demande une réécriture, ce qui n'a pas d'équivalent.