Skip to main content

Introduction

🎯 What does this module do?​

The TemplatePreviews module allows you to standardize image parameters across your project. By applying preview templates to "Image" or "Image Group" attributes, you ensure consistent sizing and formatting that aligns with your design requirements.

Preview templates configure image parameters used in attributes, delivering images standardized according to the specifications set in the preview template. This ensures consistent image display across product images, variant images, and attribute-based images.

Think of it as your attribute image configurator - you create preview templates in OneEntry admin panel (Settings > Preview Templates), and this module fetches those configurations so product attributes with images render consistently across your catalog.

📖 Simple Explanation​

Every e-commerce application needs consistent product images across attributes:

  • 🎨 Color Swatches - Product color variants (Red, Blue, Green) with preview images
  • 📏 Size Charts - Size attribute images (Small, Medium, Large) with visual guides
  • 🖼️ Material Previews - Material attribute images (Leather, Cotton, Silk) with textures
  • 💎 Finish Options - Surface finish images (Glossy, Matte, Satin) with visual examples
  • 👗 Pattern Previews - Pattern attribute images (Striped, Solid, Floral) with samples
  • 🏷️ Attribute Galleries - Consistent image sizing for all product attributes

The problem with inconsistent attribute images

Issues:

  • 🎨 Inconsistent display - Different attribute images have different sizes
  • 📊 Hard to maintain - Change requires editing multiple components
  • 🔄 No reusability - Same sizing logic duplicated everywhere
  • 🖼️ Poor UX - Attribute images look misaligned and unprofessional

The TemplatePreviews solution

Benefits:

  • 🎨 Consistent display - All attribute images use same template
  • 📊 Easy maintenance - Change template in admin panel
  • 🔄 Reusable - Same template across all attributes
  • 🖼️ Professional UX - Aligned, uniform attribute images

✨ Key Concepts​

What is a Template Preview?​

A Template Preview is an image configuration for product attributes:

  • Attribute Images - Images associated with product attributes (color, size, material)
  • Preview Size - Dimensions for attribute image display
  • Crop Settings - How to crop attribute images
  • Marker - Unique identifier for template reference
  • Consistency - Same template ensures uniform attribute image display

Template Preview Structure​

Each template preview has this structure:

{
  id: 3,                                      // Unique identifier
  title: 'Preview Templates',                 // Template name (non-unique)
  identifier: 'preview-templates',            // Template marker (unique)
  proportions: {                              // Image parameter sets
    default: {                                // Default template configuration
      horizontal: {                           // For horizontal images
        width: 234,                           // Width in pixels
        height: 324,                          // Height in pixels
        alignmentType: 'middleBottom'         // Centering type (compression axis)
      },
      vertical: {                             // For vertical images
        width: 2,
        height: 3,
        alignmentType: 'leftTop'
      },
      square: {                               // For square images
        side: 3,                              // Side length in pixels
        alignmentType: 'leftTop'
      },
    },
  },
  version: 0,                                 // Version number
  attributeValues: {},                        // Additional attribute data
  position: 1,                                // Display position
  isUsed: false,                              // Usage status
  attributeSetIdentifier: null                // Associated attribute set
}

Key Fields:

  • identifier - Unique marker for template reference (use this, not ID)
  • title - Template name displayed in admin panel
  • proportions - Image configuration for different orientations
  • alignmentType - Defines how images are cropped/centered

Template Preview Workflow​

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

Why Use TemplatePreviews Module?​

BenefitDescription
Consistent AttributesAll attribute images same size
Image OptimizationAutomatic resizing and compression
Easy MaintenanceChange template, updates all attributes
Better UXUniform, professional attribute display
CDN IntegrationOptimized delivery of attribute images
Reusable ConfigsSame template for all color swatches

📋 What You Need to Know​

Template Previews are Created in Admin Panel​

You cannot create template previews via the SDK - they're created in the OneEntry admin panel:

OneEntry Admin Panel → Settings → Preview Templates → Create Template → Set Name/Marker → Configure Parameters → Save

Creation Process:

  • Provide a Name (non-unique identifier)
  • Provide a Marker (unique identifier)
  • Click "Create" to finalize

Configuration:

  • Select template and click the gear icon to configure
  • Add preview parameter sets for three image orientations:
    • Vertical - Width, Height, Centering Type
    • Horizontal - Width, Height, Centering Type
    • Square - Side length, Centering Type
  • Designate one parameter set as the default template

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

Template Previews vs Templates​

TemplatePreviews are specifically for product attribute images:

FeatureTemplatePreviewsTemplates
PurposeAttribute image previewsGeneral content images
Use CaseColor swatches, material previewsHero images, product photos
ScopeProduct attributes onlyPages, blocks, products
Example50×50 color swatch1920×1080 hero banner

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

Applying Templates to Attribute Images​

OneEntry automatically optimizes attribute images based on preview templates

Template Preview Assignment​

Preview templates are typically assigned to specific attribute types

Consistent Attribute Display​

Use template previews to ensure uniform attribute image display

TemplatePreview Structure:

interface ITemplatesPreviewEntity {
  id: number;
  title: string;
  proportions: {
    default: {
      horizontal: IProportion | null;
      vertical: IProportion | null;
      square: ISquare;
    };
  };
  identifier: string;
  version: number;
  attributeValues: AttributeType;
  position: number;
  isUsed: boolean;
  attributeSetIdentifier?: string | null;
}

💡 Important Notes​

Template Previews are Created in Admin Panel​

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

To create/edit template previews: Use OneEntry Admin Panel.

Attribute Image Optimization​

OneEntry CDN automatically optimizes attribute images based on preview template settings:

  • Automatic resizing
  • Format conversion (JPEG, PNG, WebP)
  • Compression
  • Cropping
  • Caching

You just reference the template marker

Template Preview Caching​

Template previews rarely change - implement caching:

  • Frontend: localStorage, sessionStorage
  • Backend: Redis, memory cache
  • TTL: 1 hour recommended

Consistent Attribute Display​

Use same preview template for same attribute type:

  • All color attributes → color_swatch template
  • All material attributes → material_preview template
  • All pattern attributes → pattern_thumbnail template

Consistency improves UX and looks professional.

Common attribute image sizes:

  • Color Swatches: 50×50 to 100×100
  • Material Previews: 80×80 to 150×150
  • Pattern Thumbnails: 60×60 to 120×120
  • Size Charts: 100×80 to 200×150
  • Finish Previews: 75×75 to 100×100

LQIP Technology​

Preview templates use Low-Quality Image Placeholder (LQIP) technology for optimal loading performance:

How it works:

  • Returns a two-element array structure:
    1. Thumbnail - WebP format, optimized for fast loading (few hundred bytes)
    2. Generated Preview - Full resolution image that replaces thumbnail after loading

✅ Benefits:

  • Instant display with thumbnail
  • Smooth transition to full quality
  • Reduced bandwidth consumption
  • Better user experience

Deleting Templates​

To remove a template:

  1. Select the template in admin panel
  2. Click the delete icon
  3. Confirm removal

Note: Only unused templates can be deleted.

📊 Quick Reference Table​

MethodDescriptionUse Case
getTemplatePreviews()Get all preview templatesList all available attribute templates
getTemplatesPreviewByMarker()Get preview template by markerFetch 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 images (hero banners, product photos). 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 automatically detects image orientation and applies the appropriate proportions (horizontal, vertical, or square).

What is LQTP and why does it matter?​

LQIP (Low-Quality Image Placeholder) loads a tiny thumbnail first (few hundred bytes), then replaces it with the full-quality image. This provides instant visual feedback and improves perceived performance, especially on slow connections.

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 them to the appropriate attribute types for consistent rendering.

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

Preview templates are applied automatically when you configure them in the admin panel. Fetch the template via getTemplatesPreviewByMarker() and use the proportions to render attribute images with consistent sizing.

Keep attribute images small: 50-150px for optimal performance. Common sizes: Color swatches (50×50 to 100×100), Material previews (80×80 to 150×150), Pattern thumbnails (60×60 to 120×120).

🎓 Best Practices​

  • Use markers, not IDs - Markers are stable across environments
  • Cache preview templates - Reduce API calls for rarely-changing data
  • Create consistent sizes - Same attribute type = same template size
  • Use WebP format - Better compression for attribute images
  • Define quality settings - Balance quality vs file size (80-90 recommended)
  • Map attributes to templates - Create attributeType → template mapping
  • Use semantic markers - color_swatch, not preview_1
  • Test on mobile - Ensure attribute images look good on small screens

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

Definition of the TemplatePreviews module​


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

🔗 Related Documentation​