In diesem Teil werden wir Javascript schreiben, um unseren benutzerdefinierten Block zu registrieren und zu konfigurieren. Am Ende registrieren wir das Skript bei PHP und führen den erforderlichen PHP-Code aus, damit WordPress es als neuen Block erkennt.
Zunächst eine kurze Anmerkung zum Zugriff auf die Funktionen und Komponenten von WordPress Gutenberg.
Das globale wpPaket und die Destrukturierung
Wenn wir uns in einer Javascript-Datei befinden, die in den Gutenberg-Editor eingereiht ist, haben wir Zugriff auf ein globales Objekt/Paket: wp. Dies ist ein sehr, sehr großes Javascript-Objekt und es enthält eine ganze Reihe nützlicher Komponenten und Funktionen, die wir zum Erstellen von Blöcken verwenden werden. Wenn Sie Javascript für benutzerdefinierte Blöcke schreiben, werden Sie sich auf wpziemlich viel beziehen.
Daher ist es sowohl in modernem Javascript als auch in React üblich, das zu destrukturieren, was wir verwenden möchten. Im Grunde bedeutet es nur, dass wir lokale Variablen aus Teilen einer größeren Struktur definieren. Zum Beispiel ist die erste Funktion, die wir verwenden werden registerBlockType(), die innerhalb von existiert wp.blocks. Wir könnten die Funktion so aufrufen:
wp.blocks.registerBlockType();Aber es ist einfacher, es so zu destrukturieren:
const { registerBlockType } = wp.blocks;
registerBlockType();Jetzt können Sie direkt auf die Funktion verweisen, ohne ihr ihre Struktur voranzustellen. Es wird viel nützlicher, wenn wir uns auf Funktionen oder Komponenten beziehen, die wir oft wiederholen werden.
Wir werden in dieser Serie Umstrukturierungen vornehmen und im weiteren Verlauf des Tutorials sehen, wie viel besser lesbar und kürzer unser Code wird.
Registrieren eines neuen Blocks
Die Funktion zum Registrieren eines neuen benutzerdefinierten Blocks ist registerBlockType()im wp.blocksPaket verfügbar. Es akzeptiert zwei Parameter; erstens eine Zeichenfolge mit dem Namensraum und Namen des Blocks und zweitens ein Objekt mit der vollständigen Blockkonfiguration.
Gutenberg erwartet, dass alle Blöcke einen Namensraum und einen Namen haben, der durch einen Schrägstrich dazwischen definiert ist. Der Namespace soll sicherstellen, dass Ihr Blockname nicht mit anderen Blöcken kollidiert, die möglicherweise denselben Namen verwenden. Alle Blöcke in WordPress verwenden den Namensraum core. Beispielsweise hat der Standard-Absatzblock in WordPress den Namen core/paragraph. Wenn Sie einen anderen Namensraum wählen, können Sie auch problemlos einen Block namens Absatz erstellen.
Entscheiden Sie sich für einen Slug-Versions-Namespace, der für Sie einzigartig ist. Ich werde in dieser Serie den Namensraum awp(Kurzversion von A White Pixel) verwenden.
Öffnen Sie die Quelldatei, die wir im letzten Schritt erstellt haben; src/block-awhitepixel-myfirstblock.js, in einem Editor. Zuerst rufen wir registerBlockTypevon destructured wp.blocksmit dem Namen auf awp/firstblock. Passen Sie Ihren Namen und Namensraum nach und nach an.
const { registerBlockType } = wp.blocks;
registerBlockType('awp/firstblock', {
// Your block configuration and code here
});Im zweiten Parameter, dem Blockkonfigurationsobjekt, müssen wir einige Eigenschaften definieren, damit es erfolgreich registriert werden kann. Denken Sie daran, dass die Blockkonfiguration ein Objekt ist, was bedeutet, dass Sie alles als Schlüssel + Wert-Paare schreiben müssen, getrennt durch Kommas. Es gibt einige mögliche Konfigurationseigenschaften, also gehen wir diese durch und wir sehen den endgültigen Code am Ende.
Erforderlich: Titel
Die erste erforderliche Eigenschaft ist title. Dies ist der Name, wie er angezeigt wird, wenn Sie zwischen Blöcken auswählen. Legen Sie für diese Eigenschaft einen beliebigen Namen in einer Zeichenfolge fest.
Wir fügen Folgendes als Titel hinzu:
title: 'My first block',PS: Wir werden uns noch einmal ansehen, wie wir alle Strings in unseren Block schreiben, um sicherzustellen, dass sie in Teil 8 übersetzt werden können. Aber jetzt werden wir es einfach halten und einfach Strings schreiben.
Erforderlich: Kategorie
Die Eigenschaft categorydefiniert, wo in welcher Blockkategorie Ihr Block erscheint, wenn Sie Blöcke zum Einfügen im Editor auswählen. Mögliche Werte sind common, formatting, layout, widgets, embed.
Legen wir es in common, die erste Blockkategorie.
category: 'common',Optional: Symbol
Wenn Sie Gutenberg verwendet haben, ist Ihnen wahrscheinlich aufgefallen, dass alle Blöcke Symbole haben. Sie können Ihrem Block ein Symbol hinzufügen, entweder mit einer Zeichenfolge, die auf eines der Dashicons von WordPress verweist, oder Sie können ein benutzerdefiniertes svgElement bereitstellen.
Ich wähle einfach eines der Dashicons von WordPress aus, den Smiley – aber Sie können jedes beliebige auswählen. Beachten Sie, dass Sie das Einfügen von „dashicons-” in Ihren Icon-Klassennamen überspringen.
icon: 'smiley',Optional: Beschreibung
Sie können eine Beschreibung angeben, die in der Seitenleiste Einstellungen (auf der rechten Seite) angezeigt wird, wenn der Block aktiv ist.
Ich füge nur einen kurzen Text als Beispiel hinzu:
description: 'Learning in progress',Optional: Schlüsselwörter
Gutenberg unterstützt eine Suchfunktion bei der Auswahl von Blocktypen. Sie können ein Array möglicher Übereinstimmungen in der Eigenschaft angeben keywords. Ohne keywordswürden Sie Ihren Block nur finden, indem Sie nach seinem Namen suchen.
Ich füge exampleund hinzu test, damit wir unseren benutzerdefinierten Block leicht finden können, wenn wir mit der Eingabe eines dieser Schlüsselwörter beginnen.
keywords: ['example', 'test'],Optional: Attribute
Die Eigenschaft attributesist eine sehr wichtige Eigenschaft, auf die wir in dieser Tutorial-Reihe häufig zurückkommen werden. Hier speichern Sie Ihre strukturierten Daten und Benutzereingaben für Ihren Block. Sie können es sich als Variablen vorstellen. Wir werden es vorerst nicht hinzufügen, aber wir werden definitiv bald darauf zurückkommen.
(Art von) erforderlich: Bearbeiten und optional: Speichern
Innerhalb von editund saveEigenschaften fügen Sie Ihren gesamten Code sowohl für die Editorausgabe als auch für das Frontend-Rendering hinzu. Beide Eigenschaften erwarten eine Funktion, die eine Ausgabe zurückgeben sollte.
Die Eigenschaft editbeschreibt die Struktur Ihres Blocks innerhalb des Editors. Die saveEigenschaft behandelt im Wesentlichen zwei Dinge; Ihre Blockausgabe im Frontend, sondern auch die Struktur, wie Ihr Block in der Datenbank gespeichert wird. Sie werden hauptsächlich darin arbeiten, editda Sie hier Eingaben für die Eingabe oder Auswahl von Dingen hinzufügen und die Daten des Blocks aktualisieren. Die saveFunktion sollte die Daten in keiner Weise aktualisieren oder bearbeiten, sondern nur ausgeben.
Gutenberg muss in der Lage sein, Ihren Block mit all seinen Einstellungen im Editor aus dem zu rekonstruieren, was in der saveFunktion (und den Attributen) ausgegeben wird. Wenn Gutenberg jemals einen Beitrag öffnet, bei dem die zuvor gespeicherte Blockausgabe (auch nur geringfügig) von der Definition in save abweicht, wird Ihr Block ungültig.
Ich kann Ihnen garantieren, dass Sie bei der Entwicklung benutzerdefinierter Blöcke häufig darauf stoßen werden. In diesem Fall müssen Sie den Block entfernen (von den Punkten in der Symbolleiste) und erneut hinzufügen. Ich empfehle auch eine Browseraktualisierung (F5 oder STRG+R).
WordPress hat eine eigene Dokumentationsseite für die Bearbeitungs- und Speicherfunktionen des Blocks, wenn Sie mehr erfahren möchten.
Lassen Sie uns für unseren ersten Block etwas Grundlegendes ausgeben. Wir werden dasselbe für beide zurückgeben editund save; ein „:)” umschlossen von <div>. Das Symbol des Blocks ist schließlich ein Smiley.
Andere Eigenschaften
Es gibt weitere optionale Eigenschaften für registerBlockType; parent, supports, transforms, example, und styles. Wir werden diese vorerst überspringen, da die meisten für fortgeschrittenere oder angepasste Blockerstellung gedacht sind. Wenn Sie daran interessiert sind, mehr darüber zu lesen, werfen Sie einen Blick in die Dokumentation von WordPress.
Letzter Registerblockcode
Unser Code sieht jetzt etwa so aus.
Damit haben wir genug, damit unser Block erfolgreich als benutzerdefinierter Block registriert werden kann. Sehen wir es uns in der Praxis im Gutenberg-Editor an.
Haben Sie daran gedacht, Ihr Javascript zu kompilieren? Im vorherigen Schritt haben wir gelernt, dass wir diese Javascript-Datei nicht in Gutenberg laden können; Wir brauchen die kompilierte Version. Sie würden normalerweise npm run startim Hintergrund entwickeln, oder Sie können npm run buildes jetzt einfach einmal ausführen. Das sollte unser Quell-JavaScript kompilieren und es dort platzieren, wo Sie es in Ihrer webpack.config.js.
Der PHP-Teil der Registrierung eines Blocks
Für jeden Block müssen Sie die Javascript-Datei registrieren, und dies ist genauso, wie Sie alle anderen Skripte in WordPress registrieren würden – indem Sie [wp_register_script](https://developer.wordpress.org/reference/functions/wp_register_script/)(). Beachten Sie, dass wir das Skript registrieren, nicht in die Warteschlange stellen. Dies liegt daran, dass wir auch eine PHP-Funktion aufrufen müssen, um jeden benutzerdefinierten Block zu registrieren, und diese Funktion ist dafür verantwortlich, das Skript bei Bedarf in die Warteschlange einzureihen.
Ich ziehe es vor, Gutenberg-bezogenen Code in einer separaten Datei in meinen Themen aufzubewahren. functions.phpAber Sie können, und das werden wir in diesem Tutorial, der Einfachheit halber einfach den gesamten PHP-Code direkt in die Themes schreiben .
Ich empfehle, den initHaken für Ihre Funktion zu verwenden, und nicht enqueue_block_assets. Wir können sowohl das Registrieren des Skripts als auch das Registrieren des Blocks zusammenfassen.
Die PHP-Funktion, die wir zum Registrieren eines neuen Blocks verwenden, ist [register_block_type](https://developer.wordpress.org/reference/functions/register_block_type/)(). Ähnlich wie bei Javascript registerBlockType()akzeptiert es zwei Parameter; Namespace und Name des Blocks sowie ein Array mit Argumenten. Stellen Sie sicher, dass Sie in PHP genau denselben Namensraum und Namen wie in Javascript angeben.
Im zweiten Argument gibt es einige mögliche Argumente (auf einige davon werden wir später in dieser Serie zurückkommen). Aber der wichtigste ist editor_script, wo Sie das Handle (erster Parameter von wp_register_script()) des registrierten Skripts angeben.
Und das ist es!
Unser Block im Gutenberg-Editor
Wenn Sie jetzt Ihren Editor in einem Beitrag aktualisieren, sollten Sie unseren Block finden – entweder durch Öffnen der Kategorie „Allgemein” oder durch Suchen nach einem der von Ihnen angegebenen Schlüsselwörter oder Namen.
Unser Block rendert ein einfaches „:)” sowohl im Editor als auch im Frontend. Ab jetzt kannst du nichts im Block bearbeiten, aber das werden wir in den nächsten Schritten lernen!