Erste Schritte mit der WordPress-Blockentwicklung

Lassen Sie uns anerkennen, dass die Entwicklung für WordPress im Moment seltsam ist. Egal, ob Sie neu bei WordPress sind oder schon seit Ewigkeiten damit arbeiten, die Einführung von Funktionen für „Full-Site Editing“ (FSE) wie den Block-Editor (WordPress 5.0) und den Site-Editor (WordPress 5.9) hat die traditionelle Art und Weise, wie wir WordPress-Themes und -Plugins erstellen, auf den Kopf gestellt.

Obwohl es fünf Jahre her ist, seit wir den Block-Editor zum ersten Mal kennengelernt haben, ist die Entwicklung dafür schwierig, da die Dokumentation entweder fehlt oder veraltet ist. Das ist eher eine Aussage darüber, wie schnell sich die FSE-Funktionen entwickeln, etwas, das Geoff in einem aktuellen Beitrag bedauerte.

Ein Beispiel: Im Jahr 2018 wurde hier auf CSS-Tricks eine Einführungsserie zur Gutenberg-Entwicklung veröffentlicht. Die Zeiten haben sich seitdem geändert, und obwohl diese Art der Entwicklung immer noch funktioniert, wird sie nicht mehr empfohlen (außerdem wird das Projekt create-guten-block, auf dem sie basiert, nicht mehr gepflegt).

In diesem Artikel möchte ich Ihnen helfen, mit der WordPress-Blockentwicklung auf eine Weise zu beginnen, die der aktuellen Methodik folgt. Ja, die Dinge könnten sich nach der Veröffentlichung sehr gut ändern. Aber ich werde versuchen, mich auf eine Weise darauf zu konzentrieren, die hoffentlich die Essenz der Blockentwicklung erfasst, denn auch wenn sich die Werkzeuge im Laufe der Zeit weiterentwickeln mögen, werden die Kernideen wahrscheinlich gleich bleiben.

Was genau sind WordPress-Blöcke?

Beginnen wir damit, einige Verwirrung bezüglich der Begriffe wie Blöcke zu beseitigen. Die gesamte Entwicklung, die zu WordPress 5.0 führte, trug den Codenamen „Gutenberg“ – Sie wissen schon, der Erfinder des Buchdrucks.

Seitdem wird „Gutenberg“ verwendet, um alles zu beschreiben, was mit Blöcken zu tun hat, einschließlich des Block-Editors und des Site-Editors, so dass es so kompliziert geworden ist, dass einige Leute den Namen verabscheuen. Hinzu kommt, dass es ein Gutenberg-Plugin gibt, in dem experimentelle Funktionen auf mögliche Aufnahme getestet werden. Und wenn Sie denken, dass die Benennung all dessen „Full-Site Editing“ das Problem lösen würde, gibt es auch damit Bedenken.

Wenn wir in diesem Artikel von „Blöcken“ sprechen, meinen wir Komponenten zur Erstellung von Inhalten im WordPress Block-Editor. Blöcke werden in eine Seite oder einen Beitrag eingefügt und bilden die Struktur für einen bestimmten Inhaltstyp. WordPress wird mit einer Handvoll „Core“-Blöcken für gängige Inhaltstypen wie Absatz, Liste, Bild, Video und Audio geliefert, um nur einige zu nennen.

Neben diesen Core-Blöcken können wir auch benutzerdefinierte Blöcke erstellen. Das ist es, worum es bei der WordPress-Blockentwicklung geht (es gibt auch das Filtern von Core-Blöcken zur Änderung ihrer Funktionalität, aber das werden Sie wahrscheinlich noch nicht benötigen).

Was Blöcke tun

Bevor wir mit der Erstellung von Blöcken beginnen, müssen wir uns zunächst ein Bild davon machen, wie Blöcke intern funktionieren. Das wird uns später viel Frustration ersparen.

Ich betrachte einen Block eher abstrakt: Für mich ist ein Block eine Entität mit einigen Eigenschaften (Attributen), die einen Inhalt darstellt. Ich weiß, das klingt ziemlich vage, aber bleiben Sie dran. Ein Block manifestiert sich im Grunde auf zwei Arten: als grafische Oberfläche im Block-Editor oder als Datenblock in der Datenbank.

Wenn Sie den WordPress Block-Editor öffnen und einen Block einfügen, z. B. einen Pullquote-Block, erhalten Sie eine ansprechende Oberfläche. Sie können in diese Oberfläche klicken und den zitierten Text bearbeiten. Das Einstellungsfenster auf der rechten Seite der Block-Editor-Benutzeroberfläche bietet Optionen zur Anpassung des Textes und des Erscheinungsbilds des Blocks.

Wenn Sie mit der Erstellung Ihres schicken Pullquotes fertig sind und auf Veröffentlichen klicken, wird der gesamte Beitrag in der Datenbank in der Tabelle wp_posts gespeichert. Das ist nichts Neues wegen Gutenberg. So hat es immer funktioniert – WordPress speichert den Beitragsinhalt in einer bestimmten Tabelle in der Datenbank. Neu ist jedoch, dass eine Darstellung des Pullquote-Blocks Teil des Inhalts ist, der im Feld post_content der Tabelle wp_posts gespeichert wird.

Wie sieht diese Darstellung aus? Schauen Sie sich das an

<!-- wp:pullquote {"textAlign":"right"} -->
<figure class="wp-block-pullquote has-text-align-right">
  <blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>
</figure>
<!-- /wp:pullquote -->

Sieht aus wie einfacher HTML, richtig?! Dies ist im Fachjargon der „serialisierte“ Block. Beachten Sie die JSON-Daten im HTML-Kommentar, „textAlign“: „right“. Das ist ein Attribut – eine Eigenschaft, die dem Block zugeordnet ist.

Nehmen wir an, Sie schließen den Block-Editor und öffnen ihn später wieder. Der Inhalt aus dem entsprechenden Feld post_content wird vom Block-Editor abgerufen. Der Editor analysiert dann den abgerufenen Inhalt, und wo immer er dies antrifft

<!-- wp:pullquote {"textAlign":"right"} -->...<!-- /wp:pullquote -->

…sagt er sich laut

OK, das scheint mir ein Pullquote-Block zu sein. Hmm.. er hat auch ein Attribut… Ich habe eine JavaScript-Datei, die mir sagt, wie ich die grafische Oberfläche für einen Pullquote-Block anhand seiner Attribute im Editor erstellen kann. Das sollte ich jetzt tun, um diesen Block in seiner ganzen Pracht darzustellen.

Als Blockentwickler ist Ihre Aufgabe,

1. WordPress mitzuteilen, dass Sie einen bestimmten Blocktyp mit bestimmten Details registrieren möchten.
2. Dem Block-Editor die JavaScript-Datei zur Verfügung zu stellen, die ihm hilft, den Block im Editor darzustellen und ihn gleichzeitig für die Speicherung in der Datenbank zu „serialisieren“.
3. Alle zusätzlichen Ressourcen bereitzustellen, die der Block für seine ordnungsgemäße Funktionalität benötigt, z. B. Stile und Schriftarten.

Eines ist wichtig: Die gesamte Konvertierung von serialisierten Daten in eine grafische Oberfläche – und umgekehrt – findet nur im Block-Editor statt. Im Frontend wird der Inhalt genau so angezeigt, wie er gespeichert ist. Daher sind Blöcke in gewissem Sinne eine ausgefallene Methode, Daten in die Datenbank einzugeben.

Hoffentlich haben Sie dadurch etwas Klarheit darüber gewonnen, wie ein Block funktioniert.

Blöcke sind nur Plugins

Blöcke sind nur Plugins. Nun, technisch gesehen können Sie Blöcke in Themes platzieren und können mehrere Blöcke in einem Plugin platzieren. Aber meistens, wenn Sie einen Block erstellen möchten, werden Sie ein Plugin erstellen. Wenn Sie also jemals ein WordPress-Plugin erstellt haben, sind Sie bereits auf dem besten Weg, einen WordPress-Block zu erstellen.

Aber nehmen wir für einen Moment an, Sie haben noch nie ein WordPress-Plugin eingerichtet, geschweige denn einen Block. Wo fangen Sie überhaupt an?

Einrichtung eines Blocks

Wir haben behandelt, was Blöcke sind. Beginnen wir mit der Einrichtung, um einen zu erstellen.

Stellen Sie sicher, dass Sie Node installiert haben

Dies gibt Ihnen Zugriff auf die Befehle npm und npx. npm installiert die Abhängigkeiten Ihres Blocks und hilft beim Kompilieren, während npx Befehle für Pakete ausführt, ohne sie zu installieren. Wenn Sie macOS verwenden, haben Sie wahrscheinlich bereits Node und können nvm zur Aktualisierung von Versionen verwenden. Wenn Sie Windows verwenden, müssen Sie Node herunterladen und installieren.

Erstellen Sie einen Projektordner

Möglicherweise stoßen Sie auf andere Tutorials, die direkt in der Befehlszeile beginnen und Sie auffordern, ein Paket namens @wordpress/create-block zu installieren. Dieses Paket ist großartig, da es einen vollständig eingerichteten Projektordner mit allen Abhängigkeiten und Werkzeugen ausgibt, die Sie zum Entwickeln benötigen.

Ich persönlich gehe diesen Weg, wenn ich meine eigenen Blöcke einrichte, aber nehmen Sie es mir nicht übel, denn ich möchte die Meinungsfragen durchbrechen, die es einführt, und uns auf die erforderlichen Bits konzentrieren, um die grundlegende Entwicklungsumgebung zu verstehen.

Das sind die Dateien, auf die ich speziell hinweisen möchte

• readme.txt: Dies ist quasi die Vorderseite des Plugin-Verzeichnisses und wird typischerweise verwendet, um das Plugin zu beschreiben und zusätzliche Details zur Nutzung und Installation bereitzustellen. Wenn Sie Ihren Block im WordPress Plugin-Verzeichnis einreichen, hilft diese Datei beim Befüllen der Plugin-Seite. Wenn Sie vorhaben, ein GitHub-Repository für Ihr Block-Plugin zu erstellen, sollten Sie möglicherweise auch eine README.md-Datei mit denselben Informationen in Betracht ziehen, damit sie dort schön angezeigt wird.
• package.json: Diese Datei definiert die Node-Pakete, die für die Entwicklung benötigt werden. Wir werden sie öffnen, wenn wir zur Installation kommen. In der klassischen WordPress-Plugin-Entwicklung sind Sie möglicherweise daran gewöhnt, mit Composer und einer composer.json-Datei zu arbeiten. Dies ist das Äquivalent dazu.
• plugin.php: Dies ist die Haupt-Plugin-Datei und ja, es ist klassisches PHP! Wir werden unseren Plugin-Header und Metadaten hier einfügen und es verwenden, um das Plugin zu registrieren.

Zusätzlich zu diesen Dateien gibt es noch das Verzeichnis src, das den Quellcode unseres Blocks enthalten soll.

Diese Dateien und das Verzeichnis src sind alles, was Sie zum Starten benötigen. Von dieser Gruppe beachte ich, dass wir **technisch nur eine Datei** (plugin.php) benötigen, um das Plugin zu erstellen. Der Rest liefert entweder Informationen oder wird zur Verwaltung der Entwicklungsumgebung verwendet.

Das oben genannte Paket @wordpress/create-block generiert diese Dateien (und mehr) für uns. Sie können es als Automatisierungswerkzeug betrachten, nicht als Notwendigkeit. Unabhängig davon erleichtert es die Arbeit, sodass Sie es ruhig nutzen können, um einen Block zu generieren, indem Sie Folgendes ausführen

npx @wordpress/create-block

Blockabhängigkeiten installieren

Angenommen, Sie haben die drei im vorherigen Abschnitt erwähnten Dateien vorbereitet, ist es Zeit, die Abhängigkeiten zu installieren. Zuerst müssen wir die benötigten Abhängigkeiten angeben. Das tun wir, indem wir die package.json bearbeiten. Bei Verwendung des @wordpress/create-block-Dienstprogramms wird Folgendes für uns generiert (Kommentare hinzugefügt; JSON unterstützt keine Kommentare, also entfernen Sie die Kommentare, wenn Sie den Code kopieren)

{
  // Defines the name of the project
  "name": "block-example",
  // Sets the project version number using semantic versioning
  "version": "0.1.0",
  // A brief description of the project
  "description": "Example block scaffolded with Create Block tool.",
  // You could replace this with yourself
  "author": "The WordPress Contributors",
  // Standard licensing information
  "license": "GPL-2.0-or-later",
  // Defines the main JavaScript file
  "main": "build/index.js",
  // Everything we need for building and compiling the plugin during development
  "scripts": {
    "build": "wp-scripts build",
    "format": "wp-scripts format",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "packages-update": "wp-scripts packages-update",
    "plugin-zip": "wp-scripts plugin-zip",
    "start": "wp-scripts start"
  },
  // Defines which version of the scripts packages are used (24.1.0 at time of writing)
  // https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/
  "devDependencies": {
    "@wordpress/scripts": "^24.1.0"
  }
}

{
  "name": "block-example",
  "version": "0.1.0",
  "description": "Example block scaffolded with Create Block tool.",
  "author": "The WordPress Contributors",
  "license": "GPL-2.0-or-later",
  "main": "build/index.js",
  "scripts": {
    "build": "wp-scripts build",
    "format": "wp-scripts format",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "packages-update": "wp-scripts packages-update",
    "plugin-zip": "wp-scripts plugin-zip",
    "start": "wp-scripts start"
  },
  "devDependencies": {
    "@wordpress/scripts": "^24.1.0"
  }
}

Das Paket @wordpress/scripts ist hier die Hauptabhängigkeit. Wie Sie sehen können, ist es eine devDependency, was bedeutet, dass es bei der Entwicklung hilft. Wie? Es stellt das wp-scripts-Binary bereit, das wir zum Kompilieren unseres Codes aus dem src-Verzeichnis in das build-Verzeichnis verwenden können, unter anderem.

Es gibt eine Reihe weiterer Pakete, die WordPress für verschiedene Zwecke verwaltet. Zum Beispiel bietet das Paket @wordpress/components mehrere vorgefertigte UI-Komponenten für den WordPress Block-Editor, die zur Schaffung konsistenter Benutzererlebnisse für Ihren Block verwendet werden können, die mit den WordPress-Designstandards übereinstimmen.

Sie müssen diese Pakete nicht tatsächlich installieren, auch wenn Sie sie verwenden möchten. Das liegt daran, dass diese @wordpress-Abhängigkeiten nicht mit Ihrem Blockcode gebündelt werden. Stattdessen werden alle import-Anweisungen, die auf Code aus Utility-Paketen – wie @wordpress/components – verweisen, verwendet, um während der Kompilierung eine „Assets“-Datei zu erstellen. Darüber hinaus werden diese Import-Anweisungen in Anweisungen umgewandelt, die die Imports den Eigenschaften eines globalen Objekts zuordnen. Zum Beispiel wird import { __ } from „@wordpress/i18n“ in eine minimierte Version von const __ = window.wp.i18n.__ umgewandelt. (window.wp.i18n ist ein Objekt, das garantiert im globalen Geltungsbereich verfügbar ist, sobald die entsprechende i18n-Paketdatei geladen wird).

Bei der Blockregistrierung in der Plugin-Datei wird die „Assets“-Datei implizit verwendet, um WordPress die Paketabhängigkeiten für den Block mitzuteilen. Diese Abhängigkeiten werden automatisch geladen. All dies wird im Hintergrund erledigt, vorausgesetzt, Sie verwenden das scripts-Paket. Nichtsdestotrotz können Sie sich dafür entscheiden, Abhängigkeiten lokal zu installieren, um Codevollständigkeit und Parameterinformationen in Ihrer package.json-Datei zu erhalten.

// etc.
"devDependencies": {
  "@wordpress/scripts": "^24.1.0"
},
"dependencies": {
  "@wordpress/components": "^19.17.0"
}

Nachdem package.json eingerichtet ist, sollten wir in der Lage sein, all diese Abhängigkeiten zu installieren, indem wir zum Projektordner in der Befehlszeile navigieren und npm install ausführen.

Fügen Sie den Plugin-Header hinzu

Wenn Sie von der klassischen WordPress-Plugin-Entwicklung kommen, wissen Sie wahrscheinlich, dass alle Plugins einen Informationsblock in der Haupt-Plugin-Datei haben, der WordPress hilft, das Plugin zu erkennen und Informationen darüber auf der Plugins-Seite des WordPress-Admin anzuzeigen.

Hier ist, was @wordpress/create-block für ein kreativ „Hello World“ genanntes Plugin für mich generiert hat

<?php
/**
 * Plugin Name:       Block Example
 * Description:       Example block scaffolded with Create Block tool.
 * Requires at least: 5.9
 * Requires PHP:      7.0
 * Version:           0.1.0
 * Author:            The WordPress Contributors
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       css-tricks
 *
 * @package           create-block
 */

Das befindet sich in der Haupt-Plugin-Datei, die Sie nennen können, wie Sie möchten. Sie könnten sie etwas Generisches wie index.php oder plugin.php nennen. Das create-block-Paket nennt sie automatisch, wie auch immer Sie den Projektnamen bei der Installation angeben. Da ich dieses Beispiel „Block Example“ nannte, gab uns das Paket eine block-example.php-Datei mit all diesen Informationen.

Sie werden einige Details ändern wollen, wie z. B. sich selbst als Autor einzutragen und Ähnliches. Und nicht alles davon ist notwendig. Wenn ich das von Grund auf neu machen würde, würde es vielleicht eher so aussehen

<?php
/**
 * Plugin Name:       Block Example
 * Plugin URI:        https://css-tricks.de
 * Description:       An example plugin for learning WordPress block development.
 * Version:           1.0.0
 * Author:            Arjun Singh
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       css-tricks
 */

Ich werde nicht auf den genauen Zweck jeder Zeile eingehen, da dies bereits ein gut etabliertes Muster im WordPress Plugin Handbook ist.

Die Dateistruktur

Wir haben uns bereits die erforderlichen Dateien für unseren Block angesehen. Aber wenn Sie @wordpress/create-block verwenden, sehen Sie viele weitere Dateien im Projektordner.

Das ist im Moment darin enthalten

block-example/
├── build
├── node_modules
├── src/
│   ├── block.json
│   ├── edit.js
│   ├── editor.scss
│   ├── index.js
│   ├── save.js
│   └── style.scss
├── .editorconfig
├── .gitignore
├── block-example.php
├── package-lock.json
├── package.json
└── readme.txt

Puh, das ist viel! Nennen wir die neuen Sachen

• build/: Dieser Ordner enthält die kompilierten Assets nach der Verarbeitung der Dateien für die Produktionsnutzung.
• node_modules: Hier werden alle Entwicklung Abhängigkeiten gespeichert, die wir bei der Ausführung von npm install installiert haben.
• src/: Dieser Ordner enthält den Quellcode des Plugins, der kompiliert und in das build-Verzeichnis übertragen wird. Wir werden uns die einzelnen Dateien darin gleich ansehen.
• .editorconfig: Enthält Konfigurationen zur Anpassung Ihres Code-Editors für Konsistenz.
• .gitignore: Dies ist eine Standard-Repo-Datei, die lokale Dateien identifiziert, die von der Versionskontrolle ausgeschlossen werden sollen. Ihre node_modules sollten definitiv hier enthalten sein.
• package-lock.json: Dies ist eine automatisch generierte Datei, die zur Nachverfolgung von Updates der mit npm install installierten Pakete dient.

Block-Metadaten

Ich möchte mit Ihnen in das Verzeichnis src eintauchen, konzentriere mich aber zunächst auf nur eine Datei darin: block.json. Wenn Sie create-block verwendet haben, ist es bereits vorhanden; wenn nicht, erstellen Sie es. WordPress setzt stark darauf, dies zum Standard, kanonischen Weg zur Registrierung eines Blocks zu machen, indem Metadaten bereitgestellt werden, die WordPress Kontext geben, um den Block zu erkennen und ihn im Block-Editor darzustellen.

Hier ist, was @wordpress/create-block für mich generiert hat

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 2,
  "name": "create-block/block example",
  "version": "0.1.0",
  "title": "Block Example",
  "category": "widgets",
  "icon": "smiley",
  "description": "Example block scaffolded with Create Block tool.",
  "supports": {
    "html": false
  },
  "textdomain": "css-tricks",
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style-index.css"
}

Es gibt tatsächlich eine Vielzahl von Informationen, die wir hier aufnehmen können, aber tatsächlich erforderlich sind nur name und title. Eine super minimale Version könnte so aussehen

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 2,
  "name": "css-tricks/block-example",
  "version": "1.0.0",
  "title": "Block Example",
  "category": "text",
  "icon": "format-quote",
  "editorScript": "file:./index.js",
}

• $schema definiert das Schemaformat, das zur Validierung des Inhalts in der Datei verwendet wird. Es klingt wie eine erforderliche Sache, aber es ist völlig optional, da es unterstützenden Code-Editoren ermöglicht, die Syntax zu validieren und andere zusätzliche Vorteile wie Tooltip-Hinweise und Auto-Vervollständigung zu bieten.
• apiVersion bezieht sich auf die Version der Block-API, die das Plugin verwendet. Heute ist Version 2 die neueste.
• name ist eine erforderliche eindeutige Zeichenfolge, die zur Identifizierung des Plugins dient. Beachten Sie, dass ich diese mit css-tricks/ vorangestellt habe, was ich als Namespace verwende, um Konflikte mit anderen Plugins mit demselben Namen zu vermeiden. Sie könnten stattdessen etwas wie Ihre Initialen verwenden (z. B. as/block-example).
• version ist etwas, das WordPress als Cache-Busting-Mechanismus vorschlägt, wenn neue Versionen veröffentlicht werden.
• title ist das andere erforderliche Feld und legt den Namen fest, der überall dort verwendet wird, wo das Plugin angezeigt wird.
• category gruppiert den Block mit anderen Blöcken und zeigt sie im Block-Editor zusammen an. Aktuell existierende Kategorien sind text, media, design, widgets, theme und embed, und Sie können sogar benutzerdefinierte Kategorien erstellen.
• icon ermöglicht es Ihnen, etwas aus der Dashicons-Bibliothek auszuwählen, um Ihren Block im Block-Editor visuell darzustellen. Ich verwende das Icon format-quote, da wir in diesem Beispiel so etwas wie einen eigenen Pullquote erstellen. Es ist schön, dass wir vorhandene Icons nutzen können, anstatt eigene erstellen zu müssen, obwohl das durchaus möglich ist.
• editorScript ist der Ort, an dem die Haupt-JavaScript-Datei, index.js, liegt.

Registrieren Sie den Block

Ein letzter Punkt, bevor wir zum eigentlichen Code kommen, ist die Registrierung des Plugins. Wir haben all diese Metadaten eingerichtet und brauchen eine Möglichkeit für WordPress, sie zu verarbeiten. So weiß WordPress, wo es alle Plugin-Assets finden kann, damit sie zur Verwendung im Block-Editor geladen werden können.

Die Registrierung des Blocks ist ein zweistufiger Prozess. Wir müssen ihn sowohl in PHP als auch in JavaScript registrieren. Für die PHP-Seite öffnen Sie die Haupt-Plugin-Datei (in diesem Fall block-example.php) und fügen Sie Folgendes direkt nach dem Plugin-Header hinzu

function create_block_block_example_block_init() {
  register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'create_block_block_example_block_init' );

Das ist, was das create-block-Dienstprogramm für mich generiert hat, daher ist die Funktion so benannt. Wir können einen anderen Namen verwenden. Entscheidend ist wieder, Konflikte mit anderen Plugins zu vermeiden, daher ist es eine gute Idee, Ihren Namespace hier zu verwenden, um ihn so einzigartig wie möglich zu machen.

function css_tricks_block_example_block_init() {
  register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'css_tricks_block_example_block_init' );

Warum zeigen wir auf das build-Verzeichnis, wenn sich die block.json mit allen Block-Metadaten in src befindet? Das liegt daran, dass unser Code immer noch kompiliert werden muss. Das scripts-Paket verarbeitet den Code aus den Dateien im src-Verzeichnis und platziert die kompilierten Dateien, die für die Produktion verwendet werden, im build-Verzeichnis, während es gleichzeitig die block.json-Datei kopiert.

Nun, wechseln wir zur JavaScript-Seite der Blockregistrierung. Öffnen Sie src/index.js und stellen Sie sicher, dass es so aussieht

import { registerBlockType } from "@wordpress/blocks";

import metadata from "./block.json";
import Edit from "./edit.js";
import Save from "./save.js";

const { name } = metadata;

registerBlockType(name, {
  edit: Edit,
  save: Save,
});

Wir betreten die Welt von React und JSX! Das sagt WordPress,

• Importieren Sie das Modul registerBlockType aus dem Paket @wordpress/blocks.
• Importieren Sie Metadaten aus block.json.
• Importieren Sie die Komponenten Edit und Save aus ihren entsprechenden Dateien. Wir werden später Code in diese Dateien einfügen.
• Registrieren Sie den Block und verwenden Sie die Komponenten Edit und Save, um den Block darzustellen und seinen Inhalt in der Datenbank zu speichern.

Was hat es mit den Funktionen edit und save auf sich? Eine der Nuancen der WordPress-Blockentwicklung ist die Unterscheidung zwischen „Backend“ und „Frontend“, und diese Funktionen werden verwendet, um den Inhalt des Blocks in diesen Kontexten darzustellen, wobei edit das Backend-Rendering behandelt und save den Inhalt aus dem Block-Editor in die Datenbank schreibt, um den Inhalt auf dem Frontend der Website darzustellen.

Ein schneller Test

Wir können ein paar schnelle Arbeiten erlednen, um unseren Block im Block-Editor und auf dem Frontend dargestellt zu sehen. Öffnen wir erneut index.js und verwenden Sie die Funktionen edit und save, um einfachen Inhalt zurückzugeben, der veranschaulicht, wie sie funktionieren

import { registerBlockType } from "@wordpress/blocks";
import metadata from "./block.json";

const { name } = metadata;

registerBlockType(name, {
  edit: () => {
    return (
      "Hello from the Block Editor"
    );
  },
  save: () => {
    return (
      "Hello from the front end"
    );
  }
});

Dies ist im Grunde eine abgespeckte Version des gleichen Codes, den wir zuvor hatten. Wir verweisen nur direkt auf die Metadaten in block.json, um den Blocknamen abzurufen, und haben die Komponenten Edit und Save weggelassen, da wir die Funktionen direkt von hier aus ausführen.

Wir können dies kompilieren, indem wir npm run build in der Befehlszeile ausführen. Danach haben wir im Block-Editor Zugriff auf einen Block namens „Block Example“

Wenn wir den Block in den Inhaltsbereich einfügen, erhalten wir die Nachricht, die wir aus der Funktion edit zurückgeben

Wenn wir den Beitrag speichern und veröffentlichen, sollten wir die Nachricht erhalten, die wir aus der Funktion save zurückgeben, wenn wir ihn auf dem Frontend anzeigen.

Einen Block erstellen

Sieht aus, als wäre alles angeschlossen! Wir können zu dem zurückkehren, was wir in index.js vor dem Test hatten, jetzt, da wir bestätigt haben, dass die Dinge funktionieren

import { registerBlockType } from "@wordpress/blocks";

import metadata from "./block.json";
import Edit from "./edit.js";
import Save from "./save.js";

const { name } = metadata;

registerBlockType(name, {
  edit: Edit,
  save: Save,
});

Beachten Sie, dass die Funktionen edit und save an zwei vorhandene Dateien im Verzeichnis src gebunden sind, die @wordpress/create-block für uns generiert hat und die alle zusätzlichen Importe enthalten, die wir in jeder Datei benötigen. Noch wichtiger ist jedoch, dass diese Dateien die Komponenten Edit und Save erstellen, die die Markups des Blocks enthalten.

Backend-Markup (src/edit.js)

import { useBlockProps } from "@wordpress/block-editor";
import { __ } from "@wordpress/i18n";

export default function Edit() {
  return (
    <p {...useBlockProps()}>
      {__("Hello from the Block Editor", "block-example")}
    </p>
  );
}

Sehen Sie, was wir da gemacht haben? Wir importieren Props aus dem Paket @wordpress/block-editor, was uns ermöglicht, Klassen zu generieren, die wir später für das Styling verwenden können. Wir importieren auch die Internationalisierungsfunktion __ für die Behandlung von Übersetzungen.

Front-End-Markup (src/save.js)

Dies erstellt eine Save-Komponente, die wir praktisch genauso verwenden wie src/edit.js, mit leicht abweichendem Text.

import { useBlockProps } from "@wordpress/block-editor";
import { __ } from "@wordpress/i18n";

export default function Save() {
  return (
    <p {...useBlockProps.save()}>
      {__("Hello from the front end", "block-example")}
    </p>
  );
}

Auch hier erhalten wir eine schöne Klasse, die wir in unserem CSS verwenden können.

Block-Styling

Wir haben gerade behandelt, wie man Block-Props verwendet, um Klassen zu erstellen. Sie lesen diesen Artikel auf einer Website, die sich ausschließlich mit CSS beschäftigt. Daher habe ich das Gefühl, etwas zu versäumen, wenn wir nicht spezifisch darauf eingehen, wie Block-Stile geschrieben werden.

Unterscheidung von Front- und Back-End-Styles

Wenn Sie sich die block.json im Verzeichnis src ansehen, finden Sie dort zwei Felder, die sich auf Stile beziehen.

• editorStyle gibt den Pfad zu den Stilen an, die im Back-End angewendet werden.
• style ist der Pfad für gemeinsame Stile, die sowohl im Front- als auch im Back-End angewendet werden.

Kev Quirk hat einen detaillierten Artikel, der seinen Ansatz zeigt, wie das Back-End-Editor wie das Front-End-UI aussehen lassen kann.

Denken Sie daran, dass das Paket @wordpress/scripts die Datei block.json kopiert, wenn es den Code im Verzeichnis /src verarbeitet, und kompilierte Assets im Verzeichnis /build platziert. Die Datei build/block.json wird verwendet, um den Block zu registrieren. Das bedeutet, dass jeder Pfad, den wir in src/block.json angeben, relativ zu build/block.json geschrieben sein sollte.

Verwendung von Sass

Wir könnten ein paar CSS-Dateien in das build-Verzeichnis legen, die Pfade in src/block.json referenzieren, den Build ausführen und damit fertig sein. Das nutzt jedoch nicht die volle Leistungsfähigkeit des @wordpress/scripts-Kompilierungsprozesses, der Sass in CSS kompilieren kann. Stattdessen platzieren wir unsere Stil-Dateien im src-Verzeichnis und importieren sie in JavaScript.

Dabei müssen wir berücksichtigen, wie @wordpress/scripts Stile verarbeitet.

• Eine Datei namens style.css, style.scss oder style.sass, die in den JavaScript-Code importiert wird, wird zu style-index.css kompiliert.
• Alle anderen Stil-Dateien werden kompiliert und zu index.css gebündelt.

Das Paket @wordpress/scripts verwendet webpack zum Bündeln, und @wordpress/scripts verwendet das PostCSS-Plugin zur Verarbeitung von Stilen. PostCSS kann durch zusätzliche Plugins erweitert werden. Das Paket scripts verwendet diejenigen für Sass, SCSS und Autoprefixer, die alle verfügbar sind, ohne zusätzliche Pakete installieren zu müssen.

Tatsächlich erhalten Sie bei der Initialisierung Ihres ersten Blocks mit @wordpress/create-block einen guten Start mit SCSS-Dateien, die Sie sofort verwenden können.

• editor.scss enthält alle Stile, die auf das Back-End-Editor angewendet werden.
• style.scss enthält alle Stile, die sowohl vom Front- als auch vom Back-End gemeinsam genutzt werden.

Schauen wir uns diesen Ansatz nun in Aktion an, indem wir etwas Sass schreiben, das wir in das CSS für unseren Block kompilieren werden. Auch wenn die Beispiele nicht sehr Sass-lastig sein werden, schreibe ich sie trotzdem in die SCSS-Dateien, um den Kompilierungsprozess zu demonstrieren.

Front und Back-End-Styles

Okay, beginnen wir mit Stilen, die sowohl im Front- als auch im Back-End angewendet werden. Zuerst müssen wir src/style.scss erstellen (sie ist bereits vorhanden, wenn Sie @wordpress/create-block verwenden) und sicherstellen, dass wir sie importieren, was wir in index.js tun können.

import "./style.scss";

Öffnen Sie src/style.scss und fügen Sie dort einige grundlegende Stile ein, indem Sie die Klasse verwenden, die uns aus den Block-Props generiert wurde.

.wp-block-css-tricks-block-example {
  background-color: rebeccapurple;
  border-radius: 4px;
  color: white;
  font-size: 24px;
}

Das war's für den Moment! Wenn wir den Build ausführen, wird dies zu build/style.css kompiliert und sowohl vom Block-Editor als auch vom Front-End referenziert.

Back-End-Styles

Möglicherweise müssen Sie Stile schreiben, die spezifisch für den Block-Editor sind. Erstellen Sie dazu src/editor.scss (auch hier erledigt @wordpress/create-block dies für Sie) und fügen Sie dort einige Stile ein.

.wp-block-css-tricks-block-example {
  background-color: tomato;
  color: black;
}

Importieren Sie sie dann in edit.js, der Datei, die unsere Edit-Komponente enthält (wir können sie überall importieren, aber da diese Stile für den Editor bestimmt sind, ist es logischer, sie hier zu importieren).

import "./editor.scss";

Wenn wir nun npm run build ausführen, werden die Stile in beiden Kontexten auf den Block angewendet.

Referenzierung von Styles in block.json

Wir haben die Styling-Dateien in edit.js und index.js importiert, aber denken Sie daran, dass der Kompilierungsschritt zwei CSS-Dateien für uns im build-Verzeichnis generiert: index.css und style-index.css. Wir müssen diese generierten Dateien in den Block-Metadaten referenzieren.

Fügen wir der block.json-Metadaten ein paar Anweisungen hinzu.

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 2,
  "name": "css-tricks/block-example",
  "version": "1.0.0",
  "title": "Block Example",
  "category": "text",
  "icon": "format-quote",
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style-index.css"
}

Führen Sie npm run build erneut aus, installieren und aktivieren Sie das Plugin auf Ihrer WordPress-Website, und Sie sind bereit, es zu verwenden!

Sie können npm run start verwenden, um Ihren Build im Watch-Modus auszuführen und Ihren Code jedes Mal automatisch zu kompilieren, wenn Sie eine Änderung vornehmen und speichern.

Wir kratzen nur an der Oberfläche

Tatsächliche Blöcke nutzen die Seitenleiste „Einstellungen“ des Block-Editors und andere von WordPress bereitgestellte Funktionen, um reichhaltige Benutzererlebnisse zu schaffen. Darüber hinaus gibt es im Wesentlichen zwei Versionen unseres Blocks – edit und save –, sodass Sie auch darüber nachdenken müssen, wie Sie Ihren Code organisieren, um Code-Duplizierung zu vermeiden.

Aber hoffentlich hilft dies, den allgemeinen Prozess der Erstellung von WordPress-Blöcken zu entmystifizieren. Dies ist wirklich eine neue Ära in der WordPress-Entwicklung. Es ist schwierig, neue Vorgehensweisen zu lernen, aber ich freue mich darauf, zu sehen, wie sie sich entwickelt. Werkzeuge wie @wordpress/create-block helfen, aber selbst dann ist es gut zu wissen, was es genau tut und warum.

Werden sich die hier behandelten Dinge ändern? Höchstwahrscheinlich! Aber zumindest haben Sie eine Grundlage, von der aus Sie arbeiten können, während wir weiterhin beobachten, wie sich WordPress-Blöcke weiterentwickeln, einschließlich Best Practices für deren Erstellung.

Referenzen

Auch hier ist mein Ziel, einen effizienten Weg für den Einstieg in die Blockentwicklung in dieser Zeit zu skizzieren, in der sich die Dinge schnell entwickeln und die WordPress-Dokumentation etwas hinterherhinkt. Hier sind einige Ressourcen, die ich zur Zusammenstellung verwendet habe.

• Schlüsselkonzepte (WordPress Block Editor Handbook)
• Tutorial zur Erstellung eines Blocks (WordPress Block Editor Handbook)
• Metadaten in block.json (WordPress Block Editor Handbook)
• Quellcode für Kernblöcke (WordPress GitHub)
• webpack-Konfiguration, die im Paket @wordpress/scripts verwendet wird (WordPress GitHub)
• Ein Backend-Entwickler lernt, Block-Editor-Blöcke zu erstellen, Teil 1 (Tom McFarlin)
• Ryan Welchers Twitch-Streams (Ryan ist ein Developer Advocate bei Automattic)