TemplatePreviews

Name: OneEntry SDK
Author: OneEntry

Obtén plantillas de vista previa: los tamaños y la alineación de recorte que OneEntry usa para generar vistas previas de imágenes.

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/ (abre en una nueva pestaña)

Una plantilla de vista previa define cómo OneEntry recorta una imagen para crear una vista previa. Las plantillas se crean en el panel de administración de OneEntry (Settings > Preview Templates) y se pueden asignar a un atributo «Image» o «Image Group» de un conjunto de atributos. Entonces OneEntry genera vistas previas para las imágenes de ese atributo; cambiar o eliminar la plantilla las regenera o las elimina. También puedes pasar el marcador o el ID de una plantilla en template al subir un archivo con FileUploading.upload(); la respuesta incluye entonces previewLink. En ambos casos, la plataforma elige la proporción horizontal, vertical o cuadrada según la orientación de la imagen, recorta la imagen en el servidor y guarda la vista previa. El módulo TemplatePreviews obtiene las plantillas para que puedas leer sus ajustes.

Inicio rápido

Inicializa el módulo desde defineOneEntry:


const {  } = defineOneEntry(
  , {
    
  }
);

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

// Fetch all preview templates, localized to English.
const previews = await TemplatePreviews.getTemplatePreviews("en_US");
if ('statusCode' in previews) throw new Error(previews.message);

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

// Or fetch a single preview template by its marker.
const preview = await TemplatePreviews.getTemplatePreviewByMarker("preview", "en_US");
if ('statusCode' in preview) throw new Error(preview.message);
console.log(preview.proportions.default.horizontal);

Objeto de plantilla de vista previa

Una plantilla de vista previa (ITemplatesPreviewEntity) es una configuración de vista previa de imágenes:

identifier: el marcador único al que haces referencia en el código.
title: el nombre de la plantilla que se muestra en el panel de administración. No es único.
proportions: conjuntos de parámetros de imagen por orientación (horizontal, vertical, cuadrada). Cada conjunto tiene su propio alignmentType, que controla cómo se recorta y se centra la imagen.

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;
  position: number;
  isUsed: boolean;
}

Un valor de ejemplo de proportions:

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

En el panel de administración configuras las tres orientaciones para cada plantilla de vista previa. El sistema detecta la orientación de la imagen y aplica el conjunto de proporciones correspondiente (horizontal, vertical o square).

Flujo de trabajo

1. Create a preview template in the admin panel
   (Define proportions for each orientation)
   ↓
2. Assign it to an image attribute,
   or pass its marker as `template` when uploading a file
   ↓
3. Use the preview link OneEntry returns

Crear plantillas de vista previa

El SDK es de solo lectura: no puedes crear plantillas de vista previa con él. Créalas en el panel de administración de OneEntry (Settings > Preview Templates). Cada plantilla necesita un Nombre (no único), un Marcador único y 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

Puedes crear varias plantillas de vista previa con distintos marcadores. Las plantillas se asignan por atributo en el panel de administración.

Obtener plantillas de vista previa

Haz referencia a las plantillas de vista previa en el código por su marcador (identifier): los marcadores son estables entre entornos. Usa getTemplatePreviewByMarker(marker) para una sola plantilla y getTemplatePreviews() para todas, por ejemplo para leer los tamaños de una plantilla.

Las plantillas de vista previa cambian poco, así que conviene almacenarlas en caché.