Aller au contenu principal

Introduction

Récupérez des modèles d'affichage qui contrôlent la manière dont les pages, les blocs, les produits et les images sont rendus dans votre application.

Plus d'informations sur les modèles dans le panneau d'administration OneEntry : https://doc.oneentry.cloud/docs/category/templates

🎯 Que fait ce module ?​

Le module Templates vous permet de modifier la structure et l'apparence de votre projet sans altérer son code source. Vous créez des modèles dans le panneau d'administration OneEntry (Paramètres > Modèles), étiquetez vos composants avec eux, et ce module récupère ces configurations afin que votre application puisse rendre le contenu avec un style cohérent.

Cette séparation de la structure et du code vous permet de passer d'implémentations de modèles pour influencer la manière dont les entités sont rendues, le tout sans redéploiement. Le SDK est en lecture seule : vous ne pouvez pas créer de modèles par son intermédiaire.

🚀 Démarrage rapide​

Initialisez le module depuis defineOneEntry :


const { Templates } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Récupérez les modèles et lisez leur configuration :

// Fetch all templates of a given BlockType.
const productTemplates = await Templates.getTemplateByType("product", "en_US");

productTemplates.forEach((tpl) => {
  console.log(tpl.identifier, tpl.title, tpl.generalTypeName);
});

// Or fetch a single template by its marker.
const card = await Templates.getTemplateByMarker("product_thumbnail", "en_US");
console.log(card.attributeValues);

✨ Concepts clés​

Qu'est-ce qu'un modèle ?​

Un Modèle (ITemplateEntity) est une configuration d'affichage définissant comment le contenu doit apparaître :

  • Type général (generalTypeName) - La catégorie d'entité à laquelle le modèle s'applique, un BlockType tel que product, common_page, common_block, form, ou order
  • Titre (title) - Nom du modèle affiché dans le panneau d'administration (non unique)
  • Marqueur (identifier) - Identifiant unique pour référence dans le code (utilisez ceci, pas l'ID)
  • Valeurs d'attributs (attributeValues) - Carte des valeurs d'attributs indexées par marqueur
  • Ensemble d'attributs (attributeSetIdentifier) - Ensemble d'attributs associé optionnel

Structure du modèle (ITemplateEntity) :

interface ITemplateEntity {
  id: number;                              // Unique identifier
  title: string;                           // Template name (non-unique)
  identifier: string;                      // Template marker (unique)
  generalTypeId: number;                   // Type ID reference
  version: number;                         // Version number
  generalTypeName: BlockType;              // General type name
  attributeSetIdentifier: string | null;   // Associated attribute set
  attributeValues: IAttributeValues;       // Map of attribute values keyed by marker
  position: number;                        // Sort position
}

Types de modèles (BlockType)​

Le type d'un modèle est son generalTypeName, une valeur de BlockType. getTemplateByType(type) accepte le même BlockType. Valeurs courantes :

TypeCatégorie d'entitéCas d'utilisation exemples
productProduitsDétails du produit, affichage du produit
catalog_pagePages de catalogueListe de catégories, résultats de recherche
common_pagePages régulièresArticle de blog, page d'atterrissage, page à propos
error_pagePages d'erreurPage 404, page 500, mises en page d'erreur personnalisées
common_blockBlocs de contenuCartes de contenu, bannières, sections, widgets
formFormulairesFormulaire de contact, formulaire d'inscription, enquête
orderCommandesConfirmation de commande, historique des commandes
serviceEntités de serviceContenu lié aux services

📋 Ce que vous devez savoir​

Les modèles sont créés dans le panneau d'administration​

Vous ne pouvez pas créer de modèles via le SDK - ils sont créés dans le panneau d'administration OneEntry (Paramètres > Modèles). Chaque modèle nécessite un Nom (non unique), un Marqueur unique, et un Type (la catégorie d'entité à laquelle il s'applique). Le SDK est destiné à récupérer les configurations de modèles, pas à les créer.

Utilisez des marqueurs, pas des IDs​

Référez-vous toujours aux modèles par leur marqueur (identifier) dans votre code - les marqueurs sont stables à travers les environnements, les IDs ne le sont pas. Utilisez getTemplateByMarker(marker) pour un modèle unique, getTemplateByType(type) pour tous les modèles d'un BlockType, et getAllTemplates() pour chaque modèle regroupé par type.

Modèles manquants​

Les méthodes retournent un objet d'erreur (IError) lorsqu'un modèle n'est pas trouvé. Vérifiez toujours que les marqueurs existent et gérez les modèles manquants avec soin.

Mise en cache​

Les modèles changent rarement - mettez-les en cache (localStorage/sessionStorage sur le frontend, Redis/mémoire sur le backend ; un TTL d'environ 1 heure est un bon point de départ).

📊 Tableau de référence rapide​

MéthodeDescriptionCas d'utilisation
getAllTemplates()Obtenir tous les modèles regroupés par typeLister tous les modèles disponibles
getTemplateByType()Obtenir des modèles par type d'entitéRécupérer des modèles pour un type d'entité spécifique
getTemplateByMarker()Obtenir un modèle par marqueurRécupérer une configuration de modèle spécifique

❓ Questions fréquentes (FAQ)​

Quelle est la différence entre les modèles et les aperçus de modèles ?​

Les modèles configurent l'affichage général du contenu (pages, blocs, produits), tandis que les aperçus de modèles gèrent spécifiquement les images d'attributs de produit (échantillons de couleur, aperçus de matériaux). Utilisez les modèles pour le contenu principal, les aperçus de modèles pour les images d'attributs.

Comment puis-je récupérer un modèle spécifique ?​

Utilisez getTemplateByMarker(marker) pour un modèle unique par son identifiant, ou getTemplateByType(type) pour récupérer tous les modèles d'un BlockType donné (par exemple, product, common_page). Utilisez getAllTemplates() pour récupérer chaque modèle regroupé par type.

Que se passe-t-il si je fais référence à un modèle qui n'existe pas ?​

Les méthodes retournent un objet d'erreur (IError). Vérifiez toujours que les marqueurs de modèle existent et gérez les modèles manquants avec soin.

Quels types de modèles devrais-je utiliser pour mon contenu ?​

Choisissez en fonction du type d'entité : common_page pour les pages standard, catalog_page pour les listes de produits, common_block pour les blocs de contenu, product pour les détails de produit. Faites correspondre le type de modèle à votre catégorie de contenu.

🎓 Meilleures pratiques​

  • Utilisez des marqueurs, pas des IDs - les marqueurs sont stables à travers les environnements.
  • Créez des marqueurs sémantiques - product_card, pas tpl_1.
  • Mettez en cache les modèles - réduisez les appels API pour des données rarement changeantes.
  • Gérez les modèles manquants - vérifiez la forme de retour IError.

🔗 Documentation connexe​