Hooks für den Block-Editor

Hooks gehören zu den grundlegenden Funktionen von WordPress. Sie ermöglichen es dir, dich in den WordPress-Kern einzuklinken und an bestimmten Punkten im WordPress-Lebenszyklus eigenen Code auszuführen.

Der Block-Editor verfügt über eine eigene Reihe von Hooks, mit denen du mit dem Editor interagieren und sein Verhalten ändern kannst.

In dieser Lektion lernst du einige der verschiedenen im Block-Editor verfügbaren Hooks kennen und erfährst, wie du sie verwenden kannst, um die Funktionalität des Editors zu erweitern.

Das Paket @wordpress/hooks

Während Aktions- und Filter-Hooks historisch nur in PHP verfügbar waren, gibt es aufgrund der Tatsache, dass der Block-Editor mit JavaScript erstellt wird, nun auch eine neue Reihe von JavaScript-Hooks.

Mit diesen JavaScript-Aktions- und Filter-Hooks kannst du dich in verschiedene Aspekte des Editors einklinken und Änderungen am Verhalten des Editors oder an den Blöcken selbst vornehmen.

JavaScript-Hooks werden mithilfe der Funktionen addAction und addFilter des Pakets @wordpress/hooks registriert.

Ähnlich wie bei den PHP-Versionen übergibst du diesen Funktionen den Hook-Namen und die Callback-Funktion.

Der wichtigste Unterschied besteht darin, dass du außerdem den Namespace des Hooks übergeben musst. Der Namespace ist eine eindeutige Kennung für die Callback-Funktion und hilft, Konflikte durch Namensüberschneidungen zu verhindern.

Sehen wir uns ein Beispiel an, um zu veranschaulichen, wie ein JavaScript-Hook verwendet wird.

Der Filter blocks.registerBlockType

Bei allen Block-Beispielen, die du bisher gesehen hast, hast du die Funktion registerBlockType aus dem Paket @wordpress/blocks verwendet, um einen Block in JavaScript zu registrieren.

Jeder Block beginnt mit der Registrierung einer neuen Blocktypdefinition mithilfe dieser Funktion.

/**
 * Every block starts by registering a new block type definition.
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
 */
registerBlockType( metadata.name, {
    /**
     * @see ./edit.js
     */
    edit: Edit,

    /**
     * @see ./save.js
     */
    save,
} );

Wenn der Code, der alle registrierten Blöcke verarbeitet, ausgeführt wird, werden alle Callback-Funktionen ausgeführt, die in den Filter-Hook blocks.registerBlockType eingeklinkt sind. Sie sollten ein geändertes Blockeinstellungsobjekt zurückgeben.

    const settings = applyFilters(
        'blocks.registerBlockType',
        blockType,
        name,
        null
    );

Mit diesem Filter-Hook kannst du das Blockeinstellungsobjekt ändern, bevor der Block registriert wird.

Um eine Callback-Funktion für den Filter blocks.registerBlockType zu registrieren, verwendest du die Funktion addFilter aus dem Paket @wordpress/hooks.

Erstelle nun ein Plugin, das eine JavaScript-Datei einbindet, um den Filter zu registrieren.

Erstelle zunächst ein Verzeichnis in deinem Verzeichnis wp-content/plugins, in dem du den Code für die Block-Hooks speicherst.

mkdir -p wp-content/plugins/wp-learn-block-hooks

Erstelle die zentrale PHP-Plugin-Datei wp-learn-block-hooks.php im neu erstellten Verzeichnis.

Füge anschließend den folgenden Code hinzu, um den Plugin-Header einzurichten und sicherzustellen, dass der Plugin-Code nur in der WordPress-Umgebung ausgeführt wird:

<?php
/**
 * Plugin Name:       WP Learn Block Hooks
 * Description:       WP Learn Block Hooks
 * Requires at least: 6.6
 * Requires PHP:      7.0
 * Version:           1.0.0
 * Author:            The WordPress Contributors
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       wp-learn-block-hooks
 *
 */
if ( ! defined( 'ABSPATH' ) ) {
    exit; // Exit if accessed directly.
}

Als Nächstes kannst du eine Callback-Funktion in die Aktion enqueue_block_editor_assets einklinken, um die JavaScript-Datei einzubinden.

add_action( 'enqueue_block_editor_assets', 'wp_learn_block_hooks_editor_assets' );
function wp_learn_block_hooks_editor_assets() {
    wp_enqueue_script(
        'wp-learn-block-hooks-editor-script',
        plugin_dir_url( __FILE__ ) . 'block-hooks.js',
        array(
            'wp-hooks',
        ),
    );
}

Beachte, dass du die Abhängigkeit wp-hooks angeben musst, um sicherzustellen, dass dein Code für die Block-Hooks erst geladen wird, sobald das Paket @wordpress/hooks verfügbar ist. Das liegt daran, dass du in der JavaScript-Datei die Funktion addFilter aus dem Paket @wordpress/hooks verwenden wirst.

Erstelle nun eine Datei block-hooks.js im Plugin-Verzeichnis und beginne mit einer IIFE (Immediately Invoked Function Expression), um zu verhindern, dass Variablen aus diesem Code in den globalen Gültigkeitsbereich gelangen:

( function(){

} )()

Verwende anschließend die Funktion addFilter, um eine Callback-Funktion für den Filter-Hook blocks.registerBlockType zu registrieren:

( function(){
    wp.hooks.addFilter(
        'blocks.registerBlockType',
        'wp-learn-block-hooks/list-block-description',
        addListBlockDescription
    );
} )()

Beachte, wie du vor der Callback-Funktion addListBlockDescription einen eindeutigen Namespace angibst. Der Namespace wird vom Entwickler festgelegt und sollte für dein Plugin eindeutig sein.

Erstelle nun die Callback-Funktion addListBlockDescription, um etwas zu tun:

    function addListBlockDescription( settings, name ) {
        if ( name === 'core/list' ) {
            settings.description = 'This is a list block';
        }
        return settings;
    }

Hier erhält die Callback-Funktion addListBlockDescription das Einstellungsobjekt und den Namen des Blocks als Parameter.

Anschließend prüft sie, ob es sich bei dem registrierten Block um einen Listenblock handelt. Falls dies zutrifft, ändert sie die Eigenschaft „description“ des Einstellungsobjekts des Blocks.

Da es sich schließlich um einen Filter handelt, muss die Funktion etwas zurückgeben – in diesem Fall das geänderte Einstellungsobjekt.

Um dies zu testen, aktiviere das Plugin noch nicht. Bearbeite stattdessen einen Beitrag oder eine Seite und suche im Block-Inserter nach dem Listenblock.

Wenn du mit dem Mauszeiger über den Listenblock fährst, solltest du die Beschreibung “Create a bulleted or numbered list” sehen.

Aktiviere nun das Plugin.

Nach der Aktivierung des Plugins sollte sich die Beschreibung des Listenblocks in “This is a list block” ändern.

Dokumentation zu den Hooks des Block-Editors

Das Handbuch zum Block-Editor enthält einen Abschnitt zu Hooks des Block-Editors. Dieser umfasst verschiedene Seiten für die unterschiedlichen verfügbaren Hook-Typen.

Die Seite Block-Filter enthält eine Liste aller verfügbaren Filter, mit denen du das Verhalten bestehender Blöcke ändern kannst. Dazu gehören Abschnitte zum Ändern von Blöcken während der Blockregistrierung, zum Ändern von Blöcken im Frontend, zum Ändern des Verhaltens von Blöcken im Block-Editor, zum Entfernen und Ausblenden von Blöcken sowie zum Verwalten von Blockkategorien.

Editor-Hooks dokumentiert alle Hooks, mit denen du das Editor-Erlebnis ändern kannst, einschließlich der Änderung der Editoreinstellungen, der Deaktivierung der Verzeichnisse für Blöcke und Muster, der Erweiterung von Editor-Funktionen, der Steuerung von REST-API-Daten für den Editor und der Protokollierung von Editor-Fehlern.

Die Seite zu den i18n-Filtern enthält eine Liste von Filtern, mit denen du die im Editor verwendeten Internationalisierungsfunktionen ändern kannst.

Parser-Filter dokumentiert alle Filter, mit denen du den Block-Parser ändern kannst. Dieser wird verwendet, um die im Speicher abgelegten Blockdaten in das Block-Markup umzuwandeln, das im Beitragsinhalt der Datenbank gespeichert wird.

Autocomplete ist eine Komponente im Paket @wordpress/block-editor, die eine Möglichkeit bietet, Autovervollständigungen zum Editor hinzuzufügen.

Wenn du jemals die Funktion @username im Block-Editor verwendet hast: Sie wird von einer Autocomplete-Komponente bereitgestellt.

Die Seite zu den Autocomplete-Filtern dokumentiert, wie du eigene Autovervollständigungen zum Editor hinzufügen kannst.

Schließlich dokumentiert die Seite zu den Filtern für globale Stile die in WordPress 6.1 hinzugefügten Filter, mit denen Entwickler die globalen Einstellungen und Stile eines Block-Themes ändern können, wie sie in der Datei theme.json definiert sind.

Alle diese Seiten enthalten ausführliche Beispiele dafür, wie diese Hooks verwendet werden und wie sie zur Erweiterung der Funktionalität des Block-Editors eingesetzt werden können.