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.
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.
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.
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:
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:
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 -vAls 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:
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
npxNode.js package runner. Hiermee kun je eennpmopdracht uitvoeren zonder deze eerst te installeren. - De
npmNode.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:
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-envis 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/envLaten we dat opsplitsen:
npm installinstalleert het pakket.-gtoegevoegd aan de opdracht installeert het opgegeven pakket wereldwijd.@wordpress/envis het pakket dat je gaat installeren.
Voer de volgende opdracht uit om te bevestigen dat wp-env is geïnstalleerd:
wp-env --versionJe 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 startJe 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-blockWanneer er wordt gevraagd om te bevestigen, voer je y in om door te gaan:
Het proces duurt enkele ogenblikken. Wanneer het voltooid is, zou je het volgende antwoord moeten krijgen:
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:
Activeer indien nodig de plugin, maak een nieuwe blogpost, scrol omlaag in de blokinvoeger naar het gedeelte Widgets en selecteer je nieuwe blok:
Ga nu terug naar de terminal en verander de huidige directory in my-first-block:
cd my-first-blockVoer vervolgens de volgende opdracht uit:
npm startHierdoor kun je de plugin in de ontwikkelingsmodus uitvoeren. Om de productiecode te maken, moet je de volgende opdracht gebruiken:
npm run buildOptie 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-blockJe moet een minuut of twee wachten terwijl de projectstructuur wordt gemaakt en dependencies worden gedownload:
Wanneer het proces is voltooid, zou je het volgende scherm moeten zien:
Deze volgende afbeelding toont de projectstructuur met de terminal die wordt uitgevoerd 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 :
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 startJe zou de volgende respons moeten krijgen:
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 buildActiveer de plugin en maak een nieuwe post of pagina aan, blader vervolgens door je blokken en selecteer je gloednieuwe Gutenberg blok:
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.php, index.js, style.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
De onderstaande afbeelding toont de bestandsstructuur van een blokplugin die is gemaakt met de officiële Create Block tool:
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:
<?php
/**
* Plugin Name: Kinsta Academy Block
* Plugin URI: https://kinsta.com/
* Description: An example block for Kinsta Academy students
* Requires at least: 5.9
* Requires PHP: 7.0
* Version: 0.1.0
* Author: Kinsta Students
* License: GPL-2.0-or-later
* License URI: https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain: ka-example-block
*
* @package ka-example-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/reference/functions/register_block_type/
*/
function ka_example_block_ka_example_block_block_init() {
register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'ka_example_block_ka_example_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_Typeobject - Een reeks van bloktypeargumenten
In bovenstaande code geeft de magic constante __DIR__ de huidige map terug. Dat betekent dat het block.json bestand in de /build submap staat.
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": "ka-example-block",
"version": "0.1.0",
"description": "An example block for Kinsta Academy students",
"author": "Kinsta Students",
"license": "GPL-2.0-or-later",
"homepage": "https://kinsta.com/",
"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",
"packages-update": "wp-scripts packages-update",
"plugin-zip": "wp-scripts plugin-zip",
"start": "wp-scripts start"
},
"devDependencies": {
"@wordpress/scripts": "^24.1.0"
},
"dependencies": {
"classnames": "^2.3.2"
}
}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) productiebuildnpm run startofnpm 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
styleofscripteigenschappen 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:
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 2,
"name": "ka-example-block/ka-example-block",
"version": "0.1.0",
"title": "Kinsta Academy Block",
"category": "widgets",
"icon": "superhero-alt",
"description": "An example block for Kinsta Academy students",
"supports": {
"html": false
},
"textdomain": "ka-example-block",
"editorScript": "file:./index.js",
"editorStyle": "file:./index.css",
"style": "file:./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 naamruimteversion— de huidige versie van een bloktitle— een weergavetitel voor een blokcategory— een blokcategorieicon— een Dashicon-slug of een aangepast SVG-pictogramdescription— een korte beschrijving die zichtbaar is in de blokinspecteursupports— een set opties om functies te besturen die in de editor worden gebruikttextdomain— het tekstdomein van de plugineditorScript— definitie van editorscripteditorStyle— definitie van editorstijlstyle— 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';
import metadata from './block.json';
registerBlockType( metadata.name, {
/**
* @see ./edit.js
*/
edit: Edit,
/**
* @see ./save.js
*/
save,
} );De eerste instructie importeert de functie registerBlockType uit het pakket @wordpress/block. De volgende import statements importeren de stylesheet samen met de Edit en save functies, en een metadata object uit het block.json bestand.
De functie registerBlockType registreert het onderdeel op de client. De functie neemt twee parameters: een bloknaam en een object voor de blokconfiguratie.
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 worden toegepast in de context van de editor, terwijl het bestand style.scss de stijlen van het blok bevat voor weergave in zowel de frontend als de editor. In het tweede deel van deze gids gaan we dieper in op deze bestanden.
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 Kinsta Academy 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:
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:
- Hoe de Starter Block plugin in te stellen
- json aan het werk
- Ingebouwde componenten gebruiken: de RichText component
- Besturingselementen toevoegen aan de blokwerkbalk
- De zijbalk met blokinstellingen aanpassen
- Een externe link toevoegen en aanpassen
- Meerdere blokstijlen toevoegen
- Blokken nesten met de component InnerBlocks
- Aanvullende verbeteringen
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:
Voer nu de volgende opdracht uit:
npx @wordpress/create-blockDeze 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:
- Template variant: static
- Block slug: ka-example-block
- Internal namespace: ka-example-block
- Block display title: Kinsta Academy Block
- Short block description: An example block for Kinsta Academy students
- Dashicon: superhero-alt
- Category name: widgets
- Do you want to customize the WordPress plugin?: yes
- The home page of the plugin: https://kinsta.com/
- Current plugin version: 0.1.0
- Plugin author: your name
- License: –
- Link to the license text: –
- Custom domain path for translations: –
Het installeren van de plugin en alle dependencies duurt een paar minuten. Wanneer het proces is voltooid, zie je het volgende antwoord:
Voer nu de volgende opdracht uit vanuit de map /wp-content/plugins:
cd ka-example-block
Ten slotte kun je vanuit de map van je plugin (ka-example-block in ons voorbeeld) de ontwikkeling starten met:
npm startOpen nu het scherm Plugins om de plugin Kinsta Academy Block te zoeken en te activeren:
Maak een nieuw bericht, open de blokinvoeger en scrol omlaag naar de categorie Design. Klik om het Kinsta Academy Block toe te voegen:
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:
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 2,
"name": "ka-example-block/ka-example-block",
"version": "0.1.0",
"title": "Kinsta Academy Block",
"category": "widgets",
"icon": "superhero-alt",
"description": "An example block for Kinsta Academy students",
"supports": {
"html": false
},
"textdomain": "ka-example-block",
"editorScript": "file:./index.js",
"editorStyle": "file:./index.css",
"style": "file:./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:
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:
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",
"academy",
"superhero"
],Als je nu “kinsta”, “academy” of “superhero” invoert in de snelinvoer, zal de editor je het Kinsta Academy blok voorstellen:
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
registerBlockTypeFromMetadatamethode uit het@wordpress/blockspakket 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 metregister_block_type_from_metadata. De enige vereiste is om de eigenschaptextdomainin 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:
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() }>
{ __(
'Kinsta Academy Block – hello from the editor!',
'ka-example-block'
) }
</p>
);
}Deze code genereert een statisch blok met eenvoudige, niet-bewerkbare tekst. Maar we kunnen dingen gemakkelijk veranderen:
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:
- Importeer de benodigde componenten uit een WordPress pakket
- Neem de corresponderende elementen op in je JSX code
- Definieer de benodigde attributen in het bestand block.json
- Definieer event-handlers
- 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
useBlockPropshook gebruiken in deeditfunctie 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 viauseBlockPropsworden 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):
Als je useBlockProps uit het wrapper-element verwijdert, heb je een eenvoudige tekenreeks zonder toegang tot blokfunctionaliteit en -stijl:
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-elementonChange— functie aangeroepen wanneer de inhoud van het element verandertallowedFormats— een reeks toegestane formats. Standaard zijn alle formats toegestaanvalue— de HTML tekenreeks die bewerkbaar moet worden gemaaktplaceholder— 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:
typegeeft het type gegevens aan dat door het attribuut is opgeslagen. Het type is vereist, tenzij je een eigenschapenumdefinieert.sourcedefinieert 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).selectoris 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 ga terug naar je WordPress dashboard, maak een nieuw bericht of nieuwe pagina en voeg je aangepaste blok toe:
Voeg wat tekst toe en schakel over naar de codeweergave. Dit is hoe je code eruit zou moeten zien:
<!-- wp:ka-example-block/ka-example-block -->
<p class="wp-block-ka-example-block-ka-example-block">Kinsta Academy Block – hello from the saved content!</p>
<!-- /wp:ka-example-block/ka-example-block -->Zoals je kunt zien, is de inhoud van je blok veranderd als je overschakelt naar de code-editor. Dat komt omdat je het bestand save.js moet aanpassen om de gebruikersinput op te slaan in de database 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
RichTextcomponent uit hetblock-editor - Geef verschillende eigenschappen door via een objectargument aan de
savefunctie (in dit voorbeeld geven we alleen deattributesproperty door) - Retourneer de inhoud van de
RichTextcomponent
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:
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:
- Importeer vereiste componenten uit WordPress pakketten
- Neem de corresponderende elementen op in je JSX code
- Definieer de benodigde attributen in het block.json bestand
- Definieer event-handlers
- 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:
BlockControlsmaakt een dynamische werkbalk met besturingselementen (ongedocumenteerd).AlignmentControlgeeft 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:
valuegeeft de huidige waarde voor het elementonChangebiedt 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 blok-editor, ververs de pagina en selecteer het blok. Je zou een foutmelding in je blok moeten zien.
De reden is dat we onze event handler nog niet gedefinieerd hebben.
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 } }
/>
</>
);
}Ga nu terug naar de editor en zorg dat je de blokinhoud uitlijnt. Je blok zou nu een Alignment Toolbar moeten tonen.
Maar als je het bericht opslaat, zul je zien dat de inhoud van je blok aan de frontend niet is uitgelijnd zoals in de blok-editor. Dat komt omdat we de save functie moeten aanpassen 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 nu het bestand op en schakel over naar de code-editor. De blokcode moet er ongeveer zo uitzien:
<!-- wp:ka-example-block/ka-example-block {"align":"right"} -->
<p class="wp-block-ka-example-block-ka-example-block" style="text-align:right">This is my first editable <strong>Gutenberg</strong> <em>block</em> 😎</p>
<!-- /wp:ka-example-block/ka-example-block -->
En dat was het! Je hebt zojuist een alignmentmethode toegevoegd aan de toolbar van je blok 🤓
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:
- Importeer vereiste componenten uit WordPress pakketten
- Neem de corresponderende elementen op in je JSX code
- Definieer de benodigde attributen in het block.json bestand
- Definieer event-handlers
- 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 { content, align, backgroundColor, textColor } = attributes;
const onChangeContent = ( newContent ) => {
setAttributes( { content: newContent } )
}
const onChangeAlign = ( newAlign ) => {
setAttributes( {
align: newAlign === undefined ? 'none' : newAlign,
} )
}
return (
<>
<InspectorControls>
<PanelColorSettings
title={ __( 'Color settings', 'ka-example-block' ) }
initialOpen={ false }
colorSettings={ [
{
value: textColor,
onChange: onChangeTextColor,
label: __( 'Text color', 'ka-example-block' )
},
{
value: backgroundColor,
onChange: onChangeBackgroundColor,
label: __( 'Background color', 'ka-example-block' )
}
] }
/>
</InspectorControls>
<BlockControls>
<AlignmentControl
value={ align }
onChange={ onChangeAlign }
/>
</BlockControls>
<RichText
{ ...blockProps }
tagName="p"
onChange={ onChangeContent }
allowedFormats={ [ 'core/bold', 'core/italic' ] }
value={ content }
placeholder={ __( 'Write your text...' ) }
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...' ) }
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 } }
/>
);
}Sla het bestand op en controleer het blok in de editor. Mogelijk vind je een ongewenste verrassing: een foutmelding om je te laten weten dat het blok onverwachte of ongeldige inhoud bevat.
Dit gebeurt omdat het bestand save.js is gewijzigd en de in de database opgeslagen code niet overeenkomt met de in de editor gebruikte code.
Om dit te verhelpen, vernieuw je de pagina, verwijder je een instantie van je blok en voeg je het opnieuw toe aan je bericht:
Breng je wijzigingen aan, sla het bericht op en bekijk het aan de frontend. De wijzigingen die je in de blokeditor hebt aangebracht, moeten nu aan de frontend worden weergegeven.
Een externe link toevoegen en aanpassen
In deze sectie voeg je nieuwe componenten toe aan je bloktype:
- Een
ExternalLinkcomponent waarmee gebruikers een aanpasbare link aan je aangepaste 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';PanelBodyvoegt een inklapbare container toe aan de Instellingenzijbalk.PaneRowproduceert een generieke container voor zijbalkbedieningen.TextControlbiedt een besturingselement voor tekstinvoer.ToggleControlbiedt een schakelaar waarmee gebruikers een specifieke optie kunnen in-/uitschakelenExternalLinkis 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={ kaLink }
className="ka-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' )}
initialOpen={true}
>
...
</PanelBody>
</InspectorControls>Dit is wat we hiermee doen:
- Het
titleattribuut levert de paneeltitel. initialOpenstelt 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', 'ka-example-block' )}
initialOpen={true}
>
<PanelRow>
<fieldset>
<TextControl
label={__( 'KA link', 'ka-example-block' )}
value={ kaLink }
onChange={ onChangeKaLink }
help={ __( 'Add your Academy link', 'ka-example-block' )}
/>
</fieldset>
</PanelRow>
<PanelRow>
<fieldset>
<TextControl
label={__( 'Link label', 'ka-example-block' )}
value={ linkLabel }
onChange={ onChangeLinkLabel }
help={ __( 'Add link label', 'ka-example-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 kaLink, linkLabel en hasLinkNofollow in het bestand block.json :
"kaLink": {
"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, voeg de nieuwe attributen toe aan het attributen object en voeg de volgende functies toe:
const { content, align, backgroundColor, textColor, kaLink, linkLabel, hasLinkNofollow } = attributes;
const onChangeKaLink = ( newKaLink ) => {
setAttributes( { kaLink: newKaLink === undefined ? '' : newKaLink } )
}
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 { content, align, backgroundColor, textColor, kaLink, linkLabel, hasLinkNofollow } = attributes;
const blockProps = useBlockProps.save( {
className: `has-text-align-${ align }`
} );
return (
<div
{ ...blockProps }
style={ { backgroundColor: backgroundColor } }
>
<RichText.Content
tagName="p"
value={ content }
style={ { color: textColor } }
/>
<p>
<a
href={ kaLink }
className="ka-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.
Je kunt het resultaat in de afbeelding hieronder zien.
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:
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 kun je hetzelfde doen met style.scss. Zoals we hierboven al zeiden, worden stijlen die zijn gedefinieerd in style.scss zowel op de frontend als in de editor toegepast:
.wp-block-ka-example-block-ka-example-block {
padding: 4px;
}Nu kun je hetzelfde doen met style.scss:
.wp-block-ka-example-block-ka-example-block {
&.is-style-default{
border: 0;
background-color: #FFE2C7;
}
&.is-style-border{
border: 2px solid #000;
border-radius: 16px;
background-color: #F6F6F6;
}
}En dat is het! Ververs de pagina en veel plezier met je nieuwe blokstijlen:
Gutenberg blokken nesten met de InnerBlocks component
Hoewel volledig functioneel, is ons aangepaste blok nog steeds niet erg aantrekkelijk. Om het aantrekkelijker te maken voor het publiek 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:
InnerBlocksexporteert 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 blok:
const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [
[ 'core/column', { templateLock: 'all' }, [
[ 'core/image' ],
] ],
[ 'core/column', { templateLock: 'all' }, [
[ 'ka-example-block/ka-example-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:
all—InnerBlocksis 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:
registerBlockType('ka-example-block/ka-example-container-block', {
title: __( 'KA Container block', 'ka-example-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>
)
},
});
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 onChangeAlign = ( newAlign ) => {
setAttributes( {
align: newAlign === undefined ? 'none' : newAlign,
} )
}
const blockProps = useBlockProps( {
className: `has-text-align-${ align }`
} );
...
}We doen dezelfde wijziging in het bestand save.js:
import classnames from 'classnames';
...
export default function save( { attributes } ) {
...
const { content, align, backgroundColor, textColor, kaLink, linkLabel, hasLinkNofollow } = attributes;
const blockProps = useBlockProps.save( {
className: `has-text-align-${ align }`
} );
...
}Klaar is Kees! Je kunt de build nu uitvoeren voor productie:
npm run buildSamenvatting
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:
- Official Create a Block Tutorial voor beginners
- Official Block Tutorial voor gevorderde ontwikkelaars
- Dynamic Blocks
- How to Create Dynamic Blocks for Gutenberg
- Meta Boxes
- Creating a Sidebar for Your Plugin
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:
- Zo installeer je lokaal WordPress (gratis ebook)
- De echte waarde van managed WordPress hosting (gratis ebook)
- Wat is JavaScript?
- HTML vs HTML5
- Zo bewerk je CSS in WordPress
- Wat is PHP?
- De WordPress hooks bootcamp: Zo gebruik je actions, filters en custom hooks
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!
Carlo is een gepassioneerd liefhebber van webdesign en front-end development. Hij werkt al meer dan 10 jaar met WordPress, ook in samenwerking met Italiaanse en Europese universiteiten en onderwijsinstellingen. Hij heeft tientallen artikelen en gidsen over WordPress geschreven, gepubliceerd op zowel Italiaanse als internationale websites en in gedrukte tijdschriften. Je kunt Carlo vinden op X en LinkedIn.
Laat een reactie achter