Blocks

A pasta Blocks concentra os blocos reutilizáveis que podem ser disponibilizados no CMS para páginas configuradas com content_for_page.

Cada bloco deve possuir dois arquivos com o mesmo nome base:

• Blocks/<type>.html: responsável pela renderização do bloco na página.
• Blocks/<type>.schema.json: responsável por descrever os campos editáveis do bloco no CMS e o contrato usado na validação do salvamento.

Exemplo de estrutura

Blocks/
  banner_button.html
  banner_button.schema.json
  banner_carousel.html
  banner_carousel.schema.json
  button_carousel.html
  button_carousel.schema.json
  image_showcase.html
  image_showcase.schema.json
  product_carousel.html
  product_carousel.schema.json

Regras importantes

• O nome do arquivo deve ser igual ao type do bloco.
• Para um bloco com type: "banner_button", os arquivos esperados são Blocks/banner_button.html e Blocks/banner_button.schema.json.
• O arquivo .html é carregado na renderização da página.
• O arquivo .schema.json é carregado para montar os campos do CMS e validar os dados enviados no salvamento.
• Se o .schema.json não existir, o bloco não poderá ser salvo.
• Se o .html não existir, o bloco não poderá ser renderizado corretamente.

Guia de criação de schema.json

O schema.json define como o bloco aparece para edição no CMS e quais valores a plataforma aceita.

Estrutura base

{
  "name": "Banner com botão",
  "type": "banner_button",
  "settings": [
    {
      "label": "Título principal",
      "name": "title",
      "type": "text",
      "required": false
    }
  ]
}

Propriedades do bloco

Propriedades de cada item em settings

Tipos de campos suportados em settings

Exemplo completo com vários tipos

{
  "name": "Hero promocional",
  "type": "promo_hero",
  "settings": [
    {
      "label": "Título",
      "name": "title",
      "type": "text",
      "required": true
    },
    {
      "label": "Produtos por linha",
      "name": "items_visible",
      "type": "number",
      "required": false
    },
    {
      "label": "Link do botão",
      "name": "button_url",
      "type": "url",
      "required": false
    },
    {
      "label": "Imagem principal",
      "name": "background_image",
      "type": "image_picker",
      "required": true
    },
    {
      "label": "Cor do texto",
      "name": "text_color",
      "type": "color",
      "required": false
    },
    {
      "label": "Tema visual",
      "name": "theme",
      "type": "select",
      "required": false,
      "options": [
        { "label": "Claro", "value": "light" },
        { "label": "Escuro", "value": "dark" }
      ]
    },
    {
      "label": "Exibir selo",
      "name": "show_badge",
      "type": "checkbox",
      "required": false
    }
  ]
}

Exemplos isolados

• Campo select:

{
  "label": "Tamanho do título",
  "name": "title_size",
  "type": "select",
  "required": false,
  "options": [
    { "label": "Pequeno", "value": "sm" },
    { "label": "Médio", "value": "md" },
    { "label": "Grande", "value": "lg" },
    { "label": "Extra grande", "value": "xl" }
  ]
}

• Campo color:

{
  "label": "Cor do texto",
  "name": "text_color",
  "type": "color",
  "required": false
}

• Campo image_picker:

{
  "label": "Imagem",
  "name": "image",
  "type": "image_picker",
  "required": true
}

Como os dados chegam no HTML do bloco

No arquivo Blocks/<type>.html, os valores das configurações do bloco ficam disponíveis em block_data.

Exemplo:

{{~
  title = block_data.title
  if title | string.empty
    title = "Título padrão"
  end
~}}

<section>
  <h2>{{ title }}</h2>
</section>

Isso significa que o name de cada item em settings deve ser pensado como uma chave de dados reutilizável tanto pelo CMS quanto pelo template.

Blocos em templates que atendem várias URLs

Um mesmo template pode atender várias URLs (ver urlMatch em
pages.json), e cada uma dessas
URLs pode ter um layout exclusivo configurado pelo lojista no Design Studio.

Isso não muda nada na criação do bloco: o mesmo par
Blocks/<type>.html + Blocks/<type>.schema.json atende tanto o layout do
template quanto os layouts exclusivos por URL. Não existe schema, campo ou flag
específica para layout exclusivo.

O que muda é a recomendação de como escrever o bloco:

• Não presuma uma URL fixa dentro do bloco. Se o bloco precisa de um link,
  um título ou uma imagem diferente por página, isso deve ser um campo em
  settings, editável pelo lojista — não uma condicional no Scriban baseada
  na URL corrente.
• Não use o bloco para diferenciar páginas. O caminho suportado para "esta
  URL precisa de um banner diferente" é o layout exclusivo por URL no Design
  Studio, não uma ramificação dentro do HTML do bloco.
• O bloco continua recebendo apenas block_data. O conteúdo entregue em
  block_data é o do layout que venceu a resolução para aquela URL — exclusivo
  se houver, do template caso contrário. O bloco não precisa (e não consegue)
  saber qual dos dois foi usado.

Resumo

Para disponibilizar um bloco no CMS desta primeira versão, a agência deve seguir este fluxo:

• Criar Blocks/<type>.html.
• Criar Blocks/<type>.schema.json.
• O content_for_page pode ser declarado em dois níveis:
  • No item de customs: vale para as URLs atendidas por aquele custom.
  • No nível da página (ex.: no objeto hotsite): vale para as URLs atendidas pelo template base da página; também é usado como fallback quando o custom correspondente não declara content_for_page próprio.
• Garantir que os nomes dos campos em settings[].name sejam os mesmos usados no block_data do HTML.
• Validar se os tipos escolhidos no schemaestão entre os suportados pela plataforma.