Introduction
Des blocs de contenu réutilisables qui peuvent être utilisés sur plusieurs pages.
Plus d'informations sur l'interface utilisateur du module https://doc.oneentry.cloud/docs/category/blocks
🎯 Que fait ce module ?
Le module Blocks vous permet de récupérer des composants de contenu réutilisables (blocs) — des ensembles d'attributs que vous créez une fois dans le panneau d'administration et réutilisez sur les pages et les pages de produits : en-têtes, pieds de page, bannières, témoignages, curseurs et widgets de produits/recommandations. Mettez à jour un bloc une fois et il change partout où il est utilisé.
Le SDK est en lecture seule : vous récupérez des blocs ici et les créez ou les modifiez dans le panneau d'administration OneEntry.
🚀 Démarrage rapide
Initialisez le module depuis defineOneEntry :
const { Blocks } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
Récupérez un seul bloc par son marqueur et lisez ses attributs :
// Fetch the "footer" block.
const block = await Blocks.getBlockByMarker("footer", "en_US");
console.log(block.identifier, block.type, block.isVisible);
// "footer" "common_block" true
// Custom fields live in attributeValues.
console.log(block.attributeValues);
✨ Concepts clés
Qu'est-ce qu'un Bloc ?
Un bloc est un composant de contenu réutilisable contenant :
identifier— marqueur unique utilisé pour le référencer dans le code (utilisez toujours le marqueur ; il ne change jamais)localizeInfos— données localisées (par exemple,title), contenu différent par languetype— leBlockTypequi détermine ce que le bloc rendisVisible— indicateur de visibilitéattributeValues— champs personnalisés que vous définissez via AttributesSets
Structure du Bloc
{
id: 3, // unique ID
localizeInfos: { // block localized data
title: 'Block', // block localized title
},
version: 0, // block version
position: 1, // block position in array of blocks
identifier: 'block', // block identifier (marker)
type: 'common_block', // block type
templateIdentifier: null, // template identifier
isVisible: true, // visibility
attributeValues: {}, // block attributes
}
📋 Ce que vous devez savoir
- Référencez les blocs par marqueur (
identifier) dans le code — les marqueurs ne changent jamais. - Les blocs sont créés dans le panneau d'administration. Le SDK est en lecture seule.
- Les champs personnalisés proviennent de AttributesSets. Exemples : un bloc de pied de page (droits d'auteur, liens sociaux, informations de contact), une bannière héro (titre, CTA, image de fond), un témoignage (auteur, photo, citation, évaluation).
- Blocs vs. Pages. Une page est un document autonome avec une URL (par exemple,
/about) créé dans le module Pages ; un bloc est un composant réutilisable que vous insérez dans des pages.
📊 Tableau de référence rapide - Méthodes courantes
| Méthode | Ce qu'elle fait | Quand l'utiliser |
|---|---|---|
| getBlocks() | Obtenir tous les blocs (paginé, filtré) | Lister tous les blocs disponibles |
| getBlockByMarker() | Obtenir un bloc par marqueur | Récupérer un bloc spécifique dans le code |
| searchBlock() | Rechercher des blocs | Récupérer des blocs |
| getFrequentlyOrderedProducts() | Produits fréquemment commandés | "Souvent commandés ensemble" |
| getCartComplement() | "Complétez votre panier" par contexte de panier | Vente croisée depuis le panier |
| getCartComplementByProductIds() | "Complétez votre panier" par productIds | Vente croisée pour des produits donnés |
| getCartSimilar() | "Similaire au panier" par contexte de panier | Alternatives aux articles du panier |
| getCartSimilarByProductIds() | "Similaire au panier" par productIds | Alternatives pour des produits donnés |
| getWishlistSimilar() | "Similaire à la liste de souhaits" par liste de souhaits | Alternatives aux articles de la liste de souhaits |
| getWishlistSimilarByProductIds() | "Similaire à la liste de souhaits" par productIds | Alternatives pour des produits donnés |
| getPersonalRecommendations() | Recommandations personnelles | Fil d'actualité de produits personnalisés |
| getRecentlyViewed() | Produits récemment consultés | Widget "Récemment consulté" |
| getRepeatPurchase() | Produits pour achat répété | Widget "Acheter à nouveau" |
| getTrending() | Produits tendance | Widget "Tendance actuelle" |
| getSlides() | Arbre des diapositives du bloc curseur | Rendre un curseur/carrousel |
🧩 Types de Blocs
Le type d'un bloc (le BlockType) détermine ce qu'il rend. En plus des types de base (common_block, product_block, similar_products_block, form, et d'autres), les types de blocs de produits et de personnalisation suivants sont disponibles :
| Type de bloc | Méthode |
|---|---|
frequently_ordered_block | getFrequentlyOrderedProducts() |
trending_block | getTrending() |
recently_viewed_block | getRecentlyViewed() |
repeat_purchase_block | getRepeatPurchase() |
slider_block | getSlides() |
personal_recommendations_block | getPersonalRecommendations() |
cart_complement_block | getCartComplement() / getCartComplementByProductIds() |
cart_similar_block | getCartSimilar() / getCartSimilarByProductIds() |
wishlist_similar_block | getWishlistSimilar() / getWishlistSimilarByProductIds() |
Les blocs de personnalisation (produits récemment consultés, achat répété, recommandations personnelles, panier/liste de souhaits) sont alimentés par l'activité utilisateur suivie et fonctionnent pour les utilisateurs autorisés et les invités (voir Mode invité).
Fixation du prix (signPrice)
Les méthodes de blocs de produits et de recommandations (getCartSimilar, getRecentlyViewed, getTrending, getPersonalRecommendations, getRepeatPurchase, getCartComplement, getFrequentlyOrderedProducts, …) acceptent un argument signPrice optionnel. Il prend le marqueur d'un stockage de commande et demande au serveur de verrouiller les prix des produits retournés pour une durée limitée, de sorte que le prix qu'un client voit dans un widget de recommandation est le prix qu'il paie à la caisse.
signPrice— typestringMarqueur de stockage de commande pour la fixation des prix. Si le paramètre est défini, le prix est fixé pour un certain temps.
- Sur les méthodes de recommandation,
signPriceest le dernier argument positionnel (aprèslangCode). - Sur les variantes
…ByProductIds(getCartSimilarByProductIds,getCartComplementByProductIds, …) c'est un champ de la demandebody(body.signPrice).
Chaque produit retourné porte alors un jeton signedPrice qui encode le prix verrouillé :
const products = await Blocks.getCartSimilar("cart_similar_block", "en_US", "orders");
const signedPrice = products[0].signedPrice;
➡️ Réutilisez ce jeton lors de la création de la commande — voir la section Prix fixe du produit (signedPrice) du module Orders. Le même paramètre de fixation des prix existe également sur le module Products (dans userQuery.signPrice).
❓ Questions Fréquemment Posées (FAQ)
Quelle est la différence entre les Blocs et les Pages ?
- Pages/Pages de Produits — pages autonomes avec des URL (par exemple,
/about) créées dans le module Pages, auxquelles vous ajoutez des blocs et d'autres composants. - Blocs — composants réutilisables insérés dans des pages (par exemple, un pied de page).
Pensez à une page comme à un document complet et à un bloc comme à un paragraphe que vous réutilisez dans plusieurs documents.
Comment mettre à jour le contenu d'un bloc ?
Modifiez-le dans le panneau d'administration OneEntry (section Blocs). Toutes les pages utilisant ce bloc se mettent à jour automatiquement.
Dois-je créer de nombreux petits blocs ou quelques grands blocs ?
Préférez de nombreux petits blocs ciblés (par exemple, header_logo, footer_social_links) plutôt qu'un grand bloc entire_page_layout — les petits blocs sont plus faciles à réutiliser et à maintenir.
Comment afficher/masquer des blocs de manière conditionnelle ?
Vérifiez le champ isVisible sur le bloc récupéré.
Comment gérer gracieusement les blocs manquants ?
Enveloppez la récupération dans un try/catch et affichez un fallback lorsqu'un bloc n'est pas trouvé.
🎓 Meilleures Pratiques
- Créez des blocs petits et ciblés (responsabilité unique).
- Utilisez des marqueurs descriptifs (
global_footer, pasblock1) ; en minuscules avec des underscores. - Référencez les blocs par marqueur dans le code — les marqueurs ne changent jamais.
- Mettez en cache les blocs — ils changent rarement.
- Gérez gracieusement les blocs manquants (try/catch).
🔗 Documentation Connexe
- Module Pages - Gérer les pages qui utilisent des blocs
- Module AttributesSets - Définir les attributs des blocs
- Module Products - Utiliser des blocs dans les pages de produits
- Module User Activity - Alimente les blocs de personnalisation