IllusionCMS
FR
Manuel · 9

Données : Collections et sources REST

Vous utilisez les deux types de sources de données de la même façon dans le template : data("slug").

9.1 Collections

Une Collection est votre propre structure de données avec des champs – p. ex. Blog avec titre, date, image et texte.

Créer : Collections → + Nouveau → nom et Slug (le Slug est le nom utilisé pour data("…")). Dans l’onglet Schéma, vous créez les champs :

Type de champ Saisie Dans le template
Texte, Texte multiligne, URL Champ de texte {{ item.feld }}
Markdown Éditeur Markdown avec aperçu {{ item.feld|markdown }}
HTML Éditeur de code {{ item.feld|safe }}
Nombre Champ numérique {{ item.feld }}, {{ item.feld|floatformat:2 }}
Oui/Non Case à cocher {% if item.feld %}…{% endif %}
Date Champ de date (enregistré au format AAAA-MM-JJ) {{ item.feld }}
Sélection Liste d’options fixes {{ item.feld }}
Image Choix dans le gestionnaire de fichiers {{ image(item.feld) }}
Fichier Choix dans le gestionnaire de fichiers {{ file(item.feld).url }}
Lien (une entrée) Choix d’une entrée d’une autre Collection {{ item.feld.name }}
Liens (plusieurs) Ajouter, retirer, trier des entrées {% for x in item.feld %}{{ x.name }}{% endfor %}
Blocs Éditeur de formulaire pour des blocs faits de modules (voir 7.6) {% blocks item.feld %}

Le nom du champ (p. ex. titel) est le nom dans le template, le libellé ce qui s’affiche dans le formulaire. Requis impose une valeur.

Si vous renommez un champ, les entrées existantes ne conservent leurs anciennes valeurs que jusqu’au prochain enregistrement de l’entrée. Choisissez donc vos noms de champs le plus tôt possible.

Langue des entrées : Dans le schéma, vous définissez la langue des entrées d’une Collection. Ce n’est qu’alors que les entrées peuvent être liées à des entrées d’autres langues – voir Sites multilingues.

Liens entre Collections : avec les types de champ Lien et Liens, une entrée pointe vers des entrées d’une autre Collection (ou de la même). Vous choisissez la Collection cible dans le schéma, à côté du type. Un article de blog a ainsi un auteur (1:n), et articles et tags peuvent être associés mutuellement de façon multiple (n:m). Seuls les ID sont enregistrés. Dans data() et item(), les liens sont déjà résolus :

{% for a in data("blog") %}
  <h2>{{ a.titel }}</h2>
  <p>von {{ a.autor.name }} · {% for t in a.tags %}#{{ t.name }} {% endfor %}</p>
{% endfor %}

Dans le sens inverse, c’est-à-dire « tous les articles de cet auteur » ou « tous les articles avec ce tag », vous filtrez l’autre Collection par ID. Pour Liens (plusieurs), la comparaison signifie « contient », avec __ne « ne contient pas » :

{% for x in data("blog", "autor", autor.id) %}…{% endfor %}
{% for x in data("blog", "tags", tag.id, "sort", "-datum") %}…{% endfor %}
  • La résolution porte sur un niveau : les tags d’un article sont des entrées complètes, mais leurs propres liens ne sont que des ID. Ainsi, des liens réciproques ne forment pas de boucle. Pour descendre d’un niveau, utilisez data() et le filtre.
  • Les entrées supprimées et, pour les visiteurs, non publiées disparaissent. Un Lien est alors vide, et des Liens ne contiennent que les entrées restantes. Dans l’aperçu, les brouillons sont inclus.
  • L’onglet Utilisation contient des exemples adaptés, y compris pour le sens inverse (« Liée depuis »). Le panneau Données de template de l’éditeur de pages montre les entrées résolues.
  • L’API REST (/collections/…/items) renvoie les ID. GET /data/{slug} renvoie la même chose que data() dans le template, donc résolue.
  • CSV : l’export écrit les ID (plusieurs séparés par des virgules). L’import accepte des ID ou la valeur d’un champ de texte de l’entrée cible, de préférence le Slug. Les exports Webflow, qui sortent les liens sous forme de Slugs, conviennent ainsi. Séparez plusieurs valeurs par une virgule ou un point-virgule ; les valeurs inconnues sont signalées comme remarque.

Dossier : dans l’onglet Schéma, vous pouvez attribuer un Dossier à une Collection, p. ex. le nom d’un projet. La liste de gauche se regroupe en conséquence, et chaque dossier peut être replié. Les dossiers servent uniquement à la vue d’ensemble et ne changent rien à data("…"). Les Snippets et les fichiers CSS/JS ont le même champ à côté du nom.

Vous gérez les entrées dans l’onglet Entrées : + Entrée, modification par double-clic ou Modifier, ordre avec les flèches, Publié par entrée. Les entrées non publiées n’apparaissent que dans l’aperçu.

Dans l’onglet Utilisation, la Collection présente des exemples prêts à l’emploi pour les templates et l’API. Avec Lisible publiquement via l’API REST, des clients JavaScript peuvent récupérer les entrées publiées sans connexion – y compris depuis d’autres domaines (CORS est alors autorisé automatiquement).

Import et export CSV : dans l’onglet Entrées, Exporter CSV télécharge toutes les entrées (brouillons compris) sous forme de fichier CSV – colonnes id, published, puis les champs ; en UTF-8 avec BOM, pour qu’Excel affiche correctement les caractères accentués. Importer CSV accepte un fichier CSV (UTF-8 ; virgule, point-virgule ou tabulation sont reconnus comme séparateurs) et associe ses colonnes aux champs – automatiquement d’après le nom du champ ou le libellé, modifiable par colonne. Un aperçu montre les premières entrées telles qu’elles seront enregistrées et liste toutes les erreurs avec ligne et colonne ; tant qu’il y a des erreurs, rien n’est importé. L’import se fait en tout ou rien, les nouvelles entrées sont ajoutées à la fin ; Remplacer les entrées existantes supprime d’abord toutes les entrées présentes.

  • Correspondance au lieu d’ajout : sous Correspondance, vous choisissez un champ aux valeurs uniques, le plus souvent le Slug. S’il existe déjà une entrée avec la même valeur, elle est mise à jour – uniquement les colonnes associées, tout le reste (y compris le statut, si aucune colonne de statut n’est associée) est conservé ; sinon, une nouvelle entrée est créée. Avec Supprimer les entrées absentes du fichier, cela devient une synchronisation complète : les entrées conservent leur ID, seul ce qui manque dans le fichier disparaît. L’aperçu indique pour chaque ligne nouveau ou modifie #ID et, en haut, le résultat (p. ex. « 1 nouvelle · 2 mises à jour · 1 supprimée »). Les valeurs en double dans le fichier ou dans la Collection sont des erreurs.

  • Modifier dans Excel : exporter, modifier le fichier (changer des lignes, ajouter de nouvelles lignes avec une id vide, supprimer des lignes) et le réimporter – la colonne id est automatiquement reconnue comme ID de l’entrée et proposée pour la correspondance. Un ID inconnu est une erreur. Utilisez pour cela un export récent : si l’entrée la plus récente est supprimée, une entrée créée plus tard peut recevoir son ID.

  • Nouvelle Collection depuis un CSV : Collections → CSV (à côté de + Nouveau). IllusionCMS propose un nom, un Slug et, pour chaque colonne, un nom de champ et un type (nombre, oui/non, date, URL, HTML, texte …) – tout est modifiable avant l’import, et des colonnes peuvent être ignorées.

  • Exports Webflow : les colonnes de gestion (Collection ID, Item ID, Created On …) sont ignorées, Draft et Archived déterminent le statut (true = brouillon). Pour d’autres fichiers, vous pouvez utiliser vous-même une colonne oui/non comme Statut : en ligne ou Statut : brouillon ; sans une telle colonne, toutes les entrées sont publiées.

  • Valeurs : les nombres peuvent être écrits à l’allemande (1.234,50) ou à l’anglaise (1,234.50) – 1,5 vaut 1,5. Oui/Non comprend ja/nein, true/false, 1/0, x. Les dates sont converties au format AAAA-MM-JJ à partir de 2025-10-02, 02.10.2025, d’horodatages ISO et du format Webflow. L’import propose les valeurs commençant par un zéro (codes postaux) comme texte, et non comme nombre.

  • Images et fichiers : une colonne image ou fichier contient soit l’ID d’un fichier, soit l’adresse d’un fichier déjà repris par l’import de site web – les URL d’images d’un export Webflow retrouvent ainsi les images importées. Les autres adresses restent vides (l’aperçu les signale) ; si vous voulez conserver l’adresse, utilisez le type URL.

  • L’import ne déclenche aucun événement de Workflow – sinon, mille lignes produiraient mille exécutions de Workflow (p. ex. des notifications).

Données live : certaines Collections se remplissent d’elles-mêmes sur le serveur en production – p. ex. des demandes de contact issues d’un Workflow. Si vous cochez Données live dans le schéma, leurs entrées sont conservées sur la cible lorsque vous téléversez un Bundle depuis votre poste local ; les entrées de test de votre instance locale ne sont pas transférées. Le schéma (champs, nom) provient malgré tout de la version locale. Dans la liste, ces Collections portent le badge Live.

Singleton : pour les choses qui n’existent qu’une seule fois – paramètres du site, codes couleur, coordonnées, horaires d’ouverture –, cochez Singleton dans le schéma. La Collection contient alors exactement une entrée ; au lieu d’une liste, vous voyez directement le formulaire sous Contenu. Dans le template, data() renvoie directement l’entrée sous forme d’objet :

{% set s = data("einstellungen") %}
<header style="--primaer: {{ s.primaerfarbe }}">{{ s.firmenname }} · {{ s.telefon }}</header>

L’API (GET /api/v1/collections/einstellungen/items, /api/v1/data/einstellungen) renvoie elle aussi un objet ; vous pouvez le modifier via PUT /api/v1/collections/einstellungen/item. Une deuxième entrée n’est pas possible, pas plus qu’un import CSV. Le basculement n’est possible que tant que la Collection contient au plus une entrée.

Page de détail et aperçu : si les entrées apparaissent sur une page Catch-All (p. ex. /blog/<slug>), sélectionnez-la dans le schéma sous Page de détail, ainsi que le champ contenant la partie d’URL (le plus souvent slug). Lors de la modification d’une entrée, l’aperçu de cette page s’affiche alors à droite – avec la version non encore enregistrée, donc en direct pendant la saisie, commutable Bureau/Tablette/Mobile ; Ouvrir ↗ affiche l’entrée enregistrée sur le site.

9.2 data() et item()

{% for post in data("blog") %}…{% endfor %}

Les paramètres suivent sous forme de paires nom/valeur :

Paramètre Effet Exemple
sort Trier, - = décroissant data("blog", "sort", "-datum")
limit Au plus n entrées data("blog", "limit", 3)
offset Ignorer les n premières data("blog", "offset", 10, "limit", 10)
n’importe quel champ Filtrer sur l’égalité data("produkte", "kategorie", "schuhe")
feld__gt, __gte, __lt, __lte Supérieur / supérieur ou égal / inférieur / inférieur ou égal. Les nombres sont comparés comme des nombres, les champs de date (AAAA-MM-JJ) chronologiquement ; les entrées sans valeur sont exclues data("events", "datum__gte", today)
feld__ne Différent data("blog", "kategorie__ne", "intern")

Il existe en outre les champs id, _created et _updated (temps Unix) – p. ex. "sort", "-_created" pour « les plus récentes d’abord ». Les valeurs issues de variables fonctionnent tout aussi bien : data("produkte", "kategorie", route.query.kat).

Vous trouvez une entrée unique avec item() :

{% with p=item("produkte", "slug", "sneaker-weiss") %}{{ p.name }}{% endwith %}

9.3 Sources REST

Les sources REST connectent n’importe quelle API JSON – boutique, CRM, système de tickets, CMS headless, vos propres services. Le CMS interroge l’API au moment du rendu, extrait la liste et met le résultat en cache pendant un certain temps.

Créer : Sources REST → + Nouvelle :

Champ Signification
Nom / Slug Le Slug est le nom utilisé pour data("…")
Méthode / URL GET ou POST, URL http(s) absolue
En-têtes p. ex. Authorization: Bearer …
Corps JSON pour POST
Chemin de la liste Où se trouve la liste dans la réponse, p. ex. data.items (vide = réponse entière)
Cache Durée de réutilisation du résultat (secondes, 0 = jamais)
Délai Temps d’attente maximal (1–60 secondes)

Les espaces réservés rendent les requêtes flexibles :

  • {name} dans l’URL, le corps ou les en-têtes est rempli depuis le template : URL https://shop.example.com/api/products?cat={kat} → data("produkte", "kat", "schuhe").
  • {env.NAME} lit une variable d’environnement du serveur. Ainsi, les identifiants n’ont rien à faire dans la base de données : en-tête Authorization: Bearer {env.SHOP_TOKEN}, serveur démarré avec SHOP_TOKEN=… ./illusioncms.

Tester : à droite, Tester la requête affiche le statut, la durée et les données. Sous Listes dans le résultat figurent tous les endroits où la réponse contient des listes – un clic reprend le chemin. En dessous se trouve un exemple de template prêt à l’emploi avec les champs trouvés.

Bon à savoir :

  • Si une requête échoue (statut d’erreur, délai dépassé, JSON invalide), la page ne peut pas être rendue. Une fois connecté, vous voyez la cause exacte.
  • Une page avec des données REST reste au plus aussi longtemps dans le cache des pages que la durée de cache de la source.
  • Quiconque peut créer des sources REST peut faire interroger n’importe quelle adresse par le serveur – y compris dans le réseau interne.