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

Propriedade	Tipo	Obrigatória	Descrição
name	string	recomendada	Nome amigável exibido para quem está configurando o bloco.
type	string	sim	Identificador técnico do bloco. Deve ser o mesmo valor usado em `content_for_page` e no nome dos arquivos.
settings	array	sim	Lista de campos editáveis do bloco.

Propriedades de cada item em `settings`

Propriedade	Tipo	Obrigatória	Descrição
label	string	recomendada	Texto exibido no CMS para o usuário da plataforma.
name	string	sim	Nome técnico do campo. Ele vira a chave dentro de `content` e pode ser acessado no HTML por `block_data.<name>`.
type	string	sim	Tipo do campo.
required	boolean	não	Define se o campo é obrigatório.
options	array	obrigatória para select	Lista de opções válidas para campos fechados (select/options).

Tipos de campos suportados em `settings`

Tipo	Descrição
text	Texto simples. O valor deve ser uma string com tamanho máximo limitado. É o tipo padrão.
string	Alias de `text`. Comportamento idêntico — aceita string com limite de tamanho.
number	Valor numérico. Aceita apenas valores do tipo número (inteiro ou decimal).
url	URL. Aceita string e rejeita URLs perigosas.
image_picker	Seletor de imagem. Aceita string (URL ou caminho) e rejeita URLs perigosas.
color	Cor. Aceita string em formato hexadecimal (#RGB, #RRGGBB, #RRGGBBAA) ou rgba.
select	Seleção única. O valor deve ser uma das opções definidas na lista `options`.
options	Alias de `select`. Comportamento idêntico — valida contra a lista de opções permitidas.
checkbox	Caixa de seleção. Aceita apenas valores booleanos (`true` ou `false`).
boolean	Alias de `checkbox`. Comportamento idêntico.

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.

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.
Declarar{ "type": "<type>" }dentro de content_for_page no custom da home no pages.json.
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.

Updated about 3 hours ago