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 ownalignmentType, 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.
| Feature | TemplatePreviews | Templates |
|---|---|---|
| Purpose | Server-side image previews | General content display |
| Use Case | Thumbnails and preview images | Hero images, product layouts |
| Scope | Image attributes and uploaded images | Pages, blocks, products |
Methods
| Method | Description | Use Case |
|---|---|---|
| getTemplatePreviews() | Fetch all preview templates | List all preview templates |
| getTemplatePreviewByMarker() | Fetch a preview template by marker | Fetch a specific template configuration |
Related
- OneEntry Admin Panel - Preview Templates: official admin panel documentation
- Templates Module: general content templates
- Attributes Module: product attributes configuration
- Products Module: products with attributes
- Image Optimization Best Practices