Saltar al contenido principal

Introducción

🎯 ¿Qué hace este módulo?​

El módulo TemplatePreviews te permite estandarizar los parámetros de imagen en tu proyecto. Al aplicar plantillas de vista previa a los atributos "Imagen" o "Grupo de Imágenes", aseguras un tamaño y formato consistentes que se alinean con tus requisitos de diseño.

Las plantillas de vista previa configuran los parámetros de imagen utilizados en los atributos, entregando imágenes estandarizadas de acuerdo con las especificaciones establecidas en la plantilla de vista previa. Esto asegura una visualización consistente de las imágenes en las imágenes de productos, imágenes de variantes e imágenes basadas en atributos.

Piénsalo como tu configurador de imágenes de atributos: creas plantillas de vista previa en el panel de administración de OneEntry (Configuraciones > Plantillas de Vista Previa), y este módulo recupera esas configuraciones para que los atributos de productos con imágenes se rendericen de manera consistente en tu catálogo.

📖 Explicación Simple​

Cada aplicación de comercio electrónico necesita imágenes de productos consistentes en los atributos:

  • 🎨 Muestras de Color - Variantes de color de productos (Rojo, Azul, Verde) con imágenes de vista previa
  • 📏 Tablas de Tallas - Imágenes de atributos de tamaño (Pequeño, Mediano, Grande) con guías visuales
  • 🖼️ Vistas Previas de Materiales - Imágenes de atributos de material (Cuero, Algodón, Seda) con texturas
  • 💎 Opciones de Acabado - Imágenes de acabado de superficie (Brillante, Mate, Satinado) con ejemplos visuales
  • 👗 Vistas Previas de Patrones - Imágenes de atributos de patrón (Rayado, Sólido, Floral) con muestras
  • 🏷️ Galerías de Atributos - Tamaño de imagen consistente para todos los atributos de productos

El problema con las imágenes de atributos inconsistentes

Problemas:

  • 🎨 Visualización inconsistente - Diferentes imágenes de atributos tienen diferentes tamaños
  • 📊 Difícil de mantener - Cambios requieren editar múltiples componentes
  • 🔄 Sin reutilización - La misma lógica de tamaño duplicada en todas partes
  • 🖼️ Pobre UX - Las imágenes de atributos parecen desalineadas y poco profesionales

La solución de TemplatePreviews

Beneficios:

  • 🎨 Visualización consistente - Todas las imágenes de atributos utilizan la misma plantilla
  • 📊 Mantenimiento fácil - Cambia la plantilla en el panel de administración
  • 🔄 Reutilizable - La misma plantilla en todos los atributos
  • 🖼️ UX profesional - Imágenes de atributos alineadas y uniformes

✨ Conceptos Clave​

¿Qué es una Vista Previa de Plantilla?​

Una Vista Previa de Plantilla es una configuración de imagen para atributos de productos:

  • Imágenes de Atributos - Imágenes asociadas con atributos de productos (color, tamaño, material)
  • Tamaño de Vista Previa - Dimensiones para la visualización de imágenes de atributos
  • Configuraciones de Recorte - Cómo recortar imágenes de atributos
  • Marcador - Identificador único para referencia de plantilla
  • Consistencia - La misma plantilla asegura una visualización uniforme de imágenes de atributos

Estructura de la Vista Previa de Plantilla​

Cada vista previa de plantilla tiene esta estructura:

{
  id: 3,                                      // Unique identifier
  title: 'Preview Templates',                 // Template name (non-unique)
  identifier: 'preview-templates',            // Template marker (unique)
  proportions: {                              // Image parameter sets
    default: {                                // Default template configuration
      horizontal: {                           // For horizontal images
        width: 234,                           // Width in pixels
        height: 324,                          // Height in pixels
        alignmentType: 'middleBottom'         // Centering type (compression axis)
      },
      vertical: {                             // For vertical images
        width: 2,
        height: 3,
        alignmentType: 'leftTop'
      },
      square: {                               // For square images
        side: 3,                              // Side length in pixels
        alignmentType: 'leftTop'
      },
    },
  },
  version: 0,                                 // Version number
  attributeValues: {},                        // Additional attribute data
  position: 1,                                // Display position
  isUsed: false,                              // Usage status
  attributeSetIdentifier: null                // Associated attribute set
}

Campos Clave:

  • identifier - Marcador único para referencia de plantilla (usa esto, no ID)
  • title - Nombre de la plantilla mostrado en el panel de administración
  • proportions - Configuración de imagen para diferentes orientaciones
  • alignmentType - Define cómo se recortan/centran las imágenes

Flujo de Trabajo de la Vista Previa de Plantilla​

1. Create preview template in admin panel
   (Define size for attribute images)
   ↓
2. Assign template to attribute type
   (e.g., "Color" attribute uses "color_swatch")
   ↓
3. Fetch templates via SDK
   (TemplatePreviews.getTemplatePreviews())
   ↓
4. Apply template to attribute images
   (Use template marker in image URLs)
   ↓
5. Consistent attribute image display
   (All color swatches same size)

¿Por qué usar el módulo TemplatePreviews?​

BeneficioDescripción
Atributos ConsistentesTodas las imágenes de atributos del mismo tamaño
Optimización de ImágenesRedimensionamiento y compresión automáticos
Mantenimiento FácilCambia la plantilla, actualiza todos los atributos
Mejor UXVisualización uniforme y profesional de atributos
Integración CDNEntrega optimizada de imágenes de atributos
Configuraciones ReutilizablesLa misma plantilla para todas las muestras de color

📋 Lo Que Necesitas Saber​

Las Vistas Previas de Plantilla se Crean en el Panel de Administración​

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

OneEntry Admin Panel → Settings → Preview Templates → Create Template → Set Name/Marker → Configure Parameters → Save

Proceso de Creación:

  • Proporciona un Nombre (identificador no único)
  • Proporciona un Marcador (identificador único)
  • Haz clic en "Crear" para finalizar

Configuración:

  • Selecciona la plantilla y haz clic en el ícono de engranaje para configurar
  • Agrega conjuntos de parámetros de vista previa para tres orientaciones de imagen:
    • Vertical - Ancho, Altura, Tipo de Centración
    • Horizontal - Ancho, Altura, Tipo de Centración
    • Cuadrado - Longitud del lado, Tipo de Centración
  • Designa un conjunto de parámetros como la plantilla predeterminada

El SDK es para recuperar configuraciones de vistas previas de plantilla, no para crearlas.

Vistas Previas de Plantilla vs Plantillas​

TemplatePreviews son específicamente para imágenes de atributos de productos:

CaracterísticaTemplatePreviewsPlantillas
PropósitoVistas previas de imágenes de atributosImágenes de contenido general
Caso de UsoMuestras de color, vistas previas de materialesImágenes principales, fotos de productos
AlcanceSolo atributos de productosPáginas, bloques, productos
EjemploMuestra de color 50×50Banner principal 1920×1080

Mejor práctica: Usa TemplatePreviews para imágenes de atributos, Plantillas para contenido general.

Aplicando Plantillas a Imágenes de Atributos​

OneEntry optimiza automáticamente las imágenes de atributos basándose en las plantillas de vista previa.

Asignación de Vista Previa de Plantilla​

Las plantillas de vista previa se asignan típicamente a tipos de atributos específicos.

Visualización Consistente de Atributos​

Usa vistas previas de plantilla para asegurar una visualización uniforme de imágenes de atributos.

Estructura de Vista Previa de Plantilla:

interface ITemplatesPreviewEntity {
  id: number;
  title: string;
  proportions: {
    default: {
      horizontal: IProportion | null;
      vertical: IProportion | null;
      square: ISquare;
    };
  };
  identifier: string;
  version: number;
  attributeValues: AttributeType;
  position: number;
  isUsed: boolean;
  attributeSetIdentifier?: string | null;
}

💡 Notas Importantes​

Las Vistas Previas de Plantilla se Crean en el Panel de Administración​

Recuerda: El SDK es para recuperar configuraciones de vistas previas de plantilla, no para crearlas.

Para crear/editar vistas previas de plantilla: Usa el Panel de Administración de OneEntry.

Optimización de Imágenes de Atributos​

OneEntry CDN optimiza automáticamente las imágenes de atributos basándose en la configuración de la plantilla de vista previa:

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

Solo necesitas referenciar el marcador de la plantilla

Caché de Vista Previa de Plantilla​

Las vistas previas de plantilla rara vez cambian: implementa caché:

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

Visualización Consistente de Atributos​

Usa la misma plantilla de vista previa para el mismo tipo de atributo:

  • Todos los atributos de color → plantilla color_swatch
  • Todos los atributos de material → plantilla material_preview
  • Todos los atributos de patrón → plantilla pattern_thumbnail

La consistencia mejora la UX y se ve profesional.

Tamaños de Plantilla Recomendados​

Tamaños comunes de imágenes de atributos:

  • Muestras de Color: 50×50 a 100×100
  • Vistas Previas de Materiales: 80×80 a 150×150
  • Miniaturas de Patrones: 60×60 a 120×120
  • Tablas de Tallas: 100×80 a 200×150
  • Vistas Previas de Acabado: 75×75 a 100×100

Tecnología LQIP​

Las plantillas de vista previa utilizan la tecnología Low-Quality Image Placeholder (LQIP) para un rendimiento óptimo de carga:

Cómo funciona:

  • Devuelve una estructura de array de dos elementos:
    1. Miniatura - Formato WebP, optimizado para carga rápida (unos pocos cientos de bytes)
    2. Vista Previa Generada - Imagen de resolución completa que reemplaza la miniatura después de cargar

✅ Beneficios:

  • Visualización instantánea con miniatura
  • Transición suave a calidad completa
  • Reducción del consumo de ancho de banda
  • Mejor experiencia de usuario

Eliminación de Plantillas​

Para eliminar una plantilla:

  1. Selecciona la plantilla en el panel de administración
  2. Haz clic en el ícono de eliminar
  3. Confirma la eliminación

Nota: Solo se pueden eliminar plantillas no utilizadas.

📊 Tabla de Referencia Rápida​

MétodoDescripciónCaso de Uso
getTemplatePreviews()Obtener todas las plantillas de vista previaListar todas las plantillas de atributos disponibles
getTemplatesPreviewByMarker()Obtener plantilla de vista previa por marcadorRecuperar configuración de plantilla específica

❓ Preguntas Comunes (FAQ)​

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

TemplatePreviews son específicamente para imágenes de atributos de productos (muestras de color, vistas previas de materiales), mientras que las Plantillas manejan imágenes de contenido general (banners principales, fotos de productos). Usa TemplatePreviews solo para imágenes específicas de atributos.

¿Cómo configuro diferentes tamaños para imágenes horizontales, verticales y cuadradas?​

En el panel de administración, configura las tres orientaciones para cada plantilla de vista previa. El sistema detecta automáticamente la orientación de la imagen y aplica las proporciones apropiadas (horizontal, vertical o cuadrada).

¿Qué es LQIP y por qué es importante?​

LQIP (Low-Quality Image Placeholder) carga primero una miniatura pequeña (unos pocos cientos de bytes), luego la reemplaza con la imagen de calidad completa. Esto proporciona retroalimentación visual instantánea y mejora el rendimiento percibido, especialmente en conexiones lentas.

¿Puedo asignar diferentes plantillas de vista previa a diferentes tipos de atributos?​

¡Sí! Crea múltiples plantillas de vista previa con diferentes marcadores (por ejemplo, color_swatch, material_preview, pattern_thumbnail) y asígnalas a los tipos de atributos apropiados para un renderizado consistente.

¿Cómo aplico una plantilla de vista previa a las imágenes de atributos?​

Las plantillas de vista previa se aplican automáticamente cuando las configuras en el panel de administración. Recupera la plantilla a través de getTemplatesPreviewByMarker() y usa las proporciones para renderizar imágenes de atributos con tamaños consistentes.

¿Cuáles son los tamaños recomendados para las imágenes de atributos?​

Mantén las imágenes de atributos pequeñas: 50-150px para un rendimiento óptimo. Tamaños comunes: Muestras de color (50×50 a 100×100), Vistas previas de materiales (80×80 a 150×150), Miniaturas de patrones (60×60 a 120×120).

🎓 Mejores Prácticas​

  • Usa marcadores, no IDs - Los marcadores son estables en todos los entornos
  • Caché de plantillas de vista previa - Reduce las llamadas a la API para datos que cambian raramente
  • Crea tamaños consistentes - Mismo tipo de atributo = mismo tamaño de plantilla
  • Usa formato WebP - Mejor compresión para imágenes de atributos
  • Define configuraciones de calidad - Equilibra calidad vs tamaño de archivo (80-90 recomendado)
  • Mapea atributos a plantillas - Crea un mapeo de attributeType → plantilla
  • Usa marcadores semánticos - color_swatch, no preview_1
  • Prueba en móvil - Asegúrate de que las imágenes de atributos se vean bien en pantallas pequeñas

Más información sobre las plantillas de vista previa en el panel de administración de OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/templates/templates_preview/

Definición del módulo TemplatePreviews​


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

🔗 Documentación Relacionada​