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 alternar 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 (Configuraciones > 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 usado 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,                                    // Unique identifier
  title: "Product Thumbnail",               // Template name (non-unique)
  identifier: "product_thumbnail",          // Template marker (unique)
  generalTypeId: 1,                         // Type ID reference
  version: 0,                               // Version number
  attributeSetIdentifier: null,             // Associated attribute set
  localizeInfos: {                          // Localized information
    en_US: {
      title: "Product Thumbnail",
      description: "Small product image"
    }
  },
  attributeValues: {},                      // Additional attribute data
  isActive: true,                           // Active status
  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 de 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 Imágenes 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óvil

Flujo de Configuración del Template​

1. Create templates in admin panel
   (Define sizes, crops, formats)
   ↓
2. Fetch templates via SDK
   (Templates.getTemplates())
   ↓
3. Apply template configurations
   (Use sizes in image rendering)
   ↓
4. Images automatically optimized
   (OneEntry CDN serves correct size)
   ↓
5. Consistent display everywhere
   (Same template = same appearance)

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

BeneficioDescripción
Diseño ConsistenteMismos templates usados en toda la aplicación
Fácil MantenimientoCambiar template en el administrador, 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 optimizada
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:

OneEntry Admin Panel → Settings → Templates → Create Template → Set Name/Marker/Type → Save

Proceso de Creación:

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

Operaciones de Gestión:

  • Configuración - Haz clic en el ícono de engranaje para editar nombre, marcador o tipo
  • Eliminación - Selecciona el template y haz clic en el ícono de eliminar, luego confirma la eliminación

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

Identificación del Template​

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 CDN de Templates de Imágenes​

OneEntry optimiza automáticamente las imágenes basándose en los templates.

Diseño Responsivo con Templates​

Crea diferentes templates para diferentes tamaños de pantalla.

Estructura del Template:

interface ITemplateEntity {
  id: number;                        // Unique identifier
  title: string;                     // Template name (non-unique)
  identifier: string;                // Template marker (unique)
  generalTypeId: number;             // Type ID reference
  version: number;                   // Version number
  attributeSetIdentifier: string | null;  // Associated attribute set
  localizeInfos: {                   // Localized information
    [langCode: string]: {
      title: string;
      description?: string;
    };
  };
  attributeValues: any;              // Additional attribute data
  isActive: boolean;                 // Active status
}

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. Describe componentes en el código de tu proyecto
  2. Etiqueta componentes con templates creados por la plataforma
  3. Cambia templates para modificar cómo funcionan las entidades
  4. Actualiza la apariencia sin modificar el código fuente

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

Optimización de Imágenes​

OneEntry CDN optimiza automáticamente las imágenes basándose en 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=marker a la URL de la imagen, donde marker 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 del 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 CDN - ?template=marker 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​