Gutenberg-Entwicklung mit Beispielen: Google Maps (Teil 2)

Hi! Wir sind zurück mit unserem Tutorial zum Entwickeln in Gutenberg. Letzte Woche haben wir ein Projekt gestartet, das einen Kartenblock in WordPress hinzugefügt hat. In diesem ersten Beitrag haben wir die Anforderungen definiert, die unser Plugin erfüllen muss, und wir haben das Skelett dessen vorbereitet, was am Ende das Endprodukt sein wird, beginnend mit der fantastischen Plugin-Boilerplate, die wir bei Nelio erstellt haben.

Heute kommt der zweite Teil des Tutorials zum Erstellen des Kartenblocks . In diesem Beitrag werden wir sehen, wie man eine Google Maps-Karte im WordPress-Editor hinzufügt und wie man eine Benutzeroberfläche implementiert, die es uns ermöglicht, ihr Verhalten zu manipulieren.

Ein kurzer Blick auf den aktuellen Stand des Projekts…

Im aktuellen Stand des Projekts haben wir einen einfachen Demo -Block, der in packages/blocks/demo/ definiert ist. Dieser kleine Block ist derjenige, der als Beispiel in Nelios Plugin-Boilerplate vorkommt und so aussieht:

Offensichtlich ist dies nicht das, was wir wollen. Wir interessieren uns nicht für ein Herzsymbol, gefolgt von etwas Text, sondern für so etwas:

Das heißt, wir wollen einen Google Map -Block mit einer optionalen Markierung darin. Wie können wir von dem ursprünglichen Beispielblock, den unsere Boilerplate hatte, zu diesem anderen, leistungsfähigeren Block wechseln? Nun, das werden wir heute beantworten!

Aber lassen Sie mich vorher ein paar Minuten investieren, um zu erklären, was wir gerade haben und wie wir vorankommen werden. Ich denke, wenn Sie den aktuellen Stand des Projekts verstehen, können Sie leichter verfolgen, was als nächstes kommt.

Den Demo -Block verstehen…

Wie ich bereits sagte, ist der Demoblock in packages/blocks/demo/ definiert. In diesem Ordner finden Sie die Stile des Blocks, sein Symbol und mehrere Dateien mit dem Code, der seine Operation implementiert. Sehen wir uns die wichtigsten Dateien an.

Auf der einen Seite gibt es die Hauptdatei: index.js . Diese Datei exportiert drei Variablen: den Namen des Blocks ( name ), die Definition des Blocks ( settings ) und die Stile, die der Block unterstützt ( styles ). Diese drei Variablen werden in packages/blocks/index.js , um den Block in Gutenberg (mit registerBlockType ) zu registrieren und ihn somit den Endbenutzern zur Verfügung zu stellen.

Diese Hauptdatei dient dann als Einstiegspunkt, um den Block zu verstehen, den wir erstellen. In den Objekteinstellungen ( settings ) sehen wir drei wichtige Eigenschaften: attributes , edit und save . Jede dieser Eigenschaften hat ihre eigene JavaScript-Datei (aus Gründen der Einfachheit und des leichteren Verständnisses), die jeweils nach ihrer entsprechenden Eigenschaft benannt ist. Werfen wir einen kurzen Blick auf alle:

• Die Datei attributes.js definiert all jene Eigenschaften unseres Blocks, die dynamisch sind und daher von unseren Benutzern angepasst werden sollten. Im Fall unseres Demo -Blocks ist das einzige vorhandene Attribut der Text, den der Benutzer geschrieben hat, aber der Kartenblock wird viel mehr Optionen haben: die Koordinaten des Mittelpunkts der Karte, die Standard-Zoomstufe, die die Karte verwenden soll, was Schaltflächen (falls vorhanden) sollten sichtbar sein, um mit der Karte usw. zu interagieren.
• Die Datei edit.js ist diejenige, die definiert, wie der Block im WordPress-Editor angezeigt wird und welche Einstellungen dem Benutzer angeboten werden (sowohl in der Symbolleiste als auch in der Seitenleiste der Einstellungen des Blocks). In Demo enthält die edit einfach die RichText Komponente von WordPress, um den Inhalt zu schreiben. Wie wir sehen werden, wird der Kartenblock komplexer und enthält auch zusätzliche Einstellungen.
• Schließlich definiert save.js die Methode, die den Block, den wir in Gutenberg bearbeitet haben, in das HTML konvertiert, das im Frontend gerendert werden muss. Auch hier sehen wir in der Demo , dass diese Funktion einfach den Inhalt eines RichText mit RichText.Content , aber es könnte alles andere sein (wie wir nächste Woche im dritten und letzten Teil dieses Tutorials sehen werden).

Erstellung des Map-Blocks basierend auf dem im Plugin Boilerplate enthaltenen Demo -Block

Sobald wir genau verstanden haben, wie der Demo -Block funktioniert, ist es an der Zeit, sich zu fragen: Wie erstellen wir unseren? Nun, ganz einfach: wie Toni uns vor ein paar Tagen gesagt hat, müssen wir einfach das Verzeichnis packages/blocks/demo/ nach packages/blocks/nelio-maps/ und anfangen, alles Notwendige zu modifizieren. Ich weiß, das ist leichter gesagt als getan.

Beginnen wir mit etwas Einfachem: attributes.js . Diese Datei enthält alle Eigenschaften, die von unseren Endbenutzern geändert werden können sollten. Im vorherigen Beitrag haben wir angegeben, welche Anforderungen unser Plugin erfüllen sollte, und wir haben daher skizziert, welche Dinge optimiert werden sollten. Nun, wenn Sie sich die resultierende attributes.js ansehen, werden Sie deutlich sehen, was an unserem Kartenblock angepasst werden kann: Zoomstufe, Kartenmitte, Sichtbarkeit verschiedener Schaltflächen … Super einfaches Zeug!

Der nächste zu ändernde Punkt ist alles, was die Ausgabe des Blocks in Gutenberg betrifft. Dazu müssen wir in edit.js . Wenn Sie genau hinsehen, werden Sie feststellen, dass es nicht viel komplizierter ist als das, was wir in unserem ursprünglichen Demo -Block hatten.

Das Wichtigste ist in der render -Methode des Blocks (Zeile 33), wo wir die Attribute, die wir gerade definiert haben, aus einem Objekt namens this.props . Wir werden diese Eigenschaften natürlich verwenden, um den Block und seine Einstellungen zu rendern. Das haben wir:

1. Eine Symbolleiste ToolbarControls (Zeile 66), die wir in einer externen Datei namens toolbar.js definiert haben (keine Sorge, wir sehen ihren Inhalt in einer Minute).
2. Die Blockeinstellungen, die in der Seitenleiste des Editors erscheinen (Zeile 68), die wir in einer Komponente namens Inspector finden, die wir in inspector.js definiert haben.
3. Der Inhalt des Blocks selbst, der zwei Zustände hat:
   • Wenn ich keinen Google Maps-API-Schlüssel zur Verfügung habe, zeigen wir einen Benutzerhinweis (Zeile 122).
   • Wenn wir diesen Schlüssel haben, zeigen wir die Karte mit MapBlock (Zeile 83). Die Karte kann einen Marker (Zeile 97) enthalten, der nur sichtbar ist, wenn die Option aktiviert ist, und kann auch von einem div (Zeile 104) mit zusätzlichen Informationen darüber begleitet werden.

Google Maps als React-Komponente

Wenn wir eine Google-Karte in unseren Editor einfügen möchten, müssen wir eine Komponente verwenden, die es uns ermöglicht, die Maps-API von Google Maps zu verwenden. Wenn man bedenkt, dass Gutenberg auf React aufbaut, ist es logisch herauszufinden, ob es eine React-Komponente von Google Maps gibt. Und sicher, es gibt einen!

Wie Sie in der Dokumentation des Projekts nachlesen können, müssen wir die Komponente zuerst in unser Projekt einfügen. Installieren Sie einfach die Abhängigkeit und fügen Sie sie hinzu, indem Sie den folgenden Befehl ausführen:

 npm install react-google-maps --save-dev

was einen neuen Eintrag in unserer package.json und das Paket in node_modules .

So erstellen Sie eine WordPress-Komponente, die eine React-Komponente kapselt

Wenn wir uns die Dokumentation dieses React-Projekts für Google Maps weiter ansehen, werden wir sehen, dass sie uns empfehlen, ihre GoogleMap Komponente mit unserer eigenen Komponente zu umhüllen. Sobald es gekapselt ist, müssen wir unsere Komponente in unserem Plugin verwenden.

Nun, lassen Sie uns ihrem Beispiel folgen und eine Komponente namens MapBlock in einer eigenen Datei map-block.js . Und das ist es! Wir haben jetzt eine Kartenkomponente fertig, die wir in unserem Gutenberg-Block verwenden können.

So fügen Sie Blockeinstellungen im Inspektor des WordPress-Editors hinzu

Der nächste Schritt besteht darin, zu konfigurieren, wie diese Karte im Editor aussehen soll, und einige Einstellungen hinzuzufügen, um ihr Aussehen zu optimieren. Dazu müssen wir mehrere Einstellungsabschnitte in der Gutenberg-Seitenleiste hinzufügen. Wie ich bereits ausgeführt habe, erreichen wir dies mit einer Komponente, die wir Inspector genannt haben und die wir in der Datei inspector.js definiert haben.

Wenn Sie sich diese Datei ansehen, werden Sie feststellen, dass sie dem gleichen Muster wie immer folgt: Wir definieren eine Component mit einer render . Diese Methode ruft die relevanten Attribute in this.props und gibt JSX mit allen Steuerelementen zurück. In diesem speziellen Fall gibt es eine Instanz von InspectorControls (dies teilt WordPress mit, dass dieser Inhalt in die Seitenleiste geht) mit mehreren PanelBody Abschnitten zurück. Sehen wir uns jeden Abschnitt im Detail an.

Grundlegende Karteneinstellungen

Der erste von uns gefundene PanelBody (Zeile 47) hat keinen title und erscheint daher immer als Abschnitt, der nicht geschlossen werden kann:

Der Abschnitt definiert ein Paar RangeControl s, deren Ergebnis Sie im vorherigen Screenshot sehen können. Mit diesen beiden Steuerelementen können wir die Höhe der Karte und ihre Zoomstufe ändern.

Ein weiterer interessanter und einfacher Abschnitt befindet sich in Zeile 121. Hier fügen wir einige Optionen hinzu, um die Schaltflächen zu aktivieren oder zu deaktivieren, die auf der Karte angezeigt werden sollen, wenn sie im Frontend angezeigt werden:

Dazu müssen wir einfach die Standard-WordPress-Komponente CheckboxControl .

So fügen Sie einen benutzerdefinierten Stilabschnitt für unseren Kartenblock hinzu

Ein weiterer interessanter Abschnitt unseres Blocks ist der Stilabschnitt (Zeile 68). Das Endergebnis sehen Sie im folgenden Screenshot:

Es ist ein besonderer Abschnitt, da die von uns verwendete Komponente ( MapStyles ) nicht standardmäßig in WordPress vorhanden ist, sondern etwas, das wir speziell für diesen Block erstellt haben. Wie Sie im vorherigen Link sehen können, handelt es sich um eine Komponente, die eine Reihe vordefinierter Stile in eine Komponente vom Typ ImagePicker (die es übrigens auch nicht standardmäßig in WordPress gibt – Sie finden sie in packages/components/image-picker/ ).

Wenn der Benutzer einen der in ImagePicker enthaltenen Stile auswählt, ruft die MapStyles -Komponente die onChange -Funktion auf (siehe Zeile 76 von inspector.js ) und übergibt zwei Werte: den Namen des ausgewählten Stils und den zugehörigen JSON.

Beachten Sie schließlich, dass eine der Optionen, die MapStyles enthält, ein benutzerdefinierter Stil ist:

Bei Auswahl rendert die Komponente ein zusätzliches Textfeld (Zeile 45), damit der Benutzer seinen eigenen Stil im JSON-Format eingeben kann. Falls Sie es nicht wussten, die Karten von Google Maps können stark angepasst werden!

So fügen Sie unserer Karte einen Marker hinzu

Der nächste Abschnitt, den wir haben, ist derjenige, der unseren Marker steuert (Zeile 81). In diesem Abschnitt können wir den Marker ein- oder ausblenden (Zeile 86) und gibt uns, wenn er aktiv ist, einige zusätzliche Einstellungen:

Wie Sie sehen, erscheint ein Suchfeld zum Suchen nach Orten in Google Maps (das wir wiederum mit einer benutzerdefinierten Komponente namens AddressSearch haben) und die Möglichkeit, den Textblock ein- oder auszublenden, in dem zusätzliche Informationen über die Markierung eingefügt werden können .

Beachten Sie übrigens, dass die AddressSearch Komponente auf einer Komponente namens StandaloneSearchBox basiert, die ebenfalls Teil des React-Projekts ist. Welch ein Vergnügen, die Arbeit anderer wiederzuverwenden!

So konfigurieren Sie die Symbolleiste eines Blocks

Das letzte, was wir besprechen müssen, ist die Symbolleiste. Wenn Sie verstanden haben, wie die Seitenleiste funktioniert, ist die Symbolleiste ein Kinderspiel.

Die Symbolleiste unseres Plugins wird durch die in ToolbarControls definierte ToolbarControls-Komponente toolbar.js . Hier fügen wir einfach eine Komponente hinzu, um die Ausrichtung des Blocks zu definieren ( BlockAlignmentToolbar , in Zeile 42), ein Paar Dropdown-Menüs, um die Karte zu zentrieren (Zeile 50) und um die Position der Markierung zu ändern (Zeile 79) und ein paar zusätzliche Schaltflächen, um die Position des Textfelds zu ändern, in das wir zusätzliche Informationen über die Markierung einfügen können (Zeile 107 und 120).

Zusammenfassend

Heute haben wir gesehen, wie man die gesamte Bearbeitungsoberfläche unseres Kartenblocks erstellt. Wie Sie sehen, ist es ein Prozess, der auf den ersten Blick kompliziert erscheinen mag, aber schnell ganz natürlich wird. Am Ende besteht das Geheimnis darin, von einem gut organisierten Beispiel auszugehen (wie es bei unserem Plugin-Boilerplate der Fall ist) und die Schnittstelle Schritt für Schritt aufzubauen, indem man die von WordPress angebotenen oder bereits vorhandenen Komponenten wiederverwendet oder sogar eigene erstellt.

Bis nächste Woche mit dem letzten Teil dieses Tutorials, in dem wir sehen, wie wir unsere Karte speichern und im Frontend anzeigen können.

Vorgestelltes Bild von rawpixel auf Unsplash .