Pular para o conteúdo

Registro

Criar seus próprios blocos com Blockstudio é muito fácil. O plugin procurará uma pasta blockstudio no tema ativado no momento. Dentro dela, todas as subpastas que contiverem um arquivo block.json com uma chave blockstudio serão registradas.

block.json

JSON
{
  "name": "blockstudio/native",
  "title": "Native Block",
  "category": "text",
  "icon": "star-filled",
  "description": "Native Blockstudio block.",
  "blockstudio": true
}

Modelo

Até agora, o bloco personalizado não será registrado porque está sem um modelo. Para corrigir isso, basta criar um index.php na mesma pasta do seu arquivo block.json, e o conteúdo será renderizado automaticamente quando o bloco for usado.

PHP
<h1>My first native block.</h1>

Lógica condicional

Os blocos podem ser registrados condicionalmente usando a chave conditions. Ela aceita todas as variáveis globais também disponíveis para atributos.

Ver todas as condições

O exemplo a seguir registrará o bloco somente se o tipo de post atual for uma página:

JSON
{
  "blockstudio": {
    "conditions": [
      [
        {
          "type": "postType",
          "operator": "==",
          "value": "page"
        }
      ]
    ]
  }
}

Dependências de plugins

Os blocos podem depender de plugins WordPress ativos usando a chave pluginDependencies. Se um dos plugins listados estiver inativo, o bloco será ignorado durante o registro.

As dependências usam os slugs de plugins WordPress:

JSON
{
  "blockstudio": {
    "pluginDependencies": [
      "woocommerce",
      "advanced-custom-fields"
    ]
  }
}

Use o formato de objeto para exigir uma versão de plugin. As restrições de versão usam os mesmos operadores de PHP, em seu version_compare(); uma versão sem operador é tratada como >=.

JSON
{
  "blockstudio": {
    "pluginDependencies": {
      "woocommerce": {
        "version": ">6"
      }
    }
  }
}

Ícone personalizado

Ícones SVG personalizados para blocos podem ser registrados assim:

JSON
{
  "blockstudio": {
    "icon": "<svg></svg>"
  }
}

WordPress não permite ícones SVG personalizados na própria chave block.json icon; aqui, só são permitidos IDs de Dashicons.

Blocos padrão do WordPress

Blockstudio também registra automaticamente blocos padrão do WordPress encontrados nos diretórios Blockstudio. Qualquer block.json sem uma chave blockstudio, mas com uma propriedade name válida, é registrado pela API nativa register_block_type() do WordPress.

Isso significa que você pode colocar blocos criados com @wordpress/create-block diretamente na pasta blockstudio/, e eles serão registrados automaticamente junto com os blocos Blockstudio. Não é necessário código de registro separado no plugin.

Código
blockstudio/
├── hero/
│   ├── block.json          ← Blockstudio block (has "blockstudio" key)
│   └── index.twig
├── my-js-block/
│   ├── block.json          ← Standard WP block (no "blockstudio" key)
│   ├── index.js            ← Compiled editor script
│   ├── index.css
│   ├── style-index.css
│   └── render.php

Crie seu bloco com npx wp-scripts build e coloque a pasta de saída no diretório Blockstudio. Ele será registrado automaticamente.

O mesmo se aplica aos blocos PHP somente do WordPress 7.0: um block.json com suporte a autoRegister e um render.php não precisa de script nem compilação e é registrado aqui como qualquer outro bloco padrão. O núcleo limita esse caminho a blocos simples com atributos de string, inteiro, booleano e enumeração; assim que um deles precisar de blocos internos, texto formatado, mídia ou controles personalizados, crie um bloco do lado do cliente ou forneça uma chave blockstudio e continue usando PHP.

HTML

Blockstudio usa um analisador de elementos React para renderizar o elemento de ícone, então é possível usar HTML dentro da string do ícone.

JSON
{
  "blockstudio": {
    "icon": "<div>:-)</div>"
  }
}

Caminhos personalizados

Por padrão, Blockstudio procura recursivamente blocos na pasta blockstudio do seu tema atual ou tema filho. Você pode alterar esse comportamento de duas maneiras.

Filtro

PHP
// Custom path within your theme.
add_filter('blockstudio/path', function () {
    return get_template_directory() . '/blocks';
});

// Custom path within a plugin.
add_filter('blockstudio/path', function () {
    return WP_PLUGIN_DIR . '/my-custom-plugin/blocks';
});

Para sistemas de arquivos compostos ou virtuais, use uma fonte lógica de descoberta em vez de adicionar caminhos independentes para o diretório pai e a sobreposição. As fontes lógicas oferecem substituição por caminho, arquivos irmãos herdados, exclusões, identidade de cache e proveniência. Consulte Fontes lógicas de descoberta.

Instâncias

Se as opções acima não forem suficientes, é possível iniciar a classe Blockstudio\Build em várias pastas à sua escolha:

PHP
add_action('init', function () {
  Blockstudio\Build::init([
    'dir' => get_template_directory() . '/client-blocks'
  ]);
});

Filtrar metadados

Os metadados podem ser filtrados antes do registro do bloco usando o filtro blockstudio/blocks/meta:

PHP
add_filter('blockstudio/blocks/meta', function ($meta, $block) {
    if (str_starts_with($block['name'], 'marketing')) {
        $meta['icon'] = 'megaphone';
    }
    return $meta;
}, 10, 2);

O exemplo acima é usado internamente para dar o mesmo ícone a todos os elementos da biblioteca Blockstudio.