Saltar al contenido principal

Introducción

🎯 ¿Qué hace este módulo?​

El módulo de Templates te permite cambiar la estructura y apariencia de tu proyecto sin alterar su código fuente. Los templates te permiten gestionar componentes a través de la Plataforma OneEntry mientras mantienes opciones de diseño y comportamiento flexibles.

Los templates funcionan permitiéndote describir componentes en el código de tu proyecto, y luego etiquetarlos con templates creados por la plataforma. Esta separación permite cambiar entre diferentes implementaciones de templates para influir en cómo funcionan las entidades.

Piénsalo como tu configurador de sistema de diseño: creas templates en el panel de administración de OneEntry (Configuración > Templates), etiquetas tus componentes con estos templates, y este módulo recupera esas configuraciones para que tu aplicación pueda renderizar contenido dinámicamente con un estilo consistente.

📖 Explicación Simple​

Cada aplicación necesita una presentación de contenido consistente:

  • 🖼️ Templates de Imágenes - Tamaños y recortes predefinidos (miniatura, héroe, galería)
  • 📄 Templates de Páginas - Configuraciones de diseño de página (entrada de blog, página de destino)
  • 🧱 Templates de Bloques - Apariencias de bloques de contenido (tarjeta, banner, sección)
  • 🛍️ Templates de Productos - Formatos de exhibición de productos (rejilla, lista, detalle)
  • 🎨 Diseño Responsivo - Diferentes tamaños para móvil, tablet, escritorio
  • ♻️ Configuraciones Reutilizables - Definir una vez, usar en todas partes

El problema con la lógica de visualización codificada:

Problemas:

  • 🔒 Inconsistente - Diferentes tamaños en diferentes lugares
  • 🎨 Difícil de mantener - Cambios requieren editar múltiples archivos
  • 📱 No es responsivo - Tamaños fijos no se adaptan
  • ♻️ Sin reutilización - Código duplicado en todas partes

La solución de los Templates:

Beneficios:

  • 🔒 Consistente - Mismo template utilizado en todas partes
  • 🎨 Fácil mantenimiento - Cambio en el panel de administración, se aplica en todas partes
  • 📱 Responsivo - Diferentes templates para diferentes pantallas
  • ♻️ Reutilizable - Definir una vez, usar en toda la aplicación

✨ Conceptos Clave​

¿Qué es un Template?​

Un Template es una configuración de visualización que define cómo debe aparecer el contenido:

  • Tipo de Template - Template de imagen, página, bloque, producto
  • Dimensiones - Ancho, alto, relación de aspecto
  • Configuraciones de Recorte - Cómo recortar imágenes (centro, arriba, abajo)
  • Formato - Formato de imagen (JPEG, PNG, WebP)
  • Calidad - Calidad de compresión
  • Marcador - Identificador único para referencia de código

Estructura del Template​

Cada template tiene esta estructura:

{
  id: 1,                                    // Identificador único
  title: "Miniatura de Producto",           // Nombre del template (no único)
  identifier: "product_thumbnail",          // Marcador del template (único)
  generalTypeId: 1,                         // Referencia de ID de tipo
  version: 0,                               // Número de versión
  attributeSetIdentifier: null,             // Conjunto de atributos asociado
  localizeInfos: {                          // Información localizada
    en_US: {
      title: "Miniatura de Producto",
      description: "Imagen pequeña del producto"
    }
  },
  attributeValues: {},                      // Datos adicionales de atributos
  isActive: true,                           // Estado activo
  createdAt: "2024-01-15T10:00:00Z",
  updatedAt: "2024-01-15T10:00:00Z"
}

Campos Clave:

  • identifier - Marcador único para referencia del template (usa esto, no ID)
  • title - Nombre del template mostrado en el panel de administración
  • generalTypeId - Categoría de entidad a la que se aplica el template
  • attributeSetIdentifier - Conjunto de atributos asociado opcional

Tipos de Templates​

Los templates están organizados por tipo de entidad y soportan las siguientes categorías:

Tipo de TemplateCategoría de EntidadCasos de Uso Ejemplo
Bloques de ProductoforCatalogProductsRejilla de productos, lista de productos, productos destacados
Bloques RegularesforOneBlockTarjetas de contenido, banners, secciones, widgets
Páginas de ErrorforErrorPagesPágina 404, página 500, diseños de error personalizados
Páginas RegularesforOnePageEntrada de blog, página de destino, página de información
Páginas de ProductoforOneProductDetalle del producto, comparación de productos
Páginas de CatálogoforCatalogPageListado de categorías, resultados de búsqueda
FormulariosforFormFormulario de contacto, formulario de registro, encuesta
ÓrdenesforOrderConfirmación de pedido, historial de pedidos

Templates de Imagen Comunes​

TemplateTamañoRecorteCaso de Uso
Miniatura150×150CentroImágenes de vista previa pequeñas
Imagen de Tarjeta300×200CentroTarjetas de productos, tarjetas de blog
Imagen de Héroe1920×1080CentroBanners de ancho completo
Imagen de Galería800×600CentroGalerías de imágenes
Avatar100×100CentroImágenes de perfil de usuario
Héroe Móvil768×432CentroBanners optimizados para móviles

Flujo de Trabajo de Configuración de Templates​

1. Crear templates en el panel de administración
   (Definir tamaños, recortes, formatos)
   ↓
2. Recuperar templates a través del SDK
   (Templates.getTemplates())
   ↓
3. Aplicar configuraciones de templates
   (Usar tamaños en la renderización de imágenes)
   ↓
4. Imágenes optimizadas automáticamente
   (OneEntry CDN sirve el tamaño correcto)
   ↓
5. Visualización consistente en todas partes
   (Mismo template = misma apariencia)

¿Por qué usar el módulo de Templates?​

BeneficioDescripción
Diseño ConsistenteMismos templates utilizados en toda la aplicación
Fácil MantenimientoCambiar el template en la administración, actualiza en todas partes
Optimización de ImágenesRedimensionamiento y compresión automáticos
Diseño ResponsivoDiferentes templates para diferentes pantallas
Integración CDNEntrega de imágenes optimizadas
Configuraciones ReutilizablesDefinir una vez, usar en todas partes

📋 Lo Que Necesitas Saber​

Los Templates se Crean en el Panel de Administración​

No puedes crear templates a través del SDK - se crean en el panel de administración de OneEntry:

Panel de Administración de OneEntry → Configuración → Templates → Crear Template → Establecer Nombre/Marcador/Tipo → Guardar

Proceso de Creación:

  • Proporcionar un Nombre (identificador no único)
  • Proporcionar un Marcador (identificador único)
  • Seleccionar un Tipo (categoría de entidad a la que se aplica el template)
  • Hacer clic en "Crear" para finalizar

Operaciones de Gestión:

  • Configuración - Hacer clic en el ícono de engranaje para editar nombre, marcador o tipo
  • Eliminación - Seleccionar el template y hacer clic en el ícono de eliminar, luego confirmar la eliminación

El SDK es para recuperar configuraciones de templates, no para crearlos.

Identificación de Templates​

Tres formas de identificar templates:

MétodoCuándo UsarEjemplo
Por TipoReferencia en código (mejor práctica)product_thumbnail, hero_banner
Por MarcadorReferencia en código (mejor práctica)product_thumbnail, hero_banner
Listar TodosMostrar templates disponiblesgetTemplates()

Mejor práctica: Siempre usa marcadores en tu código (nunca cambian).

Integración de CDN de Templates de Imagen​

OneEntry optimiza automáticamente las imágenes según los templates.

Diseño Responsivo con Templates​

Crea diferentes templates para diferentes tamaños de pantalla.

Estructura del Template:

interface ITemplateEntity {
  id: number;                        // Identificador único
  title: string;                     // Nombre del template (no único)
  identifier: string;                // Marcador del template (único)
  generalTypeId: number;             // Referencia de ID de tipo
  version: number;                   // Número de versión
  attributeSetIdentifier: string | null;  // Conjunto de atributos asociado
  localizeInfos: {                   // Información localizada
    [langCode: string]: {
      title: string;
      description?: string;
    };
  };
  attributeValues: any;              // Datos adicionales de atributos
  isActive: boolean;                 // Estado activo
}

Tipos de Template Disponibles:

  • forCatalogProducts - Bloques de producto
  • forOneBlock - Bloques regulares
  • forErrorPages - Páginas de error
  • forOnePage - Páginas regulares
  • forOneProduct - Páginas de producto
  • forCatalogPage - Páginas de catálogo
  • forForm - Formularios
  • forOrder - Órdenes

💡 Notas Importantes​

Los Templates se Crean en el Panel de Administración​

Recuerda: El SDK es para recuperar configuraciones de templates, no para crear templates.

Para crear/editar templates: Usa el Panel de Administración de OneEntry.

Cómo Funcionan los Templates​

Los templates permiten una gestión flexible de componentes al separar la estructura del código:

  1. Describir componentes en el código de tu proyecto
  2. Etiquetar componentes con templates creados por la plataforma
  3. Cambiar templates para modificar cómo funcionan las entidades
  4. Actualizar apariencia sin modificar el código fuente

Esta separación permite múltiples variaciones de diseño y funcionalidad sin cambios en el código.

Optimización de Imágenes​

OneEntry CDN optimiza automáticamente las imágenes según la configuración del template:

  • Redimensionamiento automático
  • Conversión de formato (JPEG, PNG, WebP)
  • Compresión
  • Recorte
  • Caché

Solo necesitas referenciar el marcador del template:

<img src={`${image.url}?template=thumbnail`} />

Templates Responsivos​

Crea templates separados para diferentes dispositivos:

  • Templates móviles (768px de ancho o menos)
  • Templates para tabletas (1024px de ancho)
  • Templates para escritorio (1920px de ancho)

Usa con el elemento <picture> para imágenes responsivas.

Caché de Templates​

Los templates rara vez cambian - implementa caché:

  • Frontend: localStorage, sessionStorage
  • Backend: Redis, caché en memoria
  • TTL: 1 hora recomendada

📊 Tabla de Referencia Rápida​

MétodoDescripciónCaso de Uso
getAllTemplates()Obtener todos los templates agrupados por tiposListar todos los templates disponibles
getTemplateByType()Obtener templates por tipo de entidadRecuperar templates para un tipo de entidad específico
getTemplateByMarker()Obtener template por marcadorRecuperar configuración de template específica

❓ Preguntas Comunes (FAQ)​

¿Cuál es la diferencia entre Templates y TemplatePreviews?​

Los templates configuran la visualización general del contenido (páginas, bloques, productos), mientras que TemplatePreviews manejan específicamente las imágenes de atributos de productos (muestras de color, vistas previas de material). Usa Templates para el contenido principal, TemplatePreviews para imágenes de atributos.

¿Cómo aplico un template a una URL de imagen?​

Agrega ?template=marcador a la URL de la imagen, donde marcador es el identificador del template. OneEntry CDN sirve automáticamente la imagen optimizada según la configuración del template (tamaño, recorte, formato).

¿Puedo crear diferentes templates para móvil y escritorio?​

¡Sí! Crea templates separados con tamaños apropiados para cada dispositivo (por ejemplo, hero_mobile, hero_desktop). Usa técnicas de diseño responsivo o elementos <picture> para cargar el template correcto según el tamaño de la pantalla.

¿Qué sucede si hago referencia a un template que no existe?​

La imagen se cargará en su tamaño original sin optimización de template. Siempre verifica que los marcadores de templates existan y maneja los templates faltantes de manera adecuada con tamaños de reserva.

¿Cómo actualizo un template sin afectar la producción?​

Los templates son configuraciones, no código. Los cambios en el panel de administración se aplican de inmediato. Prueba los cambios de template en un entorno de staging primero, luego actualiza los templates de producción cuando estén verificados.

¿Qué tipos de templates debo usar para mi contenido?​

Elige según el tipo de entidad: forOnePage para páginas estándar, forCatalogProducts para listados de productos, forOneBlock para bloques de contenido, forOneProduct para detalles de productos. Alinea el tipo de template con tu categoría de contenido.

🎓 Mejores Prácticas​

  • Usa marcadores, no IDs - Los marcadores son estables en todos los entornos
  • Caché de templates - Reduce las llamadas a la API para datos que cambian raramente
  • Crea templates responsivos - Diferentes tamaños para diferentes pantallas
  • Usa formato WebP - Mejor compresión que JPEG/PNG
  • Define configuraciones de calidad - Equilibra calidad vs tamaño de archivo
  • Usa parámetros de template de CDN - ?template=marcador para optimización
  • Crea marcadores semánticos - product_thumbnail, no img_1
  • Documenta el uso de templates - Explica para qué es cada template

Más información sobre templates en el panel de administración de OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/templates/content_templates/

Definición del módulo de Templates​

El módulo Templates configura la visualización del contenido dentro de tu aplicación.

Algunos templates afectan imágenes almacenadas en OneEntry, mientras que otros definen la apariencia de entidades como bloques, páginas y productos.


const { Templates } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 Documentación Relacionada​