Criar um novo bloco

Este capítulo aborda o processo de criação de um novo bloco de teaser editável para um site do Edge Delivery Services por meio do editor universal.

O bloco, chamado de teaser, exibe os seguintes elementos:

O conteúdo do bloco teaser é editável no editor universal, garantindo facilidade de uso e reusabilidade em todo o site.

Observe que o bloco teaser é semelhante ao bloco hero do modelo padronizado; portanto, o bloco teaser serve apenas como um exemplo simples para ilustrar conceitos de desenvolvimento.

Criar uma nova ramificação do Git

Para manter um fluxo de trabalho limpo e organizado, crie uma nova ramificação para cada tarefa de desenvolvimento específica. Isso ajuda a evitar problemas com a implantação de um código incompleto ou não testado na produção.

# ~/Code/aem-wknd-eds-ue

$ git fetch origin
$ git checkout -b teaser origin/main

Depois de criar a ramificação teaser, é possível começar a desenvolver o bloco de teaser.

Pasta do bloco

Crie uma nova pasta chamada teaser no diretório blocks do projeto. Essa pasta contém os arquivos JSON, CSS e JavaScript do bloco, organizando os arquivos do bloco em um mesmo local:

# ~/Code/aem-wknd-eds-ue

/blocks/teaser

O nome da pasta de blocos atua como a ID do bloco e é usado para fazer referência ao bloco durante todo o desenvolvimento.

Bloco JSON

O bloco JSON define três aspectos principais do bloco:

Crie um novo arquivo em /blocks/teaser/_teaser.json com a estrutura inicial a seguir, na mesma ordem. Se as chaves estiverem fora de ordem, elas podem não ser criadas corretamente.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Nome do arquivo da amostra de código abaixo."}

{
    "definitions": [],
    "models": [],
    "filters": []
}

Modelo de bloco

O modelo de bloco é uma parte crucial da configuração do bloco, pois ele define:

É atribuído aos modelos um id que corresponde à definição do bloco e inclui uma matriz fields para especificar os campos editáveis.

Cada campo na matriz fields tem um objeto JSON que inclui as seguintes propriedades necessárias:

Para obter uma lista abrangente de propriedades, incluindo as opcionais, confira a documentação de campos do editor universal.

Design do bloco

O bloco de teaser inclui os seguintes elementos editáveis:

O design do bloco de teaser é dividido entre esses dois componentes lógicos (imagem e conteúdo de texto), garantindo uma experiência de criação estruturada e intuitiva para os usuários.

Campos do bloco

Defina os campos necessários para o bloco: imagem, texto alternativo da imagem, texto, rótulo e link do botão de chamariz.

{
    "definitions": [],
    "models": [
        {
            "id": "teaser",
            "fields": [
                {
                    "component": "reference",
                    "valueType": "string",
                    "name": "image",
                    "label": "Image",
                    "multi": false
                },
                {
                    "component": "text",
                    "valueType": "string",
                    "name": "imageAlt",
                    "label": "Image alt text",
                    "required": true
                },
                {
                    "component": "richtext",
                    "name": "textContent_text",
                    "label": "Text",
                    "valueType": "string",
                    "required": true
                },
                {
                    "component": "aem-content",
                    "name": "textContent_cta",
                    "label": "CTA",
                    "valueType": "string"
                },
                {
                    "component": "text",
                    "name": "textContent_ctaText",
                    "label": "CTA label",
                    "valueType": "string"
                }
            ]
        }
    ],
    "filters": []
}

<div>
    <div>
        <!-- This div contains the field-collapsed image fields  -->
        <picture>
            ...
            <source .../>
            <img src="..." alt="The authored alt text"/>
        </picture>
    </div>
    <div>
        <!-- This div, via element grouping contains the textContent fields -->
        <h2>The authored title</h2>
        <p>The authored body text</p>
        <a href="/authored/cta/link">The authored CTA label</a>
    </div>
</div>

{
    "definitions": [],
    "models": [
        {
            "id": "teaser",
            "fields": [
                {
                    "component": "reference",
                    "valueType": "string",
                    "name": "image",
                    "label": "Image",
                    "multi": false
                },
                {
                    "component": "text",
                    "valueType": "string",
                    "name": "alt",
                    "label": "Image alt text",
                    "required": true
                },
                {
                    "component": "richtext",
                    "name": "text",
                    "label": "Text",
                    "valueType": "string",
                    "required": true
                },
                {
                    "component": "aem-content",
                    "name": "link",
                    "label": "CTA",
                    "valueType": "string"
                },
                {
                    "component": "text",
                    "name": "label",
                    "label": "CTA label",
                    "valueType": "string"
                }
            ]
        }
    ],
    "filters": []
}

<div>
    <div>
        <!-- This div contains the field-collapsed image  -->
        <picture>
            ...
            <source .../>
            <img src="/authored/image/reference"/>
        </picture>
    </div>
    <div>
        <p>The authored alt text</p>
    </div>
    <div>
        <h2>The authored title</h2>
        <p>The authored body text</p>
    </div>
    <div>
        <a href="/authored/cta/link">/authored/cta/link</a>
    </div>
    <div>
        The authored CTA label
    </div>
</div>

Definição do bloco

A definição do bloco registra-o no editor universal. Confira a seguir um detalhamento das propriedades JSON usadas na definição do bloco:

Este é um exemplo de JSON para a definição do bloco:

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Nome do arquivo da amostra de código abaixo."}

{
    "definitions": [{
      "title": "Teaser",
      "id": "teaser",
      "plugins": {
        "xwalk": {
          "page": {
            "resourceType": "core/franklin/components/block/v1/block",
            "template": {
              "name": "Teaser",
              "model": "teaser",
              "textContent_text": "<h2>Enter a title</h2><p>...and body text here!</p>",
              "textContent_cta": "/",
              "textContent_ctaText": "Click me!"
            }
          }
        }
      }
    }],
    "models": [... from previous section ...],
    "filters": []
}

Neste exemplo:

Essa estrutura garante que o bloco seja configurado no editor universal com os campos, o modelo de conteúdo e o tipo de recurso adequados para renderização.

Filtros do bloco

A matriz filters do bloco define, para blocos de container, quais outros blocos podem ser adicionados ao container. Os filtros definem uma lista de IDs de blocos (model.id) que podem ser adicionados ao container.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Nome do arquivo da amostra de código abaixo."}

{
  "definitions": [... populated from previous section ...],
  "models": [... populated from previous section ...],
  "filters": []
}

O componente de teaser não é um bloco de container, o que significa que não é possível adicionar outros blocos a ele. Como resultado, sua matriz filters é deixada em branco. Em vez disso, adicione a ID do teaser à lista de filtros do bloco de seção, para que o teaser possa ser adicionado a uma seção.

Blocos fornecidos pela Adobe, como o bloco de seção, armazenam filtros na pasta models do projeto. Para ajustar, localize o arquivo JSON do bloco fornecido pela Adobe (por exemplo, /models/_section.json) e adicione a ID do teaser (teaser) à lista de filtros. A configuração sinaliza ao editor universal que o componente de teaser pode ser adicionado ao bloco de container da seção.

[/models/_section.json]{class="badge neutral" title="Nome do arquivo da amostra de código abaixo."}

{
  "definitions": [],
  "models": [],
  "filters": [
    {
      "id": "section",
      "components": [
        "text",
        "image",
        "button",
        "title",
        "hero",
        "cards",
        "columns",
        "fragment",
        "teaser"
      ]
    }
  ]
}

A ID de definição do bloco de teaser de teaser foi adicionada à matriz components.

Limpe os seus arquivos JSON

Certifique-se de limpar com frequência as alterações no seu código para garantir que ele esteja limpo e consistente. A limpeza periódica ajuda a detectar problemas antecipadamente e reduz o tempo geral de desenvolvimento. O comando npm run lint:js também limpa arquivos JSON e capta todos os erros de sintaxe.

# ~/Code/aem-wknd-eds-ue

$ npm run lint:js

Compilar o JSON do projeto

Após configurar os arquivos JSON do bloco (por exemplo, blocks/teaser/_teaser.json, models/_section.json), eles são automaticamente compilados nos arquivos component-models.json, component-definitions.json e component-filters.json do projeto. Essa compilação é tratada automaticamente por um gancho de pré-confirmação Husky incluso no modelo de projeto XWalk padronizado do AEM.

As compilações também podem ser acionadas de forma manual ou programática, usando-se os scripts NPM de compilação de JSON do projeto.

Implantar o JSON do bloco

Para disponibilizar o bloco no editor universal, o projeto precisa ser confirmado e enviado a uma ramificação de um repositório do GitHub, neste caso, a ramificação teaser.

O nome exato da ramificação usado pelo editor universal pode ser ajustado, por usuário, por meio do URL do editor universal.

# ~/Code/aem-wknd-eds-ue

$ git add .
$ git commit -m "Add teaser block JSON files so it is available in Universal Editor"
# JSON files are compiled automatically and added to the commit via a husky precommit hook
$ git push origin teaser

Quando o editor universal é aberto com o parâmetro de consulta ?ref=teaser, o novo bloco teaser aparece na paleta de blocos. Observe que o bloco não tem estilo; ele renderiza os campos do bloco como HTML semântico, estilizado somente por meio do CSS global.