Aller au contenu

Documentation pour développeurs · API des thèmes v1.0 · v1.1

Créez un thème complet pour un site d’entreprise, en toute sécurité.

Les thèmes Eyivo définissent un système visuel complet : structure des pages, typographie, composants et styles. Le propriétaire de l’entreprise ajoute ensuite du contenu autorisé dans l’application, sans déplacer de blocs, modifier le code ni altérer le design.

Principe de base

Liquid détermine comment le site se présente ; Eyivo Core détermine quel contenu de l’entreprise y apparaît.

1. Comprendre le fonctionnement

Le système repose sur trois responsabilités distinctes. Les séparer permet de comprendre la version 1.

Eyivo Core

Stocke les informations de l’entreprise, les pages, les médias, le référencement, la navigation et l’état de publication. C’est la référence pour le contenu.

Package du thème

Définit la structure fixe des pages, les sections autorisées, les schémas des composants personnalisés et le CSS. Il n’interroge pas les données et n’exécute pas de code applicatif.

Éditeur d'application

Génère des formulaires sécurisés à partir du schéma. Les propriétaires peuvent mettre à jour le texte, les images, les pages et l'ordre des sections à l'intérieur d'une zone.

Pas un constructeur de pages : le propriétaire peut ajouter une section autorisée à main et choisir sa position numérique. Il ne peut pas créer de zone, déplacer un hero dans le pied de page ni modifier les fichiers de votre thème. Il peut ajouter son propre CSS de site, chargé après vos feuilles de style, et donner des noms de classe aux sections (voir CSS personnalisé du site).

2. Démarrage rapide : un thème minimal et utilisable

Chaque thème v1 fournit sa mise en page, ses styles et ses scripts. Son auteur peut les organiser librement. Un thème n’hérite jamais de la mise en page ou des ressources d’un autre thème. Les composants communs eyivo: et les sept types de pages de repli proviennent de theme-core ; le thème ne contient que les types de pages qu’il remplace et les composants qu’il déclare dans l’espace de noms theme:.

Chaque thème v1 nécessite un fichier de mise en page par défaut. Les dossiers page-types/ et components/ sont facultatifs si le package utilise uniquement les éléments de repli du noyau :

acme-industrial/
├── theme.json
├── layouts/default.liquid
├── page-types/
│   └── home.liquid        # optional override
├── components/
│   └── featured_course.liquid
├── locales/
│   ├── en.json
│   └── tr.json
├── screenshots/
│   └── home-desktop.png   # demo-data screenshot
└── assets/
    ├── css/theme.css
    └── js/theme.js        # Theme API 1.1, reviewed

layouts/default.liquid provient toujours du thème actif et définit le document public complet. Eyivo cherche d’abord le type de page demandé dans ce thème, puis utilise theme-core/page-types en repli. Le noyau ne fournit ni mise en page ni ressources ; le contenu de repli reste donc intégré et stylisé par le thème actif.

3. Décrivez le modèle dans theme.json

Le manifeste déclare les capacités du thème et définit le contrat utilisé pour générer les formulaires de l’application. Il précise les structures de pages disponibles, les zones de chaque structure et les données que chaque composant peut stocker. Les thèmes intégrés déclarent explicitement les dix types de pages standard et incluent les fichiers Liquid correspondants. Les thèmes personnalisés peuvent continuer à utiliser les modèles de secours du noyau pour les types non déclarés.

{
  "name": "Acme Industrial",
  "version": "1.0.0",
  "eyivo_theme_api": "1.0",
  "settings": {
    "primary_color": { "type": "color" },
    "button_radius": { "type": "number" }
  },
  "page_types": {
    "home": {
      "areas": {
        "hero": {
          "allowed_components": ["eyivo:hero"],
          "min": 0,
          "max": 1
        },
        "main": {
          "allowed_components": ["eyivo:rich_text", "eyivo:image_text", "theme:featured_course"]
        }
      }
    },
    "page": { "areas": { "main": { "allowed_components": ["eyivo:rich_text"] } } }
  },
  "components": {
    "featured_course": {
      "variants": ["card", "compact"],
      "schema": {
        "heading": { "type": "text", "required": true, "translatable": true },
        "summary": { "type": "textarea", "translatable": true }
      }
    }
  }
}
CléSignificationExemple
keyLibellé facultatif pour votre propre référence. Eyivo attribue à chaque thème téléversé son propre identifiant ; la clé ne détermine donc jamais à quel thème appartient un téléversement.acme-industrial
versionLa version immuable du thème, selon le versionnement sémantique.1.2.0
eyivo_theme_apiLe contrat de l’API publique Eyivo pris en charge par le package.1.0
areasLes emplacements nommés que votre fichier de page Liquid affiche à des positions fixes.hero, main, bottom
allowed_componentsLes composants que l’éditeur peut ajouter à une zone.["eyivo:hero"]
componentsLes définitions des composants theme: propres au thème actif. Les définitions communes eyivo: restent dans theme-core.featured_course
min/maxLimites facultatives sur le nombre de sections dans cette zone.max: 1

Types de pages de repli : les types intégrés sont home, page, gallery, contact, products, product et videos. Si vous omettez un type, sa définition et son fichier Liquid proviennent de theme-core. Ne déclarez un type que si le thème fournit aussi le fichier de remplacement page-types/<type>.liquid correspondant.

L’éditeur utilise les définitions fusionnées des types de pages : celles du thème actif remplacent les définitions correspondantes du noyau, tandis que les types omis restent disponibles depuis le noyau.

4. Contenu de démonstration complet dans demo.json

Chaque package transmis doit contenir un fichier demo.json portable, limité aux brouillons, ainsi qu’au moins une capture d’écran réalisée avec ces données chargées. Les thèmes intégrés utilisent le même schéma. N’incluez ni identifiants de base de données, ni domaines de clients, ni identifiants de connexion ou de stockage d’objets.

{
  "schema_version": 2,
  "default_locale": "en",
  "label": "Northline Build Co.",
  "summary": "Thoughtful construction for the way life happens.",
  "media": {
    "media/hero.jpg": {
      "public_url": "https://cdn.eyivo.com/demo/hero.jpg",
      "mime_type": "image/jpeg",
      "original_name": "hero.jpg",
      "bytes": 184000,
      "width": 1600,
      "height": 900
    },
    "assets/images/team.jpg": {
      "mime_type": "image/jpeg",
      "original_name": "team.jpg"
    }
  },
  "company": { "display_name": "Northline Build Co.", "logo_asset": "media/hero.jpg" },
  "theme_settings": { "settings": { "header_cta_url": "/contact" } },
  "pages": [],
  "catalog": [],
  "galleries": [],
  "videos": []
}
CléObjectif
mediaURL sources publiques et métadonnées indexées par des identifiants de ressources portables. Réutilisez ces identifiants pour hero_asset, cover_asset, media_asset, le champ asset des images de galerie, logo_asset et favicon_asset.
companyProfil de l’entreprise, liens vers les réseaux sociaux, couleurs de marque, logo ou favicon facultatif et traductions organisées par langue.
theme_settingsParamètres initiaux du thème, avec traductions facultatives organisées par langue.
pagesType, ordre de tri, état de navigation, référencement, paramètres de page, composants et contenu organisés par langue.
catalogEntrées de catalogue avec contenu organisé par langue et cover_asset facultatif.
galleriesMétadonnées de la galerie et images. Chaque image nécessite un asset et un alt_text non vide.
videosUne URL externe source_url ou un media_asset, le mode de présentation et le contenu organisé par langue.

Chaque entrée media doit avoir soit une public_url en https sur un hôte autorisé (l’hôte des médias de démo Eyivo cdn.eyivo.com ou images.pexels.com), soit un fichier inclus dans le thème sous assets/, désigné par son chemin et sans public_url. Les autres hôtes, http, les adresses IP, les autres ports et les redirections sont refusés avec le diagnostic d’envoi demo_media_url. mime_type, width et height ne sont que des indications : Eyivo détecte le type réel à partir du contenu téléchargé, qui doit être une image ou une vidéo autorisée de 20 Mo au maximum.

Les formulaires de démo utilisent des liaisons de formulaire portables, qu’Eyivo résout séparément pour chaque site qui importe la démo. Les images de démo importées deviennent des références de médias ordinaires sur ce site ; les supprimer là ne supprime jamais l’original partagé.

Pages et composants

{
  "type": "home",
  "sort_order": 0,
  "navigation_visible": true,
  "hero_asset": "media/hero.jpg",
  "translations": {
    "en": { "slug": "home", "title": "Home", "meta_title": "Home | Northline" },
    "tr": { "slug": "ana-sayfa", "title": "Ana sayfa", "meta_title": "Ana sayfa | Northline" }
  },
  "components": [{
    "component_type": "eyivo:hero",
    "area": "hero",
    "position": 100,
    "variant": "split",
    "data": { "primary_url": "/contact" },
    "translations": {
      "en": { "heading": "Built for real life", "primary_label": "Contact us" },
      "tr": { "heading": "Gerçek yaşam için tasarlandı", "primary_label": "Bize ulaşın" }
    }
  }]
}

Les types et zones de composants doivent être déclarés dans le manifeste du thème actif ou theme-core. Utilisez des chemins relatifs tels que /contact pour les liens vers le même site. Les démos de page d’accueil intégrées utilisent leur image de bannière existante comme fond sur toute la largeur, avec un voile lisible et un texte adaptatif : immersive dans la plupart des thèmes et centered avec image dans Compact. Les autres variantes conservent leur propre mise en page.

Langues de démonstration et repli

L’anglais est la langue de base obligatoire : définissez default_locale sur en. Son absence dans les anciens fichiers signifie aussi anglais. Les autres langues prises en charge sont facultatives ; ne présentez pas des copies anglaises comme des traductions.

Fournissez translations.en et des objets de langue facultatifs pour l’entreprise, les réglages, pages, composants, produits, galeries, légendes et textes alternatifs, vidéos et articles. Les anciens champs anglais sans clé de langue restent acceptés. La création choisit la langue principale du site et utilise l’anglais pour chaque champ absent. Les tableaux remplacent le tableau anglais entier ; les valeurs explicitement vides sont conservées. Seule la langue choisie est importée, sans activer automatiquement d’autres langues.

Utilisez les slugs sources anglais pour les liens internes et les menus portables. L’import les remplace par les slugs traduits, y compris dans le texte enrichi et les articles. Les menus peuvent fournir des tables explicites slugs et labels. Les libellés absents utilisent l’anglais. Les URL externes restent inchangées.

{
  "company": {
    "translations": {
      "en": { "display_name": "Northline", "description": "Built around your needs." },
      "tr": { "display_name": "Northline", "description": "İhtiyaçlarınıza göre tasarlandı." }
    }
  },
  "theme_settings": {
    "settings": { "header_cta_url": "/contact" },
    "translations": {
      "en": { "header_cta_label": "Contact us" },
      "tr": { "header_cta_label": "Bize ulaşın" }
    }
  },
  "menus": {
    "footer": [{ "type": "page", "slug": "contact",
      "slugs": { "en": "contact", "tr": "iletisim" },
      "labels": { "en": "Contact us", "tr": "Bize ulaşın" }
    }]
  }
}

Sécurité des importations et des médias

Les nouveaux sites du tableau de bord incluent les données de démonstration par défaut et publient immédiatement la langue choisie ; le propriétaire peut décocher l’option. Sur un site existant, l’import depuis Identité visuelle crée toujours des brouillons et conserve le contenu publié. L’App centrale copie les images dans la médiathèque du nouveau site et transmet les références par l’API interne. Les masters et les thèmes ne reçoivent jamais les identifiants du stockage objet. Les thèmes utilisent la valeur media.public_url fournie.

Déclarez les captures d’écran dans theme.json.preview avec data_source: "demo_data". Le package doit contenir chaque image preview déclarée.

5. Écrivez la mise en page dont votre thème a besoin

La mise en page par défaut possède tout le document HTML. Rien en dehors du thème actif ne fournit son en-tête, son pied de page, sa feuille de style ou sa structure visuelle. La plateforme n’ajoute que ses propres scripts pour les formulaires, la vérification humaine, le consentement et le badge Eyivo ; les scripts de thème nécessitent Theme API 1.1.

<!doctype html>
<html lang="{{ locale.code }}" dir="{{ locale.direction }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {% eyivo_head %}
  <link rel="stylesheet" href="{{ 'css/theme.css' | asset_url }}">
</head>
<body>
  <header class="site-header">
    <a href="{{ locale.home_url }}">{{ company.name }}</a>
    <nav>
      {% for item in navigation.main %}
        <a href="{{ item.url }}">{{ item.label }}</a>
      {% endfor %}
    </nav>
  </header>

  {{ content | raw }}
</body>
</html>

Le fichier de chaque type de page fixe la position de ses zones dynamiques. Les composants de zone sont déjà des fragments HTML rendus : insérez-les avec | raw. Les valeurs ordinaires sont échappées par défaut.

<main class="home-layout">
  <section class="home-layout__hero">{{ areas.hero | raw }}</section>
  <div class="home-layout__content">{{ areas.main | raw }}</div>
  <aside class="home-layout__footer-cta">{{ areas.bottom | raw }}</aside>
</main>

Rendre directement un composant

Le concepteur peut placer un composant enregistré directement dans une mise en page ou un fichier de type de page. Le thème fixe cet emplacement ; le propriétaire ne peut ni le réordonner ni le supprimer dans le panneau. Transmettez un objet avec data:, des champs de schéma séparés ou les deux ; les champs nommés priment sur les clés correspondantes de data:.

{% eyivo_component "eyivo:cta",
  eyebrow: "Let’s talk",
  heading: page.title,
  text: company.description,
  button_label: "Contact us",
  button_url: routes.contact
%}

{% eyivo_component "theme:featured_course",
  data: page.settings.featured_course,
  variant: "compact"
%}

Le type doit être une chaîne littérale entre guillemets avec un espace de noms. Le rendu direct utilise le même schéma, les mêmes variantes, le même fichier et le même objet component normalisé qu’une instance dans une zone. Un fichier de composant ne peut pas afficher d’autres composants.

Ressources : utilisez toujours {{ 'css/theme.css' | asset_url }}. Eyivo le sert depuis le package actif à /theme-assets/<theme>/css/theme.css ; ne codez en dur ni le nom d’un autre thème ni un chemin du système de fichiers.

En-tête du document, routes et dictionnaires d’interface

Chaque mise en page doit afficher {% eyivo_head %} exactement une fois. Eyivo génère alors le titre, la description, les directives robots, l’URL canonique, les liens hreflang, Open Graph et les données structurées. Utilisez routes.home, routes.contact, routes.catalog, routes.gallery et routes.videos au lieu de coder en dur les routes publiques. Faites passer les URL configurables par | localized_url : les routes internes connues reçoivent le préfixe de la langue active, tandis que les URL externes restent inchangées.

{{ 'Menu' | t }}
{{ theme.settings.header_cta_url | localized_url }}

Créez au besoin des fichiers locales/<locale>.json pour les libellés d’interface propres au thème. La recherche suit cet ordre : anglais du noyau, langue du noyau, anglais du thème, puis langue du thème. Les libellés communs de theme-core fonctionnent ainsi sans copie de fichiers. Placez les textes commerciaux dans le contenu traduisible, les champs des composants ou les paramètres du thème, pas dans les dictionnaires.

Un fichier de composant personnalisé

<article class="featured-course featured-course--{{ component.variant }}">
  <div class="featured-course__content">
    <h1>{{ component.data.heading }}</h1>
    {% if component.data.summary %}<p>{{ component.data.summary }}</p>{% endif %}
  </div>
</article>

Eyivo sélectionne la langue du visiteur pour les champs traduisibles avant le rendu. Un visiteur turc et un visiteur anglophone voient donc la même structure de composant, mais des valeurs différentes dans component.data.heading.

7. Les données Liquid sûres à votre disposition

Liquid reçoit des données simples et normalisées, et non des modèles Laravel ou de base de données. Si une valeur ne figure pas dans ce tableau, traitez-la comme indisponible dans la v1.

ObjetChamps utilesUtilisation typique
sitename, localeNom du site et langue d’origine.
companyname, legal_name, description, address, phone, emailEn-tête, pied de page et informations de contact.
pageid, type, title, slug, body, settingsContenu de page générique et paramètres par page.
seotitle, description, valeurs canoniques/robots/Open Graph lorsqu'elles sont fourniesEn-tête du document.
navigation.mainChaque élément contient label, url et activeMenu du site.
localecode, name, native_name, direction, is_default, home_url, availableLangue du document, direction RTL, liens d'accueil localisés et sélecteurs de langue.
routeshome, contact, catalog, gallery, videos, blogURL système adaptées à la langue ; ne construisez jamais les préfixes dans Liquid.
blogtitle, url, categories, category, posts, post, paginationListe des articles du blog gratuit, archives des catégories et pages d’article. Chaque article fournit son titre, son résumé, son URL, ses dates, ses catégories et son image de couverture. Seul blog.post.body_html contient le HTML sûr généré par le serveur pour le corps de l’article ; affichez-le avec raw. La pagination fournit previous_url et next_url.
theme.settingsParamètres de votre manifesteUtilisez une option de couleur, d’espacement ou de conception configurée.
products/productTitre, URL, résumé et corps traduitsPages de liste et de détail des produits.
galleriesTitre et description traduitsType de page de galerie.
videostitle, description, source_type, source_url, playback_url, mediaUtilisez playback_url pour les fichiers vidéo importés et source_url pour les vidéos HTTP(S) externes, selon source_type. Les images jointes ne sont jamais des sources vidéo. N’utilisez pas le fichier vidéo lui-même comme image d’affiche.
componentid, type, variant, dataÀ l'intérieur d'un fichier de composant uniquement.

Exemple de mise en page adaptée à la langue

<html lang="{{ locale.code }}" dir="{{ locale.direction }}">
<a href="{{ locale.home_url }}">{{ company.name }}</a>
{% if locale.available.size > 1 %}
  <nav aria-label="Language">
    {% for language in locale.available %}
      <a href="{{ language.url }}" lang="{{ language.code }}"
         {% if language.current %}aria-current="page"{% endif %}>
        {{ language.native_name }}
      </a>
    {% endfor %}
  </nav>
{% endif %}

Chaque langue disponible fournit aussi label, direction, is_default, current et has_translation. Eyivo ne propose que les traductions publiées équivalentes ; les thèmes doivent donc utiliser language.url au lieu de construire /en ou un autre préfixe.

Exemple de jeton basé sur les paramètres : style="--brand: {{ theme.settings.primary_color }}". Le réglage doit au préalable être déclaré dans theme.json.

8. Composants directs et dynamiques

Les composants suivent un seul contrat de rendu, avec deux modes de placement. Le concepteur place directement un composant dans une mise en page ou un type de page. Un composant dynamique est enregistré comme instance dans une zone et géré depuis l’éditeur. Chaque instance dynamique possède un ID stable, un type avec espace de noms, une zone, une position, une variante facultative, des données et des traductions. La position définit uniquement l’ordre, pas l’identité.

Types de champs

text, textarea, richtext, number, boolean, select, url, email, image, video, file, color, icon, page, product et repeater.

Espaces de noms

Les composants eyivo: proviennent de theme-core/components, les composants theme: du thème actif et les composants plugin: sont réservés aux futures extensions. Utilisez le type exact avec son espace de noms dans une zone ou avec la balise eyivo_component.

Composant universel : définissez "universal": true dans sa définition pour le rendre disponible dans toutes les zones des types de pages compatibles. Un schéma valide et un fichier Liquid restent obligatoires.

Les liens d’action partagés adaptent les chemins internes connus à la langue active tout en conservant les paramètres de requête et les fragments. Le texte enrichi conserve la mise en forme sûre dans les conteneurs imbriqués de l’éditeur. Les images de galerie vides sont omises, les images de carte sans destination ne sont pas des liens, et les libellés des diapositives et de recherche utilisent la langue d’interface du visiteur.

9. CSS personnalisé du site et classes de section

Les propriétaires peuvent ajouter leur propre CSS à un site et donner des noms de classe aux sections (Design → CSS personnalisé). Écrivez vos thèmes pour que cela fonctionne bien :

  • Ordre de chargement : le CSS du site est ajouté sous forme de <style id="eyivo-custom-css"> juste avant </head>, après toutes les feuilles de style du thème. Gardez </head> dans vos layouts et ne comptez pas sur le fait que votre CSS soit le dernier.
  • Classes de section : le moteur de rendu ajoute les noms de classe d’une section au premier élément rendu par le composant ; donnez donc un seul élément racine à chaque modèle de composant. Les noms sont aussi disponibles via {{ component.css_class }} si vous voulez les placer ailleurs.
  • Points d’accroche stables : conservez les classes body.theme-{key} et layout-{name} et une classe racine stable par composant, pour que le CSS des propriétaires continue de fonctionner d’une version à l’autre. Signalez tout renommage dans les notes de version.
  • Thèmes importés : ils ont aussi un CSS personnalisé de site. Toutes les versions d’un thème importé partagent une feuille de style par site, supprimée lorsque la dernière version du thème sur un site est retirée ou supprimée.
  • Noms réservés : le préfixe de classe eyivo- et l’ID eyivo-custom-css appartiennent à la plateforme.

10. Scripts de thème (Theme API 1.1)

Un thème peut fournir son propre JavaScript pour les menus, carrousels, onglets, filtres et fonctions similaires. Les scripts sont facultatifs : tout thème doit fonctionner sans eux, et les paquets Theme API 1.0 continuent de fonctionner à l’identique, sans scripts.

  • Déclarez-le : indiquez "eyivo_theme_api": "1.1" et "capabilities": {"custom_javascript": true} dans theme.json, et placez chaque fichier directement dans assets/js/. Un paquet contenant des fichiers .js sans déclaration est refusé.
  • Chargez-le : utilisez uniquement <script src="{{ 'js/theme.js' | asset_url }}" defer></script> (ou type="module") pour un fichier du paquet. Les balises s’exécutent dans leur ordre d’apparition.
  • Plusieurs fichiers : chaque fichier est vérifié et autorisé séparément, donc import et export ne sont pas autorisés. Partagez le code via une seule variable globale, comme window.AcmeTheme, et chargez d’abord le fichier qui la définit.
  • Limites : 20 fichiers au maximum, 100 Ko par fichier et 300 Ko au total, texte UTF-8 uniquement.
  • Refusé dans les modèles : scripts en ligne, sources de script externes, attributs de gestionnaire d’événements on…=, URL javascript: et éléments <iframe>, <object>, <embed> et <base>.
  • Code lisible uniquement : envoyez le code source, pas du code minifié, compressé ou encodé. Les bundlers peuvent produire une sortie non minifiée.
  • Statuts : une nouvelle version est En attente de vérification jusqu’à la fin des contrôles, puis Approuvée ou Refusée. Seule une version approuvée peut être prévisualisée ou utilisée. Une version approuvée peut ensuite être Bloquée : les sites gardent le thème sans ses scripts.
  • Trois contrôles automatiques, dans l’ordre : code lisible ; règles de code (pas de eval, new Function, document.write, redirections de page, window.open, cookies ou stockage du navigateur, WebAssembly, minuteries avec chaînes, éléments script ou frame créés, ni valeurs de formulaire envoyées sur le réseau) ; et une vérification de sécurité par IA. Pour cette vérification, les scripts et les lignes de modèle qui les chargent sont envoyés à un service d’IA. Tout problème relevé refuse la version, avec le fichier et la ligne.

Accepté : un bouton de menu

(function () {
  document.querySelectorAll('[data-menu-toggle]').forEach(function (button) {
    button.addEventListener('click', function () {
      document.body.classList.toggle('menu-open');
    });
  });
})();

Refusé : envoie des valeurs de formulaire ailleurs

form.addEventListener('submit', function () {
  fetch('/collect', { method: 'POST', body: form.elements.email.value });
});
  • Propriétaire uniquement : les scripts approuvés ne s’exécutent que sur les sites du compte qui a envoyé le thème, et seulement tant que la plateforme et le propriétaire du site les autorisent.
  • Politique de sécurité : les pages qui exécutent des scripts de thème autorisent exactement les fichiers vérifiés, fixés par leurs empreintes SHA-256, avec connect-src 'self', sans frames ni workers, et sans eval. Modifier un fichier nécessite une nouvelle version. Les images et feuilles de style peuvent encore être chargées en https: ; la vérification refuse donc aussi les données envoyées via des URL d’images ou de feuilles de style.
  • Après approbation : les navigateurs signalent les tentatives de violation de la politique. Les signalements de trois visiteurs en 24 heures bloquent la version ; les signalements d’abus de trois visiteurs en 7 jours désactivent les scripts sur ce site et revérifient la version. Les propriétaires reçoivent un e-mail lorsqu’une version est approuvée, refusée ou bloquée.
  • Fonctions de la plateforme : les scripts ne doivent pas remplacer, envelopper ni masquer les formulaires et leurs champs cachés, la vérification humaine, la bannière de consentement, le badge Eyivo ou la barre du propriétaire.

11. Catalogue des composants disponibles

Ces 30 composants eyivo: partagés constituent la bibliothèque v1 complète et proviennent de theme-core. Un thème peut aussi déclarer et implémenter ses propres composants theme:.

Variantes : spliteditorialcenteredimmersive

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Oui Oui —
summary textarea Non Oui —
image_url url Non Non —
image_alt text Non Oui —
primary_label text Non Oui —
primary_url url Non Non —
secondary_label text Non Oui —
secondary_url url Non Non —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
body richtext Non Oui —

Variantes : image_leftimage_rightoverlap

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
body richtext Non Oui —
image_url url Non Non —
image_alt text Non Oui —
badge text Non Oui —
button_label text Non Oui —
button_url url Non Non —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
intro textarea Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
intro textarea Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
intro textarea Non Oui —
button_label text Non Oui —
button_url url Non Non —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
text textarea Non Oui —
submit_label text Non Oui —
form_binding select Non Non —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
heading text Non Oui —
text textarea Non Oui —
whatsapp_url url Non Non —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
address textarea Non Oui —
map_url url Non Non —
image_url url Non Non —
image_alt text Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
heading text Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
heading text Non Oui —
placeholder text Non Oui —
categories repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
summary textarea Non Oui —
video_url url Non Non —
poster_url url Non Non —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
price text Non Oui —
period text Non Oui —
features repeater Non Oui —
button_label text Non Oui —
button_url url Non Non —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
label text Non Oui —
heading text Non Oui —
body textarea Non Oui —
button_label text Non Oui —
button_url url Non Non —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
items repeater Non Oui —

Variantes : aucune

Le composant partagé eyivo:faq conserve les mêmes champs et le même balisage dans chaque thème. Chaque thème le présente avec sa propre typographie, ses espacements et ses couleurs.

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
heading text Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
heading text Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
text textarea Non Oui —
button_label text Non Oui —
button_url url Non Non —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
heading text Non Oui —
items repeater Non Oui —

Variantes : aucune

ChampTypeObligatoireTraduisibleOptions
eyebrow text Non Oui —
heading text Non Oui —
intro textarea Non Oui —
items repeater Non Oui —

12. Formulaires et historique des demandes

Forms API 1 propose sept processeurs approuvés. Les thèmes définissent présentation et style ; les plugins définissent schéma, validation et traitement. La plateforme assure stockage, vérification et notifications.

Plugin systèmeType de formulaire
eyivo/contactContact contact
eyivo/quote-requestDemande de devis quote_request
eyivo/product-inquiryQuestion produit product_inquiry
eyivo/appointment-requestDemande de rendez-vous appointment
eyivo/course-applicationCandidature à un cours course_application
eyivo/reservation-requestDemande de réservation reservation
eyivo/property-inquiryDemande immobilière property_inquiry

Un formulaire, plusieurs emplacements

La configuration crée un UUID par défaut durable par site/plugin/type. Réutiliser un emplacement conserve cette identité ; créer un formulaire nommé génère un autre UUID. Changer de thème ou réinstaller préserve l’historique. Les thèmes utilisent des alias portables ; le client sélectionne un formulaire enregistré sans saisir d’UUID.

{
  "plugins": ["eyivo/contact", "eyivo/quote-request"],
  "forms": {
    "contact": {"plugin":"eyivo/contact","type":"contact","schema_version":1,"instance":"default"},
    "quote": {"plugin":"eyivo/quote-request","type":"quote_request","schema_version":1,"instance":"default"}
  }
}

Utilisez forms.contact pour le contact et component.form pour les sections de formulaire. Remplacez form_preset par form_binding. Affichez les champs, aides, action, CSRF, form_context signé et verification_html fournis. Seuls les changements de présentation déclarés et les champs supplémentaires autorisés sont acceptés ; la validation obligatoire reste intacte.

forms.contact · component.form · form_binding · form.fields · form.action · form.csrf_token · form.context · form.verification_html

Deux vues, un enregistrement

La boîte commune et les pages liste/détail du plugin affichent les mêmes enregistrements. Les formulaires exigent Panel API 2, submission-list/submission-detail et un lien de menu sans sous-menu. Panel API 1 reste compatible. Consulter ne marque pas comme lu ; lecture, archive et traitement sont distincts, avec record_revision pour les modifications. La désactivation retire les pages du plugin, tandis que la boîte commune conserve les instantanés historiques.

{"components":[{"type":"submission-list","form_type":"contact","detail_page":"submission"}]}
{"components":[{"type":"submission-detail","form_type":"contact","list_page":"submissions"}]}

Données et permissions

Les données utilisent la base de contenu du site et son quota max_db_bytes existant. Aucun quota supplémentaire de nombre ou de conservation. La configuration reste sur le master avec 50 champs, 32 Ko et trois niveaux. Les membres consultent ; modifier exige propriétaire/gestion. Aucun accès direct à la base pour les plugins, ni transfert PHP/Blade vers l’app.

Enregistrement vérifié et notification

La plateforme valide contexte, réponses et Human Verification, puis enregistre demande, utilisation et notification ensemble. Une tentative identique se récupère pendant 24 heures sans doublon. SMTP intervient ensuite avec des reprises possibles ; une erreur mail ne supprime pas la demande. Sans destinataire du formulaire, l’adresse de l’entreprise est utilisée ; si aucune adresse n’est valide, la demande est conservée sans email.

Tous les thèmes fournis suivent ce contrat. Les anciens POST contact renvoient 410 ; les pages de contact GET restent accessibles. Les demandes de rendez-vous ou réservation ne confirment aucune réservation. Processeurs tiers, fichiers et destinations externes arbitraires sont exclus.

POST /__eyivo/forms/{UUID}/submissions
GET /__eyivo/forms/{UUID}/challenge

13. Navigation secondaire et barres latérales

Enregistrez au besoin les menus header, secondary, sidebar, footer et useful_links dans theme.json. Affichez navigation.secondary dans une barre utilitaire et navigation.sidebar à côté des pages ordinaires. Les propriétaires modifient et publient chaque menu avec l’éditeur de menus standard. Gardez le menu principal court ; sur petit écran, la barre latérale doit passer sous le contenu de la page.

Une barre latérale est une zone de mise en page, pas un composant. Déclarez une zone sidebar sur chaque type de page qui l’utilise, avec ses allowed_components (par exemple rich_text, announcement, download_list et contact_actions) et un max, puis affichez areas.sidebar dans un <aside> à côté de navigation.sidebar :

{% if navigation.secondary.size > 0 %}
<nav aria-label="{{ 'Useful information' | t }}">
  {% for item in navigation.secondary %}
    <a href="{{ item.url }}"{% if item.active %} aria-current="page"{% endif %}>{{ item.label }}</a>
  {% endfor %}
</nav>
{% endif %}
<aside aria-label="{{ 'More information' | t }}">
  {% for item in navigation.sidebar %}
    <a href="{{ item.url }}">{{ item.label }}</a>
  {% endfor %}
  {{ areas.sidebar | raw }}
</aside>

15. Modèles de page et modèles de base de secours

Il existe dix types de page standard : home, page, contact, products, product, gallery, videos, blog, blog_category et blog_post. Un thème peut fournir les dix ou seulement certains ; theme-core fournit un modèle fonctionnel pour chaque type que le thème ne déclare pas. Conservez les noms de zone et les liaisons de formulaire des types de base lorsque vous les remplacez, afin que le contenu existant et les formulaires enregistrés continuent de fonctionner après un changement de thème.

16. En-têtes de page

Les en-têtes de sous-page ont deux formes. Sans image, utilisez un bandeau compact avec fil d’Ariane, un surtitre facultatif et le titre de la page. Avec une image, placez le titre, le fil d’Ariane et le résumé au-dessus de l’image et d’un calque contrasté, pour que le texte reste lisible sur toute photo, et inversez le sens du calque dans les mises en page de droite à gauche.

17. Images, galeries et vidéo

Gardez les images envoyées dans des cadres délimités : les images du catalogue conservent leurs proportions et les photos de détail peuvent remplir le cadre avec un recadrage centré. Les galeries peuvent ouvrir l’image originale dans une boîte de dialogue qui se ferme avec Échap et rend le focus au lien de l’image ; sans scripts, liez l’original pour qu’il s’ouvre dans un nouvel onglet. Les carrousels d’images doivent prendre en charge le tactile, les boutons, le clavier et le mouvement réduit.

18. Texte enrichi et règles d’affichage communes

Le composant commun eyivo:rich_text accepte les contenus marqués par l’éditeur et les anciens contenus HTML. Les deux passent par la liste de mise en forme autorisée de la plateforme : paragraphes, titres, listes et liens sûrs s’affichent comme contenu, tandis que scripts, gestionnaires d’événements et liens dangereux sont retirés. Les autres champs de texte restent échappés. Affichez le texte enrichi avec les filtres fournis plutôt qu’avec votre propre traitement HTML.

19. Introductions, zones d’orientation et pages longues

Un type de page peut associer l’en-tête à une zone d’orientation facultative pour des liens rapides ou des informations clés ; si cette zone est vide, l’introduction doit utiliser toute la largeur. Les longues pages éditoriales doivent garder une longueur de ligne lisible et des espacements de titres clairs, et peuvent placer des sections d’appui, comme une liste de vérification ou une note, à côté de l’article sur grand écran et après lui sur petit écran. Chaque mise en page doit rester lisible sans scripts.

20. Animation et mouvement réduit

Les animations décoratives sont facultatives. Respectez prefers-reduced-motion pour les transitions, carrousels et sections animées, et mettez en pause le contenu en mouvement pendant que le visiteur le survole ou y place le focus.

21. Liste de vérification d’un thème complet

Un thème complet fournit les dix modèles de page, met en forme tous les composants communs eyivo:, prend en charge chaque liaison de formulaire portable via les plugins de formulaire existants et la vérification humaine, et fonctionne sur ordinateur, mobile et en mise en page de droite à gauche. Le filtrage du catalogue, les onglets, les carrousels et les menus dépliants sont des améliorations facultatives sur un contenu qui fonctionne sans elles.

22. Du thème activé à la publication

  1. Installez et activez le thème. Eyivo valide le package, enregistre sa clé et sa version, puis présente ses paramètres et les schémas de ses composants dans l’application.
  2. Choisissez un type de page. Eyivo utilise le fichier Liquid et la définition de zone correspondants du thème actif s’ils existent ; sinon, il utilise ceux de theme-core.
  3. Ajoutez les sections autorisées. L’application propose uniquement les types indiqués dans allowed_components. Elle enregistre le texte, les références des médias et les traductions pour chaque instance de composant.
  4. Effectuez un rendu sûr. Eyivo rassemble les données de l’entreprise, de la page, du référencement et de la navigation. Il affiche les composants enregistrés dans les zones, puis les composants directs aux emplacements définis par le concepteur, avant de générer la page et sa mise en page avec le thème actif.
  5. Publiez. Le visiteur reçoit votre HTML et votre CSS, mais jamais les identifiants de base de données, les modèles internes ou le code de l’application.
  6. Mettre à jour avec une nouvelle version. Téléverser un ZIP dans Thèmes personnalisés crée un nouveau thème. Pour modifier un thème existant, ouvrez-le, augmentez version dans theme.json et téléversez une nouvelle version. Chaque site bascule lorsque vous utilisez la nouvelle version comme brouillon puis la publiez ; la version précédente reste disponible pendant 30 jours pour un retour arrière.

23. Validation et erreurs courantes

Si vous voyez…Vérifiez d’abord
« Version d’Eyivo Theme API non prise en charge »Définissez "eyivo_theme_api": "1.0".
Erreur de type de page, de mise en page ou de composant manquantChaque type de page ou composant déclaré par le thème nécessite un fichier .liquid correspondant. Le thème actif doit toujours fournir layouts/default.liquid ; les types de pages intégrés non déclarés utilisent ceux du noyau.
Composant absent de l’éditeurSon type avec espace de noms doit figurer dans la liste allowed_components de cette zone, sauf si sa définition le rend universel.
Composant direct inconnuUtilisez un type eyivo: du catalogue commun entre guillemets, ou déclarez une définition theme: correspondante et son fichier Liquid dans le thème actif.
Champ rejetéDéclarez ce champ dans le schéma du composant et utilisez un type de champ pris en charge. Définissez translatable: true pour le texte propre à chaque langue.
Le thème apparaît sans styleUtilisez le filtre asset_url pour le CSS et vérifiez que le fichier se trouve dans assets/.
Package rejeté pour une syntaxe non sûreRetirez PHP/Blade, env, config, les appels à la base de données ou à HTTP et les accès au système de fichiers. Liquid sert uniquement à la présentation.
Règles des scripts : custom_javascript_declaration, script_file, script_tag, script_import, script_sizeSuivez Scripts de thème. Les points relevés par la vérification apparaissent sur la page de la version avec leur fichier et leur ligne ; corrigez-les et envoyez une nouvelle version.

24. FAQ

Un client peut-il créer une mise en page ou déplacer la section principale sous le pied de page ?

Non. Le client peut modifier le contenu autorisé et réordonner les composants permis au sein d’une zone. Le type de page Liquid définit la mise en page.

Un concepteur peut-il utiliser un composant sans zone modifiable ?

Oui. Utilisez eyivo_component dans une mise en page ou un type de page. Utilisez une zone lorsque le propriétaire du site doit gérer l’instance du composant et son ordre.

Un thème doit-il implémenter tous les types de pages ?

Chaque thème doit prendre en charge le blog. Les types intégrés blog, blog_category et blog_post peuvent utiliser les définitions et fichiers Liquid correspondants de theme-core dans la mise en page du thème actif. Ne déclarez un type que si vous fournissez le fichier de remplacement correspondant. Les thèmes existants restent compatibles. Les routes du blog sont /blog, /blog/category/{slug} et /blog/{slug}, avec le préfixe de langue Eyivo lorsque nécessaire. Conservez eyivo_head pour des métadonnées sûres, des styles de blog adaptatifs et des dimensions d’images limitées dans les cartes.

Un thème peut-il interroger une page, appeler une API ou lire une variable d’environnement ?

Non. Les données sont volontairement transmises sous forme d’objets sûrs, afin que les thèmes restent portables, sécurisés et prévisibles.

Comment publier une mise à jour ?

Publiez une nouvelle version du thème selon le versionnement sémantique. Ne modifiez pas discrètement une version déjà publiée ; les sites doivent passer explicitement à la nouvelle version.

Où stocker les images ?

Utilisez une URL de média Eyivo dans les données du composant ou une ressource du package référencée avec asset_url. N’utilisez pas de chemin arbitraire sur le système de fichiers du serveur.

25. Journal des modifications

  • 31 octobre 2026. Theme API 1.1 : les thèmes peuvent fournir du JavaScript vérifié dans assets/js/ avec la capacité custom_javascript. Les nouvelles versions sont vérifiées automatiquement et affichent En attente de vérification, Approuvée, Refusée ou Bloquée. Les paquets Theme API 1.0 ne changent pas.
  • 31 octobre 2026. Les propriétaires peuvent ajouter un CSS personnalisé de site, chargé après vos feuilles de style, et donner des noms de classe aux sections, ajoutés au premier élément de chaque composant et disponibles via {{ component.css_class }}. Voir CSS personnalisé du site et classes de section.
  • 31 octobre 2026. Les médias de démo de demo.json doivent utiliser un hôte https autorisé (cdn.eyivo.com ou images.pexels.com) ou un fichier inclus sous assets/. Eyivo détecte le type de chaque fichier à partir de son contenu. C’est un correctif de sécurité ; la Theme API reste en 1.0.
  • 30 octobre 2026. Eyivo attribue à chaque thème téléversé son propre identifiant, et key dans theme.json est facultatif. Téléversez les modifications comme nouvelle version depuis la page du thème. Le dépôt d’exemple place le thème dans son dossier sample-theme/, que vous compressez et téléversez. L’exemple de paquet ne montre plus assets/js/, car les téléversements Theme API 1.0 ne peuvent pas contenir de fichiers JavaScript.