#Le bloc schema

Le {% schema %} d’une section déclare ce qui, dans cette section, est modifiable sans toucher au code : son nom, ses réglages, ses blocs. C’est du JSON pur, posé à la fin du fichier, entre {% schema %} et {% endschema %}.

Il ne s’exécute pas et ne rend rien. Il est retiré du fichier avant le rendu, puis relu séparément pour en tirer les valeurs par défaut.

#La forme

<section class="temoignages">
  <h2>{{ section.settings.titre }}</h2>
  {%- for bloc in section.blocks -%}
    <blockquote>« {{ bloc.settings.citation }} »</blockquote>
  {%- endfor -%}
</section>

{% 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", "default": "Un client" }
      ]
    }
  ],
  "max_blocks": 6
}
{% endschema %}

#Les clés

#Ce que le schéma fait vraiment au rendu

Une seule chose, et elle est importante : fournir les valeurs par défaut.

1. Le schéma est extrait

   Une expression régulière cherche {% schema %} … {% endschema %}, tolérant les formes à tirets ({%- schema -%}). Le contenu est passé à JSON.parse.

2. Les défauts sont collectés

   Pour chaque entrée de settings qui a un id et un default, la valeur par défaut est retenue. Une entrée sans id — un header, un paragraph — n’apporte rien ; une entrée sans default non plus.

3. Les valeurs enregistrées recouvrent les défauts

   section.settings est le résultat de la fusion : les défauts d’abord, les valeurs du template ou de settings_data.json par-dessus.

4. Le bloc schema est retiré du fichier

   La même expression régulière le supprime avant que le balisage ne soit rendu. C’est pour ça qu’un {% schema %} ne produit jamais de sortie.

Cette fusion est ce qui permet d'ajouter un réglage à un thème déjà installé : les instances existantes ne connaissent pas le nouvel id, elles prennent donc le default. Sans elle, l’auteur du thème croirait son défaut ignoré et irait rouvrir toutes les pages.

#Ce qui se passe si le JSON est invalide

lireSchema rend null, et le rendu continue. Concrètement :

• la section reste rendable — son balisage s’affiche ;
• elle perd toutes ses valeurs par défaut : section.settings ne contient plus que ce que le template a explicitement enregistré ;
• sur une section fraîchement posée, dont le template n’a rien enregistré, cela veut dire une section vide.

C’est délibéré. Une virgule en trop dans un schéma ne doit pas éteindre une page en ligne — mais le résultat est assez visible pour qu’on aille corriger tout de suite.

#La reconnaître

{
  "name": "Prestations",
  "settings": [
    { "type": "text", "id": "titre", "label": "Titre", "default": "Nos services" },
  ]
}

La virgule après la dernière entrée. JSON.parse refuse, lireSchema rend null, et la section perd ses défauts. Un formateur JSON dans l’éditeur l’attrape en une seconde ; à l’œil nu, on peut y passer un quart d’heure.

#Deux règles de forme

Un seul bloc schema par fichier. L’expression régulière n’en trouve qu’un et n’en retire qu’un : le second serait rendu tel quel et ferait échouer la section avec tag "schema" not found, puisque schema n’est pas un tag exécutable.

Jamais dans un layout ni dans un snippet. Ces fichiers sont rendus sans retrait préalable du bloc. Un {% schema %} dans layout/theme.liquid casse toutes les pages du site d’un coup.

#Un schéma bien écrit

info est le champ le plus sous-utilisé du format, et c’est dommage : c’est la seule occasion d’expliquer à quoi sert un réglage à l’endroit où on le remplit.

{
  "type": "range",
  "id": "densite",
  "label": "Espace entre les sections",
  "info": "Plus haut, le site respire ; plus bas, il tient sur moins d'écrans.",
  "min": 60,
  "max": 160,
  "step": 10,
  "unit": "%",
  "default": 100
}

Trois habitudes qui se retrouvent dans les quatre thèmes :

• un default sur tout ce qui est visible. Un thème installé doit ressembler à quelque chose avant qu’on l’ouvre ;
• pas de default sur ce qui est facultatif. Une adresse, un téléphone : vide, la section masque proprement l’élément ;
• info pour dire l’effet, pas le champ. « Laisse vide pour masquer la barre » vaut mieux que « Le texte de l’annonce ».

#Pages voisines