Introdução

🎯 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. Os templates permitem que você gerencie componentes através da Plataforma OneEntry, mantendo opções de design e comportamento flexíveis.

Os templates funcionam permitindo que você descreva componentes no código do seu projeto e, em seguida, os marque com templates criados pela plataforma. Essa separação permite alternar entre diferentes implementações de templates para influenciar como as entidades funcionam.

Pense nisso como seu configurador de sistema de design - você cria templates no painel de administração do OneEntry (Configurações > Templates), marca seus componentes com esses templates, e este módulo busca essas configurações para que seu aplicativo possa renderizar conteúdo dinamicamente com um estilo consistente.

📖 Explicação Simples

Toda aplicação precisa de uma apresentação de conteúdo consistente:

🖼️ Templates de Imagem - Tamanhos e cortes predefinidos (miniatura, herói, galeria)
📄 Templates de Página - Configurações de layout de página (postagem de blog, página de destino)
🧱 Templates de Bloco - Aparências de blocos de conteúdo (cartão, banner, seção)
🛍️ Templates de Produto - Formatos de exibição de produtos (grade, lista, detalhe)
🎨 Design Responsivo - Tamanhos diferentes para mobile, tablet, desktop
♻️ Configs Reutilizáveis - Defina uma vez, use em toda parte

O problema com a lógica de exibição codificada:

Problemas:

🔒 Inconsistente - Tamanhos diferentes em lugares diferentes
🎨 Difícil de manter - Mudanças requerem edição de múltiplos arquivos
📱 Não responsivo - Tamanhos fixos não se adaptam
♻️ Sem reutilização - Código duplicado em toda parte

A solução dos Templates:

Benefícios:

🔒 Consistente - Mesmo template usado em toda parte
🎨 Fácil manutenção - Mudança no painel de administração, aplica-se em toda parte
📱 Responsivo - Diferentes templates para diferentes telas
♻️ Reutilizável - Defina uma vez, use em todo o aplicativo

✨ Conceitos Chave

O que é um Template?

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

Tipo de Template - Template de imagem, página, bloco, produto
Dimensões - Largura, altura, proporção
Configurações de Corte - Como cortar imagens (centro, topo, fundo)
Formato - Formato da imagem (JPEG, PNG, WebP)
Qualidade - Qualidade de compressão
Marcador - Identificador único para referência de código

Estrutura do Template

Cada template tem esta estrutura:

{
  id: 1,                                    // Identificador único
  title: "Miniatura do Produto",            // Nome do template (não único)
  identifier: "product_thumbnail",          // Marcador do template (único)
  generalTypeId: 1,                         // Referência do ID do tipo
  version: 0,                               // Número da versão
  attributeSetIdentifier: null,             // Conjunto de atributos associado
  localizeInfos: {                          // Informações localizadas
    en_US: {
      title: "Miniatura do Produto",
      description: "Imagem pequena do produto"
    }
  },
  attributeValues: {},                      // Dados adicionais de atributos
  isActive: true,                           // Status ativo
  createdAt: "2024-01-15T10:00:00Z",
  updatedAt: "2024-01-15T10:00:00Z"
}

Campos Chave:

identifier - Marcador único para referência do template (use isso, não o ID)
title - Nome do template exibido no painel de administração
generalTypeId - Categoria da entidade à qual o template se aplica
attributeSetIdentifier - Conjunto de atributos associado opcional

Tipos de Template

Os templates são organizados por tipo de entidade e suportam as seguintes categorias:

Tipo de Template	Categoria da Entidade	Exemplos de Casos de Uso
Blocos de Produto	`forCatalogProducts`	Grade de produtos, lista de produtos, produtos em destaque
Blocos Regulares	`forOneBlock`	Cartões de conteúdo, banners, seções, widgets
Páginas de Erro	`forErrorPages`	Página 404, página 500, layouts de erro personalizados
Páginas Regulares	`forOnePage`	Postagem de blog, página de destino, página sobre
Páginas de Produto	`forOneProduct`	Detalhe do produto, comparação de produtos
Páginas de Catálogo	`forCatalogPage`	Listagem de categorias, resultados de busca
Formulários	`forForm`	Formulário de contato, formulário de registro, pesquisa
Pedidos	`forOrder`	Confirmação de pedido, histórico de pedidos

Templates de Imagem Comuns

Template	Tamanho	Corte	Caso de Uso
Miniatura	150×150	Centro	Imagens de pré-visualização pequenas
Imagem de Cartão	300×200	Centro	Cartões de produtos, cartões de blog
Imagem Hero	1920×1080	Centro	Banners de largura total
Imagem de Galeria	800×600	Centro	Galerias de imagens
Avatar	100×100	Centro	Imagens de perfil de usuário
Hero Mobile	768×432	Centro	Banners otimizados para mobile

Fluxo de Trabalho de Configuração de Template

1. Crie templates no painel de administração
   (Defina tamanhos, cortes, formatos)
   ↓
2. Busque templates via SDK
   (Templates.getTemplates())
   ↓
3. Aplique configurações de template
   (Use tamanhos na renderização de imagens)
   ↓
4. Imagens otimizadas automaticamente
   (CDN OneEntry serve o tamanho correto)
   ↓
5. Exibição consistente em toda parte
   (Mesmo template = mesma aparência)

Por que usar o módulo Templates?

Benefício	Descrição
Design Consistente	Mesmos templates usados em todo o aplicativo
Fácil Manutenção	Mude o template na administração, atualiza em toda parte
Otimização de Imagem	Redimensionamento e compressão automáticos
Design Responsivo	Diferentes templates para diferentes telas
Integração CDN	Entrega otimizada de imagens
Configs Reutilizáveis	Defina uma vez, use em toda parte

📋 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:

Painel de Administração do OneEntry → Configurações → Templates → Criar Template → Definir Nome/Marcador/Tipo → Salvar

Processo de Criação:

Forneça um Nome (identificador não único)
Forneça um Marcador (identificador único)
Selecione um Tipo (categoria da entidade à qual o template se aplica)
Clique em "Criar" para finalizar

Operações de Gerenciamento:

Configuração - Clique no ícone de engrenagem para editar nome, marcador ou tipo
Exclusão - Selecione o template e clique no ícone de excluir, depois confirme a remoção

O SDK é para buscar configurações de templates, não para criá-los.

Identificação de Template

Três maneiras de identificar templates:

Método	Quando Usar	Exemplo
Por Tipo	Referência no código (melhor prática)	`product_thumbnail`, `hero_banner`
Por Marcador	Referência no código (melhor prática)	`product_thumbnail`, `hero_banner`
Listar Todos	Mostrar templates disponíveis	`getTemplates()`

Melhor prática: Sempre use marcadores no seu código (eles nunca mudam).

Integração de CDN de Template de Imagem

O OneEntry otimiza automaticamente as imagens com base nos templates.

Design Responsivo com Templates

Crie diferentes templates para diferentes tamanhos de tela.

Estrutura do Template:

interface ITemplateEntity {
  id: number;                        // Identificador único
  title: string;                     // Nome do template (não único)
  identifier: string;                // Marcador do template (único)
  generalTypeId: number;             // Referência do ID do tipo
  version: number;                   // Número da versão
  attributeSetIdentifier: string | null;  // Conjunto de atributos associado
  localizeInfos: {                   // Informações localizadas
    [langCode: string]: {
      title: string;
      description?: string;
    };
  };
  attributeValues: any;              // Dados adicionais de atributos
  isActive: boolean;                 // Status ativo
}

Tipos de Template Disponíveis:

forCatalogProducts - Blocos de produto
forOneBlock - Blocos regulares
forErrorPages - Páginas de erro
forOnePage - Páginas regulares
forOneProduct - Páginas de produto
forCatalogPage - Páginas de catálogo
forForm - Formulários
forOrder - Pedidos

💡 Notas Importantes

Templates são Criados no Painel de Administração

Lembre-se: O SDK é para buscar configurações de templates, não para criar templates.

Para criar/editar templates: Use o Painel de Administração do OneEntry.

Como os Templates Funcionam

Os templates permitem uma gestão flexível de componentes ao separar a estrutura do código:

Descreva componentes no código do seu projeto
Marque componentes com templates criados pela plataforma
Alterne templates para mudar como as entidades funcionam
Atualize a aparência sem modificar o código-fonte

Essa separação permite múltiplas variações de design e funcionalidade sem mudanças no código.

Otimização de Imagem

O CDN OneEntry otimiza automaticamente as imagens com base nas configurações do template:

Redimensionamento automático
Conversão de formato (JPEG, PNG, WebP)
Compressão
Corte
Cache

Você apenas referencia o marcador do template:

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

Templates Responsivos

Crie templates separados para diferentes dispositivos:

Templates para mobile (768px de largura ou menos)
Templates para tablet (1024px de largura)
Templates para desktop (1920px de largura)

Use com o elemento <picture> para imagens responsivas.

Cache de Template

Templates raramente mudam - implemente cache:

Frontend: localStorage, sessionStorage
Backend: Redis, cache de memória
TTL: 1 hora recomendada

📊 Tabela de Referência Rápida

Método	Descrição	Caso de Uso
getAllTemplates()	Obter todos os templates agrupados por tipos	Listar todos os templates disponíveis
getTemplateByType()	Obter templates por tipo de entidade	Buscar templates para tipo de entidade específico
getTemplateByMarker()	Obter template por marcador	Buscar 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, blocos, 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 aplico um template a uma URL de imagem?

Anexe ?template=marker à URL da imagem, onde marker é o identificador do template. O CDN OneEntry serve automaticamente a imagem otimizada com base na configuração do template (tamanho, corte, formato).

Posso criar diferentes templates para mobile e desktop?

Sim! Crie templates separados com tamanhos apropriados para cada dispositivo (por exemplo, hero_mobile, hero_desktop). Use técnicas de design responsivo ou elementos <picture> para carregar o template correto com base no tamanho da tela.

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

A imagem será carregada em seu tamanho original sem otimização de template. Sempre verifique se os marcadores de template existem e trate templates ausentes de forma adequada com tamanhos de fallback.

Como atualizo um template sem afetar a produção?

Templates são configurações, não código. Mudanças no painel de administração se aplicam imediatamente. Teste as mudanças de template em um ambiente de staging primeiro, depois atualize os templates de produção quando verificados.

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

Escolha com base no tipo de entidade: forOnePage para páginas padrão, forCatalogProducts para listagens de produtos, forOneBlock para blocos de conteúdo, forOneProduct para detalhes de produtos. Combine o tipo de template com sua categoria de conteúdo.

🎓 Melhores Práticas

Use marcadores, não IDs - Marcadores são estáveis entre ambientes
Cache templates - Reduza chamadas de API para dados que raramente mudam
Crie templates responsivos - Tamanhos diferentes para diferentes telas
Use formato WebP - Melhor compressão do que JPEG/PNG
Defina configurações de qualidade - Equilibre qualidade vs tamanho do arquivo
Use parâmetros de template CDN - ?template=marker para otimização
Crie marcadores semânticos - product_thumbnail, não img_1
Documente o uso de templates - Explique para que cada template serve

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

Definição do módulo Templates

O módulo Templates configura a exibição de conteúdo dentro do seu aplicativo.

Alguns templates afetam imagens armazenadas no OneEntry, enquanto outros definem a aparência de entidades como blocos, páginas e produtos.


const { Templates } = defineOneEntry(
  "sua-url-do-projeto", {
    "token": "seu-token-de-aplicativo"
  }
);

🔗 Documentação Relacionada

Painel de Administração do OneEntry - Templates de Conteúdo - Documentação oficial do painel de administração
Módulo TemplatePreviews - Templates de pré-visualização para imagens de atributos
Módulo Produtos - Produtos usam templates de produto
Módulo Páginas - Páginas usam templates de página
Módulo Blocos - Blocos usam templates de bloco
Módulo Formulários - Formulários usam templates de formulário
Melhores Práticas de Otimização de Imagem

Introdução

🎯 O que este módulo faz?​

📖 Explicação Simples​

✨ Conceitos Chave​

O que é um Template?​

Estrutura do Template​

Tipos de Template​

Templates de Imagem Comuns​

Fluxo de Trabalho de Configuração de Template​

Por que usar o módulo Templates?​

📋 O que você precisa saber​

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

Identificação de Template​

Integração de CDN de Template de Imagem​

Design Responsivo com Templates​

💡 Notas Importantes​

Templates são Criados no Painel de Administração​

Como os Templates Funcionam​

Otimização de Imagem​

Templates Responsivos​

Cache de Template​

📊 Tabela de Referência Rápida​

❓ Perguntas Comuns (FAQ)​

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

Como aplico um template a uma URL de imagem?​

Posso criar diferentes templates para mobile e desktop?​

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

Como atualizo um template sem afetar a produção?​

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

🎓 Melhores Práticas​

Definição do módulo Templates​

🔗 Documentação Relacionada​