Saltar al contenido principal

Introducción

Obtén plantillas de vista previa que estandarizan el tamaño y formato de las imágenes para los atributos de producto.

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

🎯 ¿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 atributos de "Imagen" o "Grupo de Imágenes", entregas imágenes dimensionadas y recortadas de manera consistente según la configuración de la plantilla, abarcando imágenes de productos, imágenes de variantes e imágenes basadas en atributos.

Creas plantillas de vista previa en el panel de administración de OneEntry (Configuración > Plantillas de Vista Previa), y este módulo obtiene esas configuraciones para que los atributos de producto con imágenes se rendericen de manera consistente. El SDK es de solo lectura: no puedes crear plantillas de vista previa a través de él.

🚀 Inicio Rápido​

Inicializa el módulo desde defineOneEntry:


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

Obtén plantillas de vista previa y lee sus proporciones:

// Fetch all preview templates, localized to English.
const previews = await TemplatePreviews.getTemplatePreviews("en_US");

previews.forEach((tpl) => {
  console.log(tpl.identifier, tpl.title, tpl.proportions.default.square);
});

// Or fetch a single preview template by its marker.
const swatch = await TemplatePreviews.getTemplatePreviewByMarker("color_swatch", "en_US");
console.log(swatch.proportions.default.horizontal);

✨ Conceptos Clave​

¿Qué es una Plantilla de Vista Previa?​

Una Plantilla de Vista Previa (ITemplatesPreviewEntity) es una configuración de imagen para atributos de producto:

  • Marcador (identifier) - Identificador único para referencia de plantilla (usa esto, no el ID)
  • Título (title) - Nombre de la plantilla mostrado en el panel de administración (no único)
  • Proporciones (proportions) - Conjuntos de parámetros de imagen por orientación (horizontal, vertical, cuadrada)
  • Alineación (alignmentType) - Cómo se recortan/centran las imágenes

Estructura de la Plantilla de Vista Previa​

interface ITemplatesPreviewEntity {
  id: number;
  title: string;
  proportions: {
    default: {
      horizontal: IProportion | null;   // { width, height, alignmentType }
      vertical: IProportion | null;     // { width, height, alignmentType }
      square: ISquare;                  // { side, alignmentType }
    };
  };
  identifier: string;
  version: number;
  attributeValues: IAttributeValues;
  position: number;
  isUsed: boolean;
  attributeSetIdentifier?: string | null;
}

Un valor de ejemplo de proporciones:

{
  default: {
    horizontal: { width: 234, height: 324, alignmentType: "middleBottom" },
    vertical:   { width: 2,   height: 3,   alignmentType: "leftTop" },
    square:     { side: 3,    alignmentType: "leftTop" },
  },
}

Flujo de Trabajo de la Plantilla de Vista Previa​

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

📋 Lo Que Necesitas Saber​

Las plantillas de vista previa se crean en el panel de administración​

No puedes crear plantillas de vista previa a través del SDK - se crean en el panel de administración de OneEntry (Configuración > Plantillas de Vista Previa). Cada plantilla necesita un Nombre (no único) y un Marcador único, además de conjuntos de proporciones para tres orientaciones de imagen:

  • Horizontal - ancho, alto, tipo de alineación
  • Vertical - ancho, alto, tipo de alineación
  • Cuadrada - longitud del lado, tipo de alineación

El SDK es para obtener configuraciones de plantillas de vista previa, no para crearlas.

Usa marcadores, no IDs​

Referencia las plantillas de vista previa por su marcador (identifier) en tu código - los marcadores son estables a través de entornos. Usa getTemplatePreviewByMarker(marker) para una plantilla única y getTemplatePreviews() para todas ellas.

TemplatePreviews vs Plantillas​

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

CaracterísticaTemplatePreviewsPlantillas
PropósitoVistas previas de imágenes de atributosVisualización de contenido general
Caso de UsoMuestras de color, vistas previas de materialImágenes principales, diseños de productos
AlcanceSolo atributos de productoPáginas, bloques, productos

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

Caché​

Las plantillas de vista previa rara vez cambian - almacénalas en caché (localStorage/sessionStorage en el frontend, Redis/memoria en el backend; ~1 hora de TTL es un punto de partida razonable).

📊 Tabla de Referencia Rápida​

MétodoDescripciónCaso de Uso
getTemplatePreviews()Obtener todas las plantillas de vista previaListar todas las plantillas de atributos disponibles
getTemplatePreviewByMarker()Obtener una plantilla de vista previa por marcadorObtener una 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 producto (muestras de color, vistas previas de material), mientras que las Plantillas manejan la visualización de contenido general (páginas, bloques, 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 la orientación de una imagen y aplica el conjunto de proporciones correspondiente (horizontal, vertical o square).

¿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 asigna cada una al tipo de atributo correspondiente para un renderizado consistente.

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

Obtén la plantilla a través de getTemplatePreviewByMarker() y usa sus proporciones para renderizar imágenes de atributos con un tamaño consistente. La asignación de una plantilla a un tipo de atributo se realiza en el panel de administración.

🎓 Mejores Prácticas​

  • Usa marcadores, no IDs - los marcadores son estables a través de entornos.
  • Usa marcadores semánticos - color_swatch, no preview_1.
  • Mapea atributos a plantillas - mantén una plantilla por tipo de atributo para consistencia.
  • Almacena en caché las plantillas de vista previa - reduce las llamadas a la API para datos que cambian raramente.

🔗 Documentación Relacionada​