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 de Blocks te permite usar componentes de contenido reutilizables (bloques) que contienen conjuntos de atributos y se pueden usar en múltiples páginas y páginas de productos. - como encabezados, pies de página, banners, testimonios o cualquier contenido repetido.
Piénsalo como ladrillos de LEGO para tu sitio web - creas un bloque una vez y lo reutilizas en todas partes donde lo necesites. Cambia el bloque una vez y se actualiza automáticamente en todas partes.
📖 Explicación Simple
Imagina que estás construyendo un sitio web con:
- 🔝 Encabezado - logo, menú de navegación (igual en cada página)
- 🔽 Pie de página - información de contacto, enlaces sociales (igual en cada página)
- 📢 Banner Promocional - oferta especial (aparece en múltiples páginas)
- ⭐ Testimonios - reseñas de clientes (reutilizadas en diferentes lugares)
- 📞 Formulario de Contacto - aparece en múltiples páginas
En lugar de copiar este contenido en cada página:
- ✅ Crea una vez como un Bloque
- ✅ Inserta el bloque donde lo necesites
- ✅ Actualiza en un lugar → cambios en todas partes automáticamente
- ✅ Mantén tu contenido DRY (No te Repitas)
Ejemplo del mundo real:
Sin Blocks (copiar-pegar):
- Actualizar pie de página → Editar 50 páginas manualmente ❌
- Agregar enlace social → Actualizar en todas partes ❌
- Contenido inconsistente en las páginas ❌
Con Blocks (reutilizables):
- Actualizar bloque de pie de página → Cambios en las 50 páginas al instante ✅
- Agregar enlace social → Actualizar una vez ✅
- Siempre consistente ✅
✨ Conceptos Clave
¿Qué es un Bloque?
Un bloque es un componente de contenido reutilizable que contiene:
- Contenido - Texto, imágenes, enlaces, cualquier dato
- Atributos - Campos personalizados que defines
- Marcador - Identificador único para referenciarlo
- Estado - Activo, borrador, archivado
Reutilización de Bloques
Los bloques pueden ser:
- ✅ Usados en múltiples páginas y si los bloques se actualizan, se actualizan en todas partes
- ✅ Localizados (contenido diferente por idioma)
📋 Lo Que Necesitas Saber
Mejor práctica: Siempre usa marcadores en tu código (nunca cambian).
Estructura del Bloque
Cada bloque tiene estos campos clave:
{
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
type: 'common_block', // block type
templateIdentifier: null, // template identifier
isVisible: true, // visibility
attributeValues: {}, // block attributes
}
Atributos Personalizados
Los bloques utilizan AttributesSets para campos personalizados:
Ejemplos:
- Bloque de pie de página: texto de copyright, enlaces sociales, información de contacto
- Banner principal: título, subtítulo, botón CTA, imagen de fondo
- Testimonio: nombre del autor, foto, cita, calificación
- Formulario de contacto: configuración de campos, texto del botón de envío
Aprende más: Consulta AttributesSets Module
📊 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 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 slider/carousel |
🧩 Tipos de Bloques
El tipo 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 producto 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 rastreada y funcionan tanto para usuarios autorizados como para invitados (consulta Modo invitado).
❓ Preguntas Comunes (FAQ)
¿Cuál es la diferencia entre Bloques y Páginas?
- Páginas/Páginas de Productos - Páginas completamente autónomas con URLs (por ejemplo,
/about) a las que puedes agregar bloques y otros componentes de página que se pueden reutilizar en múltiples páginas. - Bloques - Componentes reutilizables insertados en páginas (por ejemplo, pie de página)
Piénsalo así:
- Página = Documento completo
- Bloque = Párrafo que reutilizas en múltiples documentos
¿Cómo actualizo el contenido de un bloque?
Actualízalo en OneEntry panel de administración:
- Ve a la sección de Bloques
- Encuentra tu bloque (por ejemplo, "Pie de página")
- Edita los atributos
- Guarda
¡Todas las páginas que usan ese bloque se actualizan automáticamente! ✨
¿Debería crear muchos bloques pequeños o pocos bloques grandes?
Muchos bloques pequeños es mejor:
✅ Bueno (pequeño, enfocado):
- header_logo
- header_navigation
- footer_copyright
- footer_social_links
❌ Evitar (demasiado grande):
- entire_page_layout (contains everything)
¿Por qué? Los bloques pequeños son más fáciles de reutilizar y mantener.
¿Cómo muestro/oculto bloques condicionalmente?
Revisa el campo isVisible
¿Puedo crear bloques dinámicamente a través de la API?
El SDK es de solo lectura. Para crear bloques usa el panel de administración de OneEntry.
¿Cómo manejo bloques faltantes de manera elegante?
Siempre usa try/catch
💡 Notas Importantes
Mejores Prácticas para Marcadores de Bloques
✅ Buenos nombres de marcadores:
- Descriptivos:
global_footer,homepage_hero - Usa guiones bajos:
contact_form - Minúsculas:
promo_banner - Indica el alcance:
global_headervsblog_header
❌ Malos nombres de marcadores:
- Genéricos:
block1,content - Espacios:
my block - Mayúsculas mixtas:
MyBlock,ProMoBanner
Caché de Bloques
Los bloques cambian raramente → ¡cáchelos!
🎓 Mejores Prácticas
- Crea bloques pequeños y enfocados (responsabilidad única)
- Usa marcadores descriptivos (
footer, noblock1) - Caché de bloques para reducir llamadas a la API
- Maneja bloques faltantes de manera elegante (try/catch)
- Documenta para qué es cada bloque
- Mantén la estructura del bloque consistente
- Prueba los cambios en los bloques antes de publicarlos
- Usa
statusIdpara previsualizar cambios
Definición del módulo Blocks
const { Blocks } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
🔗 Documentación Relacionada
- Módulo de Páginas - Gestionar páginas que utilizan bloques
- Módulo de AttributesSets - Definir atributos de bloque
- Módulo de Productos - Usar bloques en páginas de productos