Skip to main content

TemplatePreviews

Fetch preview templates: the sizes and crop alignment OneEntry uses to generate image previews.

More information about preview templates in the OneEntry admin panel: https://doc.oneentry.cloud/docs/templates/templates_preview/ (opens in a new tab)


A preview template sets how OneEntry crops an image into a preview. You create templates in the OneEntry admin panel (Settings > Preview Templates) and can assign one to an "Image" or "Image Group" attribute in an attribute set. OneEntry then generates previews for that attribute's images; changing or removing the template regenerates or removes them. You can also pass a template's marker or ID in template when you upload a file with FileUploading.upload(); the response then includes previewLink. In both cases the platform picks the horizontal, vertical or square proportion set by the image's orientation, crops the image on the server and stores the preview. The TemplatePreviews module fetches the templates so you can read their settings.

Quickstart​

Initialize the module from defineOneEntry:


const { } = defineOneEntry(
, {
}
);

Fetch preview templates and read their proportions:

// 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);

Preview template object​

A preview template (ITemplatesPreviewEntity) is an image preview configuration:

  • identifier: the unique marker you reference in code.
  • title: the template name shown in the admin panel. Not unique.
  • proportions: image parameter sets per orientation (horizontal, vertical, square). Each set has its own alignmentType, which controls how the image is cropped and centered.
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;
}

A sample proportions value:

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

In the admin panel, you configure all three orientations for each preview template. The system detects an image's orientation and applies the matching proportion set (horizontal, vertical, or square).

Workflow​

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

Creating preview templates​

The SDK is read-only: you can't create preview templates through it. Create them in the OneEntry admin panel (Settings > Preview Templates). Each template needs a Name (not unique), a unique Marker, and proportion sets for three image orientations:

  • Horizontal: width, height, alignment type
  • Vertical: width, height, alignment type
  • Square: side length, alignment type

You can create several preview templates with different markers. A template is assigned per attribute in the admin panel.

Fetching preview templates​

Reference preview templates in code by marker (identifier): markers are stable across environments. Use getTemplatePreviewByMarker(marker) for a single template and getTemplatePreviews() for all of them, for example to read a template's sizes.

Preview templates rarely change, so they're good candidates for caching.

TemplatePreviews vs. Templates​

TemplatePreviews control server-side image previews; for general content, use Templates.

FeatureTemplatePreviewsTemplates
PurposeServer-side image previewsGeneral content display
Use CaseThumbnails and preview imagesHero images, product layouts
ScopeImage attributes and uploaded imagesPages, blocks, products

Methods​

MethodDescriptionUse Case
getTemplatePreviews()Fetch all preview templatesList all preview templates
getTemplatePreviewByMarker()Fetch a preview template by markerFetch a specific template configuration