Introducción
Crea bloques de contenido reutilizables que se pueden usar en múltiples páginas.
🎯 ¿Qué hace este módulo?
El módulo Blocks te permite usar componentes de contenido reutilizables (bloques) que contienen conjuntos de atributos y se pueden usar en múltiples páginas, como encabezados, pies de página, banners, testimonios o cualquier contenido repetido.
Piénsalo como bloques de LEGO para tu sitio web: creas un bloque una vez y lo reutilizas 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 a 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 Bloques (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 Bloques (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
Bloque vs Página
| Característica | Página | Bloque |
|---|---|---|
| Propósito | Contenido completo de la página | Componente reutilizable |
| URL | Tiene su propia URL (/about) | Sin URL (embebido) |
| Uso | Visto directamente | Insertado en páginas |
| Ejemplo | Página Sobre Nosotros | Pie de página, Encabezado |
Diferencia clave: Las páginas son destinos, los bloques son bloques de construcción.
Tipos Comunes de Bloques
Bloques típicos que podrías crear:
| Tipo de Bloque | Contenido de Ejemplo | Donde se Usa |
|---|---|---|
| Encabezado | Logo, menú de navegación, búsqueda | Cada página |
| Pie de página | Contacto, enlaces, derechos de autor | Cada página |
| Banner Hero | Imagen grande + botón CTA | Página de inicio, páginas de aterrizaje |
| Testimonios | Reseñas de clientes | Múltiples páginas |
| Formulario de Contacto | Formulario de correo | Página de contacto, modales |
| Banner Promocional | Alerta de oferta especial | Páginas seleccionadas |
| Enlaces Sociales | Iconos de Facebook, Twitter | Pie de página, barra lateral |
| Registro de Boletín | Caja de suscripción de correo | Pie de página, blog |
Reutilización de Bloques
Los bloques pueden ser:
- ✅ Usados en múltiples páginas
- ✅ Actualizados una vez, reflejados en todas partes
- ✅ Localizados (contenido diferente por idioma)
📋 Lo Que Necesitas Saber
Identificación de Bloques
Tres formas de identificar bloques:
| Método | Cuándo Usar | Ejemplo |
|---|---|---|
| Listar Todos | Panel de administración, selector de bloques | getBlocks() |
| Por Marcador | Referencia en código (mejor práctica) | footer, header, promo_banner |
| Buscar bloques | Referencias internas | searchBlock('foo') |
Mejor práctica: Siempre usa marcadores en tu código (nunca cambian).
Estructura del Bloque
Cada bloque tiene estos campos clave:
{
id: 3, // ID único
localizeInfos: { // datos localizados del bloque
title: 'Block', // título localizado del bloque
},
version: 0, // versión del bloque
position: 1, // posición del bloque en el array de bloques
identifier: 'block', // identificador del bloque
type: 'common_block', // tipo de bloque
templateIdentifier: null, // identificador de plantilla
isVisible: true, // visibilidad
attributeValues: {}, // atributos del bloque
}
Atributos Personalizados
Los bloques utilizan AttributesSets para campos personalizados:
Ejemplos:
- Bloque de pie de página: texto de derechos de autor, enlaces sociales, información de contacto
- Banner hero: titular, 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 el Módulo AttributesSets
📊 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 código |
| searchBlock() | Buscar bloques | Obtener bloques |
❓ Preguntas Comunes (FAQ)
¿Cuál es la diferencia entre Bloques y Páginas?
- Páginas - Páginas completas e independientes con URLs (por ejemplo,
/about) - 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 el panel de administración de OneEntry:
- 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 (contiene todo)
¿Por qué? Los bloques pequeños son más fáciles de reutilizar y mantener.
¿Puedo usar el mismo bloque múltiples veces en una página?
¡Sí! Obtén una vez, renderiza múltiples veces.
¿Cómo muestro/oculto bloques condicionalmente?
Verifica statusId y 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
✅ Nombres de marcadores buenos:
- Descriptivos:
global_footer,homepage_hero - Usa guiones bajos:
contact_form - Minúsculas:
promo_banner - Indica el alcance:
global_headervsblog_header
❌ Nombres de marcadores malos:
- 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 de bloque antes de publicar
- Usa
statusIdpara previsualizar cambios
Más información sobre la interfaz de usuario del módulo https://doc.oneentry.cloud/docs/blocks/introduction
Definición del módulo Blocks
const { Blocks } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
🔗 Documentación Relacionada
- Módulo de Páginas - Gestiona páginas que usan bloques
- Módulo AttributesSets - Define atributos de bloque
- Módulo de Productos - Usa bloques en páginas de productos