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 obtiene 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 Material - 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 experiencia de usuario - 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
  • 🖼️ Experiencia de usuario 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 las imágenes de atributos

Estructura de la Vista Previa de Plantilla​

Cada vista previa de plantilla tiene esta estructura:

{
  id: 3,                                      // Identificador único
  title: 'Plantillas de Vista Previa',       // Nombre de la plantilla (no único)
  identifier: 'plantillas-de-vista-previa',   // Marcador de plantilla (único)
  proportions: {                              // Conjuntos de parámetros de imagen
    default: {                                // Configuración de plantilla predeterminada
      horizontal: {                           // Para imágenes horizontales
        width: 234,                           // Ancho en píxeles
        height: 324,                          // Alto en píxeles
        alignmentType: 'middleBottom'         // Tipo de centrado (eje de compresión)
      },
      vertical: {                             // Para imágenes verticales
        width: 2,
        height: 3,
        alignmentType: 'leftTop'
      },
      square: {                               // Para imágenes cuadradas
        side: 3,                              // Longitud del lado en píxeles
        alignmentType: 'leftTop'
      },
    },
  },
  version: 0,                                 // Número de versión
  attributeValues: {},                        // Datos adicionales de atributos
  position: 1,                                // Posición de visualización
  isUsed: false,                              // Estado de uso
  attributeSetIdentifier: null                // Conjunto de atributos asociado
}

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. Crea una plantilla de vista previa en el panel de administración
   (Define el tamaño para las imágenes de atributos)
   ↓
2. Asigna la plantilla al tipo de atributo
   (por ejemplo, el atributo "Color" utiliza "color_swatch")
   ↓
3. Obtén las plantillas a través del SDK
   (TemplatePreviews.getTemplatePreviews())
   ↓
4. Aplica la plantilla a las imágenes de atributos
   (Usa el marcador de plantilla en las URL de las imágenes)
   ↓
5. Visualización consistente de imágenes de atributos
   (Todas las muestras de color del mismo tamaño)

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

Panel de Administración de OneEntry → Configuraciones → Plantillas de Vista Previa → Crear Plantilla → Establecer Nombre/Marcador → Configurar Parámetros → Guardar

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, Alto, Tipo de Centración
    • Horizontal - Ancho, Alto, 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 obtener 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 materialImá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 Vistas Previas 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 las imágenes de atributos.

Estructura de la 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 obtener 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​

El CDN de OneEntry 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 plantilla.

Caché de Vistas Previas 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 experiencia de usuario 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 Material: 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 marcadorObtener 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 material), 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 LQTP 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 una 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. Obtén la plantilla a través de getTemplatesPreviewByMarker() y usa las proporciones para renderizar imágenes de atributos con un tamaño consistente.

¿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 material (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(
  "tu-url-de-proyecto", {
    "token": "tu-token-de-aplicación"
  }
);

🔗 Documentación Relacionada​