Pular para o conteúdo principal

Introdução

Busque templates de exibição que controlam como páginas, blocks, produtos e imagens são renderizados em seu aplicativo.

Mais informações sobre templates no painel de administração do OneEntry: https://doc.oneentry.cloud/docs/category/templates

🎯 O que este módulo faz?​

O módulo Templates permite que você mude a estrutura e a aparência do seu projeto sem alterar seu código-fonte. Você cria templates no painel de administração do OneEntry (Configurações > Templates), marca seus componentes com eles, e este módulo busca essas configurações para que seu aplicativo possa renderizar conteúdo com um estilo consistente.

Essa separação entre estrutura e código permite que você troque entre implementações de templates para influenciar como as entidades são renderizadas, tudo isso sem precisar redeployar. O SDK é somente leitura: você não pode criar templates através dele.

🚀 Início Rápido​

Inicialize o módulo a partir de defineOneEntry:


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

Busque templates e leia suas configurações:

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

✨ Conceitos Chave​

O que é um Template?​

Um Template (ITemplateEntity) é uma configuração de exibição que define como o conteúdo deve aparecer:

  • Tipo Geral (generalTypeName) - A categoria da entidade à qual o template se aplica, um BlockType como product, common_page, common_block, form ou order
  • Título (title) - Nome do template exibido no painel de administração (não único)
  • Marcador (identifier) - Identificador único para referência de código (use isso, não o ID)
  • Valores de Atributo (attributeValues) - Mapa de valores de atributo indexados por marcador
  • Conjunto de Atributos (attributeSetIdentifier) - Conjunto de atributos associado opcional

Estrutura do Template (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
}

Tipos de Template (BlockType)​

O tipo de um template é seu generalTypeName, um valor de BlockType. getTemplateByType(type) aceita o mesmo BlockType. Valores comuns:

TipoCategoria da EntidadeExemplos de Casos de Uso
productProdutosDetalhe do produto, exibição do produto
catalog_pagePáginas de catálogoListagem de categorias, resultados de busca
common_pagePáginas regularesPostagem de blog, página de destino, página sobre
error_pagePáginas de erroPágina 404, página 500, layouts de erro personalizados
common_blockBlocos de conteúdoCartões de conteúdo, banners, seções, widgets
formFormuláriosFormulário de contato, formulário de registro, pesquisa
orderPedidosConfirmação de pedido, histórico de pedidos
serviceEntidades de serviçoConteúdo relacionado a serviços

📋 O que você precisa saber​

Templates são criados no painel de administração​

Você não pode criar templates via SDK - eles são criados no painel de administração do OneEntry (Configurações > Templates). Cada template precisa de um Nome (não único), um Marcador único e um Tipo (a categoria da entidade à qual se aplica). O SDK é para buscar configurações de templates, não para criá-los.

Use marcadores, não IDs​

Sempre faça referência aos templates pelo seu marcador (identifier) em seu código - os marcadores são estáveis entre ambientes, os IDs não são. Use getTemplateByMarker(marker) para um único template, getTemplateByType(type) para todos os templates de um BlockType, e getAllTemplates() para cada template agrupado por tipo.

Templates ausentes​

Os métodos retornam um objeto de erro (IError) quando um template não é encontrado. Sempre verifique se os marcadores existem e trate templates ausentes de forma adequada.

Cache​

Templates raramente mudam - armazene-os em cache (localStorage/sessionStorage no frontend, Redis/memória no backend; ~1 hora de TTL é um ponto de partida razoável).

📊 Tabela de Referência Rápida​

MétodoDescriçãoCaso de Uso
getAllTemplates()Obter todos os templates agrupados por tipoListar todos os templates disponíveis
getTemplateByType()Obter templates por tipo de entidadeBuscar templates para um tipo de entidade específico
getTemplateByMarker()Obter um template por marcadorBuscar uma configuração de template específica

❓ Perguntas Comuns (FAQ)​

Qual é a diferença entre Templates e TemplatePreviews?​

Templates configuram a exibição geral do conteúdo (páginas, blocks, produtos), enquanto TemplatePreviews lidam especificamente com imagens de atributos de produtos (amostras de cores, pré-visualizações de materiais). Use Templates para conteúdo principal, TemplatePreviews para imagens de atributos.

Como faço para buscar um template específico?​

Use getTemplateByMarker(marker) para um único template pelo seu identificador, ou getTemplateByType(type) para buscar todos os templates de um dado BlockType (por exemplo, product, common_page). Use getAllTemplates() para recuperar todos os templates agrupados por tipo.

O que acontece se eu referenciar um template que não existe?​

Os métodos retornam um objeto de erro (IError). Sempre verifique se os marcadores de template existem e trate templates ausentes de forma adequada.

Quais tipos de template devo usar para meu conteúdo?​

Escolha com base no tipo de entidade: common_page para páginas padrão, catalog_page para listagens de produtos, common_block para blocos de conteúdo, product para detalhes de produtos. Combine o tipo de template com a categoria do seu conteúdo.

🎓 Melhores Práticas​

  • Use marcadores, não IDs - marcadores são estáveis entre ambientes.
  • Crie marcadores semânticos - product_card, não tpl_1.
  • Armazene templates em cache - reduza chamadas à API para dados que raramente mudam.
  • Trate templates ausentes - verifique a forma de retorno IError.

🔗 Documentação Relacionada​