Skip to main content

Introduction

Fetch preview templates that standardize image sizing and formatting for product attribute images.

More information about preview templates in the OneEntry admin panel: https://doc.oneentry.cloud/docs/templates/templates_preview/

🎯 What does this module do?​

The TemplatePreviews module lets you standardize image parameters across your project. By applying preview templates to "Image" or "Image Group" attributes, you deliver images sized and cropped consistently according to the template's configuration - across product images, variant images, and attribute-based images.

You create preview templates in the OneEntry admin panel (Settings > Preview Templates), and this module fetches those configurations so product attributes with images render consistently. The SDK is read-only: you cannot create preview templates through it.

🚀 Quickstart​

Initialize the module from defineOneEntry:


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

Fetch preview templates and read their proportions:

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

✨ Key Concepts​

What is a Template Preview?​

A Template Preview (ITemplatesPreviewEntity) is an image configuration for product attributes:

  • Marker (identifier) - Unique identifier for template reference (use this, not the ID)
  • Title (title) - Template name displayed in the admin panel (non-unique)
  • Proportions (proportions) - Image parameter sets per orientation (horizontal, vertical, square)
  • Alignment (alignmentType) - How images are cropped/centered

Template Preview Structure​

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;
}

A sample proportions value:

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

Template Preview Workflow​

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)

📋 What You Need to Know​

Preview templates are created in the admin panel​

You cannot create preview templates via the SDK - they're created in the OneEntry admin panel (Settings > Preview Templates). Each template needs a Name (non-unique) and a unique Marker, plus proportion sets for three image orientations:

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

The SDK is for fetching preview template configurations, not creating them.

Use markers, not IDs​

Reference preview templates by their marker (identifier) in your code - markers are stable across environments. Use getTemplatePreviewByMarker(marker) for a single template and getTemplatePreviews() for all of them.

TemplatePreviews vs Templates​

TemplatePreviews are specifically for product attribute images:

FeatureTemplatePreviewsTemplates
PurposeAttribute image previewsGeneral content display
Use CaseColor swatches, material previewsHero images, product layouts
ScopeProduct attributes onlyPages, blocks, products

Best practice: Use TemplatePreviews for attribute images, Templates for general content.

Caching​

Preview templates rarely change - cache them (localStorage/sessionStorage on the frontend, Redis/memory on the backend; ~1 hour TTL is a reasonable starting point).

📊 Quick Reference Table​

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

❓ Common Questions (FAQ)​

What's the difference between TemplatePreviews and Templates?​

TemplatePreviews are specifically for product attribute images (color swatches, material previews), while Templates handle general content display (pages, blocks, products). Use TemplatePreviews for attribute-specific images only.

How do I configure different sizes for horizontal, vertical, and square images?​

In the admin panel, 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).

Can I assign different preview templates to different attribute types?​

Yes. Create multiple preview templates with different markers (e.g., color_swatch, material_preview, pattern_thumbnail) and assign each to the appropriate attribute type for consistent rendering.

How do I apply a preview template to attribute images?​

Fetch the template via getTemplatePreviewByMarker() and use its proportions to render attribute images with consistent sizing. Assignment of a template to an attribute type is done in the admin panel.

🎓 Best Practices​

  • Use markers, not IDs - markers are stable across environments.
  • Use semantic markers - color_swatch, not preview_1.
  • Map attributes to templates - keep one template per attribute type for consistency.
  • Cache preview templates - reduce API calls for rarely-changing data.

🔗 Related Documentation​