Aangepaste velden bieden een manier om extra informatie toe te wijzen aan websitecontent. Deze stukjes informatie worden meestal metadata genoemd.

Metadata is informatie over informatie. In het geval van WordPress is dat informatie over berichten, gebruikers, comments en termen.

Gezien de veel-op-een relatie van metadata in WordPress zijn je mogelijkheden redelijk onbeperkt. Je kunt zoveel meta-opties hebben als je wilt, en je kunt er zowat alles in opslaan.

– Plugin Handbook

Hier zijn enkele voorbeelden van metadata die je aan een bericht kunt koppelen met behulp van aangepaste velden:

  • De geografische coördinaten van een plaats of stuk onroerend goed
  • De datum van een evenement
  • Het ISBN of de auteur van een boek
  • De stemming van de dag van de auteur van het bericht

En er zijn er nog veel meer.

WordPress biedt kant-en-klaar geen gemakkelijke manier om aangepaste velden toe te voegen en te beheren. In de Classic Editor worden aangepaste velden weergegeven in een vak dat onderaan de pagina staat, onder de Post Editor.

Aangepaste velden in de Classic Editor
Aangepaste velden in de Classic Editor

In Gutenberg zijn aangepaste velden standaard uitgeschakeld, maar je kunt ze weergeven door het betreffende item in de berichtinstellingen te selecteren.

Het paneel met aangepaste velden toevoegen aan de blok editor.
Het paneel met aangepaste velden toevoegen aan de blokeditor.

Helaas is er geen manier om metadata aan de frontend weer te geven zonder een plugin te gebruiken of aan de slag te gaan met code.

Als je een normale gebruiker bent, zijn er verschillende uitstekende plugins die het werk voor je doen. Maar als je een developer bent en meer wilt halen uit de aangepaste velden van WordPress, ze naadloos wilt integreren in de blokeditor, en ze wilt weergeven aan de frontend van je WordPress website met behulp van een aangepast Gutenberg blok, dan ben je hier op de juiste plaats.

Dus als je je afvraagt wat voor WordPress developers de beste manier is om aangepaste velden zowel in Gutenberg als in de Classic Editor te gebruiken, dan is het snelle antwoord “het maken van een plugin die zowel voor de Classic Editor als voor Gutenberg werkt”.

Maar maak je niet te veel zorgen. Als het maken van een plugin om aangepaste velden in beide editors te beheren je lastig lijkt, zullen we proberen het proces zo eenvoudig mogelijk te maken. Zodra je de concepten begrijpt die we in dit artikel bespreken, zul je de vaardigheden opdoen die nodig zijn om aangepaste metavelden in Gutenberg te beheren en allerlei websites te bouwen.

Opmerking: Zorg ervoor dat je een actuele versie van Node.js op je computer hebt voordat je iets doet

Dat gezegd hebbende, tijd voor het overzicht:

Een blokplugin maken met de officiële create-block tool

De eerste stap is het maken van een nieuwe plugin met alle bestanden en dependencies die nodig zijn om een nieuw bloktype te registreren. Met de blokplugin kun je eenvoudig een aangepast bloktype maken voor het beheren en weergeven van aangepaste metadata.

Om een nieuw bloktype te maken gebruiken we de officiële create-block tool. Voor een gedetailleerd overzicht van het gebruik van de create-block tool, bekijk je ons eerdere artikel over Gutenberg blokdevelopment.

Open je commandoregeltool, navigeer naar de plugins map van je WordPress developmentwebsite en voer het volgende commando uit:

npx @wordpress/create-block

Voeg de volgende gegevens toe als daarom wordt gevraagd:

  • The template variant to use for this block: dynamic
  • The block slug used for identification (also the output folder name): metadata-block
  • The internal namespace for the block name (something unique for your products): meta-fields
  • The display title for your block: Meta Fields
  • The short description for your block (optional): Block description
  • The dashicon to make it easier to identify your block (optional): book
  • The category name to help users browse and discover your block: widgets
  • Do you want to customize the WordPress plugin? Yes/No

Laten we even de tijd nemen om die details te bekijken en proberen te begrijpen waar ze gebruikt worden.

  • De blokslug die gebruikt wordt voor identificatie definieert de mapnaam en het tekstdomein van de plugin
  • De interne namespace voor de bloknaam definieert de interne namespace van het blok en het functieprefix dat in de hele code van de plugin wordt gebruikt.
  • De displaytitel voor je blok definieert de pluginnaam en de bloknaam die gebruikt wordt in de editorinterface.

Het instellen kan een paar minuten duren. Als het proces voltooid is, krijg je een lijst met de beschikbare commando’s.

Blokplugin succesvol geïnstalleerd.
Blokplugin succesvol geïnstalleerd.

Voordat je doorgaat naar de volgende sectie, navigeer je in je commandoregeltool naar de map van je plugin en voer je de volgende commando’s uit:

cd metadata-block
npm start

Je bent nu klaar om je code te bouwen. De volgende stap is het bewerken van het hoofdbestand PHP van de plugin om een metabox te bouwen voor de Classic Editor.

Voordat je doorgaat naar de volgende sectie, installeer en activeer je de Classic Editor plugin.

Open dan het Plugins scherm en activeer de nieuwe Meta Fields plugin.

Plugins activeren.
Plugins activeren.

Een metabox toevoegen aan de Classic Editor

In de context van de Classic Editor is een metabox een container met formulierelementen om specifieke informatie in te typen, zoals de auteur van een bericht, tags, categorieën, enz.

Naast de ingebouwde metaboxes kunnen plugindevelopers een willekeurig aantal aangepaste metaboxes toevoegen om HTML formulierelementen (of andere HTML content) op te nemen waarin plugingebruikers pluginspecifieke gegevens kunnen invoeren.

De WordPress API biedt handige functies om eenvoudig aangepaste metaboxes te registreren om alle HTML elementen op te nemen die je plugin nodig heeft om te werken.

Om te beginnen voeg je de volgende code toe aan het PHP bestand van de plugin die je zojuist hebt gemaakt:

// register meta box
function meta_fields_add_meta_box(){
	add_meta_box(
		'meta_fields_meta_box', 
		__( 'Book details' ), 
		'meta_fields_build_meta_box_callback', 
		'post',
		'side',
		'default'
	 );
}

// build meta box
function meta_fields_build_meta_box_callback( $post ){
	  wp_nonce_field( 'meta_fields_save_meta_box_data', 'meta_fields_meta_box_nonce' );
	  $title = get_post_meta( $post->ID, '_meta_fields_book_title', true );
	  $author = get_post_meta( $post->ID, '_meta_fields_book_author', true );
	  ?>
	  <div class="inside">
	  	  <p><strong>Title</strong></p>
		  <p><input type="text" id="meta_fields_book_title" name="meta_fields_book_title" value="<?php echo esc_attr( $title ); ?>" /></p>	
		  <p><strong>Author</strong></p>
		  <p><input type="text" id="meta_fields_book_author" name="meta_fields_book_author" value="<?php echo esc_attr( $author ); ?>" /></p>
	  </div>
	  <?php
}
add_action( 'add_meta_boxes', 'meta_fields_add_meta_box' );

De add_meta_box functie registreert een nieuwe metabox, terwijl de callback functie de HTML bouwt die in de metabox geïnjecteerd moet worden. We zullen niet dieper op dit onderwerp ingaan omdat het buiten het bereik van ons artikel valt, maar je vindt alle details die je nodig hebt hier, hier en hier.

De volgende stap is het maken van een functie die de door de auteur van het bericht ingevoerde gegevens opslaat telkens als de save_post hook wordt geactiveerd (zie Developers resources):

// save metadata
function meta_fields_save_meta_box_data( $post_id ) {
	if ( ! isset( $_POST['meta_fields_meta_box_nonce'] ) )
		return;
	if ( ! wp_verify_nonce( $_POST['meta_fields_meta_box_nonce'], 'meta_fields_save_meta_box_data' ) )
		return;
	if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE )
		return;
	if ( ! current_user_can( 'edit_post', $post_id ) )
		return;

	if ( ! isset( $_POST['meta_fields_book_title'] ) )
		return;
	if ( ! isset( $_POST['meta_fields_book_author'] ) )
		return;

	$title = sanitize_text_field( $_POST['meta_fields_book_title'] );
	$author = sanitize_text_field( $_POST['meta_fields_book_author'] );

	update_post_meta( $post_id, '_meta_fields_book_title', $title );
	update_post_meta( $post_id, '_meta_fields_book_author', $author );
}
add_action( 'save_post', 'meta_fields_save_meta_box_data' );

Nogmaals, bekijk de online documentatie voor details. Hier wijzen we alleen op het onderstrepingsteken (_) voor de metasleutel. Dit vertelt WordPress om de sleutels van deze aangepaste velden te verbergen uit de lijst van standaard beschikbare aangepaste velden en maakt je aangepaste velden alleen zichtbaar in je aangepaste metabox.

De afbeelding hieronder laat zien hoe het aangepaste metabox eruit ziet in de Classic Editor:

Een aangepast metabox in de Classic Editor.
Een aangepast metabox in de Classic Editor.

Als je nu de Classic Editor plugin uitschakelt en kijkt wat er gebeurt in de blokeditor, zul je zien dat de metabox nog steeds verschijnt en werkt, maar niet precies op de manier die je zou verwachten.

Ons doel is om een systeem te maken voor het beheer van metadata bij blogberichten of aangepaste berichttypes dat naadloos integreert in de blokeditor. Daarom zal de tot nu toe getoonde code alleen nodig zijn om achterwaartse compatibiliteit met de Classic Editor te garanderen.

Dus, voordat we verder gaan, vertellen we WordPress om de aangepaste metabox uit de blokeditor te verwijderen door de __back_compat_meta_box flag toe te voegen aan de add_meta_box functie (zie ook Meta Box Compatibility Flags en Backward Compatibility).

Laten we teruggaan naar de callback functie die de metabox registreert en deze als volgt veranderen:

// register meta box
function meta_fields_add_meta_box(){
	add_meta_box(
		'meta_fields_meta_box', 
		__( 'Book details' ), 
		'meta_fields_build_meta_box_callback', 
		'post', 
		'side',
		'default',
		// hide the meta box in Gutenberg
		array('__back_compat_meta_box' => true)
	 );
}

Sla het pluginbestand op en ga terug naar je WordPress admin. Nu zou je de aangepaste metabox niet meer moeten zien in de blokeditor. Als je in plaats daarvan de Classic Editor opnieuw activeert, zal je aangepaste metabox weer verschijnen.

Aangepaste metavelden toevoegen aan de Gutenberg blokeditor (drie opties)

In onze vorige artikelen over Gutenberg blokdevelopment gaven we gedetailleerde overzichten van de editor, de onderdelen ervan, en hoe je statische blokken en dynamische blokken kunt ontwikkelen.

Zoals gezegd gaan we in dit artikel een stap verder en bespreken we hoe je aangepaste metavelden kunt toevoegen aan blogberichten.

Er zijn verschillende manieren om in Gutenberg berichtmetadata op te slaan en te gebruiken. Hier behandelen we de volgende:

Een aangepast blok maken om aangepaste metavelden op te slaan en weer te geven

In dit deel laten we je zien hoe je aangepaste metavelden kunt maken en beheren vanuit een dynamisch blok. Volgens het Block Editor Handbook is een berichtmetaveld “een WordPress object dat gebruikt wordt om extra gegevens over een bericht op te slaan” en moeten we eerst een nieuw metaveld registreren voordat we het kunnen gebruiken.

Aangepaste metavelden registreren

Voordat je een aangepast metaveld registreert, moet je ervoor zorgen dat het berichttype dat het gaat gebruiken aangepaste velden ondersteunt. Bovendien moet je bij het registreren van een aangepast metaveld de parameter show_in_rest instellen op true.

Nu terug naar het pluginbestand. Voeg de volgende code toe:

/**
 * Register the custom meta fields
 */
function meta_fields_register_meta() {

    $metafields = [ '_meta_fields_book_title', '_meta_fields_book_author' ];

    foreach( $metafields as $metafield ){
        // Pass an empty string to register the meta key across all existing post types.
        register_post_meta( '', $metafield, array(
            'show_in_rest' => true,
            'type' => 'string',
            'single' => true,
            'sanitize_callback' => 'sanitize_text_field',
            'auth_callback' => function() { 
                return current_user_can( 'edit_posts' );
            }
        ));
    }  
}
add_action( 'init', 'meta_fields_register_meta' );

register_post_meta registreert een metasleutel voor de opgegeven berichttypes. In bovenstaande code hebben we twee aangepaste metavelden geregistreerd voor alle op je website geregistreerde berichttypes die aangepaste velden ondersteunen. Zie voor meer informatie de functiereferentie.

Als dat gedaan is, open dan het bestand src/index.js van je blokplugin.

Het bloktype in de client registreren

Navigeer nu naar de map wp-content/plugins/metadata-block/src en open het bestand index.js:

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

registerBlockType( metadata.name, {
	edit: Edit,
} );

Bij statische blokken zouden we ook een save functie hebben gezien. In dit geval ontbreekt de functie save omdat we een dynamisch blok hebben geïnstalleerd. De content die op de frontend wordt getoond, wordt dynamisch gegenereerd via PHP.

Het bloktype bouwen

Navigeer naar de map wp-content/plugins/metadata-block/src en open het bestand edit.js. Je zou de volgende code moeten zien (comments verwijderd):

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

export default function Edit() {
	return (
		<p { ...useBlockProps() }>
			{ __( 'Meta Fields – hello from the editor!', 'metadata-block' ) }
		</p>
	);
}

Hier voeg je de code toe om het in de editor weer te geven blok te genereren.

De eerste stap is het importeren van de componenten en functies die nodig zijn om het blok te bouwen. Hier is de volledige lijst van dependencies:

import { __ } from '@wordpress/i18n';
import { useBlockProps, InspectorControls, RichText } from '@wordpress/block-editor';
import { useSelect } from '@wordpress/data';
import { useEntityProp } from '@wordpress/core-data';
import { TextControl, PanelBody, PanelRow } from '@wordpress/components';
import './editor.scss';

Als je onze vorige artikelen hebt gelezen, zou je bekend moeten zijn met veel van deze import declaraties. Hier geven we er slechts een paar aan:

import { useSelect } from '@wordpress/data';
import { useEntityProp } from '@wordpress/core-data';

Als je deze dependencies hebt geïmporteerd, is dit hoe je useSelect en useEntityProp in de functie Edit():

const postType = useSelect(
		( select ) => select( 'core/editor' ).getCurrentPostType(),
		[]
	);
const [ meta, setMeta ] = useEntityProp( 'postType', postType, 'meta' );

Deze code levert de huidige postType, een object van metavelden (meta), en een setterfunctie om ze bij te werken (setMeta).

Vervang nu de huidige code voor de Edit() functie door het volgende:

export default function Edit() {
	const blockProps = useBlockProps();
	const postType = useSelect(
		( select ) => select( 'core/editor' ).getCurrentPostType(),
		[]
	);
	const [ meta, setMeta ] = useEntityProp( 'postType', postType, 'meta' );
	const bookTitle = meta[ '_meta_fields_book_title' ];
	const bookAuthor = meta[ '_meta_fields_book_author' ];
	const updateBookTitleMetaValue = ( newValue ) => {
		setMeta( { ...meta, _meta_fields_book_title: newValue } );
    };
	const updateBookAuthorMetaValue = ( newValue ) => {
		setMeta( { ...meta, _meta_fields_book_author: newValue } );
	};
return ( ... );
}

Dus om samen te vatten:

  • We hebben useSelect gebruikt om het huidige berichttype te krijgen.
  • useEntityProp geeft een array van metavelden terug en een setterfunctie om nieuwe metawaarden in te stellen.
  • updateBookTitleMetaValue en updateBookAuthorMetaValue zijn twee eventhandlers om metaveldwaarden op te slaan.

De volgende stap is het bouwen van de JSX (JavaScript XML) code die de Edit() functie teruggeeft:

export default function Edit() {
	...
	return (
		<>
			<InspectorControls>
				<PanelBody 
					title={ __( 'Book Details' )}
					initialOpen={true}
				>
					<PanelRow>
						<fieldset>
							<TextControl
								label={__( 'Book title' )}
								value={ bookTitle }
								onChange={ updateBookTitleMetaValue }
							/>
						</fieldset>
					</PanelRow>
					<PanelRow>
						<fieldset>
							<TextControl
								label={ __( 'Book author' ) }
								value={ bookAuthor }
								onChange={ updateBookAuthorMetaValue }
							/>
						</fieldset>
					</PanelRow>
				</PanelBody>
			</InspectorControls>
			<div { ...blockProps }>
				<RichText 
					tagName="h3"
					onChange={ updateBookTitleMetaValue }
					allowedFormats={ [ 'core/bold', 'core/italic' ] }
					value={ bookTitle }
					placeholder={ __( 'Write your text...' ) }
				/>
				<TextControl
					label="Book Author"
					value={ bookAuthor }
					onChange={ updateBookAuthorMetaValue }
				/>
			</div>
		</>
	);
}

De component RichText levert een content-editable input, terwijl TextControl eenvoudige tekstvelden levert.

We hebben ook een zijbalkpaneel gemaakt met twee invoervelden om te gebruiken in plaats van de twee formulierbesturingselementen in het blok.

Sla het bestand op en ga terug naar de editor. Voeg het blok Meta Fields uit de blokinserter toe en vul de boektitel en auteur in.

Een aangepast blok inclusief twee aangepaste metavelden.
Een aangepast blok inclusief twee aangepaste metavelden.

Je zult merken dat telkens als je de waarde van het veld in het blok verandert, de waarde in het corresponderende tekstveld in de zijbalk ook verandert.

Vervolgens moeten we de PHP code maken die de HTML genereert die op de frontend wordt weergegeven.

Het blok weergeven aan de frontend

Open het PHP hoofdbestand opnieuw in je code editor en herschrijf de callback functie die de uitvoer van het blok genereert als volgt:

function meta_fields_metadata_block_block_init() {
	register_block_type(
		__DIR__ . '/build',
		array(
			'render_callback' => 'meta_fields_metadata_block_render_callback',
		)
	);
}
add_action( 'init', 'meta_fields_metadata_block_block_init' );

function meta_fields_metadata_block_render_callback( $attributes, $content, $block ) {
	
	$book_title = get_post_meta( get_the_ID(), '_meta_fields_book_title', true );
	$book_author = get_post_meta( get_the_ID(), '_meta_fields_book_author', true );
    
	$output = "";

	if( ! empty( $book_title ) ){
		$output .= '<h3>' . esc_html( $book_title ) . '</h3>';
	}
	if( ! empty( $book_author ) ){
		$output .= '<p>' . __( 'Book author: ' ) . esc_html( $book_author ) . '</p>';
	}
	if( strlen( $output ) > 0 ){
		return '<div ' . get_block_wrapper_attributes() . '>' . $output . '</div>';
	} else {
		return '<div ' . get_block_wrapper_attributes() . '>' . '<strong>' . __( 'Sorry. No fields available here!' ) . '</strong>' . '</div>';
	}
}

Deze code wijst zichzelf. Eerst gebruiken we get_post_meta om de waarden van de aangepaste metavelden op te halen. Dan gebruiken we die waarden om de content van het blok op te bouwen. Tenslotte geeft de callback functie de HTML van het blok terug.

Het blok is klaar voor gebruik. We hebben de code in dit voorbeeld met opzet zo eenvoudig mogelijk gehouden, maar met behulp van de ingebouwde componenten van Gutenberg kun je meer geavanceerde blokken bouwen en het meeste halen uit de aangepaste metavelden van WordPress.

Een aangepast blok inclusief verschillende metavelden.
Een aangepast blok inclusief verschillende metavelden.

In ons voorbeeld hebben we h3 en p elementen gebruikt om het blok voor de frontend te bouwen.

Maar je kunt de gegevens op vele manieren weergeven. De volgende afbeelding toont een eenvoudige ongeordende lijst van metavelden.

Een voorbeeldblok op de frontend.
Een voorbeeldblok op de frontend.

Je vindt de volledige code van dit voorbeeld in deze openbare gist.

Een aangepast metavak toevoegen aan de zijbalk van het document

De tweede optie is om aangepaste metavelden aan berichten toe te voegen met een plugin die een instellingenpaneel genereert in de zijbalk van het document.

Het proces is redelijk vergelijkbaar met het vorige voorbeeld, behalve dat we in dit geval geen blok nodig hebben om metadata te beheren. We maken een component om een paneel te genereren met een reeks regelaars in de Document sidebar volgens deze stappen:

  1. Maak een nieuwe blokplugin met create-block
  2. Registreer een aangepast metavak voor de Classic Editor
  3. Registreer de aangepaste metavelden in het hoofdplugin-bestand via de functie register_post_meta()
  4. Registreer een plugin in het bestand index.js
  5. Bouw de component met behulp van ingebouwde Gutenberg componenten

Maak een nieuwe blokplugin met de create-block tool

Om een nieuwe blokplugin te maken, volg je de stappen in de vorige paragraaf. Je kunt een nieuwe plugin maken of de scripts bewerken die we in het vorige voorbeeld hebben gebouwd.

Registreer aangepast metavak  voor de Classic Editor

Vervolgens moet je een aangepast metavak registreren om achterwaartse compatibiliteit te garanderen voor WordPress websites die nog steeds de Classic Editor gebruiken. Het proces is hetzelfde als beschreven in de vorige paragraaf.

Registreer de aangepaste metavelden in het hoofdbestand van de plugin

De volgende stap is het registreren van de aangepaste metavelden in het hoofdbestand van de plugin via de functie register_post_meta(). Ook hier kun je het vorige voorbeeld volgen.

Registreer een plugin in het index.js bestand

Als je de vorige stappen hebt uitgevoerd, is het tijd om een plugin te registreren in het index.js bestand om een aangepaste component te renderen.

Voordat je de plugin registreert, maak je een components map aan in de src map van de plugin. Maak in de components map een nieuw MetaBox.js bestand aan. Je kunt elke naam kiezen waarvan je denkt dat die goed is voor je component. Zorg ervoor dat je de best practice voor naamgeving binnen React volgt.

Voordat je verder gaat, installeer je de module@wordpress/plugins vanuit je commandoregeltool.

Stop het proces (mac), installeer de module en start het proces opnieuw:

^C
npm install @wordpress/plugins --save
npm start

Wanneer je klaar bent open je het index.js bestand van je plugin en voeg de volgende code toe.

/**
 * Registers a plugin for adding items to the Gutenberg Toolbar
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-sidebar/
 */
import { registerPlugin } from '@wordpress/plugins';

import MetaBox from './components/MetaBox';

Deze code spreekt redelijk voor zich. We willen echter even stilstaan bij de twee import statements voor de lezers die geen geavanceerde React vaardigheden hebben.

Met het eerste import statement hebben we de naam van de functie ingesloten tussen accolades. Bij het tweede import statement is de naam van de component niet tussen accolades ingesloten.

Registreer vervolgens je plugin:

registerPlugin( 'metadata-plugin', {
	render: MetaBox
} );

registerPlugin registreert simpelweg een plugin. De functie accepteert twee parameters:

  • Een unieke string die de plugin identificeert
  • Een object met plugininstellingen. Let op dat de property render gespecificeerd moet worden en een geldige functie moet zijn.

Bouw het component met behulp van ingebouwde Gutenberg componenten

Het is tijd om ons React component te bouwen. Open het bestand MetaBox.js (of hoe je het ook genoemd hebt) en voeg de volgende importstatements toe:

import { __ } from '@wordpress/i18n';
import { compose } from '@wordpress/compose';
import { withSelect, withDispatch } from '@wordpress/data';
import { PluginDocumentSettingPanel } from '@wordpress/edit-post';
import { PanelRow, TextControl, DateTimePicker } from '@wordpress/components';
  • De functie compose voert functiecompositie uit, wat betekent dat het resultaat van een functie wordt doorgegeven aan een andere functie. Voordat je compose kunt gebruiken, moet je mogelijk de bijbehorende module installeren: 
    npm install @wordpress/compose --save

    We zullen de functie compose straks in actie zien.

  • withSelect en withDispatch zijn twee higher-order componenten waarmee je gegevens van of naar een WordPress store kunt halen of verzenden. withSelect wordt gebruikt om van de staat afgeleide props te injecteren met behulp van geregistreerde selectors, withDispatch wordt gebruikt om props te verzenden met behulp van geregistreerde action creators.
  • PluginDocumentSettingPanel rendert items in de Document Sidebar (zie de broncode op Github).

Vervolgens maak je de component om het metaboxpaneel in de Document Sidebar weer te geven. Voeg in je MetaBox.js bestand de volgende code toe:

const MetaBox = ( { postType, metaFields, setMetaFields } ) => {

	if ( 'post' !== postType ) return null;

	return(
		<PluginDocumentSettingPanel 
			title={ __( 'Book details' ) } 
			icon="book"
			initialOpen={ false }
		>
			<PanelRow>
				<TextControl 
					value={ metaFields._meta_fields_book_title }
					label={ __( "Title" ) }
					onChange={ (value) => setMetaFields( { _meta_fields_book_title: value } ) }
				/>
			</PanelRow>
			<PanelRow>
				<TextControl 
					value={ metaFields._meta_fields_book_author }
					label={ __( "Author" ) }
					onChange={ (value) => setMetaFields( { _meta_fields_book_author: value } ) }
				/>
			</PanelRow>
			<PanelRow>
				<TextControl 
					value={ metaFields._meta_fields_book_publisher }
					label={ __( "Publisher" ) }
					onChange={ (value) => setMetaFields( { _meta_fields_book_publisher: value } ) }
				/>
			</PanelRow>
			<PanelRow>
				<DateTimePicker
					currentDate={ metaFields._meta_fields_book_date }
					onChange={ ( newDate ) => setMetaFields( { _meta_fields_book_date: newDate } ) }
					__nextRemoveHelpButton
					__nextRemoveResetButton
				/>
			</PanelRow>
		</PluginDocumentSettingPanel>
	);
}

const applyWithSelect = withSelect( ( select ) => {
	return {
		metaFields: select( 'core/editor' ).getEditedPostAttribute( 'meta' ),
		postType: select( 'core/editor' ).getCurrentPostType()
	};
} );

const applyWithDispatch = withDispatch( ( dispatch ) => {
	return {
		setMetaFields ( newValue ) {
			dispatch('core/editor').editPost( { meta: newValue } )
		}
	}
} );

export default compose([
	applyWithSelect,
	applyWithDispatch
])(MetaBox);

Laten we deze code opsplitsen.

  • Het PluginDocumentSettingPanel element rendert een nieuw paneel in de Document zijbalk. We stellen de titel (“Book details”) en het pictogram in, en stellen initialOpen in op false, wat betekent dat het paneel aanvankelijk gesloten is.
  • Binnen de PluginDocumentSettingPanel hebben we drie tekstvelden en een DateTimePicker element waarmee de gebruiker de publicatiedatum kan instellen.
  • withSelect geeft toegang tot de functie select die we gebruiken om metaFields en postType op te halen. withDispatch geeft toegang tot de functie dispatch, waarmee de metadatawaarden kunnen worden bijgewerkt.
  • Tenslotte kunnen we met de compose functie onze component samenstellen met withSelect en withDispatch higher-order componenten. Dit geeft de component toegang tot de metaFields en postType properties en de setMetaFields functie.

Sla je MetaBox.js bestand op en maak een nieuw bericht aan in je WordPress ontwikkelingswebsite en bekijk de zijbalk van het document. Je zou het nieuwe paneel Book details moeten zien.

Een aangepast metaboxpaneel in Gutenberg.
Een aangepast metaboxpaneel in Gutenberg.

Voer nu je tests uit. Stel de waarden van je aangepaste metavelden in en sla het bericht op. Herlaad dan de pagina en controleer of de waarden die je hebt ingevoerd op hun plaats staan.

Voeg het blok toe dat we in de vorige sectie hebben gebouwd en controleer of alles goed werkt.

Een aangepaste zijbalk toevoegen om metadata van berichten te beheren

Als je een groot aantal aangepaste metavelden hebt om toe te voegen aan je berichten of aangepaste berichttypes, kun je ook een Custom Settings Sidebar maken, speciaal voor je plugin.

Het proces lijkt sterk op het vorige voorbeeld, dus als je de stappen hebt begrepen die in de vorige sectie zijn besproken, zul je geen moeite hebben met het bouwen van een Custom Sidebar voor Gutenberg.

Nogmaals:

  1. Maak een nieuwe blokplugin met create-block
  2. Registreer een aangepast metavak voor de Classic Editor
  3. Registreer de aangepaste metavelden in het hoofdpluginbestand via de functie register_post_meta()
  4. Registreer een plugin in het bestand index.js
  5. Bouw de component met behulp van ingebouwde Gutenberg componenten

Maak een nieuwe blokplugin met de create-block tool

Nogmaals, om een nieuwe blokplugin te maken volg je de hierboven besproken stappen. Je kunt een nieuwe plugin maken of de in de vorige voorbeelden gebouwde scripts bewerken.

Registreer een aangepast metabox voor de Classic Editor

Registreer nu een aangepast metabox om achterwaartse compatibiliteit te garanderen voor WordPress websites die nog steeds de Classic Editor gebruiken. Het proces is hetzelfde als beschreven in de vorige paragraaf.

Registreer de aangepaste metavelden in het hoofdbestand van de plugin

Registreer de aangepaste metavelden in het hoofdpluginbestand via de functie register_post_meta().

Registreer een plugin  in het index.js bestand

Maak nu een leeg CustomSidebar.js bestand in je componenten map.

Als je dat gedaan hebt, verander je je index.js bestand als volgt:

/**
 * Registers a plugin for adding items to the Gutenberg Toolbar
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-sidebar/
 */
import { registerPlugin } from '@wordpress/plugins';

import CustomSidebar from './components/CustomSidebar';
// import MetaBox from './components/MetaBox';

registerPlugin( 'metadata-block', {
    render: CustomSidebar
} );

Met bovenstaande code importeren we eerst de CustomSidebar component, daarna vertellen we de registerPlugin functie om de nieuwe component te renderen.

Bouw het component met behulp van ingebouwde Gutenberg componenten

Open vervolgens het CustomSidebar.js bestand en voeg de volgende dependencies toe:

import { __ } from '@wordpress/i18n';
import { compose } from '@wordpress/compose';
import { withSelect, withDispatch } from '@wordpress/data';
import { PluginSidebar, PluginSidebarMoreMenuItem } from '@wordpress/edit-post';
import { PanelBody, PanelRow, TextControl, DateTimePicker } from '@wordpress/components';

Je zou moeten opmerken dat we twee nieuwe componenten importeren:

  • PluginSidebar voegt een pictogram toe aan de Gutenberg Toolbar dat, wanneer erop geklikt wordt, een zijbalk weergeeft inclusief de content die in het <PluginSidebar /> element is gewikkeld (Het component is ook gedocumenteerd op GitHub).
  • PluginSidebarMoreMenuItem geeft een menu item weer onder Plugins in more menu dropdown en kan worden gebruikt om de bijbehorende PluginSidebar component te activeren (zie ook op GitHub).

Nu kun je je aangepaste component bouwen:

const CustomSidebar = ( { postType, metaFields, setMetaFields } ) => {
        
    if ( 'post' !== postType ) return null;

    return (
        <>
            <PluginSidebarMoreMenuItem 
                target="metadata-sidebar" 
                icon="book"
            >
                Metadata Sidebar
            </PluginSidebarMoreMenuItem>
            <PluginSidebar 
                name="metadata-sidebar" 
                icon="book" 
                title="My Sidebar"
            >
                <PanelBody title="Book details" initialOpen={ true }>
                    <PanelRow>
                        <TextControl 
                            value={ metaFields._meta_fields_book_title }
                            label={ __( "Title" ) }
                            onChange={ (value) => setMetaFields( { _meta_fields_book_title: value } ) }
                        />
                    </PanelRow>
                    <PanelRow>
                        <TextControl 
                            value={ metaFields._meta_fields_book_author }
                            label={ __("Author", "textdomain") }
                            onChange={ (value) => setMetaFields( { _meta_fields_book_author: value } ) }
                        />
                    </PanelRow>
                    <PanelRow>
                        <TextControl 
                            value={ metaFields._meta_fields_book_publisher }
                            label={ __("Publisher", "textdomain") }
                            onChange={ (value) => setMetaFields( { _meta_fields_book_publisher: value } ) }
                        />
                    </PanelRow>
                    <PanelRow>
                        <DateTimePicker
                            currentDate={ metaFields._meta_fields_book_date }
                            onChange={ ( newDate ) => setMetaFields( { _meta_fields_book_date: newDate } ) }
                            __nextRemoveHelpButton
                            __nextRemoveResetButton
                        />
                    </PanelRow>
                </PanelBody>
            </PluginSidebar>
        </>
    )
}

De laatste stap is de componentcompositie met withSelect en withDispatch higher-order componenten:

const applyWithSelect = withSelect( ( select ) => {
    return {
        metaFields: select( 'core/editor' ).getEditedPostAttribute( 'meta' ),
        postType: select( 'core/editor' ).getCurrentPostType()
    };
} );

const applyWithDispatch = withDispatch( ( dispatch ) => {
    return {
        setMetaFields ( newValue ) {
            dispatch('core/editor').editPost( { meta: newValue } )
        }
    }
} );

export default compose([
    applyWithSelect,
    applyWithDispatch
])(CustomSidebar);

Sla je wijzigingen op en bekijk dan de editor interface. Als je de Options dropdown opent, zie je een nieuw item Metadata Sidebar onder de sectie Plugins. Door op het nieuwe item te klikken activeer je je gloednieuwe aangepaste zijbalk.

De PluginSidebarMoreMenuItem component voegt een menu item toe onder Options - Plugins.
De PluginSidebarMoreMenuItem component voegt een menu item toe onder Options – Plugins.

Hetzelfde gebeurt als je klikt op het boekicoontje in de rechterbovenhoek.

De zijbalk met plugininstellingen.
De zijbalk met plugininstellingen.

Ga nu terug naar je ontwikkelingswebsite, en maak een nieuw blogbericht aan. Vul je metavelden in, en voeg het blok toe aan het canvas van de editor. Het zou dezelfde metawaarden moeten bevatten die je in je aangepaste zijbalk hebt ingevoerd.

Sla het bericht op en bekijk de pagina op de frontend. Je zou je kaart moeten zien met de boektitel, auteur, uitgever en publicatiedatum.

Je vindt de volledige code van dit artikel in deze openbare gist.

Verder lezen

In dit artikel hebben we meerdere onderwerpen behandeld, van selectors tot higher-order componenten en nog veel meer. We hebben ook de belangrijkste resources die we hebben gebruikt als referentie in het artikel opgenomen.

Maar als je dieper in die onderwerpen wilt duiken, kun je misschien ook de volgende aanvullende resources bekijken:

Gutenberg Documentatie en Officiële WordPress Hulpbronnen

Meer officiële resources

Aanvullende resources van de community

Nuttige leessuggesties van de Kinsta website

Samenvatting

In dit derde artikel in onze serie over Gutenberg blokdevelopment hebben we nieuwe geavanceerde onderwerpen behandeld die het in eerdere artikelen geschetste beeld over statische en dynamische blokontwikkeling completer moeten maken.

Je zou nu moeten kunnen profiteren van het potentieel van aangepaste velden in Gutenberg en meer geavanceerde en functionele WordPress websites moeten kunnen maken.

Maar er is meer. Met de vaardigheden die je hebt opgedaan in onze artikelen over blokdevelopment, zou je ook een goed idee moeten hebben van hoe je React componenten buiten WordPress kunt ontwikkelen. Gutenberg is immers een op React gebaseerde SPA.

En nu is het jouw beurt! Heb jij al Gutenberg blokken gemaakt die aangepaste metavelden gebruiken? Deel je creaties met ons in de comments hieronder.

Carlo Daniele Kinsta

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.