Fügen Sie eine benutzerdefinierte Inspektor-Seitenleiste in WordPress Gutenberg mit Post Meta hinzu

In diesem Tutorial sehen wir uns an, wie man eine benutzerdefinierte Seitenleiste zum Inspektor (rechte Seitenleiste) in WordPress Gutenberg hinzufügt. Darin implementieren wir ein Feld, das mit einem Post-Meta verbunden ist. Alles wird mit Javascript im Gutenberg-Editor implementiert und ist eine Alternative zum traditionellen Hinzufügen von Metaboxen.

Kopf hoch!

Dies ist ein Tutorial zum Erstellen Ihrer eigenen benutzerdefinierten Seitenleiste. Aber wenn Sie daran interessiert sind, nur Meta/Einstellungen zur Standard-Inspector-Seitenleiste (Registerkarte „Dokument”) hinzuzufügen, habe ich genau dafür ein Tutorial:

Was wir schaffen

WordPress Gutenberg ermöglicht es Entwicklern, benutzerdefinierte Seitenleisten zu erstellen, indem sie ein sogenanntes Javascript-Plugin erstellen. (Nicht zu verwechseln mit traditionellen WordPress-Plugins). Durch die Verwendung eines Javascript-Plugins können wir eine neue Seitenleiste erstellen und auch in das Menü „Tools und Optionen” einbinden.

Wir werden einen neuen Menüpunkt in den „Tools” hinzufügen, der unsere benutzerdefinierte Seitenleiste öffnet. Der Inhalt der Seitenleiste liegt ganz bei Ihnen, aber ich werde einige Beispiele durchgehen, darunter auch, wie man ein Post-Meta-Feld darin verbindet.

Richten Sie Ihr Javascript ein

Für dieses Tutorial werde ich ES6/ESNext Javascript mit JSX schreiben, was bedeutet, dass wir einen Compiler einrichten müssen. Wenn Sie mitmachen und kein ES5-Javascript schreiben möchten, müssen Sie eine Entwicklungsumgebung einrichten, die Ihr Javascript während der Arbeit kompiliert. Wenn Sie damit nicht vertraut sind, folgen Sie meinem Beitrag, in dem erklärt wird, wie Sie dies einrichten, und kehren Sie dann hierher zurück.

Ich habe meine eingerichtet webpack.config.js, um meine Quell-JavaScript-Datei in den /assets/js/sidebar-plugin.js. Diese kompilierte Datei benötigen wir, um sie in den Gutenberg-Editor einzureihen. Während ich diesen Code schreibe, habe ich den Laufzeitcompiler gestartet, der das Javascript jedes Mal neu kompiliert, wenn ich Änderungen im Quellcode speichere (npm run start). All dies wird ausführlich in dem zuvor erwähnten Tutorial erklärt.

Ich schreibe dies in einem Thema, aber es funktioniert genauso in einem Plugin. Denken Sie nur daran, die Pfade anzupassen, wenn Sie das Skript zum Editor hinzufügen.

Hinzufügen des Skripts zum Editor

Um unser Skript zum Gutenberg-Editor hinzuzufügen, müssen wir etwas PHP schreiben. Wenn Sie sich in einem Thema befinden, functions.phpist dies ein guter Ausgangspunkt oder irgendwo in Ihren Plugin-Dateien. Beachten Sie, dass wir das endgültig kompilierte Skript hinzufügen müssen, nicht den Quellcode. In meinem Beispiel befindet sich das kompilierte Javascript in meinem Theme-Ordner /assets/js/sidebar-plugin.js.

Wir erstellen eine angehängte Funktion enqueue_block_editor_assets. Drinnen machen wir das Übliche [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)(). Als Abhängigkeiten zum Skript fügen wir zwei hinzu; wp-plugins, und wp-edit-post. Diese beiden Pakete müssen vor unserem Skript geladen werden, da wir Funktionen von ihnen verwenden.

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-sidebar-plugin', get_stylesheet_directory_uri(). '/assets/js/sidebar-plugin.js', ['wp-plugins', 'wp-edit-post']);
});

Da wir das Skript in den Hook einreihen, enqueue_block_editor_assetswird unser Skript nur geladen, wenn der Gutenberg-Editor aktiv ist. Groß! Jetzt ist alles bereit, um unser Javascript-Plugin zu schreiben.

Registrieren Sie ein Javascript-Plugin

Der erste Schritt ist die Registrierung eines Plugins. Wir tun dies mit der [registerPlugin](https://github.com/WordPress/gutenberg/tree/master/packages/plugins#registerPlugin)Funktion in wp.plugins aus dem wp.pluginsPaket heraus.

Als Parameter für das registerPlugin geben wir einen Namen an (stellen Sie sicher, dass er eindeutig ist) und ein Objekt mit Einstellungen. Als Minimum müssen Sie eine Komponente für die Render-Eigenschaft bereitstellen. Sie können optional auch ein Symbol aus den Dashicons von WordPress hinzufügen. Denken Sie daran, dass, wenn Sie kein Symbol angeben, es auf das Plugin-Symbol zurückfällt. Zu Demonstrationszwecken verwende ich das 'carrot'Symbol.

Was die Komponente betrifft, beginnen wir mit der Definition einer Basiskomponente, die ein einfaches div mit etwas zufälligem Text darin zurückgibt. Und vor dem ganzen Code destrukturieren wir die Funktionen aus den Paketen, die wir verwenden möchten.

Wenn beim Aktualisieren von Gutenberg nichts passiert (nicht einmal Fehler), sind wir alle startklar. Wir sehen unsere Komponente nicht, weil wir WordPress nicht gesagt haben, wo sie gerendert werden soll. Der nächste Schritt ist das Einhängen in das benutzerdefinierte Seitenleistenmenü und die Komponenten des Werkzeugmenüs, um unsere Inhalte zu rendern.

Registrieren Sie eine benutzerdefinierte Seitenleiste

Aber zuerst eine Erklärung, wie Gutenberg mit benutzerdefinierten Seitenleisten umgeht und warum wir tun müssen, was wir tun werden. Wenn wir erfolgreich eine benutzerdefinierte Seitenleiste registrieren, passiert zunächst automatisch eine Sache. Gutenberg fügt unserer Seitenleiste in der oberen Symbolleiste neben dem Menü „Extras” eine Verknüpfung hinzu. Dies geschieht, weil unsere Seitenleiste automatisch „gepinnt” wird.

Das Problem beim Hinzufügen einer benutzerdefinierten Seitenleiste besteht darin, dass jeder Benutzer diese Verknüpfung „lösen” kann. Wenn sie das tun, gibt es keinen Zugangspunkt, um die Seitenleiste erneut zu öffnen! Aus diesem Grund müssen wir auch einen Menüpunkt zum Menü Extras hinzufügen.

Die Registrierung einer benutzerdefinierten Seitenleiste erfolgt mit der Komponente PluginSidebaraus dem wp.editPostPaket. Das Hinzufügen eines Menüeintrags zum Menü Extras erfolgt mit der treffend benannten Komponente PluginSidebarMoreMenuItem(ebenfalls im wp.editPostPaket enthalten).

Für die PluginSidebarKomponente müssen wir einige Requisiten bereitstellen. Sie sollten mindestens nameund bereitstellen title. Die Requisite titleist selbsterklärend, dies ist der Name, der oben in der Seitenleiste angezeigt wird. Stellen Sie in der Requisite nameeine einzigartige Schnecke bereit. Wenn Sie den Menüpunkt hinzufügen, müssen Sie sich auf diesen Slug beziehen.

Das Hinzufügen einer PluginSidebarMoreMenuItemKomponente (Werkzeugmenü) erfordert mindestens eine Requisite; target. Hier geben Sie denselben Namen an, den Sie in der nameStütze der Seitenleiste angegeben haben. Als Inhalt der Komponente schreiben Sie den Text, der als Menüpunkt angezeigt wird. Normalerweise ist dies dasselbe wie in der Seitenleiste title.

Da React einen einzigen Wrapping-Knoten um die Rückkehr der Komponente benötigt, packen wir alles in eine FragmentKomponente (aus dem wp.elementPaket). Ich wickle auch meine Zeichenfolgen __()aus dem wp.i18nPaket ein, um die Übersetzung zu ermöglichen.

Mit dem obigen Code werden die folgenden zwei (höchstwahrscheinlich drei) Dinge passieren. Sie erhalten eine Karottensymbol-Verknüpfung in der Symbolleiste (falls Sie sie noch nicht gelöst haben). Ein Klick darauf öffnet die Seitenleiste. Sie haben auch einen neuen Menüpunkt in der Seitenleiste im Tools-Menü unter der Überschrift „Plugins”.

Hinzufügen von Inhalten zur Seitenleiste

Der tatsächliche Inhalt der Seitenleiste liegt ganz bei Ihnen. Sie müssen nur HTML oder Komponenten innerhalb der PluginSidebarKomponente mit dem, was Sie möchten, hinzufügen (anstelle des „Hallo”-Texts).

Möglicherweise stellen Sie fest, dass der Inhalt der Seitenleiste nicht gefüllt ist. Dies ist beabsichtigt, da die Idee darin besteht, Panels innerhalb dieser Seitenleiste zu erstellen. Panels sind die zusammenklappbaren Abschnitte in der normalen Gutenberg-Seitenleiste. Dies sind Komponenten, die Sie ganz einfach in Ihre benutzerdefinierte Seitenleiste einfügen können. Sie können so viele Panels hinzufügen, wie Sie möchten, und sie eignen sich hervorragend zum Gruppieren verschiedener Dinge.

Hinzufügen von Panels zu unserer Seitenleiste

Schauen wir uns schnell an, wie wir Panels zu unserer Seitenleiste hinzufügen können. Wenn Sie Ihre eigenen benutzerdefinierten Blocktypen erstellt haben, sind Sie möglicherweise mit diesen Komponenten vertraut. Wir verwenden PanelBodyund optional PanelRowaus dem wp.componentsPaket.

Für eine PanelBodyKomponente geben Sie mindestens das Prop an title. Sie können dem Prop optional true oder false initialOpenzuweisen, um zu entscheiden, ob das Panel standardmäßig erweitert werden soll oder nicht. Als Inhalt innerhalb der Komponente gilt alles innerhalb des Panels.

In einem PanelBodykönnen Sie optional PanelRowKomponenten verwenden. Sie sind nicht wirklich notwendig, können Ihnen aber dabei helfen, ein gutes Styling für Ihre Panel-Inhalte zu erhalten.

Lassen Sie uns zum Beispiel zwei Panels zu unserer benutzerdefinierten Seitenleiste hinzufügen.

Mit diesem Code sieht unsere benutzerdefinierte Seitenleiste wirklich so aus, als ob sie zu Gutenberg gehört!

Hinzufügen von Post-Meta-Feldern zur benutzerdefinierten Seitenleiste

Jetzt kommen wir wirklich ins Fleisch der nützlichen Dinge für eine benutzerdefinierte Seitenleiste; Hinzufügen von Einstellungen und Speichern ihrer Werte. Aber zuerst müssen wir verstehen, wie.

Es ist wirklich einfach, Einstellungsfelder (Eingaben, Kontrollkästchen, Toggle-Felder usw.) in der Seitenleiste hinzuzufügen, indem Sie die gebrauchsfertigen Komponenten in den WordPress-Paketen verwenden. Allerdings müssen wir uns überlegen, wie wir die Werte speichern. Die offensichtliche Option besteht darin, sie als Post-Meta zu speichern. Das Verbinden einer Einstellung mit einem Post-Meta-Feld erfordert jedoch zusätzlichen Code. Genauer gesagt müssen wir sogenannte Komponenten höherer Ordnung verwenden, um Post-Meta in Javascript abzurufen und zu aktualisieren. Wir müssen auch jedes Post-Meta mit PHP registrieren und für die REST-API verfügbar machen.

Zum Abschluss dieses Tutorials werde ich zeigen, wie man ein Post-Meta mit einem Schlüssel hinzufügt awp_my_custom_meta, der entweder als wahr oder falsch gespeichert werden sollte. In der Seitenleiste wird es als Toggle-Feld (eine Wahr/Falsch-Komponente) angezeigt.

Registrieren Sie Post-Meta für die REST-API

Der erste Schritt zum Hinzufügen von Post-Meta in unserer Javascript-Datei besteht darin, sie zu registrieren und in der REST-API als zugänglich zu definieren. Dazu kehren wir wieder zu PHP zurück.

Innerhalb einer Funktion, die mit der initAktion verbunden ist, verwenden wir die [register_meta](https://developer.wordpress.org/reference/functions/register_meta/)()Funktion. Als Parameter müssen wir den Objekttyp als ‘ post‘ definieren, weil wir ihn als Post-Meta verwenden (es schließt z. B. den Seiten-Post-Typ nicht aus). Wir geben den Metaschlüssel und dann ein Array von Argumenten an. Die kritische Sache, die im arguments-Array hinzugefügt werden muss, ist das Setzen von ‘ show_in_rest‘ auf true. Post-Meta wird häufig als „ single” verwendet (überlegen Sie, wie Sie verwenden get_post_meta()). Wir definieren auch die type. In unserem Fall setzen wir es auf „ boolean“.

Mit diesem Code awp_my_custom_metaist das Post-Meta-Feld ‘ ‘ von Gutenberg aus zugänglich. Sie müssen das register_meta()für jedes Post-Meta wiederholen, das Sie in Ihrer Seitenleiste hinzufügen möchten.

Kehren wir nun zu unserem Javascript zurück.

Hinzufügen einer Einstellung zu unserer Seitenleiste

Beginnen wir mit dem einfachen Teil: Hinzufügen der Eingabe zu unserer Seitenleiste. Später werden wir weiteren Code hinzufügen, um das Einstellungsfeld tatsächlich mit Post-Meta zu verbinden. Aufgrund der Art und Weise, wie wir dies tun müssen, definieren wir eine separate neue Komponente für unsere Einstellung. Innerhalb des Panels, dem Sie Ihre Einstellungen hinzufügen möchten, rufen Sie einfach diese neue Komponente auf.

Nennen wir die Komponente CustomSidebarMetaComponent(Sie könnten sie etwas nennen, das für Ihr Projekt relevant ist). Innerhalb dieser Komponente möchten wir ein Umschaltfeld rendern. Dazu verwenden wir die ToggleControlKomponente aus dem wp.componentsPaket. Als Props zum ToggleControl liefern wir ein passendes Label im titleProp. Ein ToggleControl benötigt auch die Requisiten onChangezum Aktualisieren des Werts und checkedfür den aktuellen Wert. Wir werden diese beiden vorerst bis zum nächsten Schritt weglassen.

Mit dem obigen Code sollten Sie ein Umschaltfeld in der Seitenleiste erhalten. Es ist deaktiviert und es passiert nichts, wenn Sie darauf klicken. Das ist der nächste Schritt: Verbinden mit unserem Post-Meta.

Zugriff auf Post-Meta mit withSelect und withDispatch

Um auf einen Post-Meta-Wert zuzugreifen und ihn zu aktualisieren, müssen wir Komponenten höherer Ordnung (HOC) verwenden, um auf die WordPress-Version von Stores zuzugreifen (ähnlich wie Redux). WordPress bietet uns einige nützliche HOC mit Funktionen, die wir im wp.dataPaket verwenden können.

Die Komponente höherer Ordnung [withSelect](https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect)stellt unserer Komponente Requisiten zur Verfügung, die in unserem Fall aus Post-Meta abgerufen werden. Wir verwenden dies, um den Wert unserer Post-Meta zu ermitteln. Darin withSelectkönnen wir verwenden select('core/editor').getEditedPostAttribute('meta'), um das Meta des aktuellen Beitrags abzurufen.

Andererseits handelt [withDispatch](https://developer.wordpress.org/block-editor/packages/packages-data/#withDispatch)es sich um eine Komponente höherer Ordnung, die Aktionen ausführen kann. In unserem Fall möchten wir das Post-Meta aktualisieren, wenn die entsprechende Feldeinstellung in unserer Seitenleiste geändert wird. Innerhalb dieser Komponente verwenden wir dispatch('core/editor').editPost()WordPress, um eine Aktion zu senden. Innerhalb des von uns bereitgestellten Objekts teilen wir WordPress mit, dass es sich um ein Meta handelt, das wir aktualisieren möchten.

Schließlich müssen wir withSelectund withDispatchmit unserer Komponente kombinieren, die das Post-Meta-Feld (CustomSidebarMetaComponent) behandelt. Dazu verwenden wir WordPress’ composeaus dem wp.composePaket. Die Idee ist das withSelectund withDispatchversorgt unsere CustomSidebarMetaComponentKomponente mit Requisiten. withSelectstellt den Wert des Post-Metas als Prop bereit und withDispatchstellt eine Funktion bereit, die wir aufrufen können, um den Wert als Prop zu aktualisieren. Wir setzen diese Requisiten entsprechend auf unser ToggleField checkedund onChange.

Das ist viel zu erklären. Schauen wir uns den eigentlichen Code an:

Beginnen wir am Anfang. Was ganz unten ist. In Zeile #36ändern wir die Komponente, die wir in unserer Seitenleiste rendern, in die Komponente, mit der wir erstellt haben compose(in Zeile #15). Die CustomSidebarMetaKomponente kombiniert die withSelectund withDispatchKomponenten und gibt die zurück CustomSidebarMetaComponent.

Die CustomSidebarMetaComponenthaben Zugriff auf die customPostMetaValueRequisiten von withSelectund die setCustomPostMetaRequisiten von withDispatchDiese beiden verwenden wir für die checkedund onChangeRequisiten in der ToggleField.

Beachten Sie, dass #5wir propsden Komponenten als Parameter hinzufügen, um Requisiten in der Komponente zugänglich zu machen.

Fazit und letzte Worte

Ich hoffe, dass dieses Tutorial für Sie von Nutzen war. Dies ist, was ich zu dem Thema durch viel Versuch und Irrtum verstanden habe. Es gibt noch kaum Dokumentation zu diesem Thema. Ich kämpfe immer noch damit, besonders wenn es darum geht, mehrere Post-Meta effizient zu handhaben. Wenn ich es schaffe, ein paar gute Tricks zu lernen, werde ich dieses Tutorial auf jeden Fall aktualisieren!

Wenn Sie diesem Tutorial folgen, sollten Sie hoffentlich Code haben, der dem WordPress Gutenberg-Editor erfolgreich eine neue benutzerdefinierte Seitenleiste hinzufügt, und hoffentlich mit einigen sinnvollen Inhalten und Einstellungen. Hier ist der endgültige Code für die benutzerdefinierte Seitenleiste mit Post-Meta-Feld.