Introdução
Crie blocos de conteúdo reutilizáveis que podem ser usados em várias páginas.
🎯 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 - 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 é atualizado 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 (Não Repita Você Mesmo)
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
Bloco vs Página
| Recurso | Página | Bloco |
|---|---|---|
| Propósito | Conteúdo completo da página | Componente reutilizável |
| URL | Tem sua própria URL (/about) | Sem URL (embutido) |
| Uso | Visualizado diretamente | Inserido em páginas |
| Exemplo | Página Sobre Nós | Rodapé, Cabeçalho |
Diferença chave: Páginas são destinos, Blocos são blocos de construção.
Tipos Comuns de Blocos
Blocos típicos que você pode criar:
| Tipo de Bloco | Conteúdo Exemplo | Onde Usado |
|---|---|---|
| Cabeçalho | Logo, menu de navegação, busca | Cada página |
| Rodapé | Contato, links, direitos autorais | Cada página |
| Banner Hero | Imagem grande + botão CTA | Página inicial, páginas de destino |
| Depoimentos | Avaliações de clientes | Várias páginas |
| Formulário de Contato | Formulário de e-mail | Página de contato, modais |
| Banner Promocional | Alerta de oferta especial | Páginas selecionadas |
| Links Sociais | Ícones do Facebook, Twitter | Rodapé, barra lateral |
| Inscrição em Newsletter | Caixa de assinatura de e-mail | Rodapé, blog |
Reutilização de Blocos
Os blocos podem ser:
- ✅ Usados em várias páginas
- ✅ Atualizados uma vez, refletidos em todos os lugares
- ✅ Localizados (conteúdo diferente por idioma)
📋 O que você precisa saber
Identificação de Blocos
Três maneiras de identificar blocos:
| Método | Quando Usar | Exemplo |
|---|---|---|
| Listar Todos | Painel de administração, seletor de blocos | getBlocks() |
| Por Marcador | Referência no código (melhor prática) | footer, header, promo_banner |
| Buscar blocos | Referências internas | searchBlock('foo') |
Melhor prática: Sempre use marcadores no seu código (eles nunca mudam).
Estrutura do Bloco
Cada bloco tem esses campos principais:
{
id: 3, // ID único
localizeInfos: { // dados localizados do bloco
title: 'Block', // título localizado do bloco
},
version: 0, // versão do bloco
position: 1, // posição do bloco no array de blocos
identifier: 'block', // identificador do bloco
type: 'common_block', // tipo do bloco
templateIdentifier: null, // identificador do template
isVisible: true, // visibilidade
attributeValues: {}, // atributos do bloco
}
Atributos Personalizados
Os blocos usam AttributesSets para campos personalizados:
Exemplos:
- Bloco de Rodapé: texto de direitos autorais, links sociais, informações de contato
- Banner Hero: 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 AttributesSets Module
📊 Tabela de Referência Rápida - Métodos Comuns
| Método | O que Faz | Quando Usar |
|---|---|---|
| getBlocks() | Obtém todos os blocos (paginados, filtrados) | Listar todos os blocos disponíveis |
| getBlockByMarker() | Obtém bloco por marcador | Buscar bloco específico no código |
| searchBlock() | Busca blocos | Buscar blocos |
❓ Perguntas Comuns (FAQ)
Qual é a diferença entre Blocos e Páginas?
- Páginas - Páginas completas e independentes com URLs (por exemplo,
/about) - 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 painel de administração do OneEntry:
- 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 (contém tudo)
Por quê? Blocos pequenos são mais fáceis de reutilizar e manter.
Posso usar o mesmo bloco várias vezes em uma página?
Sim! Busque uma vez, renderize várias vezes.
Como mostro/ou escondo blocos condicionalmente?
Verifique statusId e 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 - Caso misto:
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 mudanças do bloco antes de publicar
- Use
statusIdpara visualizar mudanças
Mais informações sobre a interface do usuário do módulo https://doc.oneentry.cloud/docs/blocks/introduction
Definição do módulo Blocks
const { Blocks } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
🔗 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