Introduction

🎯 What does this module do?

The Templates module enables you to change the structure and appearance of your project without altering its source code. Templates allow you to manage components through the OneEntry Platform while maintaining flexible design and behavior options.

Templates work by letting you describe components in your project code, then tag them with platform-created templates. This separation allows switching between different template implementations to influence how entities function.

Think of it as your design system configurator - you create templates in OneEntry admin panel (Settings > Templates), tag your components with these templates, and this module fetches those configurations so your app can dynamically render content with consistent styling.

📖 Simple Explanation

Every application needs consistent content presentation:

🖼️ Image Templates - Predefined sizes and crops (thumbnail, hero, gallery)
📄 Page Templates - Page layout configurations (blog post, landing page)
🧱 Block Templates - Content block appearances (card, banner, section)
🛍️ Product Templates - Product display formats (grid, list, detail)
🎨 Responsive Design - Different sizes for mobile, tablet, desktop
♻️ Reusable Configs - Define once, use everywhere

The problem with hardcoded display logic:

Issues:

🔒 Inconsistent - Different sizes in different places
🎨 Hard to maintain - Change requires editing multiple files
📱 Not responsive - Fixed sizes don't adapt
♻️ No reusability - Duplicate code everywhere

The Templates solution:

Benefits:

🔒 Consistent - Same template used everywhere
🎨 Easy maintenance - Change in admin panel, applies everywhere
📱 Responsive - Different templates for different screens
♻️ Reusable - Define once, use throughout app

✨ Key Concepts

What is a Template?

A Template is a display configuration defining how content should appear:

Template Type - Image, page, block, product template
Dimensions - Width, height, aspect ratio
Crop Settings - How to crop images (center, top, bottom)
Format - Image format (JPEG, PNG, WebP)
Quality - Compression quality
Marker - Unique identifier for code reference

Template Structure

Each template has this structure:

{
  id: 1,                                    // Unique identifier
  title: "Product Thumbnail",               // Template name (non-unique)
  identifier: "product_thumbnail",          // Template marker (unique)
  generalTypeId: 1,                         // Type ID reference
  version: 0,                               // Version number
  attributeSetIdentifier: null,             // Associated attribute set
  localizeInfos: {                          // Localized information
    en_US: {
      title: "Product Thumbnail",
      description: "Small product image"
    }
  },
  attributeValues: {},                      // Additional attribute data
  isActive: true,                           // Active status
  createdAt: "2024-01-15T10:00:00Z",
  updatedAt: "2024-01-15T10:00:00Z"
}

Key Fields:

identifier - Unique marker for template reference (use this, not ID)
title - Template name displayed in admin panel
generalTypeId - Entity category the template applies to
attributeSetIdentifier - Optional associated attribute set

Template Types

Templates are organized by entity type and support the following categories:

Template Type	Entity Category	Example Use Cases
Product Blocks	`forCatalogProducts`	Product grid, product list, featured products
Regular Blocks	`forOneBlock`	Content cards, banners, sections, widgets
Error Pages	`forErrorPages`	404 page, 500 page, custom error layouts
Regular Pages	`forOnePage`	Blog post, landing page, about page
Product Pages	`forOneProduct`	Product detail, product comparison
Catalog Pages	`forCatalogPage`	Category listing, search results
Forms	`forForm`	Contact form, registration form, survey
Orders	`forOrder`	Order confirmation, order history

Common Image Templates

Template	Size	Crop	Use Case
Thumbnail	150×150	Center	Small preview images
Card Image	300×200	Center	Product cards, blog cards
Hero Image	1920×1080	Center	Full-width banners
Gallery Image	800×600	Center	Image galleries
Avatar	100×100	Center	User profile pictures
Mobile Hero	768×432	Center	Mobile-optimized banners

Template Configuration Workflow

1. Create templates in admin panel
   (Define sizes, crops, formats)
   ↓
2. Fetch templates via SDK
   (Templates.getTemplates())
   ↓
3. Apply template configurations
   (Use sizes in image rendering)
   ↓
4. Images automatically optimized
   (OneEntry CDN serves correct size)
   ↓
5. Consistent display everywhere
   (Same template = same appearance)

Why Use Templates Module?

Benefit	Description
Consistent Design	Same templates used throughout app
Easy Maintenance	Change template in admin, updates everywhere
Image Optimization	Automatic resizing and compression
Responsive Design	Different templates for different screens
CDN Integration	Optimized image delivery
Reusable Configs	Define once, use everywhere

📋 What You Need to Know

Templates are Created in Admin Panel

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

OneEntry Admin Panel → Settings → Templates → Create Template → Set Name/Marker/Type → Save

Creation Process:

Provide a Name (non-unique identifier)
Provide a Marker (unique identifier)
Select a Type (entity category the template applies to)
Click "Create" to finalize

Management Operations:

Configuration - Click the gear icon to edit name, marker, or type
Deletion - Select template and click delete icon, then confirm removal

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

Template Identification

Three ways to identify templates:

Method	When to Use	Example
By Type	Reference in code (best practice)	`product_thumbnail`, `hero_banner`
By Marker	Reference in code (best practice)	`product_thumbnail`, `hero_banner`
List All	Show available templates	`getTemplates()`

Best practice: Always use markers in your code (they never change).

Image Template CDN Integration

OneEntry automatically optimizes images based on templates.

Responsive Design with Templates

Create different templates for different screen sizes.

Template Structure:

interface ITemplateEntity {
  id: number;                        // Unique identifier
  title: string;                     // Template name (non-unique)
  identifier: string;                // Template marker (unique)
  generalTypeId: number;             // Type ID reference
  version: number;                   // Version number
  attributeSetIdentifier: string | null;  // Associated attribute set
  localizeInfos: {                   // Localized information
    [langCode: string]: {
      title: string;
      description?: string;
    };
  };
  attributeValues: any;              // Additional attribute data
  isActive: boolean;                 // Active status
}

Available Template Types:

forCatalogProducts - Product blocks
forOneBlock - Regular blocks
forErrorPages - Error pages
forOnePage - Regular pages
forOneProduct - Product pages
forCatalogPage - Catalog pages
forForm - Forms
forOrder - Orders

💡 Important Notes

Templates are Created in Admin Panel

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

To create/edit templates: Use OneEntry Admin Panel.

How Templates Work

Templates enable flexible component management by separating structure from code:

Describe components in your project code
Tag components with platform-created templates
Switch templates to change how entities function
Update appearance without modifying source code

This separation allows multiple design and functional variations without code changes.

Image Optimization

OneEntry CDN automatically optimizes images based on template settings:

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

You just reference the template marker:

<img src={`${image.url}?template=thumbnail`} />

Responsive Templates

Create separate templates for different devices:

Mobile templates (768px wide or less)
Tablet templates (1024px wide)
Desktop templates (1920px wide)

Use with <picture> element for responsive images.

Template Caching

Templates rarely change - implement caching:

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

📊 Quick Reference Table

Method	Description	Use Case
getAllTemplates()	Get all templates grouped by types	List all available templates
getTemplateByType()	Get templates by entity type	Fetch templates for specific entity type
getTemplateByMarker()	Get template by marker	Fetch specific template configuration

❓ Common Questions (FAQ)

What's the difference between Templates and TemplatePreviews?

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

How do I apply a template to an image URL?

Append ?template=marker to the image URL, where marker is the template identifier. OneEntry CDN automatically serves the optimized image based on the template configuration (size, crop, format).

Can I create different templates for mobile and desktop?

Yes! Create separate templates with appropriate sizes for each device (e.g., hero_mobile, hero_desktop). Use responsive design techniques or <picture> elements to load the correct template based on screen size.

What happens if I reference a template that doesn't exist?

The image will load in its original size without template optimization. Always verify template markers exist and handle missing templates gracefully with fallback sizes.

How do I update a template without affecting production?

Templates are configuration, not code. Changes in the admin panel apply immediately. Test template changes in a staging environment first, then update production templates when verified.

Which template types should I use for my content?

Choose based on entity type: forOnePage for standard pages, forCatalogProducts for product listings, forOneBlock for content blocks, forOneProduct for product details. Match the template type to your content category.

🎓 Best Practices

Use markers, not IDs - Markers are stable across environments
Cache templates - Reduce API calls for rarely-changing data
Create responsive templates - Different sizes for different screens
Use WebP format - Better compression than JPEG/PNG
Define quality settings - Balance quality vs file size
Use CDN template parameters - ?template=marker for optimization
Create semantic markers - product_thumbnail, not img_1
Document template usage - Explain what each template is for

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

Definition of the Templates module

The Templates module configures the display of content within your application.

Some templates affect images stored in the OneEntry, while others define the appearance of entities such as blocks, pages, and products.


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

OneEntry Admin Panel - Content Templates - Official admin panel documentation
TemplatePreviews Module - Preview templates for attribute images
Products Module - Products use product templates
Pages Module - Pages use page templates
Blocks Module - Blocks use block templates
Forms Module - Forms use form templates
Image Optimization Best Practices

Introduction

🎯 What does this module do?​

📖 Simple Explanation​

✨ Key Concepts​

What is a Template?​

Template Structure​

Template Types​

Common Image Templates​

Template Configuration Workflow​

Why Use Templates Module?​

📋 What You Need to Know​

Templates are Created in Admin Panel​

Template Identification​

Image Template CDN Integration​

Responsive Design with Templates​

💡 Important Notes​

Templates are Created in Admin Panel​

How Templates Work​

Image Optimization​

Responsive Templates​

Template Caching​

📊 Quick Reference Table​

❓ Common Questions (FAQ)​

What's the difference between Templates and TemplatePreviews?​

How do I apply a template to an image URL?​

Can I create different templates for mobile and desktop?​

What happens if I reference a template that doesn't exist?​

How do I update a template without affecting production?​

Which template types should I use for my content?​

🎓 Best Practices​

Definition of the Templates module​

🔗 Related Documentation​

🎯 What does this module do?

📖 Simple Explanation

✨ Key Concepts

What is a Template?

Template Structure

Template Types

Common Image Templates

Template Configuration Workflow

Why Use Templates Module?

📋 What You Need to Know

Templates are Created in Admin Panel

Template Identification

Image Template CDN Integration

Responsive Design with Templates

💡 Important Notes

Templates are Created in Admin Panel

How Templates Work

Image Optimization

Responsive Templates

Template Caching

📊 Quick Reference Table

❓ Common Questions (FAQ)

What's the difference between Templates and TemplatePreviews?

How do I apply a template to an image URL?

Can I create different templates for mobile and desktop?

What happens if I reference a template that doesn't exist?

How do I update a template without affecting production?

Which template types should I use for my content?

🎓 Best Practices

Definition of the Templates module

🔗 Related Documentation