Ana içeriğe geç

Introduction

Fetch display templates that control how pages, blocks, products, and images render across your app.

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

🎯 What does this module do?​

The Templates module lets you change the structure and appearance of your project without altering its source code. You create templates in the OneEntry admin panel (Settings > Templates), tag your components with them, and this module fetches those configurations so your app can render content with consistent styling.

This separation of structure from code lets you switch between template implementations to influence how entities render, all without redeploying. The SDK is read-only: you cannot create templates through it.

🚀 Quickstart​

Initialize the module from defineOneEntry:


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

Fetch templates and read their configuration:

// Fetch all templates of a given BlockType.
const productTemplates = await Templates.getTemplateByType("product", "en_US");

productTemplates.forEach((tpl) => {
  console.log(tpl.identifier, tpl.title, tpl.generalTypeName);
});

// Or fetch a single template by its marker.
const card = await Templates.getTemplateByMarker("product_thumbnail", "en_US");
console.log(card.attributeValues);

✨ Key Concepts​

What is a Template?​

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

  • General Type (generalTypeName) - The entity category the template applies to, a BlockType such as product, common_page, common_block, form, or order
  • Title (title) - Template name displayed in the admin panel (non-unique)
  • Marker (identifier) - Unique identifier for code reference (use this, not the ID)
  • Attribute Values (attributeValues) - Map of attribute values keyed by marker
  • Attribute Set (attributeSetIdentifier) - Optional associated attribute set

Template structure (ITemplateEntity):

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
  generalTypeName: BlockType;              // General type name
  attributeSetIdentifier: string | null;   // Associated attribute set
  attributeValues: IAttributeValues;       // Map of attribute values keyed by marker
  position: number;                        // Sort position
}

Template Types (BlockType)​

A template's type is its generalTypeName, a BlockType value. getTemplateByType(type) accepts the same BlockType. Common values:

TypeEntity CategoryExample Use Cases
productProductsProduct detail, product display
catalog_pageCatalog pagesCategory listing, search results
common_pageRegular pagesBlog post, landing page, about page
error_pageError pages404 page, 500 page, custom error layouts
common_blockContent blocksContent cards, banners, sections, widgets
formFormsContact form, registration form, survey
orderOrdersOrder confirmation, order history
serviceService entitiesService-related content

📋 What You Need to Know​

Templates are created in the admin panel​

You cannot create templates via the SDK - they're created in the OneEntry admin panel (Settings > Templates). Each template needs a Name (non-unique), a unique Marker, and a Type (the entity category it applies to). The SDK is for fetching template configurations, not creating them.

Use markers, not IDs​

Always reference templates by their marker (identifier) in your code - markers are stable across environments, IDs are not. Use getTemplateByMarker(marker) for a single template, getTemplateByType(type) for all templates of one BlockType, and getAllTemplates() for every template grouped by type.

Missing templates​

The methods return an error object (IError) when a template is not found. Always verify markers exist and handle missing templates gracefully.

Caching​

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
getAllTemplates()Get all templates grouped by typeList all available templates
getTemplateByType()Get templates by entity typeFetch templates for a specific entity type
getTemplateByMarker()Get a template by markerFetch a 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 fetch a specific template?​

Use getTemplateByMarker(marker) for a single template by its identifier, or getTemplateByType(type) to fetch all templates of a given BlockType (e.g. product, common_page). Use getAllTemplates() to retrieve every template grouped by type.

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

The methods return an error object (IError). Always verify template markers exist and handle missing templates gracefully.

Which template types should I use for my content?​

Choose based on entity type: common_page for standard pages, catalog_page for product listings, common_block for content blocks, product for product details. Match the template type to your content category.

🎓 Best Practices​

  • Use markers, not IDs - markers are stable across environments.
  • Create semantic markers - product_card, not tpl_1.
  • Cache templates - reduce API calls for rarely-changing data.
  • Handle missing templates - check for the IError return shape.

🔗 Related Documentation​