Introducción
Bloques de contenido reutilizables que se pueden usar en múltiples páginas.
Más información sobre la interfaz de usuario del módulo https://doc.oneentry.cloud/docs/category/blocks
🎯 ¿Qué hace este módulo?
El módulo Blocks te permite obtener componentes de contenido reutilizables (bloques) — conjuntos de atributos que creas una vez en el panel de administración y reutilizas en páginas y páginas de productos: encabezados, pies de página, banners, testimonios, deslizadores y widgets de productos/recomendaciones. Actualiza un bloque una vez y se cambia en todas partes donde se utiliza.
El SDK es solo de lectura: obtienes bloques aquí y los creas o editas en el panel de administración de OneEntry.
🚀 Inicio Rápido
Inicializa el módulo desde defineOneEntry:
const { Blocks } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
Obtén un solo bloque por su marcador y lee sus atributos:
// 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);
✨ Conceptos Clave
¿Qué es un Bloque?
Un bloque es un componente de contenido reutilizable que contiene:
identifier— marcador único utilizado para referenciarlo en el código (siempre usa el marcador; nunca cambia)localizeInfos— datos localizados (por ejemplo,title), contenido diferente por idiomatype— elBlockTypeque determina lo que renderiza el bloqueisVisible— bandera de visibilidadattributeValues— campos personalizados que defines a través de AttributesSets
Estructura del Bloque
{
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
}
📋 Lo Que Necesitas Saber
- Referencia bloques por marcador (
identifier) en el código — los marcadores nunca cambian. - Los bloques se crean en el panel de administración. El SDK es de solo lectura.
- Los campos personalizados provienen de AttributesSets. Ejemplos: un bloque de pie de página (derechos de autor, enlaces sociales, información de contacto), un banner principal (título, CTA, imagen de fondo), un testimonio (autor, foto, cita, calificación).
- Bloques vs. Páginas. Una página es un documento autónomo con una URL (por ejemplo,
/about) creado en el módulo Pages; un bloque es un componente reutilizable que insertas en las páginas.
📊 Tabla de Referencia Rápida - Métodos Comunes
| Método | Qué Hace | Cuándo Usar |
|---|---|---|
| getBlocks() | Obtener todos los bloques (paginados, filtrados) | Listar todos los bloques disponibles |
| getBlockByMarker() | Obtener bloque por marcador | Obtener un bloque específico en el código |
| searchBlock() | Buscar bloques | Obtener bloques |
| getFrequentlyOrderedProducts() | Productos frecuentemente ordenados | "A menudo ordenados juntos" |
| getCartComplement() | "Completa tu carrito" por contexto del carrito | Venta cruzada desde el carrito |
| getCartComplementByProductIds() | "Completa tu carrito" por productIds | Venta cruzada para productos dados |
| getCartSimilar() | "Similar al carrito" por contexto del carrito | Alternativas a los artículos del carrito |
| getCartSimilarByProductIds() | "Similar al carrito" por productIds | Alternativas para productos dados |
| getWishlistSimilar() | "Similar a la lista de deseos" por lista de deseos | Alternativas a los artículos de la lista de deseos |
| getWishlistSimilarByProductIds() | "Similar a la lista de deseos" por productIds | Alternativas para productos dados |
| getPersonalRecommendations() | Recomendaciones personales | Feed de productos personalizados |
| getRecentlyViewed() | Productos vistos recientemente | Widget de "Vistos recientemente" |
| getRepeatPurchase() | Productos para compra repetida | Widget de "Comprar de nuevo" |
| getTrending() | Productos en tendencia | Widget de "Tendencias ahora" |
| getSlides() | Árbol de diapositivas del bloque deslizante | Renderizar un deslizador/carrusel |
🧩 Tipos de Bloques
El type de un bloque (el BlockType) determina lo que renderiza. Además de los tipos base (common_block, product_block, similar_products_block, form, y otros), están disponibles los siguientes tipos de bloques de productos y personalización:
| Tipo de bloque | Método |
|---|---|
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() |
Los bloques de personalización (vistos recientemente, compra repetida, recomendaciones personales, carrito/lista de deseos) se basan en la actividad del usuario y funcionan tanto para usuarios autorizados como para invitados (ver Modo invitado).
Fijando el precio (signPrice)
Los métodos de bloques de productos y recomendaciones (getCartSimilar, getRecentlyViewed, getTrending, getPersonalRecommendations, getRepeatPurchase, getCartComplement, getFrequentlyOrderedProducts, …) aceptan un argumento opcional signPrice. Toma el marcador de un almacenamiento de pedidos y le pide al servidor que bloquee los precios de los productos devueltos por un tiempo limitado, de modo que el precio que un cliente ve en un widget de recomendaciones sea el precio que paga al finalizar la compra.
signPrice— tipostringMarcador de almacenamiento de pedidos para fijar precios. Si se establece el parámetro, el precio se fija por un cierto tiempo.
- En los métodos de recomendación,
signPricees el último argumento posicional (después delangCode). - En las variantes
…ByProductIds(getCartSimilarByProductIds,getCartComplementByProductIds, …) es un campo del cuerpo de la solicitud (body.signPrice).
Cada producto devuelto lleva un token de signedPrice que codifica el precio bloqueado:
const products = await Blocks.getCartSimilar("cart_similar_block", "en_US", "orders");
const signedPrice = products[0].signedPrice;
➡️ Reutiliza ese token al crear el pedido — consulta la sección Precio de producto fijo (signedPrice) del módulo Orders. El mismo parámetro de fijación de precios también existe en el módulo Products (en userQuery.signPrice).
❓ Preguntas Comunes (FAQ)
¿Cuál es la diferencia entre Bloques y Páginas?
- Páginas/Páginas de Productos — páginas autónomas con URLs (por ejemplo,
/about) creadas en el módulo Pages, a las que agregas bloques y otros componentes. - Bloques — componentes reutilizables insertados en páginas (por ejemplo, un pie de página).
Piensa en una página como un documento completo y un bloque como un párrafo que reutilizas en documentos.
¿Cómo actualizo el contenido de un bloque?
Edítalo en el panel de administración de OneEntry (sección de Blocks). Todas las páginas que usan ese bloque se actualizan automáticamente.
¿Debería crear muchos bloques pequeños o pocos bloques grandes?
Prefiere muchos bloques pequeños y enfocados (por ejemplo, header_logo, footer_social_links) en lugar de un gran bloque entire_page_layout — los bloques pequeños son más fáciles de reutilizar y mantener.
¿Cómo muestro/oculto bloques condicionalmente?
Verifica el campo isVisible en el bloque obtenido.
¿Cómo manejo la falta de bloques de manera elegante?
Envuelve la obtención en un try/catch y renderiza un fallback cuando no se encuentra un bloque.
🎓 Mejores Prácticas
- Crea bloques pequeños y enfocados (responsabilidad única).
- Usa marcadores descriptivos (
global_footer, noblock1); en minúsculas con guiones bajos. - Referencia bloques por marcador en el código — los marcadores nunca cambian.
- Almacena en caché los bloques — cambian raramente.
- Maneja la falta de bloques de manera elegante (try/catch).
🔗 Documentación Relacionada
- Módulo Pages - Gestiona páginas que utilizan bloques
- Módulo AttributesSets - Define atributos de bloque
- Módulo Products - Usa bloques en páginas de productos
- Módulo User Activity - Impulsa bloques de personalización