Vai al contenuto

Registrazione

Comporre blocchi personalizzati con Blockstudio è estremamente semplice. Il plugin cercherà una cartella blockstudio nel tema attualmente attivo. Al suo interno verranno registrate tutte le sottocartelle che contengono un file block.json con una chiave blockstudio.

block.json

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

Template

Finora il blocco personalizzato non verrà registrato perché manca un template. Per risolvere il problema, create un file index.php nella stessa cartella del file block.json: il suo contenuto verrà renderizzato automaticamente quando userete il blocco.

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

Logica condizionale

I blocchi possono essere registrati in modo condizionale usando la chiave conditions. Supporta tutte le variabili globali disponibili anche per gli attributi.

Visualizza tutte le condizioni

L’esempio seguente registra il blocco solo se il tipo di contenuto corrente è una pagina:

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

Dipendenze dei plugin

I blocchi possono dipendere dai plugin WordPress attivi usando la chiave pluginDependencies. Se uno dei plugin elencati è inattivo, il blocco viene ignorato durante la registrazione.

Le dipendenze usano gli slug dei plugin WordPress:

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

Usate la forma oggetto per richiedere una versione del plugin. I vincoli di versione usano gli stessi operatori di PHPversion_compare(); una versione senza operatore viene considerata >=.

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

Icona personalizzata

Le icone SVG personalizzate per i blocchi possono essere registrate così:

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

WordPress non consente icone SVG personalizzate nella propria chiave block.json icon: qui sono consentiti solo gli ID dei Dashicons.

Blocchi WordPress standard

Blockstudio registra automaticamente anche i blocchi WordPress standard trovati nelle directory Blockstudio. Qualsiasi block.json privo di una chiave blockstudio, ma con una proprietà name valida, viene registrato tramite l’WordPressregister_block_type() nativa di.

Questo significa che potete inserire direttamente nella cartella blockstudio/ i blocchi creati con @wordpress/create-block: verranno registrati automaticamente insieme ai blocchi Blockstudio. Non serve codice di registrazione separato nel plugin.

Codice
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

Create il vostro blocco con npx wp-scripts build, poi inserite la cartella generata nella directory Blockstudio. Verrà registrato automaticamente.

Lo stesso vale per i blocchi PHP esclusivamente- di WordPress 7.0: un block.json con supporto autoRegister e un render.php non richiede script né compilazione e viene registrato qui come qualsiasi altro blocco standard. Core limita questo percorso a blocchi semplici con attributi di tipo stringa, intero, booleano ed enum; quando servono blocchi interni, testo formattato, contenuti multimediali o controlli personalizzati, create un blocco lato client oppure assegnategli una chiave blockstudio e continuate a usare PHP.

HTML

Blockstudio usa un parser di elementi React per renderizzare l’elemento icona, quindi è possibile usare HTML nella stringa dell’icona.

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

Percorsi personalizzati

Per impostazione predefinita, Blockstudio esamina ricorsivamente la cartella blockstudio del tema o tema child attualmente attivo per individuare i blocchi. Potete modificare questo comportamento in due modi.

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';
});

Per filesystem composti o virtuali, usate una sorgente di rilevamento logica invece di aggiungere percorsi indipendenti per genitore e overlay. Le sorgenti logiche supportano la sostituzione per percorso, l’ereditarietà dei file fratelli, le eliminazioni, l’identità della cache e la provenienza. Consultate Sorgenti di rilevamento logiche.

Istanze

Se le opzioni precedenti non bastano, potete avviare la classe Blockstudio\Build in varie cartelle a vostra scelta:

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

Filtrare i metadati

I metadati possono essere filtrati prima della registrazione del blocco usando il 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);

L’esempio precedente viene usato internamente per assegnare la stessa icona a tutti gli elementi della libreria Blockstudio.