Aller au contenu

Enregistrement

Créer vos propres blocs avec Blockstudio est très simple. L’extension recherche un dossier blockstudio dans le thème actuellement activé. Tous les sous-dossiers qui contiennent un fichier block.json avec une clé blockstudio y seront enregistrés.

block.json

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

Modèle

Jusqu’ici, le bloc personnalisé ne sera pas enregistré, car il lui manque un modèle. Pour y remédier, créez un fichier index.php dans le même dossier que votre fichier block.json ; son contenu sera automatiquement affiché lorsque votre bloc sera utilisé.

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

Logique conditionnelle

Les blocs peuvent être enregistrés sous condition à l’aide de la clé conditions. Elle prend en charge toutes les variables globales également disponibles pour les attributs.

Voir toutes les conditions

L’exemple suivant n’enregistrera le bloc que si le type de publication actuel est une page :

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

Dépendances des extensions

Les blocs peuvent dépendre d’extensions WordPress actives à l’aide de la clé pluginDependencies. Si l’une des extensions répertoriées est inactive, le bloc est ignoré lors de l’enregistrement.

Les dépendances utilisent les slugs des extensions WordPress :

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

Utilisez la forme objet pour exiger une version d’extension. Les contraintes de version utilisent les mêmes opérateurs que version_compare() de PHP ; une version sans opérateur est considérée comme >=.

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

Icône personnalisée

Les icônes SVG personnalisées des blocs peuvent être enregistrées ainsi :

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

WordPress n’autorise pas les icônes SVG personnalisées dans sa propre clé icon block.json ; seuls les identifiants Dashicons sont autorisés ici.

Blocs WordPress standard

Blockstudio enregistre également automatiquement les blocs WordPress standard présents dans vos répertoires Blockstudio. Tout block.json sans clé blockstudio, mais avec une propriété name valide, est enregistré via le register_block_type() natif de WordPress.

Vous pouvez donc placer directement dans votre dossier blockstudio/ les blocs générés avec @wordpress/create-block ; ils seront enregistrés automatiquement avec vos blocs Blockstudio. Aucun code d’enregistrement distinct pour l’extension n’est nécessaire.

Code
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

Créez votre bloc avec npx wp-scripts build, puis déposez le dossier généré dans votre répertoire Blockstudio. Il sera enregistré automatiquement.

Il en va de même pour WordPress 7.0 PHP uniquement : un block.json avec la prise en charge de autoRegister et un render.php ne nécessitent ni script ni compilation et s’enregistrent ici comme tout bloc standard. Core limite cette approche aux blocs simples avec des attributs de type chaîne, entier, booléen et énumération ; dès qu’un bloc nécessite des blocs internes, du texte enrichi, des médias ou des contrôles personnalisés, créez un bloc côté client ou attribuez-lui une clé blockstudio et restez dans PHP.

HTML

Blockstudio utilise un analyseur d’éléments React pour afficher l’élément d’icône ; il est donc possible d’utiliser HTML dans la chaîne de l’icône.

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

Chemins personnalisés

Par défaut, Blockstudio parcourt récursivement le dossier blockstudio de votre thème actuel ou thème enfant pour trouver les blocs. Vous pouvez modifier ce comportement de deux façons.

Filtre

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

Pour les systèmes de fichiers composés ou virtuels, utilisez une source logique de découverte au lieu d’ajouter séparément des chemins parent et superposé. Les sources logiques prennent en charge la substitution par chemin, l’héritage des fichiers frères, les suppressions, l’identité du cache et la provenance. Consultez Sources logiques de découverte.

Instances

Si les options ci-dessus ne suffisent pas, vous pouvez instancier la classe Blockstudio\Build dans différents dossiers de votre choix :

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

Filtrer les métadonnées

Les métadonnées peuvent être filtrées avant l’enregistrement du bloc à l’aide du filtre 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’exemple ci-dessus est utilisé en interne pour attribuer la même icône à tous les éléments de la bibliothèque Blockstudio.