Desenvolver um bloco com opções

Este tutorial demonstra como usar um tipo de entrada select (lista suspensa) para permitir que os criadores escolham uma opção de bloco, que é aplicada como uma classe de CSS correspondente.

{align="center"}

Modelo de bloco

A opção Padrão é representada por uma string vazia (""), enquanto a opção Lado a lado usa "side-by-side". O nome e o valor da opção não precisam ser iguais, mas o valor determina as classes de CSS aplicadas ao HTML do bloco. Por exemplo, o valor da opção Lado a lado pode ser layout-10 em vez de side-by-side. No entanto, é melhor usar nomes semanticamente significativos para classes de CSS, garantindo clareza e consistência nos valores da opção.

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

...
"fields": [
    {
        "component": "select",
        "name": "classes",
        "value": "",
        "label": "Teaser options",
        "valueType": "string",
        "options": [
            {
                "name": "Default",
                "value": ""
            },
            {
                "name": "Side-by-side",
                "value": "side-by-side"
            }
        ]
    }
]
...

HTML do bloco

Quando o criador seleciona uma opção, o valor correspondente é adicionado como uma classe de CSS ao HTML do bloco:

• Se Padrão for selecionado:

  code language-html
  <div class="block teaser"> <!-- Block content here --> </div>

• Se Lado a lado for selecionado:

  code language-html
  <div class="block teaser side-by-side"> <!-- Block content here --> </div>

Permite que um estilo diferente e um JavaScript condicional sejam aplicados, dependendo da abertura escolhida.

Esta abordagem não é usada neste tutorial, mas ilustra um método alternativo e opções de bloco avançadas.

O tipo de entrada select permite que os criadores escolham uma única opção de bloco, que pode, opcionalmente, ser mapeado para várias classes de CSS. Para isso, liste as classes de CSS como valores delimitados por espaço.

{align="center"}

Modelo de bloco

Por exemplo, a opção Lado a lado pode permitir variações nas quais a imagem aparece à esquerda (side-by-side left) ou à direita (side-by-side right).

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

...
"fields": [
    {
        "component": "select",
        "name": "classes",
        "value": "",
        "label": "Teaser options",
        "valueType": "string",
        "options": [
            {
                "name": "Default",
                "value": ""
            },
            {
                "name": "Side-by-side with Image on left",
                "value": "side-by-side left"
            },
            {
                "name": "Side-by-side with Image on right",
                "value": "side-by-side right"
            }
        ]
    }
]
...

HTML do bloco

Quando o autor seleciona uma opção, o valor correspondente é aplicado como um conjunto de classes de CSS separadas por espaços no HTML do bloco:

• Se Padrão for selecionado:

  code language-html
  <div class="block teaser"> <!-- Block content here --> </div>

• Se Lado a lado com a imagem à esquerda for selecionado:

  code language-html
  <div class="block teaser side-by-side left"> <!-- Block content here --> </div>

• Se Lado a lado com a imagem à direita for selecionado:

  code language-html
  <div class="block teaser side-by-side right"> <!-- Block content here --> </div>

Permite que estilos diferentes e um JavaScript condicional sejam aplicados, dependendo da opção escolhida.

Esta abordagem não é usada neste tutorial, mas ilustra um método alternativo e opções de bloco avançadas.

O tipo de entrada "component": "multiselect" permite que o autor selecione várias opções simultaneamente. Isso permite permutas complexas da aparência do bloco ao combinar várias opções de design.

{align="center"}

Modelo de bloco

Por exemplo, a Lado a lado, Imagem à esquerda e Imagem à direita podem permitir variações nas quais a imagem é posicionada à esquerda (side-by-side left) ou à direita (side-by-side right).

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

...
"fields": [
    {
        "component": "multiselect",
        "name": "classes",
        "value": [],
        "label": "Teaser options",
        "valueType": "array",
        "options": [
            {
                "name": "Side-by-side",
                "value": "side-by-side"
            },
            {
                "name": "Image on left",
                "value": "left"
            },
            {
                "name": "Image on right",
                "value": "right"
            }
        ]
    }
]
...

HTML do bloco

Quando o criador seleciona várias opções, os valores correspondentes são aplicados como classes de CSS separadas por espaço no HTML do bloco:

• Se Lado a lado e Imagem à esquerda forem selecionados:

  code language-none h-1
  <div class="block teaser side-by-side left"> <!-- Block content here --> </div>

• Se Lado a lado e Imagem à direita forem selecionados:

  code language-none h-1
  <div class="block teaser side-by-side right"> <!-- Block content here --> </div>

Embora a seleção múltipla ofereça flexibilidade, ela aumenta a complexidade do gerenciamento de permutas de design. Sem restrições, seleções conflitantes podem levar a experiências corrompidas ou não condizentes com a marca.

Por exemplo:

• Imagem à esquerda ou Imagem à direita sem selecionar Lado a lado aplica implicitamente o Padrão, que sempre define a imagem como um plano de fundo, portanto, o alinhamento à esquerda e à direita é irrelevante.
• A seleção de Imagem à esquerda e Imagem à direita é contraditória.
• Selecionar Lado a lado sem Imagem à esquerda ou Imagem à direita pode ser considerado ambíguo, pois a posição da imagem não é especificada.

Para evitar problemas e confusão do autor ao usar a seleção múltipla, verifique se as opções foram bem planejadas e se todas as permutas foram testadas. A seleção múltipla funciona melhor para aprimoramentos simples e não conflitantes, como “grande” ou “destaque”, em vez de opções de alteração de layout.

Esta abordagem não é usada neste tutorial, mas ilustra um método alternativo e opções de bloco avançadas.

As opções de bloco podem ser definidas como padrão ao adicionar uma nova instância de bloco a uma página no editor universal. Para isso, é necessário definir o valor padrão da propriedade classes na definição do bloco.

Definição do bloco

No exemplo abaixo, a opção padrão é definida como Lado a Lado, atribuindo-se a propriedade value do campo classes a side-by-side. A entrada da opção de bloco correspondente no modelo de bloco é opcional.

Você também pode definir várias entradas para o mesmo bloco, cada uma com um nome e uma classe diferentes. Isso permite que o editor universal exiba entradas de blocos distintas, cada uma pré-configurada com uma opção de bloco específica. Embora apareçam como blocos separados no editor, a base de código contém um bloco que é renderizado dinamicamente com base na opção selecionada.

[/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",
              "classes": "side-by-side",
              "textContent_text": "<h2>Enter a title</h2><p>...and body text here!</p>",
              "textContent_cta": "/",
              "textContent_ctaText": "Click me!"
            }
          }
        }
      }
    }],
    "models": [... from previous section ...],
    "filters": []
}

O código a seguir é o DOM do bloco de teaser, com a opção de bloco Lado a lado selecionada, que é o destino a ser decorado com JavaScript e CSS.

...
<body>
    <header/>
    <main>
        <div>
            <!-- Start block HTML -->
            <div class="teaser block side-by-side" data-block-name="teaser" data-block-status="loaded">
                <div>
                    <div>
                    <picture>
                        <source type="image/webp" srcset="./media_15ba2b455e29aca38c1ca653d24c40acaec8a008f.jpeg?width=2000&format=webply&optimize=medium" media="(min-width: 600px)">
                        <source type="image/webp" srcset="./media_15ba2b455e29aca38c1ca653d24c40acaec8a008f.jpeg?width=750&format=webply&optimize=medium">
                        <source type="image/jpeg" srcset="./media_15ba2b455e29aca38c1ca653d24c40acaec8a008f.jpeg?width=2000&format=jpeg&optimize=medium" media="(min-width: 600px)">
                        <img loading="eager" alt="Woman looking out over a river." src="./media_15ba2b455e29aca38c1ca653d24c40acaec8a008f.jpeg?width=750&format=jpeg&optimize=medium" width="1600" height="900">
                    </picture>
                    </div>
                </div>
                <div>
                    <div>
                    <h2 id="wknd-adventures">WKND Adventures</h2>
                    <p>Join us on one of our next adventures. Browse our list of curated experiences and sign up for one when you're ready to explore with us.</p>
                    <p>Terms and conditions: By signing up, you agree to the rules for participation and booking.</p>
                    <p class="button-container"><a href="/" title="View trips" class="button">View trips</a></p>
                    </div>
                </div>
            </div>
            <!-- End block HTML -->
        </div>
    </main>
    <footer/>
</body>
...

Para localizar o DOM a ser decorado, abra a página com o bloco no seu ambiente de desenvolvimento local, selecione o bloco com as ferramentas de desenvolvedor do navegador da web e inspecione o DOM. Isso permitirá identificar os elementos relevantes a serem decorados.

{align="center"}