Ein Crashkurs in WordPress Block Filtern

Blöcke in WordPress sind großartig. Füge ein paar davon auf der Seite ein, ordne sie nach Belieben an, und du hast im Handumdrehen eine ziemlich coole Landingpage erstellt. Aber was, wenn die Standardblöcke in WordPress ein wenig angepasst werden müssen? Was, wenn wir zum Beispiel die Ausrichtungsoptionen in den Einstellungen des Cover-Blocks entfernen könnten? Oder wie wäre es mit der Steuerung der Größe für den Button-Block?

Es gibt viele Möglichkeiten, die Funktionalität von Kernblöcken in WordPress zu erweitern. Wir können einem Block im Editor eine benutzerdefinierte CSS-Klasse hinzufügen, einen benutzerdefinierten Stil hinzufügen oder eine Block-Variante erstellen. Aber selbst diese reichen möglicherweise nicht aus, um das zu bekommen, was du brauchst, und du wirst feststellen, dass du den Kernblock filtern musst, um Funktionen hinzuzufügen oder zu entfernen, oder dass du einen völlig neuen Block von Grund auf neu erstellen musst.

Ich zeige dir, wie du Kernblöcke mit Filtern erweiterst, und gehe auch darauf ein, wann es am besten ist, einen benutzerdefinierten Block zu erstellen, anstatt einen Kernblock zu erweitern.

Eine kurze Anmerkung zu diesen Beispielen

Bevor wir eintauchen, möchte ich darauf hinweisen, dass die Code-Snippets in diesem Artikel bewusst aus dem Kontext gerissen sind, um uns auf Filter zu konzentrieren und nicht auf Build-Tools und Dateistrukturen. Wenn ich den vollständigen Code für die Filter einfügen würde, wäre der Artikel schwer zu verfolgen. Trotzdem verstehe ich, dass es für jemanden, der gerade erst anfängt, nicht offensichtlich ist, wo die Snippets platziert werden sollen oder wie Build-Skripte ausgeführt werden und das Ganze zum Laufen gebracht wird.

Um es dir leichter zu machen, habe ich ein WordPress-Plugin mit den Beispielen aus diesem Artikel auf meinem GitHub verfügbar gemacht. Lade es dir gerne herunter und erkunde die Dateistruktur, Abhängigkeiten und Build-Skripte. Es gibt eine README, die dir den Einstieg erleichtert.

Block-Filter im Überblick

Das Konzept der Filter ist in WordPress nicht neu. Die meisten von uns kennen die PHP-Funktion add_filter(). Sie ermöglicht es Entwicklern, verschiedene Arten von Daten mithilfe von Hooks zu ändern.

Ein einfaches Beispiel für einen PHP-Filter könnte so aussehen

function filter_post_title( $title ){
  return '<strong>' . $title . '</strong>';
};

add_filter( 'the_title',  'filter_post_title' );

In diesem Snippet erstellen wir eine Funktion, die einen String empfängt, der einen Beitragstitel darstellt, umschließt ihn dann mit einem <strong>-Tag und gibt einen geänderten Titel zurück. Anschließend verwenden wir add_filter(), um WordPress mitzuteilen, dass diese Funktion für einen Beitragstitel verwendet werden soll.

JavaScript-Filter funktionieren auf ähnliche Weise. Es gibt eine JavaScript-Funktion namens addFilter(), die im Paket wp.hooks lebt und fast wie ihr PHP-Pendant funktioniert. In seiner einfachsten Form sieht ein JavaScript-Filter so aus

function filterSomething(something) {
  // Code for modifying something goes here.
  return something;
}

wp.hooks.addFilter( 'hookName', 'namespace', filterSomething );

Sieht ziemlich ähnlich aus, oder? Ein bemerkenswerter Unterschied ist, dass addFilter() als zweites Argument einen namespace hat. Laut dem WordPress Handbook, „Ein Namespace identifiziert eindeutig einen Callback in der Form vendor/plugin/function.“ Die Beispiele im Handbuch folgen jedoch unterschiedlichen Mustern: plugin/what-filter-does oder plugin/component-name/what-filter-does. Ich folge normalerweise letzterem, da dies die Handles im gesamten Projekt eindeutig hält.

Was JavaScript-Filter schwierig zu verstehen und zu verwenden macht, ist die unterschiedliche Natur dessen, was sie filtern können. Einige filtern Strings, einige filtern JavaScript-Objekte und andere filtern React-Komponenten und erfordern das Verständnis des Konzepts von Higher Order Components.

Darüber hinaus musst du wahrscheinlich JSX verwenden, was bedeutet, dass du den Code nicht einfach in dein Theme oder Plugin einfügen und erwarten kannst, dass er funktioniert. Du musst ihn zu Vanilla JavaScript kompilieren, das Browser verstehen. All das kann am Anfang einschüchternd sein, besonders wenn du aus einem PHP-Hintergrund kommst und nur begrenzte Kenntnisse von ES6, JSX und React hast.

Aber keine Angst! Wir haben zwei Beispiele, die die Grundlagen von Block-Filtern abdecken, um dir zu helfen, die Idee zu verstehen und dich mit JavaScript-Filtern in WordPress wohlzufühlen. Zur Erinnerung: Wenn dir das Schreiben dieses Codes für den Block-Editor neu ist, erkunde das Plugin mit Beispielen aus diesem Artikel.

Ohne weiteres Verzögerung werfen wir einen Blick auf das erste Beispiel.

Entfernen der Ausrichtungsoptionen des Cover-Blocks

Wir werden den Kern-Cover-Block filtern und die Ausrichtungsoptionen Links, Mitte, Rechts und Breit aus seinen Blockeinstellungen entfernen. Dies kann in Projekten nützlich sein, bei denen der Cover-Block nur als Seiten-Hero oder als Banner verwendet wird und nicht links- oder rechtsbündig ausgerichtet werden muss.

Wir verwenden den Filter blocks.registerBlockType. Er empfängt die Einstellungen des Blocks und seinen Namen und muss ein gefiltertes Einstellungs-Objekt zurückgeben. Durch das Filtern von Einstellungen können wir das supports-Objekt aktualisieren, das das Array der verfügbaren Ausrichtungen enthält. Machen wir das Schritt für Schritt.

Wir beginnen damit, den Filter hinzuzufügen, der die Einstellungen und den Namen des Blocks einfach in die Konsole protokolliert, um zu sehen, womit wir arbeiten.

const { addFilter } = wp.hooks;

function filterCoverBlockAlignments(settings, name) {
  console.log({ settings, name });
  return settings;
}

addFilter(
  'blocks.registerBlockType',
  'intro-to-filters/cover-block/alignment-settings',
  filterCoverBlockAlignments,
);

Lass uns das aufschlüsseln. Die erste Zeile ist eine einfache Destrukturierung des wp.hooks-Objekts. Sie ermöglicht es uns, addFilter() im Rest der Datei zu schreiben, anstatt wp.hooks.addFilter(). Dies mag in diesem Fall redundant erscheinen, ist aber nützlich, wenn mehrere Filter in derselben Datei verwendet werden (wie wir im nächsten Beispiel sehen werden).

Als Nächstes definieren wir die Funktion filterCoverBlockAlignments(), die das Filtern durchführt. Vorerst protokolliert sie nur das Einstellungs-Objekt und den Namen des Blocks in der Konsole und gibt die Einstellungen unverändert zurück.

Alle Filterfunktionen empfangen Daten und müssen gefilterte Daten zurückgeben. Andernfalls wird der Editor abstürzen.

Und schließlich initialisieren wir den Filter mit der Funktion addFilter(). Wir geben ihm den Namen des Hooks, den wir verwenden werden, den Filter-Namespace und eine Funktion, die das Filtern durchführt.

Wenn wir alles richtig gemacht haben, sollten wir viele Meldungen in der Konsole sehen. Aber beachte, dass sich nicht alle davon auf den Cover-Block beziehen.

Das ist korrekt, weil der Filter auf *alle* Blöcke angewendet wird und nicht nur auf den spezifischen Block, den wir wollen. Um das zu beheben, müssen wir sicherstellen, dass wir den Filter nur für den Block core/cover anwenden.

function filterCoverBlockAlignments(settings, name) {
  if (name === 'core/cover') {
    console.log({ settings, name });
  }
  return settings;
}

Mit dieser Änderung sollten wir jetzt etwas Ähnliches in der Konsole sehen.

Mach dir keine Sorgen, wenn du mehr Log-Meldungen als Cover-Blöcke auf der Seite siehst. Ich habe noch nicht herausgefunden, warum das so ist. Wenn du den Grund kennst, teile ihn bitte in den Kommentaren!

Und hier kommt der lustige Teil: das eigentliche Filtern. Wenn du Blöcke von Grund auf neu erstellt hast, weißt du, dass Ausrichtungsoptionen mit der Supports API definiert werden. Lass mich dich kurz daran erinnern, wie es funktioniert – wir können es entweder auf true setzen, um alle Ausrichtungen zuzulassen, so:

supports: {
  align: true
}

...oder ein Array von Ausrichtungen angeben, die unterstützt werden sollen. Das folgende Snippet tut dasselbe wie das obige.

supports: {
  align: [ 'left', 'right', 'center', 'wide', 'full' ]
}

Betrachten wir nun genauer das settings-Objekt aus einer der Konsolenmeldungen, die wir erhalten haben, und sehen wir, womit wir es zu tun haben.

Alles, was wir tun müssen, ist align: true durch align: ['full'] innerhalb der supports-Eigenschaft zu ersetzen. So können wir das tun.

function filterCoverBlockAlignments(settings, name) {
  if (name === 'core/cover') {
    return assign({}, settings, {
      supports: merge(settings.supports, {
        align: ['full'],
      }),
    });
  }
  return settings;
}

Ich möchte hier kurz innehalten, um deine Aufmerksamkeit auf die Lodash-Methoden assign und merge zu lenken. Wir verwenden diese, um ein brandneues Objekt zu erstellen und zurückzugeben und sicherzustellen, dass das ursprüngliche settings-Objekt intakt bleibt. Der Filter funktioniert auch dann noch, wenn wir so etwas tun.

/* 👎 WRONG APPROACH! DO NOT COPY & PASTE! */
settings.supports.align = ['full'];
return settings;

...aber das ist eine Objektmutation, die als schlechte Praxis gilt und vermieden werden sollte, es sei denn, du weißt, was du tust. Zell Liew diskutiert warum Mutationen beängstigend sein können auf A List Apart.

Zurück zu unserem Beispiel, es sollte jetzt nur noch eine Ausrichtungsoption in der Block-Toolbar geben.

Ich habe die Option "zentriert" entfernt, weil die Ausrichtungs-Toolbar es dir ermöglicht, die Ausrichtung "ein" und "aus" umzuschalten. Das bedeutet, dass Cover-Blöcke jetzt Standard- und "Vollbreite"-Zustände haben.

Und hier ist das vollständige Snippet.

const { addFilter } = wp.hooks;
const { assign, merge } = lodash;

function filterCoverBlockAlignments(settings, name) {
  if (name === 'core/cover') {
    return assign({}, settings, {
      supports: merge(settings.supports, {
        align: ['full'],
      }),
    });
}
  return settings;
}

addFilter(
  'blocks.registerBlockType',
  'intro-to-filters/cover-block/alignment-settings',
  filterCoverBlockAlignments,
);

Das war doch gar nicht schwer, oder? Du hast jetzt ein grundlegendes Verständnis davon, wie Filter mit Blöcken funktionieren. Lass es uns auf die nächste Stufe heben und uns ein etwas fortgeschritteneres Beispiel ansehen.

Hinzufügen einer Größensteuerung zum Button-Block

Fügen wir nun eine Größensteuerung zum Kern-Button-Block hinzu. Dies wird etwas fortgeschrittener, da wir mehrere Filter zusammenarbeiten lassen müssen. Der Plan ist, eine Steuerung hinzuzufügen, die es dem Benutzer ermöglicht, aus drei Größen für einen Button zu wählen: Klein, Normal und Groß.

Es mag kompliziert erscheinen, aber wenn wir es aufschlüsseln, wirst du sehen, dass es eigentlich ziemlich einfach ist.

1. Hinzufügen eines Größenattributs zum Button-Block

Als Erstes müssen wir ein zusätzliches Attribut hinzufügen, das die Größe des Buttons speichert. Wir verwenden den bereits bekannten blocks.registerBlockType-Filter aus dem vorherigen Beispiel.

/**
 * Add Size attribute to Button block
 *
 * @param  {Object} settings Original block settings
 * @param  {string} name     Block name
 * @return {Object}          Filtered block settings
 */
function addAttributes(settings, name) {
  if (name === 'core/button') {
    return assign({}, settings, {
      attributes: merge(settings.attributes, {
        size: {
          type: 'string',
          default: '',
        },
      }),
    });
  }
  return settings;
}

addFilter(
  'blocks.registerBlockType',
  'intro-to-filters/button-block/add-attributes',
  addAttributes,
);

Der Unterschied zwischen dem, was wir hier tun, und dem, was wir zuvor getan haben, ist, dass wir attributes anstelle des supports-Objekts filtern. Dieses Snippet allein bewirkt nicht viel und du wirst keine Veränderung im Editor bemerken, aber ein Attribut für die Größe ist für das Funktionieren des Ganzen unerlässlich.

2. Hinzufügen der Größensteuerung zum Button-Block

Wir arbeiten mit einem neuen Filter, editor.BlockEdit. Er ermöglicht es uns, das Inspector Controls-Panel (d.h. das Einstellungs-Panel auf der rechten Seite des Block-Editors) zu ändern.

/**
 * Add Size control to Button block
 */
const addInspectorControl = createHigherOrderComponent((BlockEdit) => {
  return (props) => {
    const {
      attributes: { size },
      setAttributes,
      name,
    } = props;
    if (name !== 'core/button') {
      return <BlockEdit {...props} />;
    }
    return (
      <Fragment>
        <BlockEdit {...props} />
        <InspectorControls>
          <PanelBody
            title={__('Size settings', 'intro-to-filters')}
            initialOpen={false}
          >
            <SelectControl
              label={__('Size', 'intro-to-filters')}
              value={size}
              options={[
                {
                  label: __('Regular', 'intro-to-filters'),
                  value: 'regular',
                },
                {
                  label: __('Small', 'intro-to-filters'),
                  value: 'small'
                },
                {
                  label: __('Large', 'intro-to-filters'),
                  value: 'large'
                },
              ]}
              onChange={(value) => {
                setAttributes({ size: value });
              }}
            />
          </PanelBody>
      </InspectorControls>
      </Fragment>
    );
  };
}, 'withInspectorControl');

addFilter(
  'editor.BlockEdit',
  'intro-to-filters/button-block/add-inspector-controls',
  addInspectorControl,
);

Das mag viel aussehen, aber wir werden es aufschlüsseln und sehen, wie geradlinig es tatsächlich ist.

Das Erste, was dir vielleicht aufgefallen ist, ist die createHigherOrderComponent-Konstruktion. Im Gegensatz zu anderen Filtern in diesem Beispiel empfängt editor.BlockEdit eine *Komponente* und muss eine *Komponente* zurückgeben. Deshalb müssen wir ein Higher Order Component-Muster, abgeleitet von React, verwenden.

In seiner reinsten Form sieht der Filter zum Hinzufügen von Steuerelementen so aus

const addInspectorControl = createHigherOrderComponent((BlockEdit) => {
  return (props) => {
    // Logic happens here.
    return <BlockEdit {...props} />;
  };
}, 'withInspectorControl');

Das tut nichts weiter, als dir zu ermöglichen, die <BlockEdit />-Komponente und ihre props in der Konsole zu inspizieren. Hoffentlich ergibt die Konstruktion selbst jetzt Sinn, und wir können den Filter weiter aufschlüsseln.

Der nächste Teil ist die Destrukturierung der Props.

const {
  attributes: { size },
  setAttributes,
  name,
} = props;

Dies geschieht, damit wir name, setAttributes und size im Gültigkeitsbereich des Filters verwenden können, wobei

• size das Attribut des Blocks ist, das wir in Schritt 1 hinzugefügt haben.
• setAttributes eine Funktion ist, mit der wir die Attributwerte des Blocks aktualisieren können.
• name ist der Name des Blocks, der in unserem Fall core/button ist.

Als Nächstes vermeiden wir, versehentlich Steuerelemente zu anderen Blöcken hinzuzufügen.

if (name !== 'core/button') {
  return <BlockEdit {...props} />;
}

Und wenn wir es mit einem Button-Block zu tun *haben*, umschließen wir das Einstellungsfenster mit einem <Fragment /> (einer Komponente, die ihre Kinder ohne umschließendes Element rendert) und fügen eine zusätzliche Steuerung für die Auswahl der Button-Größe hinzu.

return (
  <Fragment>
    <BlockEdit {...props} />
    {/* Additional controls go here */}
  </Fragment>
);

Schließlich werden zusätzliche Steuerelemente wie folgt erstellt:

<InspectorControls>
  <PanelBody title={__('Size settings', 'intro-to-filters')} initialOpen={false}>
    <SelectControl
      label={__('Size', 'intro-to-filters')}
      value={size}
      options={[
        { label: __('Regular', 'intro-to-filters'), value: 'regular' },
        { label: __('Small', 'intro-to-filters'), value: 'small' },
        { label: __('Large', 'intro-to-filters'), value: 'large' },
      ]}
      onChange={(value) => {
        setAttributes({ size: value });
      }}
    />
  </PanelBody>
</InspectorControls>

Auch hier gilt: Wenn du schon einmal Blöcke erstellt hast, kennst du diesen Teil vielleicht schon. Wenn nicht, ermutige ich dich, die Bibliothek der Komponenten, mit der WordPress geliefert wird, zu studieren.

Zu diesem Zeitpunkt sollten wir einen zusätzlichen Abschnitt in den Inspektor-Steuerelementen für jeden Button-Block sehen.

Wir können die Größe auch speichern, aber das wird sich weder im Editor noch im Frontend widerspiegeln. Lass uns das beheben.

3. Hinzufügen einer Größenklasse zum Block im Editor

Wie der Titel schon sagt, ist der Plan für diesen Schritt, dem Button-Block eine CSS-Klasse hinzuzufügen, damit die ausgewählte Größe sich im Editor selbst widerspiegelt.

Wir verwenden den Filter editor.BlockListBlock. Er ist ähnlich wie editor.BlockEdit in dem Sinne, dass er die Komponente empfängt und die Komponente zurückgeben muss; aber anstatt das Block-Inspektor-Panel zu filtern, filtert er die Block-Komponente, die im Editor angezeigt wird.

import classnames from 'classnames';
const { addFilter } = wp.hooks;
const { createHigherOrderComponent } = wp.compose;

/**
 * Add size class to the block in the editor
 */
const addSizeClass = createHigherOrderComponent((BlockListBlock) => {
  return (props) => {
    const {
      attributes: { size },
      className,
      name,
    } = props;

    if (name !== 'core/button') {
      return <BlockListBlock {...props} />;
    }

    return (
      <BlockListBlock
        {...props}
        className={classnames(className, size ? `has-size-${size}` : '')}
      />
    );
  };
}, 'withClientIdClassName');

addFilter(
   'editor.BlockListBlock',
   'intro-to-filters/button-block/add-editor-class',
   addSizeClass
);

Du hast vielleicht schon eine ähnliche Struktur bemerkt.

1. Wir extrahieren die Variablen size, className und name aus props.
2. Als Nächstes prüfen wir, ob wir es mit dem Block core/button zu tun haben, und geben andernfalls einen unveränderten <BlockListBlock> zurück.
3. Dann fügen wir dem Block basierend auf der ausgewählten Button-Größe eine Klasse hinzu.

Ich möchte hier innehalten, da es auf den ersten Blick verwirrend aussehen könnte.

className={classnames(className, size ? `has-size-${size}` : '')}

Ich verwende hier das Dienstprogramm classnames, und es ist keine Pflicht – ich finde es einfach etwas übersichtlicher als manuelle Verkettungen. Es erspart mir die Sorge, ein Leerzeichen vor einer Klasse zu vergessen oder mich mit doppelten Leerzeichen herumzuschlagen.

4. Hinzufügen der Größenklasse zum Block im Frontend

Alles, was wir bisher getan haben, bezieht sich auf die Ansicht des Block-Editors, die eine Art Vorschau dessen ist, was wir im Frontend erwarten können. Wenn wir die Button-Größe ändern, den Beitrag speichern und das Button-Markup im Frontend überprüfen, beachte, dass die Button-Klasse nicht auf den Block angewendet wird.

Um dies zu beheben, müssen wir sicherstellen, dass wir die Änderungen tatsächlich speichern und die Klasse im Frontend zum Block hinzufügen. Das machen wir mit dem Filter blocks.getSaveContent.extraProps, der sich in die save()-Funktion des Blocks einklinkt und uns erlaubt, die gespeicherten Eigenschaften zu ändern. Dieser Filter empfängt Block-Props, den Typ des Blocks und Block-Attribute und muss modifizierte Block-Props zurückgeben.

import classnames from 'classnames';
const { assign } = lodash;
const { addFilter } = wp.hooks;

/**
 * Add size class to the block on the front end
 *
 * @param  {Object} props      Additional props applied to save element.
 * @param  {Object} block      Block type.
 * @param  {Object} attributes Current block attributes.
 * @return {Object}            Filtered props applied to save element.
 */
function addSizeClassFrontEnd(props, block, attributes) {
  if (block.name !== 'core/button') {
    return props;
  }

  const { className } = props;
  const { size } = attributes;

  return assign({}, props, {
    className: classnames(className, size ? `has-size-${size}` : ''),
  });
}

addFilter(
  'blocks.getSaveContent.extraProps',
  'intro-to-filters/button-block/add-front-end-class',
  addSizeClassFrontEnd,
);

Im obigen Snippet tun wir drei Dinge:

1. Prüfen, ob wir es mit einem core/button-Block zu tun haben und schnell zurückgeben, wenn nicht.
2. Extrahieren der Variablen className und size aus den Objekten props bzw. attributes.
3. Erstellen eines neuen props-Objekts mit einer aktualisierten className-Eigenschaft, die bei Bedarf eine Größenklasse enthält.

Hier ist, was wir im Markup erwarten sollten, komplett mit unserer Größenklasse.

<div class="wp-block-button has-size-large">
  <a class="wp-block-button__link" href="#">Click Me</a>
</div>

5. Hinzufügen von CSS für die benutzerdefinierten Button-Größen

Noch eine kleine Sache, bevor wir fertig sind! Die Idee ist sicherzustellen, dass große und kleine Buttons entsprechende CSS-Stile haben.

Hier sind die Stile, die ich mir ausgedacht habe.

.wp-block-button.has-size-large .wp-block-button__link {
  padding: 1.5rem 3rem;
}
.wp-block-button.has-size-small .wp-block-button__link {
  padding: 0.25rem 1rem;
}

Wenn du ein benutzerdefiniertes Theme erstellst, kannst du diese Frontend-Stile in die Stylesheet des Themes einfügen. Ich habe ein Plugin für das Standard-Theme Twenty Twenty One erstellt, also musste ich in meinem Fall eine separate Stylesheet erstellen und sie mit wp_enqueue_style() einbinden. Du könntest genauso gut direkt in functions.php arbeiten, wenn du dort Funktionen verwaltest.

function frontend_assets() {
  wp_enqueue_style(
    'intro-to-block-filters-frontend-style',
    plugin_dir_url( __FILE__ ) . 'assets/frontend.css',
    [],
    '0.1.0'
  );
}
add_action( 'wp_enqueue_scripts', 'frontend_assets' );

Ähnlich wie im Frontend müssen wir sicherstellen, dass Buttons im Editor korrekt gestylt sind. Wir können die gleichen Stile über die Aktion enqueue_block_editor_assets einbinden.

function editor_assets() {
  wp_enqueue_style(
    'intro-to-block-filters-editor-style',
    plugin_dir_url( __FILE__ ) . 'assets/editor.css',
    [],
    '0.1.0'
  );
}
add_action( 'enqueue_block_editor_assets', 'editor_assets' );

Wir sollten nun Stile für große und kleine Buttons im Frontend und im Editor haben!

Wie ich bereits erwähnt habe, sind diese Beispiele in einem WordPress-Plugin verfügbar, das ich extra für diesen Artikel erstellt habe. Wenn du also sehen möchtest, wie all diese Teile zusammenarbeiten, lade es von GitHub herunter und experimentiere damit. Und wenn etwas unklar ist, frag gerne in den Kommentaren.

Filter verwenden oder einen neuen Block erstellen?

Das ist eine knifflige Frage, die man ohne Kontext nicht beantworten kann. Aber einen Tipp kann ich dir geben.

Hast du jemals eine solche Fehlermeldung gesehen?

Sie tritt normalerweise auf, wenn das Markup des Blocks auf der Seite vom Markup, das von der save()-Funktion des Blocks generiert wird, abweicht. Was ich damit meine, ist, dass es sehr einfach ist, diesen Fehler auszulösen, wenn man mit dem Markup eines Blocks per Filter spielt.

Wenn du also das Markup eines Blocks erheblich ändern musst, das über das Hinzufügen einer Klasse hinausgeht, würde ich in Erwägung ziehen, einen benutzerdefinierten Block zu schreiben, anstatt einen bestehenden zu filtern. Das heißt, es sei denn, du bist damit einverstanden, das Markup für den Editor konsistent zu halten und nur das Frontend-Markup zu ändern. In diesem Fall kannst du einen PHP-Filter verwenden.

Wo wir gerade dabei sind…

Bonus-Tipp: render_block()

Dieser Artikel wäre nicht vollständig ohne die Erwähnung des Hooks render_block. Er filtert das Block-Markup, *bevor* es gerendert wird. Er ist nützlich, wenn du das Markup eines Blocks über das Hinzufügen einer neuen Klasse hinaus ändern musst.

Der große Vorteil dieses Ansatzes ist, dass er keine Validierungsfehler im Editor verursacht. Allerdings funktioniert er nur im Frontend. Wenn ich das Beispiel für die Button-Größe mit diesem Ansatz neu schreiben würde, müsste ich zuerst den Code entfernen, den wir im vierten Schritt geschrieben haben, und dies hinzufügen.

/**
 * Add button size class.
 *
 * @param  string $block_content Block content to be rendered.
 * @param  array  $block         Block attributes.
 * @return string
 */
function add_button_size_class( $block_content = '', $block = [] ) {
  if ( isset( $block['blockName'] ) && 'core/button' === $block['blockName'] ) {
    $defaults = ['size' => 'regular'];
    $args = wp_parse_args( $block['attrs'], $defaults );

    $html = str_replace(
      '<div class="wp-block-button',
      '<div class="wp-block-button has-size-' . esc_attr( $args['size']) . ' ',
      $block_content
    );

    return $html;
}
  return $block_content;
}

add_filter( 'render_block', 'add_button_size_class', 10, 2 );

Das ist nicht der sauberste Ansatz, da wir eine CSS-Klasse mit str_replace() einfügen – aber das ist manchmal die einzige Option. Ein klassisches Beispiel wäre die Arbeit mit einem Block eines Drittanbieters, bei dem wir ein <div> mit einer Klasse darum herum für das Styling hinzufügen müssen.

Zusammenfassung

WordPress Block-Filter sind mächtig. Ich mag es, wie sie es dir erlauben, viele ungenutzte Blockoptionen zu deaktivieren, wie wir es im ersten Beispiel mit dem Cover-Block getan haben. Dies kann die Menge an CSS, die du schreiben musst, reduzieren, was wiederum eine schlankere Stylesheet und weniger Wartung bedeutet – und weniger kognitiven Aufwand für jeden, der die Blockeinstellungen verwendet.

Aber wie ich bereits erwähnt habe, kann die Verwendung von Block-Filtern für umfangreiche Modifikationen schwierig werden, da du die Blockvalidierung berücksichtigen musst.

Daher greife ich normalerweise zu Block-Filtern, wenn ich muss:

• bestimmte Blockfunktionen deaktivieren,
• eine Option zu einem Block hinzufügen und dies nicht mit benutzerdefiniertem Stil tun kann/möchte (und diese Option darf das Markup des Blocks nicht ändern, außer durch Hinzufügen/Entfernen einer benutzerdefinierten Klasse), oder
• das Markup nur im Frontend ändern (mithilfe eines PHP-Filters).

Ich schreibe normalerweise auch benutzerdefinierte Blöcke, wenn Kernblöcke umfangreiche Markup-Anpassungen sowohl im Frontend als auch im Editor erfordern.

Wenn du mit Block-Filtern gearbeitet hast und andere Gedanken, Fragen oder Kommentare hast, lass es mich wissen!

Ressourcen

• Block Filter Referenz
• Block Editor Handbuch
• Demo Plugin auf GitHub