Veel mensen klagen dat het lastig is om aan de slag te gaan met het bouwen van Gutenberg blokken en -apps. De leercurve is steil, voornamelijk omdat het moeilijk is de ontwikkelomgeving te installeren en configureren. Daarnaast zijn een gedegen kennis van JavaScript, Node.js, React en Redux onmisbare ingrediënten voor dit vrij complexe recept.

Het officiële WordPress Block Editor handboek biedt ontwikkelaars een enorme hoeveelheid informatie, maar het kan zijn dat je verdwaalt in de zee van details.

En het is de moeite waard om te vermelden wat Matías Ventura, hoofdarchitect van het Gutenberg project, meldde in zijn interview met WP Tavern:

Hoewel er mensen zijn die het snel kunnen leren, is het nog steeds een grote barrière voor mensen. Ik denk dat er verschillende lagen zijn; documentatie zou zowel qua organisatie als presentatie een orde van grootte beter kunnen zijn. Ik hoop dat we daar nog veel kunnen doen.

Met dat in gedachten hebben we besloten om een ​​stapsgewijze tutorial aan te bieden om onze lezers te helpen aan de slag te gaan met de ontwikkeling van Gutenberg blokken.

Klinkt interessant? Laten we erin duiken!

Vereisten voor Gutenberg blokontwikkeling

Voor deze tutorial zijn de enige vereiste vaardigheden een goede kennis van de ontwikkeling van WordPress plugins en ten minste een basiskennis van HTML, CSS, JavaScript en React.

Wordt dit een ambitieus project? Reken daar maar op!

Het was niet eenvoudig om het juiste compromis tussen volledigheid en eenvoud te vinden of te beslissen welke onderwerpen wel en niet moesten worden opgenomen.

Hopelijk zullen gemiddelde en gevorderde lezers ons vergeven dat we niet diep in bepaalde concepten zijn gedoken, zoals de React-status, Redux-winkel, hoogwaardige componenten, enzovoort. Deze onderwerpen vereisen extra ruimte en aandacht en zijn waarschijnlijk te geavanceerd voor het ontwikkelen van beginnende blokken (tenzij je een React-ontwikkelaar bent).

Om dezelfde reden zullen we enkele van de meer geavanceerde onderwerpen met betrekking tot de ontwikkeling van Gutenberg blokken, zoals dynamische blokken en metaboxen, niet behandelen.

Met de kennis die je aan het einde van dit artikel opdoet, kun je meteen beginnen met plezier maken en productief zijn.

Als je eenmaal aan de slag gaat met het bouwen van blokken, ben je klaar om je vaardigheden verder te verbeteren en zelf nog geavanceerdere Gutenberg blokken te bouwen.

Beginnen met het ontwikkelen van blokken in Gutenberg kan in het begin intimiderend zijn ...😵‍💫 Maar geen zorgen! Deze complete gids voor beginners staat voor je klaar🙏Click to Tweet

 

Wat is een Gutenberg blok?

Sinds de release in december 2018 is de Block Editor in alle opzichten sterk verbeterd: krachtigere API’s, een geavanceerdere gebruikersinterface, verbeterde bruikbaarheid, een heleboel nieuwe blokken, de eerste implementaties van Full Site Editing en nog veel meer.

Kortom, Gutenberg is nog volop in ontwikkeling en heeft al een lange weg afgelegd, maar desalniettemin is de Bock Editor een volwaardige kandidaat als een betrouwbare, functionele pagina- en sitebouwer.

Vanuit het oogpunt van een ontwikkelaar is Gutenberg een op React gebaseerde Single Page Application (SPA) waarmee WordPress gebruikers inhoud in WordPress kunnen maken, bewerken en verwijderen. Dit zou je echter niet moeten doen denken aan een verbeterde versie van de traditionele inhoudseditor.

Dit willen we duidelijk maken:

In Gutenberg is de inhoud verdeeld in blokken, dit zijn ‘stenen’ die gebruikers kunnen gebruiken om berichten en pagina’s of hun volledige websites te maken.

Maar wat is technisch gezien een blok?

We zijn wel fan van de definitie van WordPress:

“Blok” is de abstracte term die wordt gebruikt om eenheden van opmaak te beschrijven die, samengesteld, de inhoud of layout van een webpagina vormen. Het idee combineert concepten van wat we tegenwoordig in WordPress bereiken met shortcodes, aangepaste HTML en embed discovery in een enkele consistente API en gebruikerservaring.

Titels, alinea’s, kolommen, afbeeldingen, galerijen en alle elementen waaruit de interface van de editor bestaat, van zijbalkpanelen tot blokbesturingselementen, zijn React componenten.

Maar wat zijn React componenten? W3Schools geeft de volgende definitie:

Componenten zijn onafhankelijke en herbruikbare stukjes code. Ze hebben hetzelfde doel als JavaScript functies, maar werken afzonderlijk en retourneren HTML via een render() functie.

Werken met Gutenberg blokken in WordPress 5.8.
Werken met Gutenberg blokken in WordPress 5.8.

Hoewel de bewerkingservaring van Gutenberg nieuw is in vergelijking met de klassieke WordPress editor, verandert de manier waarop WordPress je stukken inhoud in de database opslaat niet. Dat komt omdat Gutenberg een applicatie is die binnen WordPress werkt, maar de manier waarop het CMS in de kern werkt niet verandert.

Artikelen (en dit zijn berichten, pagina’s en aangepaste berichttypen) die met Gutenberg zijn gemaakt, worden nog steeds opgeslagen in de wp_posts  tabel, precies zoals met de klassieke editor.

Maar in een bericht dat met Gutenberg is gemaakt, vind je extra stukjes informatie in de tabel die een fundamenteel verschil vertegenwoordigen tussen berichten die zijn gemaakt via de klassieke editor versus Gutenberg.

Deze stukjes informatie zien eruit als HTML opmerkingen en hebben een specifieke functie: scheidingsblokken.

Een blogbericht in de Code editor.
Een blogbericht in de Code editor.

Blokscheidingstekens vertellen WordPress welk blok op het scherm moet worden weergegeven. Ze bieden ook waarden voor blokeigenschappen in een JSON object. Die rekwisieten bepalen de manier waarop het blok op het scherm moet worden weergegeven:

Een blogbericht opgeslagen in de wp_poststabel.
Een blogbericht opgeslagen in de wp_posts tabel.

Je WordPress ontwikkelomgeving instellen

Het opzetten van een moderne JavaScript ontwikkelomgeving vereist een gedegen kennis van geavanceerde technologieën zoals Webpack, React en JSX, Babel, ESLint, etc.

Geïntimideerd? Niet nodig! De WordPress community is te hulp gekomen door krachtige tools te bieden waarmee je een rommelig handmatig configuratieproces kunt vermijden.

Om het simpel te houden, behandelen we transpilen niet in dit artikel (wat we toch aanraden om jezelf vertrouwd mee te maken als je eenmaal de basis van blokontwikkeling hebt geleerd). In plaats daarvan introduceren we twee alternatieve tools die je kunt gebruiken om binnen enkele minuten snel en eenvoudig een moderne JavaScript ontwikkelomgeving op te zetten. Het is aan jou om degene te kiezen die je het handigst vindt voor je project.

Het opzetten van een JavaScript ontwikkelomgeving om Gutenberg blokken te bouwen is een proces in drie stappen:

  1. Installeer Node.js en npm
  2. Stel de ontwikkelomgeving in
  3. Stel de blokplugin in

Laten we beginnen.

1. Installeer Node.js en npm

Voordat je je ontwikkelomgeving installeert en je eerste blok registreert, moet je Node.js en de Node-pakketmanager (npm) installeren.

Je kunt Node.js en npm op verschillende manieren installeren. Maar eerst wil je misschien controleren of de software al op je computer is geïnstalleerd.

Om dit te doen, start je de terminal en voer je de volgende opdracht uit:

node -v

Als het resultaat command not found is, is Node.js niet op je computer geïnstalleerd en kun je doorgaan met de installatie.

Voor dit artikel hebben we de eenvoudigste installatie-optie gekozen, namelijk de Node Installer. Het enige wat je hoeft te doen is de versie te downloaden die overeenkomt met je besturingssysteem en de installatiewizard te starten:

Node.js downloadpagina.
NNode.js downloadpagina.

Nadat je Node.js hebt geïnstalleerd, voer je de opdracht node -v  opnieuw in je terminal uit. Je kunt ook de opdracht nmp -v uitvoeren om te bevestigen dat het npm pakket beschikbaar is.

Je bent nu uitgerust met de volgende tools:

  • De npx Node.js package runner (zie documenten). Hiermee kun je een npm opdracht uitvoeren zonder deze eerst te installeren.
  • De npm  Node.js package manager (zie documenten). Dit wordt gebruikt om dependencies te installeren en scripts uit te voeren.

De volgende stap is het installeren van de ontwikkelomgeving.

2. Stel je ontwikkelomgeving in

Zodra je de nieuwste versies van Node.js en npm op je lokale computer hebt staan, heb je een ontwikkelomgeving voor WordPress nodig.

Je kunt een lokale ontwikkelomgeving zoals DevKinsta of de officiële WordPress tool gebruiken. Laten we een kijkje nemen naar beide opties.

Optie 1: Lokale ontwikkelomgeving (DevKinsta)

Met slechts een paar klikken kun je WordPress lokaal installeren met DevKinsta, onze moderne lokale WordPress ontwikkeltool. Of je kunt kiezen voor een andere lokale ontwikkelingstool, zoals MAMP of XAMPP:

Maak een nieuwe WordPress website in DevKinsta.
Maak een nieuwe WordPress website in DevKinsta.

Optie 2: wp-env

Je kunt ook kiezen voor de officiële wp-env -tool, die een lokale WordPress ontwikkelomgeving biedt die je rechtstreeks vanaf de opdrachtregel kunt starten. Noah Alen definieert het als volgt:

Lokale WordPress omgevingen zijn nu net zo eenvoudig als het uitvoeren van een enkele opdracht. wp-env is een nulconfiguratietool voor pijnloze lokale WordPress omgevingen. Het biedt vele opties, zodat gebruikers WordPress snel kunnen opstarten zonder tijd te verspillen. Het doel is inderdaad om deze omgevingen voor iedereen gemakkelijk toegankelijk te maken – of je nu een ontwikkelaar, ontwerper, manager of iemand anders bent.

Als je besluit om het eens te proberen, vereist het installeren van wp-env minimale inspanning. Volg gewoon deze stappen:

Stap 1: Bevestig de installatie van Docker en Node.js

Om aan de technische vereisten te voldoen, moetje eerst zowel Docker als Node.js op je computer hebben geïnstalleerd. Dat komt omdat wp-env  een Docker instantie maakt waarop een WordPress website wordt uitgevoerd. Alle wijzigingen die in de code worden aangebracht, worden onmiddellijk weergegeven in de WordPress instantie.

Stap 2: Installeer @wordpress/env vanaf de opdrachtregel

Met Docker en Node.js op je computer kun je doorgaan en de WordPress ontwikkelomgeving installeren.

Je kunt wp-env wereldwijd of lokaal installeren. Om het wereldwijd te doen, moet je de volgende opdracht uitvoeren vanuit de map met plugins (meer hierover in het onderstaande berichtvenster “Belangrijk”):

npm install -g @wordpress/env

Laten we dat opsplitsen:

Voer de volgende opdracht uit om te bevestigen dat wp-env is geïnstalleerd:

wp-env --version

Je zou de huidige wp-env  versie moeten zien, wat betekent dat je de omgeving nu kunt starten met de volgende opdracht uit van je plugin’s map:

wp-env start

Je hebt toegang tot het WordPress dashboard via de volgende link:

  • http://localhost:8888/wp-admin/

De standaardreferenties zijn als volgt:

  • Gebruikersnaam: admin
  • Wachtwoord: password

Stel je blokplugin in

Nu heb je een startblok plugin nodig om op voort te bouwen. Maar in plaats van handmatig een plugin voor ontwikkelingsblokken te maken met alle benodigde bestanden en mappen, kun je eenvoudig een dev-tool uitvoeren die alle bestanden en configuraties biedt die je nodig hebt om aan de slag te gaan met blokontwikkeling.

Nogmaals, je hebt een aantal opties om uit te kiezen. Laten we ze eens bekijken.

Optie 1: een blokplugin instellen met @wordpress/create-block

@wordpress/create-block is de officiële nulconfiguratietool voor het maken van Gutenberg blokken:

Create Block is een officieel ondersteunde manier om blokken te maken voor het registreren van een blok voor een WordPress plugin. Het biedt een moderne build-setup zonder configuratie. Het genereert PHP, JS, CSS code en al het andere dat je nodig hebt om het project te starten.

Het is grotendeels geïnspireerd op de create-react-app. Dikke pluim voor @gaearon, het hele Facebookteam en de React community.

Zodra je lokale omgeving actief is, kun je een startblok instellen door simpelweg de opdracht npx @wordpress/create-block  uit te voeren, en het zal alle bestanden en mappen bieden die je nodig hebt om de plugin-steiger te maken en een nieuw blok te registreren .

Laten we een test uitvoeren om te zien hoe het werkt.

Navigeer vanuit je opdrachtregelprogramma naar de map /wp-content/plugins/ en voer de volgende opdracht uit:

npx @wordpress/create-block my-first-block

Wanneer er wordt gevraagd om te bevestigen, voer je y in om door te gaan:

Een blok maken met @wordpress/create-block.
Een blok maken met @wordpress/create-block.

Het proces duurt enkele ogenblikken. Wanneer het voltooid is, zou je het volgende antwoord moeten krijgen:

De blokplugin is gemaakt.
De blokplugin is gemaakt.

En dat is alles!

Start nu je WordPress ontwikkelomgeving en ga naar het scherm Plugins in het WordPress dashboard. Een nieuwe plugin met de naam “My First Block” zou aan je pluginlijst moeten zijn toegevoegd:

De blokplugin is succesvol geïnstalleerd.
De blokplugin is succesvol geïnstalleerd.

Activeer indien nodig de plugin, maak een nieuwe blogpost, scrol omlaag in de blokinvoeger naar het gedeelte Widgets en selecteer je nieuwe blok:

Een voorbeeldblok gemaakt met @wordpress/create-block.
Een voorbeeldblok gemaakt met @wordpress/create-block.

Ga nu terug naar de terminal en verander de huidige directory in my-first-block:

cd my-first-block

Voer vervolgens de volgende opdracht uit:

npm start

Hierdoor kun je de plugin in de ontwikkelingsmodus uitvoeren. Om de productiecode te maken, moet je de volgende opdracht gebruiken:

npm run build

Optie 2: een blokplugin instellen met create-guten-block

create-guten-block is een externe ontwikkelingstool voor het bouwen van Gutenberg blokken:

create-guten-blockis een nulconfiguratie dev-toolkit (#0CJS) om WordPress Gutenberg blokken in enkele minuten te ontwikkelen zonder React, webpack, ES6/7/8/Next, ESLint, Babel, etc. te configureren.

Net als de officiële create-block tool, is create-guten-block gebaseerd op de create-react-app en kan het je helpen om zonder gedoe je eerste blokplugin te genereren.

De toolkit biedt alles wat je nodig hebt om een ​​moderne WordPress plugin te maken, inclusief het volgende:

 

  • Ondersteuning voor React, JSX en ES6-syntaxis.
  • webpack dev/productie bouwproces achter de schermen.
  • Taalextra’s buiten ES6 zoals de objectspreidingsoperator.
  • CSS met automatisch voorvoegsel, dus je hebt geen -webkit of andere voorvoegsels nodig.
  • Een buildscript om JS, CSS en afbeeldingen voor productie te bundelen met bronkaarten.
  • Probleemloze updates voor de bovenstaande tools met een enkele dependency cgb-scripts.

 

Let op het volgende voorbehoud:

Het nadeel is dat deze tools vooraf zijn geconfigureerd om op een specifieke manier te werken. Als je project meer maatwerk nodig heeft, kun je het “uitwerpen” en aanpassen, maar dan moet je deze configuratie behouden.

Zodra je een lokale WordPress website bij de hand hebt, start je je Command Line tool, navigeer je naar de map /wp-content/plugins van je installatie en voer je de volgende opdracht uit:

npx create-guten-block my-first-block

Je moet een minuut of twee wachten terwijl de projectstructuur wordt gemaakt en dependencies worden gedownload:

Een Gutenberg blok maken met create-guten-block.
Een Gutenberg blok maken met create-guten-block.

Wanneer het proces is voltooid, zou je het volgende scherm moeten zien:

Gutenberg blok succesvol gemaakt met create-guten-block.
Gutenberg blok succesvol gemaakt met create-guten-block.

Deze volgende afbeelding toont de projectstructuur met de terminal die wordt uitgevoerd in Visual Studio Code:

De blokplugin in Visual Studio Code.
De blokplugin in Visual Studio Code.

Ga nu terug naar je WordPress dashboard. Er moet een nieuw item worden vermeld in het scherm Plugins – het is de plugin my-first-block :

Het Plugins scherm met een nieuwe plugin gemaakt met create-guten-block.
Het Plugins scherm met een nieuwe plugin gemaakt met create-guten-block.

Activeer de plugin en ga terug naar de terminal. Wijzig de huidige map in my-first-block en voer vervolgens npm startuit:

cd my-first-block
npm start

Je zou de volgende respons moeten krijgen:

npm is gestart.
npm is gestart.

Nogmaals, dit stelt je in staat om de plugin in de ontwikkelingsmodus uit te voeren. Om de productiecode te maken, moet je de volgende code gebruiken:

npm run build

Activeer de plugin en maak een nieuwe post of pagina aan, blader vervolgens door je blokken en selecteer je gloednieuwe Gutenberg blok:

Een nieuw blok gemaakt met create-guten-block.
Een nieuw blok gemaakt met create-guten-block.

Raadpleeg de documentatie van Ahmad Awais voor een meer diepgaand overzicht of in geval van fouten.

Een overzicht van de startbloksteigers

Welke van de twee dev-tools – create-block  of create-guten-block  – je ook kiest, je hebt nu een “steiger”, een scaffold, die je als startpunt kunt gebruiken om een ​​blokplugin te bouwen.

Maar wat is block scaffolding precies?

Block scaffolding is een verkorte term die de ondersteunende directorystructuur beschrijft die WordPress nodig heeft om een ​​blok te herkennen. Meestal bevat die map bestanden zoals index.phpindex.jsstyle.css en anderen – die op hun beurt oproepen bevatten zoals register_block_type.

We hebben gekozen voor de officiële Create Block  dev-tool, zoals die wordt gebruikt in het Block Editor Handbook. Maar zelfs als je zou besluiten om met een externe tool zoals create-guten-block in zee te gaan, zal je ervaring niet al te veel anders zijn.

Dat gezegd hebbende, laten we dieper ingaan op de create-block tool.

Een nadere blik op de Create Block Dev-Tool

Zoals hierboven vermeld, is Create Block de officiële opdrachtregeltool om Gutenberg blokken te maken. Als je @wordpress/create-block in je terminal uitvoert, worden de PHP, JS  en SCSS bestanden en code gegenereerd die nodig zijn om een ​​nieuw bloktype te registreren:

npx @wordpress/create-block [options] [slug]
  • [slug] (optioneel) — gebruikt om de block slug toe te wijzen en de plugin te installeren
  • [options] (optioneel) — beschikbare opties

Standaard wordt een ESNext template toegewezen. Dit betekent dat je de volgende versie van JavaScript krijgt, met toevoeging van de JSX syntaxis.

Als je de bloknaam weglaat, wordt de opdracht in interactieve modus uitgevoerd, zodat je verschillende opties kunt aanpassen voordat je de bestanden genereert:

npx @wordpress/create-block
Create-block uitvoeren in interactieve modus.
Create-block uitvoeren in interactieve modus.

De onderstaande afbeelding toont de bestandsstructuur van een blokplugin die is gemaakt met de officiële Create Block tool:

Bestanden en mappen van een blokplugin gemaakt met @wordpress/create-block
Bestanden en mappen van een blokplugin gemaakt met @wordpress/create-block.

Dat gezegd hebbende, laten we de hoofdbestanden en mappen van onze nieuwe blokplugin doornemen.

Het pluginbestand

Met het hoofdpluginbestand registreer je het blok op de server:

/**
 * Plugin Name: My First Block
 * Description: Example block written with ESNext standard and JSX support – build step required.
 * Requires at least: 5.8
 * Requires PHP: 7.0
 * Version: 0.1.0
 * Author: The WordPress Contributors
 * License: GPL-2.0-or-later
 * License URI: https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain: my-first-block
 *
 * @package create-block
 */
/**
 * Registers the block using the metadata loaded from the `block.json` file.
 * Behind the scenes, it registers also all assets so they can be enqueued
 * through the block editor in the corresponding context.
 *
 * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/
 */
function create_block_my_first_block_block_init() {
	register_block_type( __DIR__ );
}
add_action( 'init', 'create_block_my_first_block_block_init' );

De register_block_type  functie registreert een bloktype op de server met behulp van de metagegevens die zijn opgeslagen in het bestand block.json

De functie heeft twee parameters:

  • De naam van het bloktype inclusief naamruimte, of een pad naar de map waar het json bestand zich bevindt, of een compleet WP_Block_Type  object
  • Een reeks van bloktypeargumenten

In de bovenstaande code wordt het argument voor het bloktype geleverd door de magische constante __DIR__ Dat betekent dat het bestand block.json  zich in dezelfde map bevindt als het bestand van de plugin.

Het package.json bestand

Het bestand package.json definieert JavaScript eigenschappen en scripts voor je project. Hier kunt je je projectdependencies installeren.

Om beter te begrijpen waar dit bestand voor bedoeld is, open je het met je favoriete code-editor:

{
	"name": "my-first-block",
	"version": "0.1.0",
	"description": "Example block written with ESNext standard and JSX support – build step required.",
	"author": "The WordPress Contributors",
	"license": "GPL-2.0-or-later",
	"main": "build/index.js",
	"scripts": {
		"build": "wp-scripts build",
		"format": "wp-scripts format",
		"lint:css": "wp-scripts lint-style",
		"lint:js": "wp-scripts lint-js",
		"start": "wp-scripts start",
		"packages-update": "wp-scripts packages-update"
	},
	"dependencies": {
		"@wordpress/block-editor": "^7.0.1",
		"@wordpress/blocks": "^11.0.1",
		"@wordpress/i18n": "^4.2.1"
	},
	"devDependencies": {
		"@wordpress/scripts": "^18.0.0"
	}
}

De scripts eigenschap is een directory met opdrachten die op verschillende momenten in de levenscyclus van een pakket worden uitgevoerd met npm run [cmd].

In dit artikel gebruiken we de volgende opdrachten:

  • npm run build — maak een (gecomprimeerde) productiebuild
  • npm run start — maak een (ongecomprimeerde) ontwikkelingsbuild

dependencies en devDependencies zijn twee objecten die een pakketnaam toewijzen aan een versie. dependencies  zijn vereist in productie, terwijl devDependences  alleen nodig zijn voor lokale ontwikkeling (lees meer).

De enige standaard dev dependency is het @wordpress/script, dat wordt gedefinieerd als “een verzameling herbruikbare scripts die is afgestemd op de ontwikkeling van WordPress.”

Het block.json bestand

Vanaf WordPress 5.8 is het block.json  metadatabestand de manier om bloktypes te registreren.

Het hebben van een block.json bestand biedt verschillende voordelen, waaronder verbeterde prestaties en betere zichtbaarheid in de WordPress Plugins Directory:

Vanuit een prestatieperspectief, wanneer thema’s lazyloaden van assets ondersteunen, zullen blokken die zijn geregistreerd bij block.json , hun assets-enqueuing out-of-the-box geoptimaliseerd hebben. De frontend CSS- en JavaScript- assets die in de style of script eigenschappen worden vermeld, worden alleen in de wachtrij geplaatst wanneer het blok op de pagina aanwezig is, wat resulteert in kleinere paginaformaten.

Het uitvoeren van de opdracht @wordpress/create-block  genereert het volgende block.json -bestand:

{
	"apiVersion": 2,
	"name": "create-block/my-first-block",
	"version": "0.1.0",
	"title": "My First Block",
	"category": "widgets",
	"icon": "smiley",
	"description": "Example block written with ESNext standard and JSX support – build step required.",
	"supports": {
		"html": false
	},
	"textdomain": "my-first-block",
	"editorScript": "file:./build/index.js",
	"editorStyle": "file:./build/index.css",
	"style": "file:./build/style-index.css"
}

Hier is de volledige lijst met standaardeigenschappen:

  • apiVersion — de versie van de API die door het blok wordt gebruikt (huidige versie is 2)
  • name — een unieke identificatie voor een blok inclusief een naamruimte
  • version — de huidige versie van een blok
  • title — een weergavetitel voor een blok
  • category — een blokcategorie
  • icon — een Dashicon-slug of een aangepast SVG-pictogram
  • description — een korte beschrijving die zichtbaar is in de blokinspecteur
  • supports — een set opties om functies te besturen die in de editor worden gebruikt
  • textdomain — het tekstdomein van de plugin
  • editorScript — definitie van editorscript
  • editorStyle — definitie van editorstijl
  • style — biedt alternatieve stijlen voor een blok

Naast de hierboven genoemde eigenschappen, kun je (en zul je waarschijnlijk) een attributes  object definiëren dat informatie geeft over gegevens die door jouw blok zijn opgeslagen. In je block.json  kun je een willekeurig aantal attributen instellen in sleutel/waarde-paren, waarbij de sleutel de attribuutnaam en de waarde de attribuutdefinitie is.

Bekijk het volgende voorbeeld van attribuutdefinities:

"attributes": {
	"content": {
		"type": "array",
		"source": "children",
		"selector": "p"
	},
	"align": {
		"type": "string",
		"default": "none"
	},
	"link": { 
		"type": "string", 
		"default": "https://kinsta.com" 
	}
},

We zullen later in het artikel dieper ingaan op het block.json bestand, maar je kunt ook het Block Editor handboek raadplegen voor meer gedetailleerde informatie over block.json  metadata en attributen.

De src map

De src map is waar de ontwikkeling plaatsvindt. In die map vind je de volgende bestanden:

  • index.js
  • edit.js
  • save.js
  • editor.scss
  • style.scss

index.js

Het bestand index.js is je startpunt. Hier importeer je afhankelijkheden en registreer je het bloktype op de client:

import { registerBlockType } from '@wordpress/blocks';
import './style.scss';
import Edit from './edit';
import save from './save';

registerBlockType('create-block/my-first-block', {
	edit: Edit,
	save,
});

De eerste instructie importeert de functie registerBlockType uit het pakket @wordpress/block. De volgende importinstructies importeren het stylesheet samen met de functies Edit en save.

De functie registerBlockType registreert het onderdeel op de client. De functie heeft twee parameters: een bloknaam namespace/block-name  (dezelfde als geregistreerd op de server) en een blokconfiguratieobject.

De Edit functie biedt de blokinterface zoals weergegeven in de Block Editor, terwijl de save  functie de structuur biedt die wordt geserialiseerd en in de database wordt opgeslagen (lees meer).

edit.js

edit.js is waar je de blokbeheerdersinterface gaat bouwen:

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit() {
	return (
		<p {...useBlockProps()}>
			{__('My First Block – hello from the editor!', 'my-first-block')}
		</p>
	);
}

Eerst importeert het de __-functie uit het @wordpress/i18n  pakket (dit pakket bevat een JavaScript versie van de vertaalfuncties), de useBlockPropsReact hook en het editor.scss bestand.

Daarna exporteert het de React component (lees meer over import– en export statements).

save.js

In het bestand save.js bouwen we de blokstructuur die in de database moet worden opgeslagen:

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';

export default function save() {
	return (
		<p {...useBlockProps.save()}>
			{__(
				'My First Block – hello from the saved content!',
				'my-first-block'
			)}
		</p>
	);
}

editor.scss en style.scss

Afgezien van de scripts bevinden zich twee SASS bestanden in de src -mappen. Het bestand editor.scss bevat de stijlen die op het blok zijn toegepast in de context van de editor, terwijl het bestand style.scss de stijlen van het blok bevat voor weergave in de frontend. In het tweede deel van deze handleiding gaan we dieper op deze bestanden in.

De node_modules en build-mappen

De map node_modules bevat nodemodules en hun dependencies. We zullen niet dieper ingaan op nodepackages omdat dit buiten het bestek van dit artikel valt, maar je kunt in dit artikel meer lezen over waar npm de pakketten installeert.

De build map bevat de JS  en CSS bestanden die het resultaat zijn van het buildproces. Je kan dieper in het bouwproces duiken in de ESNext-syntaxis en JavaScript Build Setup handleidingen.

Het project: je eerste Gutenberg blok bouwen

Het is tijd om onze handen vuil te maken. In dit gedeelte leer je hoe je een plugin maakt die een CTA blok met de naam Affiliate Block biedt.

Het blok zal uit twee kolommen bestaan, met links een afbeelding en rechts een tekstparagraaf. Een knop met een aanpasbare link wordt onder de tekst geplaatst:

Het bloktype dat u in deze handleiding leert bouwen.
Het bloktype dat u in deze handleiding leert bouwen.

Dit is slechts een eenvoudig voorbeeld, maar het stelt ons in staat om de basisprincipes van de ontwikkeling van Gutenberg blokken te behandelen. Als je eenmaal een duidelijk begrip hebt van de basis, kun je doorgaan en steeds complexere Gutenberg blokken maken met behulp van het Block Editor Handbook en alle andere uitgebreide bronnen die er zijn.

Ervan uitgaande dat je de nieuwste versie van WordPress in je lokale ontwikkelomgeving draait, ga je hier het volgende leren:

Klaar voor de start, af!

Hoe de Starter Block plugin in te stellen

Start je opdrachtregel tool en navigeer naar de map /wp-content/plugins:

Nieuwe terminal in map in Mac OS.
Nieuwe terminal in map in Mac OS.

Voer nu de volgende opdracht uit:

npx @wordpress/create-block

Deze opdracht genereert de PHP, SCSS en JS bestanden voor het registreren van een blok in interactieve modus, zodat je eenvoudig de benodigde gegevens voor je blok kunt toevoegen. Voor ons voorbeeld gebruiken we de volgende details:

  • Block slug: my-affiliate-block
  • Internal namespace: my-affiliate-plugin
  • Block display title: Affiliate block
  • Short block description: an example block for Kinsta readers
  • Dashicon: money
  • Category name: design
  • Plugin author: Je naam
  • License: –
  • Link to the license text: –
  • Current plugin version: 0.1.0

Het installeren van de plugin en alle dependencies duurt een paar minuten. Wanneer het proces is voltooid, zie je het volgende antwoord:

Het Affiliate-blok is geïnstalleerd en geregistreerd voor ontwikkeling.
Het Affiliate-blok is geïnstalleerd en geregistreerd voor ontwikkeling.

Voer nu de volgende opdracht uit vanuit de map /wp-content/plugins:

cd my-affiliate-block
Opdrachten uitvoeren vanuit Visual Studio Code Terminal.
Opdrachten uitvoeren vanuit Visual Studio Code Terminal.

Ten slotte kun je vanuit de map van je plugin (my-affiliate-block in ons voorbeeld) de ontwikkeling starten met:

npm start

Open nu het scherm Plugins om de plugin Affiliate Block te zoeken en te activeren:

Affiliate Block-plugin.
Affiliate Block-plugin.

Maak een nieuw bericht, open de blokinvoeger en scrol omlaag naar de categorie Design. Klik om het Affiliate Block toe te voegen:

startblok gebouwd met @wordpress/create-block.
startblok gebouwd met @wordpress/create-block.

block.json aan het werk

Zoals we eerder vermeldden, vindt de blokregistratie aan de serverzijde plaats in het hoofd .php bestand. We zullen echter geen instellingen definiëren in het .php bestand. In plaats daarvan gebruiken we het bestand block.json.

Dus, open block.json  opnieuw en bekijk de standaardinstellingen van dichterbij:

{
	"apiVersion": 2,
	"name": "my-affiliate-plugin/my-affiliate-block",
	"version": "0.1.0",
	"title": "Affiliate Block",
	"category": "design",
	"icon": "money",
	"description": "An example block for Kinsta readers",
	"supports": {
		"html": false
	},
	"textdomain": "my-affiliate-block",
	"editorScript": "file:./build/index.js",
	"editorStyle": "file:./build/index.css",
	"style": "file:./build/style-index.css"
}

Scripts en stijlen

editorScript, editorStyle, en style properties bieden de relatieve paden naar frontend en backend scripts en stijlen.

Je hoeft de hier gedefinieerde scripts en stijlen niet handmatig te registreren, omdat deze automatisch worden geregistreerd en in de wachtrij worden geplaatst door WordPress. Om dat te bewijzen, start je de browserinspecteur en open je het tabblad Network:

Bronnen inspecteren in Chrome DevTools.
Bronnen inspecteren in Chrome DevTools.

Zoals je kunt zien in de afbeelding hierboven, is ons index.js script dat zich in de build map bevindt regelmatig in de wachtrij geplaatst zonder dat je PHP code hoeft toe te voegen.

UI labels

De properties title en description bieden de labels die nodig zijn om het blok in de editor te identificeren:

Bloknaam en beschrijving in de blokzijbalk.
Bloknaam en beschrijving in de blokzijbalk.

Trefwoorden

Zoals we eerder vermeldden, kun je je blokinstellingen nauwkeurig configureren met behulp van properties en attributes. Je kunt bijvoorbeeld een of meer keywords toevoegen om gebruikers te helpen bij het zoeken naar blokken:

{ "keywords": [ "kinsta", "affiliate", "money" ] }

Als je nu “kinsta”, “affiliate” of “money” invoert in de snelinvoer, zal de editor je het Affiliate blok voorstellen:

Zoeken naar een blok met behulp van een trefwoord in de snelle invoegfunctie.
Zoeken naar een blok met behulp van een trefwoord in de snelle invoegfunctie.

Lokalisatie

Als je je afvraagt ​​hoe de lokalisatie van de strings in het JSON bestand gebeurt, is hier het antwoord:

In JavaScript kun je nu de registerBlockTypeFromMetadata methode uit het @wordpress/blocks pakket gebruiken om een ​​bloktype te registreren met behulp van de metagegevens die zijn geladen uit het block.json bestand. Alle gelokaliseerde eigenschappen worden automatisch verpakt in _x (van het @wordpress/i18n -pakket) functieaanroepen vergelijkbaar met hoe het werkt in PHP met register_block_type_from_metadata. De enige vereiste is om de eigenschap textdomain in het bestand block.json in te stellen.

Hier gebruiken we de functie registerBlockType in plaats van registerBlockTypeFromMetadata, aangezien de laatste sinds Gutenberg 10.7 is verouderd, maar het mechanisme is hetzelfde.

Ingebouwde componenten gebruiken: de RichText component

De elementen waaruit een Gutenberg blok bestaat, zijn React componenten en je hebt toegang tot deze componenten via de global variabele wp. Probeer bijvoorbeeld wp.editor in de console van je browser te typen. Dit geeft je de volledige lijst van de componenten die zijn opgenomen in de wp.editor module.

Scrol door de lijst en raad welke componenten met hun naam bedoeld zijn.

Op dezelfde manier kun je de lijst met componenten in de wp.components module controleren:

WP Editor-componenten.
WP Editor-componenten.

Ga nu terug naar het edit.js bestand en bekijk het script van dichterbij:

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit() {
	return (
		<p {...useBlockProps()}>
			{__('My First Block – hello from the editor!', 'my-first-block')}
		</p>
	);
}

Deze code genereert een statisch blok met eenvoudige, niet-bewerkbare tekst. Maar we kunnen dingen gemakkelijk veranderen:

Het startblok in de code-editor.
Het startblok in de code-editor.

Om de tekst bewerkbaar te maken, moet je de huidige <p> tag vervangen door een component die de invoerinhoud bewerkbaar maakt. Daarvoor biedt Gutenberg de ingebouwde RichText component.

Het toevoegen van een ingebouwd onderdeel aan je blok is een proces van 5 stappen:

  1. Importeer de benodigde componenten uit een WordPress pakket
  2. Neem de corresponderende elementen op in je JSX code
  3. Definieer de benodigde attributen in het bestand block.json
  4. Definieer event-handlers
  5. Gegevens opslaan

Stap 1: Importeer de benodigde componenten uit een WordPress pakket

Open nu het bestand edit.js en wijzig het volgende import statement:

import { useBlockProps } from '@wordpress/block-editor';

…naar:

import { useBlockProps, RichText } from '@wordpress/block-editor';

Op deze manier importer je de useBlockProps functie en RichText component uit het @wordpress/block-editor pakket.

useBlockProps

De useBlockProps React hook markeert het wrapper-element van het blok:

Wanneer je API versie 2 gebruikt, moet je de nieuwe useBlockProps hook gebruiken in de edit  functie van het blok om het wrapper-element van het blok te markeren. De hook zal attributen en event-handlers invoegen die nodig zijn om blokgedrag mogelijk te maken. Alle attributen die je aan het blokelement wil doorgeven, moeten via useBlockProps worden doorgegeven en de geretourneerde waarde moet op het element worden gespreid.

Simpel gezegd, useBlockProps wijst automatisch attributen en klassen toe aan het wrapper-element (het p element in ons voorbeeld):

Elementen en klassen gegenereerd door useBlockProps.
Elementen en klassen gegenereerd door useBlockProps.

Als je useBlockProps uit het wrapper-element verwijdert, heb je een eenvoudige tekenreeks zonder toegang tot blokfunctionaliteit en -stijl:

Hetzelfde blok zonder useBlockProps.
Hetzelfde blok zonder useBlockProps.

Zoals we later zullen uitleggen, kun je useBlockProps ook een object met eigenschappen doorgeven om de uitvoer aan te passen.

RichText

De RichText component biedt een inhoudbewerkbare invoer, waarmee gebruikers de inhoud kunnen bewerken en opmaken.

Je vindt de component gedocumenteerd op GitHub op gutenberg/packages/block-editor/src/components/rich-text/README.md.

Stap 2: Neem de corresponderende elementen op in uw JSX-code

...

const blockProps = useBlockProps();

return (
	<RichText 
		{ ...blockProps }
		tagName="p"
		onChange={ onChangeContent }
		allowedFormats={ [ 'core/bold', 'core/italic' ] }
		value={ attributes.content }
		placeholder={ __( 'Write your text...' ) }
	/>
);

Laten we de code regel voor regel becommentariëren:

  • tagName — de tagnaam van het bewerkbare HTML-element
  • onChange — functie aangeroepen wanneer de inhoud van het element verandert
  • allowedFormats — een reeks toegestane formats. Standaard zijn alle formats toegestaan
  • value — de HTML tekenreeks die bewerkbaar moet worden gemaakt
  • placeholder — tijdelijke tekst om te tonen wanneer het element leeg is

Stap 3: Definieer de benodigde attributen in het block.json bestand

Attributes geven informatie over de gegevens die door een blok zijn opgeslagen, zoals rich content, achtergrondkleur, URL’s, enz.

Je kunt een willekeurig aantal attributen binnen een attributes object instellen in key/value paren, waarbij de sleutel de attribuutnaam is en de waarde de attribuutdefinitie.

Open nu het bestand block.json  en voeg de volgende attributes prop toe:

"attributes": {
	"content": {
		"type": "string",
		"source": "html",
		"selector": "p"
	}
},

Met het content attribuut kan de door de gebruiker getypte tekst in het bewerkbare veld worden opgeslagen:

  • type geeft het type gegevens aan dat door het attribuut is opgeslagen. Het type is vereist, tenzij je een eigenschap enum definieert.
  • source definieert hoe de attribuutwaarde wordt geëxtraheerd uit de berichtinhoud. In ons voorbeeld is dit de HTML inhoud. Houd er rekening mee dat als je geen broneigenschap opgeeft, gegevens worden opgeslagen in het blokscheidingsteken (lees meer).
  • selector is een HTML tag of een andere selector, zoals een klassenaam of een id-attribuut.

We zullen de Edit functie een object van eigenschappen doorgeven. Ga dus terug naar het edit.js bestand en breng de volgende wijziging aan:

export default function Edit( { attributes, setAttributes } ) { ... }

Stap 4: Definieer event-handlers

Het RichText element heeft een onChange-attribuut, dat een functie biedt die kan worden aangeroepen wanneer de inhoud van het element verandert.

Laten we die functie definiëren en het hele edit.js script bekijken:

import { __ } from '@wordpress/i18n';
import { useBlockProps, RichText } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit( { attributes, setAttributes } ) {
	const blockProps = useBlockProps();

	const onChangeContent = ( newContent ) => {
		setAttributes( { content: newContent } )
	}

	return (
		<RichText 
			{ ...blockProps }
			tagName="p"
			onChange={ onChangeContent }
			allowedFormats={ [ 'core/bold', 'core/italic' ] }
			value={ attributes.content }
			placeholder={ __( 'Write your text...' ) }
		/>
	);
}

Sla nu het bestand op en voer npm run start uit in je terminalvenster. Ga vervolgens terug naar je WordPress dashboard, maak een nieuw bericht of nieuwe pagina en voeg je Affiliate blok toe:

De uitvoer van de RichText component in de Block Editor.
De uitvoer van de RichText component in de Block Editor.

Voeg wat tekst toe en schakel over naar de codeweergave. Dit is hoe je code eruit zou moeten zien:

<!-- wp:my-affiliate-plugin/my-affiliate-block -->
<p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable Gutenberg block 🤓</p>
<!-- /wp:my-affiliate-plugin/my-affiliate-block -->

Als je nu de pagina opslaat en het resultaat van de frontend controleert, ben je misschien een beetje teleurgesteld omdat je wijzigingen geen invloed hebben op de site. Dat komt omdat je het bestand save.js moet wijzigen om gebruikersinvoer in de database op te slaan wanneer het bericht wordt opgeslagen.

Stap 5: Gegevens opslaan

Open nu het bestand save.js en wijzig het script als volgt:

import { __ } from '@wordpress/i18n';
import { useBlockProps, RichText } from '@wordpress/block-editor';

export default function save( { attributes } ) {
	const blockProps = useBlockProps.save();
	return (
		<RichText.Content 
			{ ...blockProps } 
			tagName="p" 
			value={ attributes.content } 
		/>
	);
}

Dat is wat we hier doen:

  • Importeer de RichText component uit het block-editor
  • Geef verschillende eigenschappen door via een objectargument aan de save functie (in dit voorbeeld geven we alleen de attributesproperty door)
  • Retourneer de inhoud van de RichText component

Je kunt meer lezen over de RichText component in het Block Editor Handboek en de volledige lijst met rekwisieten vinden op Github.

Laten we nu een stap verder gaan. In het volgende gedeelte leer je hoe je besturingselementen aan de blokwerkbalk kunt toevoegen.

Besturingselementen toevoegen aan de blokwerkbalk

De blokwerkbalk bevat een set bedieningselementen waarmee gebruikers delen van blokinhoud kunnen manipuleren. Voor elk werkbalkbesturingselement vind je een onderdeel:

De blokwerkbalk van het core paragraph.
De blokwerkbalk van het core paragraph.

Je kunt bijvoorbeeld een besturingselement voor tekstuitlijning voor je blok toevoegen. Het enige wat je hoeft te doen, is twee componenten uit het pakket @wordpress/block-editor te importeren.

We doorlopen dezelfde stappen als in het vorige voorbeeld:

  1. Importeer vereiste componenten uit WordPress pakketten
  2. Neem de corresponderende elementen op in je JSX code
  3. Definieer de benodigde attributen in het block.json bestand
  4. Definieer event-handlers
  5. Gegevens opslaan

Stap 1: Importeer BlockControls en AlignmentControl componenten van @wordpress/block-editor

Om een ​​uitlijningsbesturingselement aan de blokwerkbalk toe te voegen, heb je twee componenten nodig:

Heb je het gehad met onkundige WordPress-supportmedewerkers die nergens antwoord op kunnen geven? Geef ons gerenommeerde supportteam een kans! Bekijk onze pakketten

  • BlockControls maakt een dynamische werkbalk met besturingselementen (ongedocumenteerd).
  • AlignmentControl geeft een vervolgkeuzemenu weer dat uitlijningsopties voor het geselecteerde blok weergeeft (lees meer)

Open het edit.js bestand en bewerk het import statement zoals hieronder weergegeven:

import { 
	useBlockProps, 
	RichText, 
	AlignmentControl, 
	BlockControls 
} from '@wordpress/block-editor';

Stap 2: BlockControls en AlignmentControl elementen toevoegen

Ga naar de Edit functie en voeg het element <BlockControls /> in op hetzelfde niveau als <RichText />. Voeg vervolgens <AlignmentControl /> toe binnen <BlockControls />:

export default function Edit( { attributes, setAttributes } ) {
	const blockProps = useBlockProps();
	return (
		<>
			<BlockControls>
				<AlignmentControl
					value={ attributes.align }
					onChange={ onChangeAlign }
				/>
			</BlockControls>
			<RichText 
				{ ...blockProps }
				tagName="p"
				onChange={ onChangeContent }
				allowedFormats={ [ 'core/bold', 'core/italic' ] }
				value={ attributes.content }
				placeholder={ __( 'Write your text...' ) }
				style={ { textAlign: attributes.align } }
			/>
		</>
	);
}

In de bovenstaande code zijn <> en </> de korte syntaxis voor het declareren van React fragmenten, en zo retourneren we meerdere elementen in React.

In dit voorbeeld heeft AlignmentControl twee attributen:

  • value geeft de huidige waarde voor het element
  • onChange biedt een gebeurtenishandler die kan worden uitgevoerd wanneer de waarde verandert

We hebben ook extra attributen gedefinieerd voor het RichText  element (bekijk de volledige lijst met attributen met voorbeelden)

Stap 3: Definieer het uitlijnattribuut in block.json

Ga nu naar het bestand block.json en voeg het align attribuut toe:

"align": {
	"type": "string",
	"default": "none"
}

Ga terug naar de terminal, stop het huidige proces met ^C en start het script opnieuw met  npm run start. Ga dan terug naar de Block Editor, ververs de pagina en selecteer het blok. Je zou de blokwerkbalk moeten zien met een uitlijningsbesturingselement:

De uitlijnwerkbalk is succesvol toegevoegd.
De uitlijnwerkbalk is succesvol toegevoegd.

Als je nu de blokinhoud probeert op te maken met behulp van de nieuwe uitlijningsbesturingselementen, zie je dat er niets gebeurt. Dat komt omdat we de event-handler nog niet hebben gedefinieerd.

Stap 4: Definieer de event-handlers

Definieer nu onChangeAlign:

const onChangeAlign = ( newAlign ) => {
	setAttributes( { 
		align: newAlign === undefined ? 'none' : newAlign, 
	} )
}

Als newAlign  undefined is, stellen we newAlign  in op none. Anders gebruiken we newAlign.

Ons edit.js script zou (voorlopig) compleet moeten zijn:

export default function Edit( { attributes, setAttributes } ) {
	const blockProps = useBlockProps();
	const onChangeContent = ( newContent ) => {
		setAttributes( { content: newContent } )
	}
	const onChangeAlign = ( newAlign ) => {
		setAttributes( { 
			align: newAlign === undefined ? 'none' : newAlign, 
		} )
	}
	return (
		<>
			<BlockControls>
				<AlignmentControl
					value={ attributes.align }
					onChange={ onChangeAlign }
				/>
			</BlockControls>
			<RichText 
				{ ...blockProps }
				tagName="p"
				onChange={ onChangeContent }
				allowedFormats={ [ 'core/bold', 'core/italic' ] }
				value={ attributes.content }
				placeholder={ __( 'Write your text...' ) }
				style={ { textAlign: attributes.align } }
			/>
		</>
	);
}

Nu kun je teruggaan naar de editor en de blokinhoud uitlijnen.

We moeten de opslagfunctie wijzigen om blokinhoud en attributen in de database op te slaan.

Stap 5: Gegevens opslaan

Open save.js  en wijzig de save functie als volgt:

export default function save( { attributes } ) {
	const blockProps = useBlockProps.save();
	return (
		<RichText.Content 
			{ ...blockProps } 
			tagName="p" 
			value={ attributes.content } 
			style={ { textAlign: attributes.align } }
		/>
	);
}

Ten slotte, om de code leesbaarder te maken, kun je de individuele eigenschappen uit het attribute object extraheren met behulp van de destructurerende toewijzingssyntaxis:

export default function save( { attributes } ) {
	const blockProps = useBlockProps.save();
	const { content, align } = attributes;
	return (
		<RichText.Content 
			{ ...blockProps } 
			tagName="p" 
			value={ content } 
			style={ { textAlign: align } }
		/>
	);
}

Sla het bestand op, start het proces opnieuw en keer terug naar de editor in de code-editormodus. De code zou er ongeveer zo uit moeten zien:

<!-- wp:my-affiliate-plugin/my-affiliate-block {"align":"right"} -->
<p class="wp-block-my-affiliate-plugin-my-affiliate-block" style="text-align:right">This is my first editable <strong><em>Gutenberg</em></strong> <em>block</em> 🤓</p>
<!-- /wp:my-affiliate-plugin/my-affiliate-block -->
Tekst rechts uitlijnen
Tekst rechts uitlijnen.

En dat is het! Je hebt zojuist een uitlijningsbesturingselement toegevoegd aan de blokwerkbalk 🤓

Je kunt meer lezen over blokwerkbalkbesturingselementen in het Block Editor Handboek.

De zijbalk met blokinstellingen aanpassen

Je kunt ook bedieningselementen toevoegen aan het blok instellingenzijbalk  (of zelfs een nieuwe zijbalk voor je toepassing maken).

De API biedt daarvoor een InspectorControls– component.

In het Block Editor handboek wordt uitgelegd hoe je de Instellingenzijbalk gebruikt:

De instellingenzijbalk wordt gebruikt om minder vaak gebruikte instellingen of instellingen weer te geven waarvoor meer schermruimte nodig is. De Instellingenzijbalk mag alleen worden gebruikt voor instellingen op blokniveau.

Als je instellingen hebt die alleen van invloed zijn op geselecteerde inhoud in een blok (bijvoorbeeld: de “vet” instelling voor geselecteerde tekst in een alinea): plaats deze dan niet in de Instellingenzijbalk. De instellingenzijbalk wordt zelfs weergegeven wanneer een blok in HTML modus wordt bewerkt, dus deze mag alleen instellingen op blokniveau bevatten.

Nogmaals:

  1. Importeer vereiste componenten uit WordPress pakketten
  2. Neem de corresponderende elementen op in je JSX code
  3. Definieer de benodigde attributen in het block.json bestand
  4. Definieer event-handlers
  5. Gegevens opslaan

Stap 1. Importeer InspectorControls en PanelColorSettings componenten van @wordpress/block-editor

Je kunt verschillende bedieningselementen toevoegen zodat gebruikers specifieke aspecten van het blok kunnen aanpassen. Je kunt bijvoorbeeld een kleurenbedieningspaneel leveren. Om dit te doen, moet je de componenten InspectorControls  en PanelColorSettings  uit de block-editor  module importeren:

import { 
	useBlockProps, 
	RichText, 
	AlignmentControl, 
	BlockControls,
	InspectorControls,
	PanelColorSettings
} from '@wordpress/block-editor';

Stap 2: De corresponderende elementen op in je JSX code opnemen

Nu kun je de overeenkomstige elementen toevoegen aan de JSX die wordt geretourneerd door de Edit functie:

export default function Edit( { attributes, setAttributes } ) {
	const blockProps = useBlockProps();
	const onChangeContent = ( newContent ) => {
		setAttributes( { content: newContent } )
	}
	const onChangeAlign = ( newAlign ) => {
		setAttributes( { 
			align: newAlign === undefined ? 'none' : newAlign, 
		} )
	}
	return (
		<>
			<InspectorControls>
				<PanelColorSettings 
					title={ __( 'Color settings', 'my-affiliate-block' ) }
					initialOpen={ false }
					colorSettings={ [
						{
						  value: textColor,
						  onChange: onChangeTextColor,
						  label: __( 'Text color', 'my-affiliate-block' ),
						},
						{
						  value: backgroundColor,
						  onChange: onChangeBackgroundColor,
						  label: __( 'Background color', 'my-affiliate-block' ),
						}
					] }
				/>
			</InspectorControls>
			<BlockControls>
				<AlignmentControl
					value={ attributes.align }
					onChange={ onChangeAlign }
				/>
			</BlockControls>
			<RichText 
				{ ...blockProps }
				tagName="p"
				onChange={ onChangeContent }
				allowedFormats={ [ 'core/bold', 'core/italic' ] }
				value={ attributes.content }
				placeholder={ __( 'Write your text...', 'my-affiliate-block' ) }
				style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } }
			/>
		</>
	);
}

Merk op dat we ook het style  attribuut van het RichText element hebben bijgewerkt:

<RichText 
	 { ...blockProps }
	 tagName="p"
	 onChange={ onChangeContent }
	 allowedFormats={ [ 'core/bold', 'core/italic' ] }
	 value={ content }
	 placeholder={ __( 'Write your text...', 'my-affiliate-block' ) }
	 style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } }
/>

Stap 3: Definieer de benodigde attributen in block.json

Definieer nu de attributen backgroundColor  en textColor  in het bestand block.json:

"attributes": {
	"content": {
		"type": "string",
		"source": "html",
		"selector": "p"
	},
	"align": {
		"type": "string",
		"default": "none"
	},
	"backgroundColor": {
		"type": "string"
	},	 
	"textColor": {
		"type": "string"
	}
},

Stap 4: Definieer de event-handlers

Nu moet je twee functies definiëren om backgroundColor  en textColor bij gebruikersinvoer bij te werken:

const onChangeBackgroundColor = ( newBackgroundColor ) => {
	setAttributes( { backgroundColor: newBackgroundColor } )
}
const onChangeTextColor = ( newTextColor ) => {
	setAttributes( { textColor: newTextColor } )
}

Stap 5: Gegevens opslaan

Nog een laatste stap: Open het bestand save.js en wijzig het script als volgt:

export default function save( { attributes } ) {
	const blockProps = useBlockProps.save();
	const { content, align, backgroundColor, textColor } = attributes;
	return (
		<RichText.Content 
			{ ...blockProps } 
			tagName="p" 
			value={ content } 
			style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } }
		/>
	);
}

Stop nu het proces (^C) en voer npm run start opnieuw uit. Vernieuw de pagina, verwijder elke instantie van je blok en voeg het opnieuw toe aan je bericht:

Een aangepast blok met een Color Settings paneel.
Een aangepast blok met een Color Settings paneel.

Breng je wijzigingen aan, sla het bericht op en bekijk het in de frontend. De wijzigingen die je in de Block Editor hebt aangebracht, moeten worden weergegeven op de frontsite.

In deze sectie voeg je nieuwe componenten toe aan je bloktype:

  • Een ExternalLink component waarmee gebruikers een aanpasbare link aan het Affiliate blok kunnen toevoegen
  • Verschillende bedieningselementen in de zijbalk waarmee gebruikers linkinstellingen kunnen aanpassen

Stap 1. Importeer componenten van @wordpress/components

Nu moet je verschillende componenten importeren uit @wordpress/components. Open je edit.js bestand en voeg het volgende import  statement toe:

import {
	TextControl,
	PanelBody,
	PanelRow,
	ToggleControl,
	ExternalLink
} from '@wordpress/components';
  • PanelBody voegt een inklapbare container toe aan de Instellingenzijbalk.
  • PaneRow produceert een generieke container voor zijbalkbedieningen.
  • TextControl biedt een besturingselement voor tekstinvoer.
  • ToggleControl biedt een schakelaar waarmee gebruikers een specifieke optie kunnen in-/uitschakelen
  • ExternalLink is een eenvoudig onderdeel om een ​​externe link toe te voegen.

Stap 2. Neem de corresponderende elementen op in je JSX code

Je voegt eerst het ExternalLink  element toe op hetzelfde niveau als RichText  in een div  container:

<div { ...blockProps }>
	<RichText 
		...
	/>
	<ExternalLink 
		href={ affiliateLink }
		className="affiliate-button"
		rel={ hasLinkNofollow ? "nofollow" : "" }
	>
			{ linkLabel }
	</ExternalLink>

</div>

De ExternalLink component is niet gedocumenteerd, dus we verwezen naar de component zelf om de lijst met beschikbare attributen te krijgen. Hier gebruiken we de attributen href, className en rel .

Standaard is de rel  attribuutwaarde ingesteld op noopener noreferrer. Onze code voegt het nofollow sleutelwoord toe aan het rel  attribuut van de resulterende a tag wanneer de toggle-besturing is ingeschakeld.

Nu kun je de linkinstellingen toevoegen aan de blokzijbalk.

Eerst voeg je een PanelBody  element toe in InspectorControls  op hetzelfde niveau als PanelColorSettings:

<InspectorControls>
	<PanelColorSettings 
	...
	/>
	<PanelBody 
		title={ __( 'Link Settings', 'my-affiliate-block' )}
		initialOpen={true}
	>
	...
	</PanelBody>
</InspectorControls>

Dit is wat we hiermee doen:

  1. Het title attribuut levert de paneeltitel.
  2. initialOpen stelt in of het paneel initieel open is of niet.

Vervolgens voegen we twee PanelRow  elementen toe in PanelBody en een TextControl  element in elke PanelRow:

<PanelBody 
	title={ __( 'Link Settings', 'my-affiliate-block' )}
	initialOpen={true}
>
	<PanelRow>
		<fieldset>
			<TextControl
				label={__( 'Affiliate link', 'my-affiliate-block' )}
				value={ affiliateLink }
				onChange={ onChangeAffiliateLink }
				help={ __( 'Add your affiliate link', 'my-affiliate-block' )}
			/>
		</fieldset>
	</PanelRow>
	<PanelRow>
		<fieldset>
			<TextControl
				label={__( 'Link label', 'my-affiliate-block' )}
				value={ linkLabel }
				onChange={ onChangeLinkLabel }
				help={ __( 'Add link label', 'my-affiliate-block' )}
			/>
		</fieldset>
	</PanelRow>
</PanelBody>

De bovenstaande code zou er nu vrij eenvoudig uit moeten zien. Met de twee tekstbesturingselementen kunnen gebruikers het linklabel en de URL instellen.

We zullen ook een extra PanelRow  toevoegen met een ToggleControl  om een ​​specifieke optie in of uit te schakelen, zoals het wel of niet opnemen van een attribuut:

<PanelRow>
	<fieldset>
		<ToggleControl
			label="Add rel = nofollow"
			help={
				hasLinkNofollow
					? 'Has rel nofollow.'
					: 'No rel nofollow.'
			}
			checked={ hasLinkNofollow }
			onChange={ toggleNofollow }
		/>
	</fieldset>
</PanelRow>

Stap 3: Definieer de benodigde attributen in block.json

Definieer nu de attributen affiliateLink, linkLabel en hasLinkNofollow  in het bestand block.json :

"affiliateLink": {
	"type": "string",
	"default": ""
},
"linkLabel": {
	"type": "string",
	"default": "Check it out!"
},
"hasLinkNofollow": {
	"type": "boolean",
	"default": false
}

Hier valt niets meer aan toe te voegen! Laten we verder gaan met het definiëren van de event-handler functies.

Stap 4: Definieer de event-handlers

Ga terug naar het edit.js  bestand en voeg de volgende functies toe:

const onChangeAffiliateLink = ( newAffiliateLink ) => {
	setAttributes( { affiliateLink: newAffiliateLink === undefined ? '' : newAffiliateLink } )
}

const onChangeLinkLabel = ( newLinkLabel ) => {
	setAttributes( { linkLabel: newLinkLabel === undefined ? '' : newLinkLabel } )
}

const toggleNofollow = () => {
	setAttributes( { hasLinkNofollow: ! hasLinkNofollow } )
}

Deze functies updaten de corresponderende attribuutwaarden bij gebruikersinvoer.

Stap 5: Gegevens opslaan

Als laatste moeten we de save functie in save.js bijwerken:

export default function save( { attributes } ) {

	const { align, content, backgroundColor, textColor, affiliateLink, linkLabel, hasLinkNofollow } = attributes;

	const blockProps = useBlockProps.save();

	return (
		<div { ...blockProps }>
			<RichText.Content 
				tagName="p" 
				value={ content } 
				style={ { backgroundColor: backgroundColor, color: textColor } }
			/>
			<p>
				<a 
					href={ affiliateLink }
					className="affiliate-button"
					rel={ hasLinkNofollow ? "nofollow" : "noopener noreferrer" }
				>
					{ linkLabel }
				</a>
			</p>
		</div>
	);
}

Merk op dat we hier een regulier a  element hebben gebruikt in plaats van ExternalLink:

Affiliate blok link instellingen.
Affiliate blok link instellingen.

Sla nu gegevens op en start je omgeving opnieuw op.

Meerdere blokstijlen toevoegen

In een vorige sectie heb je geleerd hoe je een blokwerkbalkbesturingselement kunt toevoegen waarmee gebruikers de gebruikersinvoer kunnen uitlijnen. We kunnen meer stijlbesturingselementen toevoegen aan de blokwerkbalk, maar we kunnen ook een set vooraf gedefinieerde blokstijlen bieden waaruit de gebruiker met een enkele klik kan kiezen.

Voor dit doel gaan we een handige functie van de Blok API gebruiken: Block Styles.

Het enige wat je hoeft te doen, is de property block.json  styles  definiëren en de bijbehorende stijlen in je stylesheets declareren.

Je kunt bijvoorbeeld de volgende reeks stijlen toevoegen:

"styles": [
	{
		"name": "default",
		"label": "Default",
		"isDefault": true
	},
	{
		"name": "border",
		"label": "Border"
	}
],

Hiermee heb je zojuist een standaardstijl en een extra stijl met de naam border toegevoegd. Ga nu terug naar de Block Editor:

Twee voorgedefinieerde blokstijlen.
Twee voorgedefinieerde blokstijlen.

De stijlen zijn beschikbaar voor de gebruiker door op de blok switcher te klikken en vervolgens naar het Styles panel  in de Block Settings Sidebar te zoeken.

Selecteer een stijl en controleer de klassen die op het p element zijn toegepast. Klik met de rechtermuisknop op het blok en Inspect. Er is een nieuwe klasse toegevoegd met een naam die als volgt is opgebouwd:

is-style-{style-name}

Als je de “Border” stijl hebt aangevinkt, wordt een is-style-border  toegevoegd aan het p -element. Als je de stijl ” Default” hebt aangevinkt, wordt in plaats daarvan een is-style-default klasse toegevoegd.

Nu hoef je alleen nog maar de CSS eigenschappen te declareren. Open het bestand editor.scss  en vervang de huidige stijlen door het volgende:

.wp-block-my-affiliate-plugin-my-affiliate-block {
	padding: 2px;
	&.is-style-default{
		border: 0;
	}
	&.is-style-border{
		border: 1px solid #000;
	}
}

Nu kun je hetzelfde doen met style.scss:

.wp-block-my-affiliate-plugin-my-affiliate-block {
	&.is-style-default{
		border: 0;
	}
	&.is-style-border{
		border: 1px solid #000;
	}
}

Stop het proces (^C) en voer npm run start opnieuw uit.

En dat is het! Ververs de pagina en veel plezier met je nieuwe blokstijlen:

Affiliate blokstijlen.
Affiliate blokstijlen.

Gutenberg blokken nesten met de InnerBlocks component

Hoewel volledig functioneel, is ons Affiliate Block nog steeds niet erg aantrekkelijk. Om het voor het publiek aantrekkelijker te maken, kunnen we een afbeelding toevoegen.

Dit voegt misschien een laag complexiteit toe aan ons blok, maar gelukkig hoef je het wiel niet opnieuw uit te vinden omdat Gutenberg een specifiek component biedt dat je kunt gebruiken om een ​​structuur van geneste blokken te maken.

De component InnerBlocks  is als volgt gedefinieerd:

InnerBlocks exporteert een paar componenten die kunnen worden gebruikt in blokimplementaties om geneste blokinhoud mogelijk te maken.

Eerst moet je een nieuw .js bestand maken in de src map. In ons voorbeeld noemen we dit bestand container.js.

Nu moet je de nieuwe bron importeren in het index.js bestand:

import './container';

Ga terug naar container.js en importeer de benodigde componenten:

import { registerBlockType } from "@wordpress/blocks";
import { __ } from "@wordpress/i18n";
import {
	useBlockProps, 
	InnerBlocks 
} from "@wordpress/block-editor";

De volgende stap is het definiëren van een template die de structuur biedt waarbinnen de blokken worden geplaatst. In het volgende voorbeeld definiëren we een template die bestaat uit twee kolommen met een core Image blok en ons aangepaste Affiliate blok:

const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [
	[ 'core/column', { templateLock: 'all' }, [
		[ 'core/image' ],
	] ],
	[ 'core/column', { templateLock: 'all' }, [
		[ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ],
	] ],
] ] ];

De template is gestructureerd als een reeks blok typen (bloknaam en optionele attributen).

In de bovenstaande code hebben we verschillende attributen gebruikt om de kolommen en kolomblokken te configureren. In het bijzonder vergrendelt het templateLock: 'all' attribuut Kolomblokken zodat de gebruiker geen bestaande blokken kan toevoegen, opnieuw ordenen of verwijderen. templateLock  kan een van de volgende waarden aannemen:

  • allInnerBlocks is vergrendeld en er kunnen geen blokken worden toegevoegd, opnieuw gerangschikt of verwijderd.
  • insert — Blokken kunnen alleen opnieuw worden gerangschikt of verwijderd.
  • false — De template is niet vergrendeld.

De sjabloon wordt vervolgens toegewezen aan het InnerBlocks  element:

<InnerBlocks
	template={ TEMPLATE }
	templateLock="all"
/>

Om compatibiliteitsproblemen te voorkomen, hebben we ook een templateLock  attribuut toegevoegd aan de InnerBlocks  component (zie ook probleem #17262 en #26128).

Hier is het definitieve container.js  bestand:

import { registerBlockType } from "@wordpress/blocks";
import { __ } from "@wordpress/i18n";
import { useBlockProps, InnerBlocks } from "@wordpress/block-editor";

const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [
	[ 'core/column', { templateLock: 'all' }, [
		[ 'core/image' ],
	] ],
	[ 'core/column', { templateLock: 'all' }, [
		[ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ],
	] ],
] ] ];

registerBlockType('my-affiliate-plugin/my-affiliate-container-block', {
	title: __( 'Container', 'my-affiliate-block' ),
	category: 'design',

	edit( { className } ) {
		
		return(
			<div className={ className }>
				<InnerBlocks
					template={ TEMPLATE }
					templateLock="all"
				/>
			</div>
		)
	},

	save() {
		const blockProps = useBlockProps.save();
		return(
			<div { ...blockProps }>
				<InnerBlocks.Content />
			</div>
		)
	},
});
Het geneste Affiliate blok in de editor.
Het geneste Affiliate blok in de editor.

Aanvullende verbeteringen

Ons blok is volledig functioneel, maar we kunnen het een beetje verbeteren met een paar kleine veranderingen.

We hebben het attribuut backgroundColor  toegewezen aan de alinea die is gegenereerd door de RichText  component. We kunnen er echter de voorkeur aan geven de achtergrondkleur toe te wijzen aan de container div:

Wijzig dus het bestand edit.js  en save.js  div als volgt:

<div 
	{ ...blockProps }
	style={ { backgroundColor: backgroundColor } }
>
...
</div>

Hierdoor kan de gebruiker de achtergrond van het hele blok wijzigen.

Aan de andere kant is een meer relevante verandering de useBlockProps  methode. In de originele code hebben we de constante blockProps  als volgt gedefinieerd:

const blockProps = useBlockProps();

Maar we kunnen de useBlockProps  effectiever gebruiken door een reeks properties door te geven. We kunnen bijvoorbeeld classnames  importeren uit de module classnames  en de naam van de wrapperklasse dienovereenkomstig instellen.

In het volgende voorbeeld wijzen we een klassenaam toe op basis van de waarde van het align attribuut (edit.js):

import classnames from 'classnames';

...

export default function Edit( { attributes, setAttributes } ) {
	...
	const blockProps = useBlockProps( {
		className: classnames( {
			[ `has-text-align-${ align }` ]: align,
		} )
	} );
	...
}

We doen dezelfde wijziging in het bestand save.js:

import classnames from 'classnames';

...

export default function save( { attributes } ) {
	...
	const blockProps = useBlockProps.save({
		className: classnames( {
			[ `has-text-align-${ align }` ]: align,
		} )
	});
	...
}

Klaar is Kees! Je kunt de build nu uitvoeren voor productie.

Als je op zoek bent naar een diepgaande gids om aan de slag te gaan met de ontwikkeling van Gutenberg blokken, dan is deze uitgebreide gids iets voor jou. Bekijk het en begin vandaag nog met het bouwen van je Gutenberg blokken! 👷‍♀️🧱Click to Tweet

Samenvatting

En hier zijn we dan, aan het einde van deze ongelooflijke reis! We zijn begonnen met de configuratie van de ontwikkelomgeving en hebben uiteindelijk een compleet bloktype gemaakt.

Zoals we in de inleiding al zeiden, is een gedegen kennis van Node.js, Webpack, Babel en React essentieel om geavanceerde Gutenberg blokken te maken en jezelf als professionele Gutenberg ontwikkelaar in de markt te positioneren.

Maar je hoeft geen React ervaring te hebben om plezier te hebben met blokontwikkeling. Blokontwikkeling kan je motivatie en doelen geven om steeds bredere vaardigheden te verwerven in de technologieën achter Gutenberg blokken.

Deze gids is dan ook verre van volledig. Het is slechts een inleiding tot een breed scala aan onderwerpen die je zullen helpen om aan de slag te gaan met het bouwen van je allereerste Gutenberg blokken.

Om deze reden raden we je aan je kennis te verdiepen door zorgvuldig online documentatie en handleidingen te lezen. Van de vele beschikbare bronnen raden we het volgende aan:

Als je net begint met WordPress ontwikkeling, wil je misschien de basisconcepten van frontend-ontwikkeling begrijpen. Hier is een korte lijst met bronnen die je kunnen helpen om aan de slag te gaan:

En onthoud dat de volledige code van de voorbeelden van deze handleiding beschikbaar is op Gist.

Nu is het jouw beurt: heb je Gutenberg blokken ontwikkeld? Wat zijn de belangrijkste moeilijkheden die je tot nu toe hebt ondervonden? Laat ons weten wat je ervaring is in de comments!


Bespaar tijd en kosten en maximaliseer siteprestaties met:

  • Directe hulp van WordPress-hostingexperts, 24/7.
  • Cloudflare Enterprise integration.
  • Globaal bereik met 34 datacenters verspreid over de wereld.
  • Optimalisatie met onze ingebouwde Application Performance Monitoring.

Dat alles en nog veel meer, in één pakket zonder langlopende contracten, met migraties en een 30 dagen geld-terug-garantie. Bekijk onze pakketten of neem contact op met sales om het pakket te vinden dat bij je past.