So fügen Sie dem Gutenberg-Editor mit @wordpress/scripts eine Schaltfläche hinzu

Vor fast anderthalb Jahren schrieb Antonio diesen Blogbeitrag, in dem er eine der Schwierigkeiten erklärte, mit denen wir bei der Anpassung unserer Plugins an den neuen WordPress-Blockeditor konfrontiert waren. Das Ergebnis seines Tutorials sah in etwa so aus:

Glücklicherweise oder leider hat sich Gutenberg in diesen anderthalb Jahren sehr verändert. Der Entwicklungsstapel wurde erweitert und verbessert, und Plugin- und Themenentwickler mussten die neuen Technologien annehmen und anpassen. Und diejenigen von uns, die auch über unsere Erfahrungen schreiben und das Gelernte teilen, sind jetzt „gezwungen“, unsere Tutorials zu aktualisieren, damit Sie auf dem Laufenden bleiben. Aber wir freuen uns!

Vor ein paar Wochen hat uns Ivan, einer unserer Leser, einen Kommentar in Antonios Tutorial hinterlassen und um Hilfe gebeten. Anscheinend war er nicht in der Lage, Antonios Plugin zu implementieren. Und ehrlich gesagt überrascht mich das nicht, denn in letzter Zeit hat sich einiges geändert. Um Ivan und allen anderen zu helfen, die uns lesen und weiter über WordPress lernen möchten, erstellen wir das Tutorial zum Hinzufügen einer Schaltfläche zum Gutenberg-Blockeditor neu und nutzen dabei alle neuen Tools, die WordPress uns bietet!

Erstellen Sie ein Plugin

Als erstes müssen wir ein WordPress-Plugin erstellen. Das ist ganz einfach. Im Grunde müssen wir nur einen Ordner in wp-content/plugins mit dem Namen erstellen, den wir unserem Plugin geben möchten (z. B. gutenberg-button ), und darin eine Datei mit demselben Namen und einer .php Erweiterung. Geben Sie dann den folgenden Code in Ihre Plugin-Datei ein:

Schauen wir uns nun genauer an, was das vorherige Snippet bewirkt:

• Zuerst öffnen wir ein <?php -Tag. Keine Überraschungen hier.
• Als nächstes fügen wir in dieser Hauptdatei einen mehrzeiligen Kommentar hinzu. Der Kommentar enthält mehrere Zeilen mit „Schlüssel/Wert“-Paaren. Beispielsweise sehen wir, wie wir den Namen des Plugins ( Plugin Name ), seine Version ( Version ) oder den Namen des Autors ( Author ) angeben. Alle diese Informationen werden dann im Abschnitt „ Plugins “ in WordPress angezeigt.
• Abschließend fügen wir einen Boilerplate-Code hinzu:
  • wir geben einen namespace an (wir haben hier über Namensräume gesprochen),
  • Wir stellen sicher, dass die Datei, wenn sie ausgeführt wird, als Teil von WordPress ausgeführt wird, und
  • Wir definieren einige Konstanten über das Plugin (was später hilfreich sein wird).

Sobald wir dies alles getan haben, sehen wir, wenn wir zum Plugins -Bildschirm unseres WordPress gehen, dass der Gutenberg-Button dort ist:

wir aktivieren es und… voila! Sicher, es bringt nichts, aber es ist schon da.

Entwicklung von JavaScript-Plugins

Heutzutage müssen WordPress-Entwickler JavaScript beherrschen. Das ist eine der Konsequenzen, wenn Gutenberg im Kern ist, denke ich. Und dieses Tutorial ist keine Ausnahme.

Umgebung vorbereiten

Wenn wir der Gutenberg-Oberfläche eine neue Schaltfläche hinzufügen möchten, müssen wir diese Funktion in JavaScript codieren. Bereiten wir also die JavaScript-Entwicklungsumgebung in unserem Plugin vor. Führen Sie dazu einfach den folgenden Befehl von Ihrer Befehlszeile aus (stellen Sie sicher, dass Sie sich dabei in wp-content/plugins/gutenberg-button befinden):

 npm init

und folgen Sie den Anweisungen:

 This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install <pkg>` afterwards to install a package and save it as a dependency in the package.json file. Press ^C at any time to quit. package name: (gutenberg-button) version: (1.0.0) description: Adding a formatting button in Gutenberg. entry point: (index.js) ...

Das Ergebnis dieses Prozesses ist eine package.json -Datei. Wie Sie gleich sehen werden, wird diese Datei in Zukunft äußerst hilfreich sein.

Wie ich bereits im Titel dieses Beitrags verraten habe, werden wir @wordpress/scripts verwenden, um unser Plugin zu erstellen. Fügen wir es also als Abhängigkeit hinzu, indem wir den folgenden Befehl ausführen:

 npm install --save-dev @wordpress/scripts

Dieser Befehl lädt eine Reihe von Abhängigkeiten in unser Plugin herunter (unter node_modules ) und ändert unsere package.json , sodass klar ist, dass @wordpress/scripts jetzt eine Entwicklungsabhängigkeit ist.

Wenn Sie sich die Dokumentation dieses Pakets ansehen, werden Sie feststellen, dass es viele Skripte zum Erstellen, Überprüfen der Syntax, Formatieren von Code usw. enthält:

 { "scripts": { "build": "wp-scripts build", "check-engines": "wp-scripts check-engines", "check-licenses": "wp-scripts check-licenses", "format:js": "wp-scripts format-js", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "lint:md:docs": "wp-scripts lint-md-docs", "lint:md:js": "wp-scripts lint-md-js", "lint:pkg-json": "wp-scripts lint-pkg-json", "packages-update": "wp-scripts packages-update", "start": "wp-scripts start", "test:e2e": "wp-scripts test-e2e", "test:unit": "wp-scripts test-unit-js" } }

Bearbeiten wir also unsere Datei „ package.json “, sodass der Abschnitt "scripts" alle empfohlenen Befehle enthält.

So überprüfen Sie, ob alles funktioniert …

Lassen Sie uns einen src -Ordner im Stammverzeichnis Ihres Projekts erstellen und darin eine index.js -Datei hinzufügen. Dies wird die Haupt-JavaScript-Datei unseres Plugins sein und Ihren gesamten Code enthalten (Sie können den Code dann nach Belieben organisieren, solange die Hauptdatei src/index.js ist).

Lassen Sie uns ausprobieren, ob die Dinge wie erwartet funktionieren, indem Sie die folgende Anweisung index.js :

 console.log( 'Hi!' );

und Erstellen des Projekts mit npm run build . Dadurch wird Ihr Code in etwas transpiliert, das ein Browser ausführen kann (es war im Moment nicht wirklich notwendig, aber es wird in nur wenigen Minuten geschehen) und ein neues Skript in einem build -Ordner generieren.

Jetzt müssen wir WordPress nur noch mitteilen, dass dieses Skript existiert, damit es geladen werden kann. Öffnen Sie dazu einfach die Hauptdatei Ihres Plugins ( gutenberg-button.php ) und fügen Sie am Ende folgende Zeilen hinzu:

 function enqueue_script() { wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', [], GUTENBERG_BUTTON_VERSION ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

Wenn Sie aufpassen, werden Sie sehen, dass wir WordPress einfach anweisen, unser neues Skript /build/index.js als Blockeditor-Ressource einzureihen. Wenn ein Benutzer auf den Blockeditor zugreift, ist unser Skript auf diese Weise Teil der Assets, die der Editor enthält.

Also lasst uns das überprüfen. Gehen Sie zu Ihrem WordPress-Dashboard, bearbeiten Sie einen Beitrag und sehen Sie sich die JavaScript-Konsole Ihres Browsers an. Wenn alles wie erwartet gelaufen ist, sollten Sie „Hi!“ sehen. auf der Konsole geschrieben:

Replizieren unseres Tutorials zum Hinzufügen einer Schaltfläche zu Gutenberg

Okay, jetzt, da wir gesehen haben, dass wir JavaScript-Code schreiben und ihn mit npm run build das unsere Browser verstehen, ist es an der Zeit, Antonios Tutorial zu replizieren. Und das, lieber Leser, ist denkbar einfach.

Öffnen Sie die Datei src/index.js und ersetzen Sie die vorherige Anweisung console.log durch Folgendes:

Wie Sie sehen können, ist dies fast derselbe Code, den Antonio vor ein paar Monaten geschrieben hat. Der Hauptunterschied besteht darin, dass wir die globale Variable wp nicht mehr verwenden, um auf die Funktionen und Komponenten von Gutenberg zuzugreifen; Stattdessen verlassen wir uns jetzt auf import Anweisungen. Aber ansonsten ist es ziemlich gleich.

Sobald Sie den Code geschrieben haben, führen Sie ihn einfach mit npm run build aus und fertig! Du hast jetzt den Button in Gutenberg:

Stellen wir sicher, dass es funktioniert, indem wir einen Text auswählen und auf die Schaltfläche klicken:

und los geht's, wir sehen, dass der Text wieder in der Konsole erscheint!

Eine letzte Anmerkung zu Abhängigkeiten…

Wenn Sie einen Blick in den build -Ordner werfen, werden Sie sehen, dass @wordpress/scripts nicht nur eine index.js -Datei erstellt hat, sondern auch eine index.asset.php -Datei hat. Diese Datei definiert ein kleines Objekt mit zwei Eigenschaften:

• eine Liste von Abhängigkeiten (nämlich WordPress-Skripte), die von unserem Plugin benötigt werden
• eine Build-Version

Wir können (und sollten) diese beiden Eigenschaften verwenden, wenn wir unser Skript in WordPress einreihen, wenn wir sicherstellen wollen, dass das Skript ordnungsgemäß ausgeführt wird. Gehen Sie dazu einfach zurück zu gutenberg-button.php und ändern Sie es wie unten gezeigt:

 function enqueue_script() { $asset = include GUTENBERG_BUTTON_PATH . '/build/index.asset.php'; wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', $asset['dependencies'], $asset['version'] ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

Laden Sie einfach das Objekt in index.asset.php mit einer include -Anweisung und ersetzen Sie die Liste der Abhängigkeiten, die wir hatten ( [] ), durch die tatsächlichen Abhängigkeiten und verwenden Sie die Build-Nummer als Plugin-Version.

Schlussfolgerungen

Das Erstellen wirklich nützlicher WordPress-Plugins ist schwierig. Sie müssen gut verstehen, wie JavaScript funktioniert, und mit allen Ressourcen von WordPress vertraut sein. Aber dank des Pakets @wordpress/scripts ist das Vorbereiten der JavaScript-Entwicklungsumgebung und das Erstellen eines JavaScript-Plugins, das in WordPress ausgeführt werden kann, einfacher als je zuvor.

Ich hoffe euch hat der heutige Beitrag gefallen. Und wie immer, wenn Sie an irgendeinem Punkt nicht weiterkommen oder Fragen haben, hinterlassen Sie bitte einen Kommentar und wir helfen Ihnen weiter.

Oh, und übrigens, hier ist ein Link zu dem Projekt, das heruntergeladen und getestet werden kann, wenn Sie dies wünschen. Klonen Sie einfach das Projekt, npm install Sie alle Abhängigkeiten, npm run build es und probieren Sie es aus!

Vorgestelltes Bild von Ashim D'Silva auf Unsplash.