Saltar al contenido principal

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 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 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

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, // ID único
  localizeInfos: { // datos localizados del bloque
    title: 'Bloque', // título localizado del bloque
  },
  version: 0, // versión del bloque
  position: 1, // posición del bloque en el array de bloques
  identifier: 'bloque', // 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 copyright, enlaces sociales, información de contacto
  • Banner principal: 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étodoQué HaceCuándo Usar
getBlocks()Obtener todos los bloques (paginados, filtrados)Listar todos los bloques disponibles
getBlockByMarker()Obtener bloque por marcadorObtener bloque específico en el código
searchBlock()Buscar bloquesObtener bloques

❓ 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:

  1. Ve a la sección de Bloques
  2. Encuentra tu bloque (por ejemplo, "Pie de página")
  3. Edita los atributos
  4. 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.

¿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​

✅ Nombres de marcadores buenos:

  • Descriptivos: global_footer, homepage_hero
  • Usa guiones bajos: contact_form
  • Minúsculas: promo_banner
  • Indica el alcance: global_header vs blog_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, no block1)
  • 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 publicar
  • Usa statusId para 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​