Introdução
Blocos de conteúdo reutilizáveis que podem ser usados em várias páginas.
Mais informações sobre a interface do usuário do módulo https://doc.oneentry.cloud/docs/category/blocks
🎯 O que este módulo faz?
O módulo Blocks permite que você use componentes de conteúdo reutilizáveis (blocos) que contêm conjuntos de atributos e podem ser usados em várias páginas e páginas de produtos - como cabeçalhos, rodapés, banners, depoimentos ou qualquer conteúdo repetido.
Pense nisso como peças de LEGO para o seu site - você cria um bloco uma vez e o reutiliza onde precisar. Altere o bloco uma vez e ele se atualiza automaticamente em todos os lugares.
📖 Explicação Simples
Imagine que você está construindo um site com:
- 🔝 Cabeçalho - logo, menu de navegação (igual em todas as páginas)
- 🔽 Rodapé - informações de contato, links sociais (igual em todas as páginas)
- 📢 Banner Promocional - oferta especial (aparece em várias páginas)
- ⭐ Depoimentos - avaliações de clientes (reutilizados em diferentes lugares)
- 📞 Formulário de Contato - aparece em várias páginas
Em vez de copiar esse conteúdo para cada página:
- ✅ Crie uma vez como um Bloco
- ✅ Insira o bloco onde precisar
- ✅ Atualize em um lugar → mudanças em todos os lugares automaticamente
- ✅ Mantenha seu conteúdo DRY (Don't Repeat Yourself)
Exemplo do mundo real:
Sem Blocos (copiar-colar):
- Atualizar rodapé → Editar 50 páginas manualmente ❌
- Adicionar link social → Atualizar em todos os lugares ❌
- Conteúdo inconsistente entre páginas ❌
Com Blocos (reutilizáveis):
- Atualizar bloco de rodapé → Mudanças em todas as 50 páginas instantaneamente ✅
- Adicionar link social → Atualizar uma vez ✅
- Sempre consistente ✅
✨ Conceitos Chave
O que é um Bloco?
Um bloco é um componente de conteúdo reutilizável que contém:
- Conteúdo - Texto, imagens, links, qualquer dado
- Atributos - Campos personalizados que você define
- Marcador - Identificador único para referenciá-lo
- Status - Ativo, rascunho, arquivado
Reutilização de Blocos
Os blocos podem ser:
- ✅ Usados em várias páginas e, se os blocos forem atualizados, eles são atualizados em todos os lugares
- ✅ Localizados (conteúdo diferente por idioma)
📋 O que você precisa saber
Melhor prática: Sempre use marcadores em seu código (eles nunca mudam).
Estrutura do Bloco
Todo bloco tem esses campos principais:
{
id: 3, // unique ID
localizeInfos: { // block localized data
title: 'Block', // block localized title
},
version: 0, // block version
position: 1, // block position in array of blocks
identifier: 'block', // block identifier
type: 'common_block', // block type
templateIdentifier: null, // template identifier
isVisible: true, // visibility
attributeValues: {}, // block attributes
}
Atributos Personalizados
Os blocos usam AttributesSets para campos personalizados:
Exemplos:
- Bloco de rodapé: texto de copyright, links sociais, informações de contato
- Banner principal: título, subtítulo, botão CTA, imagem de fundo
- Depoimento: nome do autor, foto, citação, avaliação
- Formulário de contato: configuração de campos, texto do botão de envio
Saiba mais: Veja Módulo AttributesSets
📊 Tabela de Referência Rápida - Métodos Comuns
| Método | O que faz | Quando usar |
|---|---|---|
| getBlocks() | Obter todos os blocos (paginados, filtrados) | Listar todos os blocos disponíveis |
| getBlockByMarker() | Obter bloco por marcador | Buscar bloco específico no código |
| searchBlock() | Pesquisar blocos | Buscar blocos |
| getFrequentlyOrderedProducts() | Produtos frequentemente pedidos | "Frequentemente pedidos juntos" |
| getCartComplement() | "Complete seu carrinho" pelo contexto do carrinho | Venda cruzada a partir do carrinho |
| getCartComplementByProductIds() | "Complete seu carrinho" por productIds | Venda cruzada para produtos dados |
| getCartSimilar() | "Semelhante ao carrinho" pelo contexto do carrinho | Alternativas para itens do carrinho |
| getCartSimilarByProductIds() | "Semelhante ao carrinho" por productIds | Alternativas para produtos dados |
| getWishlistSimilar() | "Semelhante à lista de desejos" pela lista de desejos | Alternativas para itens da lista de desejos |
| getWishlistSimilarByProductIds() | "Semelhante à lista de desejos" por productIds | Alternativas para produtos dados |
| getPersonalRecommendations() | Recomendações pessoais | Feed de produtos personalizados |
| getRecentlyViewed() | Produtos visualizados recentemente | Widget "Visualizados recentemente" |
| getRepeatPurchase() | Produtos para compra repetida | Widget "Comprar novamente" |
| getTrending() | Produtos em alta | Widget "Tendências agora" |
| getSlides() | Árvore de slides do bloco de slider | Renderizar um slider/carrossel |
🧩 Tipos de Blocos
O tipo de um bloco (o BlockType) determina o que ele renderiza. Além dos tipos básicos (common_block, product_block, similar_products_block, form, e outros), os seguintes tipos de blocos de produto e personalização estão disponíveis:
| Tipo de bloco | Método |
|---|---|
frequently_ordered_block | getFrequentlyOrderedProducts() |
trending_block | getTrending() |
recently_viewed_block | getRecentlyViewed() |
repeat_purchase_block | getRepeatPurchase() |
slider_block | getSlides() |
personal_recommendations_block | getPersonalRecommendations() |
cart_complement_block | getCartComplement() / getCartComplementByProductIds() |
cart_similar_block | getCartSimilar() / getCartSimilarByProductIds() |
wishlist_similar_block | getWishlistSimilar() / getWishlistSimilarByProductIds() |
Os blocos de personalização (visualizados recentemente, compra repetida, recomendações pessoais, carrinho/lista de desejos) são impulsionados por atividade do usuário rastreada e funcionam tanto para usuários autorizados quanto para convidados (veja Modo convidado).
❓ Perguntas Comuns (FAQ)
Qual é a diferença entre Blocos e Páginas?
- Páginas/Páginas de Produto - Páginas completamente autônomas com URLs (por exemplo,
/about) às quais você pode adicionar blocos e outros componentes de página que podem ser reutilizados em várias páginas. - Blocos - Componentes reutilizáveis inseridos em páginas (por exemplo, rodapé)
Pense nisso como:
- Página = Documento completo
- Bloco = Parágrafo que você reutiliza em vários documentos
Como atualizo o conteúdo de um bloco?
Atualize-o no OneEntry painel de administração:
- Vá para a seção Blocos
- Encontre seu bloco (por exemplo, "Rodapé")
- Edite os atributos
- Salve
Todas as páginas que usam esse bloco são atualizadas automaticamente! ✨
Devo criar muitos blocos pequenos ou poucos blocos grandes?
Muitos blocos pequenos é melhor:
✅ Bom (pequeno, focado):
- header_logo
- header_navigation
- footer_copyright
- footer_social_links
❌ Evitar (muito grande):
- entire_page_layout (contains everything)
Por quê? Blocos pequenos são mais fáceis de reutilizar e manter.
Como mostro/escondo blocos condicionalmente?
Verifique o campo isVisible
Posso criar blocos dinamicamente via API?
O SDK é somente leitura. Para criar blocos, use o painel de administração do OneEntry.
Como lido com blocos ausentes de forma elegante?
Sempre use try/catch
💡 Notas Importantes
Melhores Práticas para Marcadores de Blocos
✅ Bons nomes de marcadores:
- Descritivos:
global_footer,homepage_hero - Use sublinhados:
contact_form - Minúsculas:
promo_banner - Indique escopo:
global_headervsblog_header
❌ Maus nomes de marcadores:
- Genéricos:
block1,content - Espaços:
my block - Mistura de maiúsculas e minúsculas:
MyBlock,ProMoBanner
Cache de Blocos
Blocos mudam raramente → cache-os!
🎓 Melhores Práticas
- Crie blocos pequenos e focados (responsabilidade única)
- Use marcadores descritivos (
footer, nãoblock1) - Cache blocos para reduzir chamadas de API
- Lide com blocos ausentes de forma elegante (try/catch)
- Documente para que cada bloco serve
- Mantenha a estrutura do bloco consistente
- Teste as alterações do bloco antes de publicar
- Use
statusIdpara visualizar alterações
Definição do módulo Blocks
const { Blocks } = defineOneEntry( "sua-url-do-projeto", { "token": "seu-token-de-aplicativo" });
🔗 Documentação Relacionada
- Módulo de Páginas - Gerenciar páginas que usam blocos
- Módulo AttributesSets - Definir atributos de bloco
- Módulo de Produtos - Usar blocos em páginas de produtos