Pular para o conteúdo

Extensões

As extensões permitem ampliar qualquer bloco registrado na sua instalação de WordPress usando uma API simples, baseada em .json, semelhante à configuração de block.json. Isso inclui blocos principais, de terceiros e criados com Blockstudio.

Todos os tipos de campos podem ser adicionados a qualquer bloco, com os dados salvos nos atributos do bloco. Todo o conjunto de recursos de atributos, como filtragem , desativação , lógica condicional e preenchimento de opções , está disponível para extensões.

Tipos de extensão

Os valores estendidos podem ser usados de várias maneiras:

  • classe: adiciona uma classe ao bloco usando o valor do atributo
  • estilo: adiciona estilos em linha ao bloco usando o valor do atributo
  • atributos: define diretamente qualquer valor de atributo no bloco
  • atributos de dados: usa valores da extensão para definir atributos de dados específicos

Configuração

Imagine o seguinte cenário: você quer adicionar um campo select de classe personalizada a cada bloco do núcleo. Basta adicionar esse arquivo .json em qualquer lugar da pasta do bloco, e ele será registrado automaticamente como uma extensão.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "priority": 10,
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Custom color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

Isso adicionará um campo customColor a cada bloco do núcleo, permitindo definir a cor do texto do bloco.

Nome do arquivo

Como não há um modelo de renderização, uma extensão não precisa de um arquivo index correspondente e, portanto, não precisa se chamar block.json. Isso permite armazenar todas as extensões convenientemente em uma única pasta. Vários arquivos podem estender os mesmos blocos, por exemplo, dois arquivos com "name": "core/*"; cada um registra seus próprios campos.

Esquema

Blockstudio fornece um esquema JSON personalizado para configurações de extensões:

Esquema da extensão View

Nome

A propriedade name do objeto de configuração define quais blocos devem ser estendidos. Há três opções, conforme suas necessidades:

  • blockName: um único nome de bloco, e.g. core/paragraph
  • [blockNameA, blockNameB]: uma matriz de nomes de blocos, e.g. ["core/paragraph", "core/heading"]
  • core/*: um curinga para estender todos os blocos de determinado tipo

Qualquer nome que termine em asterisco é um curinga de prefixo, não apenas core/*. A extensão a seguir se aplica a todos os blocos cujo nome começa com my-plugin/, incluindo blocos criados com Blockstudio:

JSON
{
  "name": "my-plugin/*",
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

Excluindo blocos

Use um array de nível superior exclude para ignorar blocos que corresponderiam a name:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "exclude": ["core/button", "core/image"],
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

As exclusões usam a mesma correspondência por nome exato e por prefixo com * no final que name. Elas têm precedência sobre nomes individuais, listas de nomes e curingas. Um bloco excluído não recebe os campos do editor da extensão nem seus atributos ou recursos do frontend. As outras extensões correspondentes não são afetadas. Omita exclude ou use um array vazio para manter o comportamento existente.

Chave Blockstudio

Assim como ao usar block.json para blocos personalizados, a propriedade blockstudio precisa estar presente no objeto de configuração, com extend definido como true.

Posição

Por padrão, as extensões são exibidas em sua própria aba no inspetor de blocos. Para movê-las para outra posição, você pode usar a propriedade group:

  • settings: posição padrão
  • styles: aba de estilos
  • advanced: aba avançada
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

Prioridade

A propriedade priority permite definir a ordem em que as extensões são renderizadas. Extensões com prioridade maior são renderizadas depois. Defina-a no nível superior do arquivo, como no exemplo de configuração, ou dentro de extend:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": { "priority": 10 },
    "attributes": []
  }
}

Quando ambas estão definidas, blockstudio.extend.priority prevalece.

Atributos

Para mais informações sobre como os atributos funcionam, consulte a seção atributos.

A única coisa que você precisa saber sobre atributos em extensões é a propriedade set. Ela é usada para aplicar o valor do atributo a um dos tipos de extensão.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Heading color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

Obtendo valores

A notação de ponto dentro de chaves é usada para obter o valor de um atributo.

Também é possível obter valores aninhados quando os atributos não retornam um único valor, por exemplo, ao definir o formato de retorno como both em tipos de campo com opções.

JSON
{
  "attributes": [
    {
      "id": "customColor",
      "type": "select",
      "label": "Heading color",
      "options": [
        {
          "value": "#f00",
          "label": "Red"
        },
        {
          "value": "#00f",
          "label": "Blue"
        }
      ],
      "returnFormat": "both",
      "set": [
        {
          "attribute": "style",
          "value": "color: {attributes.customColor.value}"
        },
        {
          "attribute": "data-color",
          "value": "{attributes.customColor.label}"
        }
      ]
    }
  ]
}

O exemplo acima definirá o atributo style como color: #f00 ou color: #00f e o atributo data-color como Red ou Blue, dependendo do valor.

Por enquanto, somente valores do atributo atual podem ser usados nas definições de set. A possibilidade de usar valores de outros atributos poderá ser adicionada no futuro.

Matrizes

Ao usar matrizes, a propriedade set será aplicada a cada item da matriz.

Cada item adiciona sua própria classe ou declaração de estilo. Qualquer outro atributo contém um único valor, então cada item o substitui e o último prevalece. Defina join como true para gravar os resultados de todos os itens, separados por espaços e sem valores vazios ou repetidos, para que um seletor como [data-langs~="en"] corresponda a cada item escolhido. join não tem efeito sobre class e style, nem sobre campos que retornam um único valor.

JSON
{
  "id": "langs",
  "type": "checkbox",
  "label": "Languages",
  "options": [
    {
      "value": "en",
      "label": "English"
    },
    {
      "value": "de",
      "label": "German"
    }
  ],
  "set": [
    {
      "attribute": "data-langs",
      "value": "{attributes.langs}",
      "join": true
    }
  ]
}

Escolher ambas as opções renderiza data-langs="en de". Sem join, renderiza data-langs="de".

Campo de atributos

Ao usar o campo attributes, não é necessário definir a propriedade set, pois o campo mapeia automaticamente os valores para o nome e o valor do atributo.

Inspecionando campos de extensão

bs_block_extension_fields('core/paragraph') retorna as definições de campos de cada extensão que corresponde a um bloco. Consulte Inspecionando blocos para ver o valor retornado e como ele se relaciona com bs_block_fields().