Comment ajouter des champs dans un document avec ParoiCMS

Sur ParoiCMS, les pages web sont appelées des "documents". Un document a un document parent (à part le document racine qui représente le site) et peut avoir plusieurs documents enfants, c'est-à-dire que les documents sont placés dans une arborescence.

Un document est décrit par un type de document.

Le fichier site-schema.json décrit les types de documents et leurs relations hiérarchiques. Voici par exemple le type de document d'une page d'accueil :

  "leafTypes": [
    ...
    {
      "kind": "document",
      "typeName": "home",
      "lists": ...,
      "children": ["pages", "posts", "aboutPage", "contactPage", "searchPage"]
    },

Cette page d'accueil contient une liste de sous-parties, mais aucun champ. Nous allons ajouter un champ texte simple pour donner à l'utilisateur la possibilité de saisir une couleur.

Par exemple après la ligne "typeName": "home", insérons :

  "fields": [
    {
      "name": "myColor",
      "storedOn": "leaf",
      "storedAs": "varchar",
      "dataType": "string",
      "visibility": ["table", "overview", "feed"]
    }
  ],

La commande de lancement du serveur local (npm run dev) se charge de redémarrer le serveur automatiquement à chaque modification du schéma du site. En rafraîchissant l'espace d'administration, le champ sera donc immédiatement disponible :

Voici l'explication sur les options utilisées dans la déclaration du champ :

• name : c'est la clé du champ dans la payload.
• storedOn : Les deux valeurs possibles sont "leaf" et "section". On utilise "leaf" pour du contenu commun à toutes les traductions d'un document, comme par exemple une adresse e-mail, une couleur. La valeur "section" est utilisée pour des champs dont la valeur variera selon la langue du document.
• storedAs est le mode de stockage du champ. Les valeurs autorisées sont :
  • "varchar" : un stockage sous forme de texte, mais destiné à des tailles de textes limitées (5000 caractères).
  • "text" : un autre stockage sous forme de texte, de taille illimitée. C'est le stockage qu'on utilise de préférence pour le contenu d'un éditeur de texte.
  • "mediaHandle" : le stockage se fera dans la base des médias. Cela sert à stocker une image ou une galerie d'images.
• dataType est le type de la donnée manipulée par l'utilisateur. Les valeurs possibles sont :
  • "string" : pour une valeur textuelle,
  • "number" : pour un nombre,
  • "boolean" : pour un booléen,
  • "quillDelta" : pour le contenu d'un éditeur de texte Quill,
  • "media" : pour une image,
  • "gallery" : pour une liste d'images,
  • "json" : pour une valeur en JSON.
• visibility : La liste de visibilité sert à savoir où le champ sera affiché dans l'espace d'administration ("table", "overview") et dans le flux RSS ("feed").

Certains champs sont prédéfinis par le CMS. La liste peut être trouvée ici. Les plugins peuvent aussi prédéfinir des champs, c'est le cas notamment du plugin de l'éditeur de texte Quill, dont la liste des champs est ici.

Lorsqu'un champ est prédéfini, il suffit, pour l'utiliser, de le mentionner dans la liste des champs du document. Reprenons notre code précédent dans le document home et ajoutons une image en mentionnant juste le nom "image", car c'est un champ prédéfini :

  "fields": [
    {
      "name": "myColor",
      "storedOn": "leaf",
      "storedAs": "varchar",
      "dataType": "string",
      "visibility": ["table", "overview", "feed"]
    },
    "image"
  ],

Voici le résultat dans l'espace d'administration :

Traduire le libellé du champ

On remarque que le libellé de notre champ n'est pas traduit. C'est la clé backgroundColor qui est directement affichée dans l'espace d'administration. Pour écrire les traductions, cela se passe dans le fichier de localisation du schéma du site :

1. Éditer le fichier site-schema.l10n.fr.json ;
2. Dans la section "home", sous le "label", ajouter :

      "fields": {
        "myColor": {
          "label": "Le champ de ma couleur"
        }
      }

Après rafraîchissement de l'espace d'administration :

Templates HTML (LiquidJS)

Éditer le fichier theme/templates/home.liquid et insérer quelque part :

{{ doc | info }}

Sur le site public, cela affiche le contenu de la payload, et l'on peut voir en particulier :

Voici un exemple d'utilisation :

<main style="color: {{ doc.field.myColor }}">