Pular para o conteúdo principal

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 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 é 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 (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, // 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 copyright, 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étodoO que fazQuando usar
getBlocks()Obter todos os blocos (paginados, filtrados)Listar todos os blocos disponíveis
getBlockByMarker()Obter bloco por marcadorBuscar bloco específico no código
searchBlock()Pesquisar blocosBuscar blocos

❓ Perguntas Comuns (FAQ)​

Qual é a diferença entre Blocos e Páginas?​

  • Páginas/Páginas de Produtos - 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:

  1. Vá para a seção Blocos
  2. Encontre seu bloco (por exemplo, "Rodapé")
  3. Edite os atributos
  4. 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.

Como mostro/ou 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 o escopo: global_header vs blog_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ão block1)
  • Cache blocos para reduzir chamadas à 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 statusId para visualizar alterações

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(
  "sua-url-do-projeto", {
    "token": "seu-token-de-aplicativo"
  }
);

🔗 Documentação Relacionada​