JavaScript Plugins API

Neben den schon von PHP bekannten Hooks (Action und Filter), gibt es in nun auch eine API um Erweiterungen für den Editor zu erstellen.

Slot / Fill

Die JS Plugins API basiert auf Slots, die mit sogenannten Fills erweitert werden können. Unter Slots versteht man erweiterbare Bereiche, denen UI Elemente hinzugefügt werden können. Beispiele für Slots im Editor sind Einträge in Menüs, Buttons in der Toolbar, Elemente in der Sidebar oder zusätzliche Sidebars.

Man kann also eigene React Komponenten erstellen und diese an den jeweiligen Slots rendern lassen. Ein Slot kann dabei mehrere Fills enthalten.

Beispiel Post Status Panel

Zuerst wird mit Hilfe der Funktion createSlotFill ein Fill und ein Slot erstellt (Zeile 3). In Zeile 5 – 11 wird der Fill definiert. Jeder Fill wird mit einem PanelRow Element umgeben und kann eine Klasse als Parameter entgegen nehmen.

import { createSlotFill, PanelRow } from '@wordpress/components';

export const { Fill, Slot } = createSlotFill( 'PluginPostStatusInfo' );

const PluginPostStatusInfo = ( { children, className } ) => (
	<Fill>
		<PanelRow className={ className }>
			{ children }
		</PanelRow>
	</Fill>
);

PluginPostStatusInfo.Slot = Slot;

export default PluginPostStatusInfo;

An der Stelle, an der dieser Slot gerendert wird, importiert man diese Komponente. PluginPostStatusInfo.Slot enthält eine Funktion, die ausgeführt wird, sobald ein Fill gerendert wird. In diesem Fall die weiteren Komponenten der Sidebar. Die registrierten Fills werden in Zeile 14 mit Hilde von { fills } ausgegeben.

import PluginPostStatusInfo from '../plugin-post-status-info';

... 

<PluginPostStatusInfo.Slot>
	{ ( fills ) => (
		<Fragment>
			<PostVisibility />
			<PostSchedule />
			<PostFormat />
			<PostSticky />
			<PostPendingStatus />
			<PostAuthor />
			{ fills }
			<PostTrash />
		</Fragment>
	) }
</PluginPostStatusInfo.Slot>

...
Position für das Slot Beispiel
An dieser Position werden die Fills gerendert.

Plugin registrieren

const { registerPlugin } = wp.plugins;
registerPlugin( name: string, settings: Object )

Um ein eigenes Plugin zu registrieren wird die Funktion registerPlugin aus dem Paket Plugins verwendet.

Als name wird ein eindeutiger Bezeichner übergeben, um das Plugin zu identifizieren. Das setting Objekt enthält ein optionales Icon für das UI (Dies ist nicht für alle Plugins nötig) und eine React Komponente mit den UI Elementen, die hinzugefügt werden sollen.

const { PluginPostStatusInfo } = wp.editPost;
const { registerPlugin } = wp.plugins;

const MyPluginPostStatusInfo = () => (
	<PluginPostStatusInfo
		className="my-plugin-post-status-info"
	>
		My post status info
	</PluginPostStatusInfo>
);

registerPlugin( 'my-plugin-post-status-info', {
	render: MyPluginPostStatusInfo,
} );

Die Render-Komponente im Settings-Objekt enthält einen oder mehrere Fills, in diesem Beispiel das PluginPostStatusInfo Element. Dieses Element enthält den Inhalt (hier: „My post status info„), der in den Slot gerendert werden soll.

Ergebnis des Beispiel Plugins
JS Plugin mit Fill/Slot

Eigene Bock-Stile erstellen

In den Block-Einstellungen kannst du im Bereich Erweitert über ein Textfeld ganz einfach einem Block weitere Klassen hinzufügen. Diese Klassen können genutzt werden, um das Aussehen per CSS zu ändern und so bsw. eine andere Button Form und Größe darzustellen. Mit der Block-Style API bekommst du eine weitere Möglichkeit, die es erlaubt Blöcken weitere Klassen zu geben. Der Vorteil dieser API ist es, dass die Klassen vordefiniert werden können, der Editor ein Interface erstellt und eine Vorschau des Stils angezeigt wird.

Stile für eigene Blöcke

Ein Beispiel für Block-Stile ist bereits im Zitat-Block vorhanden, hier gibt es die Stile „Normal“ und „Groß“, die jeweils eigene CSS Definition haben. Über das erste Icon in der Block-Toolbar kannst du ein Menü öffnen, über das du die Block-Stile auswählen oder den Block in einen andern Typ umwanden kannst. Auf der rechten Seite erhältst du gleich eine Vorschau, wie die Block mit dem Stil aussehen wird.

Block-Stile Menü für den Zitate Block
Block-Stile im Zitat-Block

In der Block-Definition (/block-library/src/quote/index.js) sind diese wie folgt definiert:

styles: [
	{ name: 'default', label: __( 'Regular' ), isDefault: true },
	{ name: 'large', label: __( 'Large' ) },
]

Styles ist ein Array mit den Stil-Objekten. Jedes Object hat dabei einen Namen, der für die Klasse verwendet wird. Aus name: ‚large‘ wird class=“is-style-large“. Das Label wird im Toolbar Menü angezeigt. Über den Parameter isDefault kannst du festlegen, welcher Stil vorausgewählt sein soll.

<blockquote class="wp-block-quote is-style-large">
	<p>Lorem ipsum dolor sit amet...</p>
	<cite>Das ist ein Beispiel</cite>
</blockquote>

Bestehende Blöcke erweitern

Neben der Stil Deklaration in der Block-Definition kannst du mit Hilfe eines Hooks auch Stile zu bereits bestehenden Blöcken hinzufügen. Wenn du beispielsweise einen eigenen Button-Stil hinzufügen möchtest, reichen die folgende JavaScript und CSS Anweisungen.

Mit der Funktion registerBlockStyle() registrierst du den Stil im Editor. Der erste parameter ist der registrierte Name des Blocks, bestehend aus namespace/block-name, der zweite Parameter ist ein Objekt mit mit dem Namen und dem Label.

wp.blocks.registerBlockStyle( 'core/button', { name: 'red-button', label: 'Rot' });

Der Editor erzeugt nun die Klasse is-style-red-button. Für diese Klasse kannst du eine CSS Anweisung erstellen, um so die Darstellung des Button zu definieren.

.wp-block-button.is-style-red-button .wp-block-button__link {
	background: #cf2e2e;
	text-transform: uppercase;
	border-radius: 0;
}

Im Editor sieht es dann folgendermaßen aus. Der Stil wird im Stil-Menü angezeigt und wenn du nun mit der Maus über den Stil gehst oder per Tastatur diesen auswählst, wird eine große Vorschau auf der rechten Seite dargestellt.

Block-Stil Menü für einen eigenen Button Stil
Eigener Block-Stil im Editor

Eigene Farben definieren

Einige Blöcke bieten die Möglichkeit Farben von bestimmten Elementen im Block anzupassen. Dies sind zum Beispiel die Hintergrundfarbe eines Buttons oder die Textfarbe eines Absatzes. Gutenberg liefert schon 11 vordefinierte Farben mit.

Neben den Farben gibt es auch eine Möglichkeit mit einem Farbmischer eine eigene Farbe zu mischen.

Farbwähler in Gutenberg

Mit folgenden Code lässt sich der Farbmicher deaktivieren, sodass nur die vordefinierten Farben verwendet werden können.

add_theme_support( 'disable-custom-colors' );

Vordefinierte Farben überschreiben

Themes haben die Möglichkeit die vordefinierten Farben zu überschreiben, die in der Farbwahl Palette in allen Komponenten angezeigt werden sollen.

function mytheme_add_custom_colors() {
	add_theme_support( 'editor-color-palette', array(
		// Fügt eine goldene Farbe hinzu.
		array(
			'name' => __( 'gold', 'themeLangDomain' ),
			'slug' => 'nitschmahler-gold',
			'color' => '#ae9a63',
		),
	) );
}

add_action( 'after_setup_theme', 'mytheme_add_custom_colors' );
Angepasste Farbwahl Komponente
Farbwahl Komponente

Man ruft die add_theme_support Funktion auf und übergibt als Parameter den Wert „editor-color-palette“ und ein Array mit den Farbdefinitionen. Jede Farbe ist dabei ein Array, das die Werte „name„, „slug“ und „color“ enthält.

  • Name: Der Name der angezeigt wird, dieser sollte übersetzbar sein.
  • Slug: Der Wert, der abgespeichert wird und aus dem die CSS Klasse generiert wird.
  • Color: Der Hex-Wert der Farbe um eine Vorschau zu zeigen.

Beim Auswählen einer Farbe wird bsw. im Button ein Attribut mit dem Slug „nitschmahler-gold“ abgespeichert und eine eine Klasse ‚has-nitschmahler-gold-background-color‚ zum Element hinzugefügt

<!-- wp:button {"backgroundColor":"nitschmahler-gold"} -->
<div class="wp-block-button alignnone">
<a class="wp-block-button__link has-background has-nitschmahler-gold-background-color">Mein Button</a>
</div>
<!-- /wp:button -->

Für diese Klasse muss man nun noch eine CSS Definition erstellen. Diese Definition muss im Editor und im direkt in der Seite geladen werden.

// Für die Hintergrudnfarbe
.has-nitschmahler-gold-background-color {
	color: #ae9a63;
}
// Für die Textfarbe
.has-nitschmahler-gold-color {
	color: #ae9a63;
}

Fertig ist der Button:

Fertiger Button

Gutenberg Linktipps #4

Voraussetzungen für den Erfolg

Morten Rand-Hendriksen hat den zweiten Artikel in seiner "Gutenberg and the Future of WordPress"-Reihe veröffentlicht. In Conditions for Success beschreibt Morten, ähnlich wie schon Daniel Bachhuber, was für eine erfolgreiche Einführung von Gutenberg notwendig ist. Er geht dabei auf die Punkte Accessibility, eine lange Test- und Übergangsphase, sowie einen möglichen Fork und was dieser als Konsequenzen hätte, ein.

WYSIWYG und Accessibility

Amanda Rush hat sich einige Gedanken zu WYSIWYG-Editoren und Gutenberg im Bezug zu Accessibility gemacht. Sie sieht Gutenberg mittlerweile auf einen guten Weg, bemängelt aber, dass es zu wenig Dokumentation gibt um das Konzept des neuen Editors zu erklären.

Page Builders in einer Gutenberg Welt

Robby McCullough von Beaver Builder beschreibt in seinem Artikel Page Builders in a Gutenberg World warum Page Builder auch mit Gutenberg noch gebraucht werden und wie sie Kompatibilität zwischen den Editoren umgehen wollen.

Gutenberg 1.9

Am 11. Dezember wurde die mit Gutenberg 1.9 die 19. Betaversion veröffentlicht. Eine ausführliche Zusammenfassung mit allen Änderungen ist im Core Make-Blog zu finden,

Die größte Neuerung des Release sind die globalen wiederverwendbaren Blöcke, aber es gibt auch Verbesserungen bei den Templates (diese können nun gesperrt werden), Versionierung von Blockattributen, so dass Markup migriert werden kann, und viele Erweiterungen und Bugfixes.

Gutenberg Linktipps #3

3 Dinge die man über Gutenberg wissen sollte

Im Artikel WordPress is Changing. Here are 3 Things You Need to Know About Gutenberg beschreibt Morten Rand-Hendriksen wie man sich auf Gutenberg vorbereitet, warum Gutenberg mehr als ein Editor ist und wie man dabei mithelfen kann.

State of the Word Transcript

Im TinyMCE Block gibt es das vollständige Transcript der State of the Word Session vom WordCamp US 2017 zum Nachlesen.

Warum sich Josh Pollock nun auf Gutenberg freut

Josh Pollock ist Core Contributor und Entwickler des Caldera Forms Plugins. In seinem Artikel Why I Came Back From Nashville All Excited About Gutenberg erklärt warum er vor dem WordCamp US das Gutenberg Projekt sehr skeptisch gesehen hat und was sich daran nun geändert hat. Viele Kritikpunkte wurden behoben, einige neue interessante Funktionen sind hinzugekommen und das Ziel von Gutenberg ist nun besser erkennbar.

Gutenberg Linktipps #2

Wie Gutenberg ein Erfolg werden kann

Daniel Bachhuber hat sich einige Gedanken gemacht, wie wir es schafften, dass die überwiegende Mehrheit der WordPress Benutzer ab dem ersten Tag von Gutenberg begeistert ist und ihn ohne Probleme nutzen kann. Hierfür sieht er 2 Vorraussetzungen: Gute UX und Kompatibilität. Seine Idee, wie dies erreicht werden könnte, ist im Artikel Landing Gutenberg in WordPress 5.0 nachzulesen.

Gutenberg und Publishers

Im August auf dem WordCamp for Publishers hat Aaron Jorbin eine Session zu Gutenberg gehalten. nach einer kurzen Präsentation und Demo gab es eine Diskussion in der die Anforderungen für Publisher an Gutenberg diskutiert wurden. In seinem Blogbeitrag Gutenberg and Publishers fasst Aaron die ausführliche Diskussion zusammen.

Was WordPress VIPs über Gutenberg wissen müssen

Das WordPress VIP Programm von Automattic richtet sich an Enterprise Kunden und Agenturen für die Entwicklung, Hosting und Support großer Seiten. Im Artikel The New WordPress Editor: What You Need to Know about Gutenberg fasst Steph Yiu die Konzepte des Editors und den aktuellen Stand zusammen und beschreibt, wie sich die Kunden mit ihren Teams darauf vorbereiten können.

Gutenberg Linktipps #1

Werbung in der Gutenberg Welt

Im Artikel Ads in a Gutenberg World macht sich Helen Hou-Sandi darüber Gedanken, wie Werbung in Blocks aussehen könnte. Es wäre möglich Werbung automatische in jedem 5. Block auszuspielen oder bereits bei Beginn Werbeanzeigen darzustellen, um die der Inhalt geschrieben wird. Dies ist allerdings nur eine Überlegung was möglich wäre. Ebenfalls nennt sie noch ein paar Schnittstellen, die dafür nötig wären diese Funktionalität in Gutenberg zu integrieren.

Werbeblöcke in Gutenberg

Die Strategie hinter Gutenberg

Der Webworker Torsten Landsiedel hat einige Bedenken zur Einführung von Gutenberg in seinem Artikel State of the word – oder auch Tomorrowland zusammengefasst. Er nennt zum einen den frühzeitigen Merge in den Core, als auch die Kommunikationsstrategie als Probleme. Torsten selbst ist im Supportbereich aktiv und hat hier aus Erfahrungen kein Gutes Gefühl, wenn ein unfertiges Produkt auf den Kunden losgelassen wird. Lesenswert ist auch die Diskussion in den Kommentaren unter dem Beitrag.

State of the Word

In seiner jährlichen Keynote "State of the Word" sprach Matt Mullenweg am 2. Dezember beim WordCamp US in Nashville über das vergangene Jahr in der "WordPress-Welt". Dabei gab es neben einer Gutenberg Präsentation von Matias Ventura auch einige Ausblicke auf die Pläne des kommenden Jahres. Matt glaubt, dass es noch ungefähr 12 Iterationen, also rund 4 Monate (April 2018) dauern wird, bis Gutenberg für den Massenmarkt bereit ist. Neben dem Editor sind der Customizer und Themes Gutenberg Entwicklungs-Schwerpunkte, die im nächsten Jahr angegangen werden. In einer Q&A nach dem Talk wurden noch einige Fragen rund um Gutenberg beantwortet.

Das Video gibt es jetzt online auf WordPress.tv zu sehen. Gute Zusammenfassungen des Talks sind auf Krautpress.de (Deutsch) und Poststatus.com (Englisch) zu finden.

Gutenberg 1.8

Am 28.11.2017 wurde mit Gutenberg die 18. Beta Version des Plugins veröffentlicht. Diese kann zu Testzwecken über das offizielle Plugin Verzeichnis heruntergeladen werden.

Die neue Version 1.8 bring einige Verbesserungen unter der Haube mit sich, um Plugins mehr Möglichkeiten zu bieten Gutenberg anzupassen. Dies betrifft zum einen die Erweiterung bestehender Blöcke, die Eingrenzung verfügbarer Blöcke oder die Einstellungsmöglichkeit von Meta-Boxen, ob sie unter Gutenberg erscheinen sollen. Eine weitere Interessante Funktion sind die Block Templates, die ich bereits in einem eigenen Artikel vorgestellt habe.

Meta Box Kompatibilität

Wenn eine Meta Box nicht mit Gutenberg funktioniert und der Entwickler kein Update liefern möchte oder kann, so kann er beim Initialisieren das __block_editor_compatible_meta_box Argument mit angeben.

add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
    null, 'normal', 'high',
    array(
        '__block_editor_compatible_meta_box' => false,
    )
);

Ist der Wert auf false gesetzt, so wird nicht der Gutenberg Editor geladen, sondern WordPress fällt auf den Classic Editor zurück und die Box funktioniert weiterhin.

Wenn eine Meta Box in eine Blockfunktion umgewandelt wurde, so kann der Entwickler mit __back_compat_meta_box angeben, dass die Box nur im Classic Editor aber nicht unter Gutenberg angezeigt wird.

add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
    null, 'normal', 'high',
    array(
        '__back_compat_meta_box' => false,
    )
);

Weitere Infos zu den Meta Boxen findet ihr im Gutenberg Handbuch.

Weitere Neuerungen

Aber auch an der Benutzeroberfläche hat sich einiges getan. So worden einige Elemente nach User-Feedback verbessert und die Unterstützung auf mobilen Geräten verbessert. Beim Veröffentlichungs-Ablauf wurden die ersten Verbesserungen umgesetzt, weitere werde in den nächsten Versionen folgen.

Ein heiß diskutiertes Thema sind die Textfarben und Hintergründe, die man selbst definieren kann. In dieser Version ist ein Kontrast-Checker hinzugekommen, der prüft ob die Texte mit den Farben gut lesbar sind und somit barrierefrei bleiben.

Eine vollständige Übersicht der Änderungen gibt es im Make-Blog auf WordPress.org.