In 2018 introduceerde WordPress met versie 5.0 de Gutenberg editor, een nieuwe manier om pagina’s en berichten op te bouwen met behulp van “blokken”. In het begin waren deze blokken vrij basic, maar in de loop der jaren zijn ze geëvolueerd om meer flexibiliteit en een betere bewerkingservaring te bieden.
Toch zijn er momenten waarop een blok niet helemaal doet wat je nodig hebt. Misschien wil je bepaalde features verwijderen, nieuwe toevoegen, standaard een bepaalde stijl toepassen of bepaalde instellingen gemakkelijker toegankelijk maken. In dit soort gevallen lijkt het misschien een optie om helemaal opnieuw een custom blok te maken, maar – laten we eerlijk zijn – dat is overkill voor kleine aanpassingen. Zou het niet eenvoudiger zijn als je gewoon blokken die al bestaan zou kunnen aanpassen?
Dat is waar de Blocks API je kan helpen. Dit artikel legt uit hoe je blokken van de WordPress core kunt uitbreiden met behulp van de Blocks API, met praktische voorbeelden die je kunt gebruiken in echte projecten.
De WordPress Blocks API begrijpen
De WordPress Blocks API is de basis van de blokken-editor, waarmee ontwikkelaars blokken kunnen maken, wijzigen en uitbreiden. De API biedt verschillende manieren om met blokken te werken. Je kunt:
- Blokinstellingen wijzigen – Blokattributen, standaardwaarden en gedragingen wijzigen.
- Blokondersteuning toevoegen of verwijderen – Eigenschappen zoals typografie, kleuren en spatiëring in- of uitschakelen.
- Aangepaste besturingselementen injecteren – Nieuwe opties toevoegen in het paneel met blokinstellingen.
- Variaties op blokken maken – Voorgeconfigureerde versies van bestaande blokken maken om het maken van inhoud te versnellen.
Elk blok in WordPress, of het nu een Paragraph, Image of Button blok is, wordt gedefinieerd door een set attributen en instellingen die zijn opgeslagen in een block.json bestand. Dit bestand bevat metadata over het blok, waaronder de naam, categorie, standaard attributen en de functies die het ondersteunt.
Met WordPress kun je deze waarden wijzigen met PHP of JavaScript, maar dit artikel legt uit hoe je filterhooks in de Blocks API kunt gebruiken. Dit zorgt ervoor dat je wijzigingen worden geregistreerd op de server zonder dat je extra JavaScript bestanden hoeft aan te roepen.
Als je bijvoorbeeld bepaalde functies van een blok wilt in- of uitschakelen, kun je dat het beste doen met het filter register_block_type_args in PHP. Met deze methode kun je blokinstellingen dynamisch aanpassen zonder het bestand block.json direct te wijzigen.
Blok ondersteuning wijzigen
WordPress blokken worden geleverd met voorgedefinieerde steunen, die de opties van de editor regelen. Sommige blokken, zoals het Image blok (core/image), hebben standaard duotone filters ingeschakeld, waarmee gebruikers kleuroverlays kunnen toepassen.
Het Media & Text blok (core/media-text) ondersteunt duotoon echter niet out of the box, ook al stelt het gebruikers in staat om een afbeelding in te voegen. Dit betekent dat je wel een duotoon filter kunt toepassen op een losstaand afbeeldingsblok, maar niet wanneer je een afbeelding in een Media & Text blok plaatst.
Omdat het Media & Text blok een afbeelding kan bevatten, is het zinvol om duotone filters in te schakelen. We kunnen dit doen door de supports array aan te passen en de juiste CSS selector op te geven zodat het filter correct wordt toegepast. We kunnen het inschakelen met het register_block_type_args filter in PHP.
Voeg de volgende code toe aan het bestand functions.php van je thema:
function enable_duotone_for_media_text_block($args, $block_type) {
// Only modify the Media & Text block
if ( 'core/media-text' === $block_type ) {
$args['supports'] ??= [];
$args['supports']['filter'] ??= [];
$args['supports']['filter']['duotone'] = true;
$args['selectors'] ??= [];
$args['selectors']['filter'] ??= [];
$args['selectors']['filter']['duotone'] = '.wp-block-media-text .wp-block-media-text__media';
}
return $args;
}
add_filter('register_block_type_args', 'enable_duotone_for_media_text_block', 10, 2);De bovenstaande code schakelt het duotone filter in binnen de supports array en definieert de juiste CSS selector om het duotone effect toe te passen op afbeeldingen binnen het Media & Text blok. De functie add_filter() gebruikt 10 als prioriteit (wanneer het filter wordt uitgevoerd) en 2 om het aantal doorgegeven argumenten op te geven ($args, $block_type).
Als je het bestand opslaat en opnieuw laadt, zou je de Duotone regelaars beschikbaar moeten zien in het Filters gedeelte.
Duotoon inschakelen voor het blok Media & Text met register_block_type_args is een effectieve manier om het gedrag van blokken dynamisch aan te passen. WordPress biedt echter nog een andere methode voor het wijzigen van blokinstellingen: het overschrijven van blok metadata met behulp van block_type_metadata.
Met beide benaderingen kun je blokken aanpassen, maar ze werken in verschillende stadia van het blokregistratieproces.
Laten we bijvoorbeeld zeggen dat we het Paragraph blok (core/paragraph) willen aanpassen zodat het alleen marge-aanpassingen ondersteunt en opvulling uitschakelt. Een manier om dit te doen is door register_block_type_args te gebruiken:
function modify_paragraph_spacing_args($args, $block_type) {
if ($block_type === 'core/paragraph') {
$args['supports']['spacing'] = [
'margin' => true,
'padding' => false
];
}
return $args;
}
add_filter('register_block_type_args', 'modify_paragraph_spacing_args', 10, 2);Deze methode werkt in de meeste gevallen goed, maar omdat het blok wordt aangepast nadat het al is geregistreerd, kan het soms worden overschreven door andere plugins of thema’s die hetzelfde blok later in het proces aanpassen.
Een meer gestructureerde aanpak in dit geval zou kunnen zijn om de metadata van het blok direct te overschrijven met block_type_metadata:
function mytheme_modify_paragraph_spacing($metadata) {
if ($metadata['name'] === 'core/paragraph') {
$metadata['supports']['spacing'] = [
'margin' => true,
'padding' => false
];
}
return $metadata;
}
add_filter('block_type_metadata', 'mytheme_modify_paragraph_spacing');Geen van beide benaderingen is per definitie beter dan de andere – het hangt er gewoon vanaf wanneer je het blok wilt wijzigen en hoe persistent je de wijziging wilt hebben.
Blokstijlen registreren
Veel WordPress blokken hebben voorgedefinieerde stijlen die gebruikers kunnen selecteren in de editor. Een goed voorbeeld is het Image blok (core/image), dat standaard een afgeronde stijl bevat. De standaard afgeronde hoeken zijn echter vaak te extreem, waardoor de afbeelding meer op een ovaal lijkt dan op een netjes gestileerd element.
In plaats van het handmatig aanpassen van de randradius voor elke afbeelding, is een betere aanpak om de afgeronde stijl aan te passen zodat deze een meer verfijnde hoekradius toepast – misschien door een subtiele schaduw toe te voegen voor een moderne look. Op deze manier kunnen gebruikers gewoon op een knop klikken om een goed ontworpen stijl toe te passen zonder dat ze elke keer handmatig de instellingen hoeven aan te passen.
Laten we de stijl Rounded in het Image blok als voorbeeld nemen en deze aanpassen zodat de hoeken licht afgerond zijn in plaats van overdreven gebogen en er een subtiele schaduw wordt toegevoegd voor een meer gepolijste look.
Omdat de blok-editor blokstijlen kan registreren en verwijderen, kunnen we de standaard Rounded stijl verwijderen en vervangen door een aangepaste versie.
Zo doe je dat:
function modify_image_block_rounded_style() {
// Remove the default "Rounded" style
unregister_block_style( 'core/image', 'rounded' );
// Register a new "Rounded" style with custom CSS
register_block_style(
'core/image',
array(
'name' => 'rounded',
'label' => __( 'Rounded', 'your-text-domain' ),
'inline_style' => '
.wp-block-image.is-style-rounded img {
border-radius: 20px; /* Adjust this value */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* Optional shadow */
}
',
)
);
}
add_action( 'init', 'modify_image_block_rounded_style' );De code vervangt de standaard overdreven afgeronde stijl door een verfijnde versie die border-radius: 20px; toepast voor zachtere hoeken en box-shadow voor een subtiele lift.
Een extern CSS bestand gebruiken in plaats van inline stijlen
Hoewel inline stijlen goed werken voor eenvoudige stijlen, is het niet ideaal voor de onderhoudbaarheid. Een betere aanpak is om stijlen te definiëren in een extern CSS bestand en dit in plaats daarvan te enqueuen.
Om dit te doen, maak je een nieuw CSS bestand, bijvoorbeeld custom-block-styles.css, en voeg je dit toe:
/* Custom Rounded Image Block Style */
.wp-block-image.is-style-rounded img {
border-radius: 20px; /* Adjusted rounded corners */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* Subtle shadow */
}Enqueue vervolgens het CSS bestand in functions.php:
function enqueue_custom_block_styles() {
wp_enqueue_style(
'custom-block-styles',
get_template_directory_uri() . '/css/custom-block-styles.css',
array(),
'1.0'
);
}
add_action('wp_enqueue_scripts', 'enqueue_custom_block_styles');
add_action('enqueue_block_editor_assets', 'enqueue_custom_block_styles');In plaats van een inline stijl te gebruiken, kun je nu de stijl registreren zonder CSS direct in PHP in te sluiten:
register_block_style(
'core/image',
array(
'name' => 'rounded',
'label' => __( 'Rounded', 'your-text-domain' ),
'style_handle' => 'custom-block-styles'
)
);Op deze manier kun je stijlen aanpassen zonder PHP aan te raken.
Blokvariaties registreren
Met blokvariaties kun je vooraf gedefinieerde versies van een blok maken met aangepaste instellingen, waardoor het voor gebruikers gemakkelijker wordt om met één klik consistente ontwerpen toe te passen. In plaats van elke keer handmatig de instellingen van een blok aan te passen, kun je met een variatie een blok invoegen waarop de juiste attributen, stijlen of configuraties al zijn toegepast.
Sommige WordPress core blokken werken op deze manier. Het Embed blok is niet één blok – het is een verzameling variaties voor verschillende platforms zoals YouTube, Twitter en Spotify. Het Row blok en het Stack blok zijn ook slechts variaties van het Group blok, elk met verschillende layout instellingen.
Deze aanpak houdt de dingen modulair, waardoor WordPress op maat gemaakte ervaringen kan bieden terwijl er gebruik wordt gemaakt van een gedeelde onderliggende structuur.
Een Testimonial variant van het Quote blok maken
Hoewel WordPress geen specifiek Testimonial blok heeft, kan het Quote blok (core/quote) worden aangepast om dat doel te dienen. In plaats van gebruikers handmatig een afbeelding te laten toevoegen, de tekst uit te lijnen en alles op te maken, kunnen we een Testimonial variant van het Quote blok definiëren.
Deze variant bevat automatisch een Image blok, een Quote blok en twee Paragraph blokken voor de naam van de persoon en het bedrijf. Dit zorgt ervoor dat elke testimonial dezelfde gestructureerde opmaak heeft zonder dat er extra aanpassingen nodig zijn.
Om een blokvariatie in WordPress te registreren, gebruiken we registerBlockVariation() in JavaScript. Omdat blokvariaties aan de kant van de client worden afgehandeld, moeten we een JavaScript bestand enqueue maken dat onze aangepaste Testimonial variatie registreert.
Om dit te implementeren, maak je een JavaScript bestand (zoals custom-block-variations.js) dat de Testimonial variatie van het Quote blok definieert. Je kunt dit bestand maken in de assets/js/ map van je thema en de volgende code toevoegen:
wp.domReady(() => {
wp.blocks.registerBlockVariation(
'core/quote',
{
name: 'testimonial',
title: 'Testimonial',
description: 'A variation of the Quote block for testimonials.',
category: 'text',
attributes: {
className: 'is-style-testimonial',
},
innerBlocks: [
['core/image', { align: 'center', width: 100, height: 100 }],
['core/quote'],
['core/paragraph', { placeholder: 'Name', align: 'center', fontSize: 'medium', className: 'testimonial-name' }],
['core/paragraph', { placeholder: 'Company / Role', align: 'center', fontSize: 'small', className: 'testimonial-company' }]
],
scope: ['inserter'],
}
);
// Inject inline styles for the editor preview
const style = document.createElement('style');
style.innerHTML = `
.wp-block-quote.is-style-testimonial {
background-color: #f9f9f9;
padding: 24px;
border: none !important;
border-radius: 8px;
text-align: center;
font-size: 1.2em;
font-style: normal;
color: #333;
box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
display: flex;
flex-direction: column;
align-items: center;
}
.wp-block-quote.is-style-testimonial p {
margin-bottom: 12px;
font-size: 1.1em;
}
.wp-block-quote.is-style-testimonial cite {
font-weight: bold;
display: block;
margin-top: 10px;
color: #0073aa;
}
.wp-block-quote.is-style-testimonial .wp-block-image {
display: flex;
justify-content: center;
margin: 0 auto 12px;
}
.wp-block-quote.is-style-testimonial .wp-block-image img {
width: 100px;
height: 100px;
object-fit: cover;
border-radius: 12px;
}
.wp-block-quote.is-style-testimonial .testimonial-name {
font-weight: bold;
font-size: 1.2em;
margin-top: 12px;
color: #222;
}
.wp-block-quote.is-style-testimonial .testimonial-company {
font-size: 0.9em;
color: #555;
}
`;
document.head.appendChild(style);
});In de bovenstaande code definieert registerBlockVariation() de Testimonial variant van het Quote blok, waarbij een Image blok, een Quote blok en twee Paragraph blokken voor de naam van de persoon en het bedrijf worden voorgeladen. Het Image blok wordt gecentreerd op 100×100 pixels voor uniforme profielfoto’s, terwijl het Quote blok ongewijzigd blijft als de tekst van de testimonial.
Een aangepaste class (is-style-testimonial) wordt toegepast voor styling, waardoor het blok een lichte achtergrond, subtiele schaduw en gecentreerde tekst krijgt. De standaard linkerrand is verwijderd en de afbeelding behoudt zijn beeldverhouding met licht afgeronde hoeken voor een gepolijste look.
Omdat het JavaScript bestand vervolgens in de blok-editor moet worden geladen, moeten we het enqueue-en in functions.php.
function enqueue_custom_block_variations() {
wp_enqueue_script(
'custom-block-variations',
get_template_directory_uri() . '/assets/js/custom-block-variations.js',
array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
filemtime( get_template_directory() . '/assets/js/custom-block-variations.js' ),
true
);
}
add_action( 'enqueue_block_editor_assets', 'enqueue_custom_block_variations' );Dit zorgt ervoor dat de Testimonial blokvariatie in de blok-editor verschijnt.
Waar de JavaScript code ervoor zorgt dat het blok er correct uitziet in de editor, moeten we ook de stijlen toepassen op de front-end zodat testimonials correct worden weergegeven wanneer ze worden gepubliceerd. Voeg de volgende code toe aan functions.php:
function register_testimonial_block_style() {
register_block_style(
'core/quote',
array(
'name' => 'testimonial',
'label' => __( 'Testimonial', 'your-text-domain' ),
'inline_style' => '
.wp-block-quote.is-style-testimonial {
background-color: #f9f9f9;
padding: 24px;
border: none !important;
border-radius: 8px;
text-align: center;
font-size: 1.2em;
font-style: normal;
color: #333;
box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
display: flex;
flex-direction: column;
align-items: center;
}
.wp-block-quote.is-style-testimonial .wp-block-image img {
width: 100px;
height: 100px;
object-fit: cover;
border-radius: 12px;
}
.wp-block-quote.is-style-testimonial .testimonial-name {
font-weight: bold;
font-size: 1.2em;
margin-top: 12px;
color: #222;
}
.wp-block-quote.is-style-testimonial .testimonial-company {
font-size: 0.9em;
color: #555;
}
',
)
);
}
add_action( 'init', 'register_testimonial_block_style' );Wanneer een gebruiker nu een Testimonial blok invoegt, bevat het al de velden voor de afbeelding, het citaat, de naam en het bedrijf, allemaal voorgeformatteerd en correct gestyled. Hierdoor zijn handmatige aanpassingen niet meer nodig en wordt ervoor gezorgd dat elke testimonial dezelfde strakke en professionele structuur heeft.
In plaats van gebruikers te dwingen om testimonials vanaf nul op te bouwen, biedt deze blokvariant een gestroomlijnde workflow die het maken van inhoud verbetert terwijl het ontwerp van de site consistent blijft.
Geavanceerd gebruik: De Supports en Styles API’s combineren om gebrande knoppen te maken
Nu je weet wat elke API kan doen en hoe het werkt, waarom gaan we niet een stapje verder? In plaats van de Supports API of Styles API afzonderlijk te gebruiken, kunnen we ze samen gebruiken om één probleem op te lossen: behoud van ontwerpconsistentie en gebruikers een gestructureerde manier geven om de juiste stijlen toe te passen.
Laten we eens kijken naar een scenario uit de praktijk. Een bedrijf wil dat alle knoppen op zijn site strikte branding richtlijnen volgen. Ze willen niet dat gebruikers willekeurige kleuren kiezen, de vulling veranderen of funky typografie toepassen. Ze willen echter wel flexibiliteit – dus gebruikers moeten kunnen kiezen tussen twee vooraf goedgekeurde knopstijlen:
- Primaire knop – De belangrijkste call-to-action knop, met een effen achtergrond en gedurfde styling.
- Secundaire knop – Een subtielere, omlijnde knop die meestal wordt gebruikt voor secundaire acties.
Om dit te bereiken moeten we:
- De Styles API gebruiken om de twee knopstijlen te definiëren.
- De Supports API gebruiken om onnodige instellingen te verwijderen, zodat gebruikers de branding niet handmatig overschrijven door kleuren, spatiëring of typografie te veranderen.
Door beide API’s te combineren, staan we gestructureerde keuzes toe terwijl we voorkomen dat gebruikers het ontwerpsysteem kapot maken.
Stap 1: Definieer aangepaste knopstijlen
Begin met het toevoegen van de volgende code aan het bestand functions.php:
function register_custom_button_styles() {
register_block_style(
'core/button',
array(
'name' => 'primary-button',
'label' => __( 'Primary Button', 'your-text-domain' ),
'inline_style' => '
.wp-block-button.is-style-primary-button .wp-block-button__link {
background-color: #4D4D4D;
color: #ffffff;
padding: 12px 24px;
border-radius: 4px;
font-size: 1em;
font-weight: 500;
text-transform: none;
box-shadow: 2px 2px 6px rgba(0, 0, 0, 0.1);
}
',
)
);
register_block_style(
'core/button',
array(
'name' => 'secondary-button',
'label' => __( 'Secondary Button', 'your-text-domain' ),
'inline_style' => '
.wp-block-button.is-style-secondary-button .wp-block-button__link {
background-color: transparent;
color: #4D4D4D;
padding: 12px 24px;
border: 1px solid #4D4D4D;
border-radius: 4px;
font-size: 1em;
font-weight: 500;
text-transform: none;
box-shadow: none;
}
',
)
);
}
add_action( 'init', 'register_custom_button_styles' );Wanneer gebruikers nu een Button blok invoegen, zien ze Primaire knop en Secundaire knop als stijlkeuzes.
De primaire knop heeft een effen donkergrijze achtergrond, terwijl de secundaire knop een transparante achtergrond met een rand heeft. Beide knoppen hebben een consistente opvulling, randradius en lettertype, zodat ze er op de hele site professioneel uitzien.
Stap 2: Beperk het aanpassen van knoppen
Hoewel de stijlen van de knoppen nu vooraf zijn gedefinieerd, kunnen gebruikers ze nog steeds handmatig veranderen met de instellingen van de blok-editor van WordPress. Als ze de kleuren, vulling of typografie veranderen, kan het zijn dat de knoppen niet meer voldoen aan de branding richtlijnen.
We kunnen de Supports API gebruiken om deze aanpassingsopties uit te schakelen, zodat gebruikers geen onbedoelde wijzigingen kunnen aanbrengen. Voeg dit toe aan functions.php:
function restrict_button_customization($args, $block_type) {
if ($block_type === 'core/button') {
// Disable specific color settings (text, background, link)
$args['supports']['color'] = [
'text' => false,
'background' => false,
'link' => false,
];
// Disable typography settings (font size, font weight, line height)
$args['supports']['typography'] = false;
// Disable spacing settings (padding, margin)
$args['supports']['spacing'] = false;
}
return $args;
}
add_filter('register_block_type_args', 'restrict_button_customization', 10, 2);Met dit op zijn plaats:
- Gebruikers kunnen de kleur van knoppen niet wijzigen, dus alle knoppen moeten voldoen aan het kleurenschema van de branding.
- Typografie-aanpassingen worden verwijderd, zodat de tekstopmaak consistent blijft.
- Spatiëringsaanpassingen zijn uitgeschakeld, zodat gebruikers de opvulling en marges niet kunnen wijzigen.
In plaats van gebruikers een willekeurige mix van knopstijlen te laten maken, kunnen ze nu eenvoudig kiezen tussen primaire en secundaire stijlen, waardoor het ontwerp professioneel en gestructureerd blijft.
Samenvatting
We hebben nog maar een tipje van de sluier opgelicht van wat er allemaal mogelijk is met WordPress blokaanpassingen. WordPress biedt een uitgebreide verzameling API’s die het eenvoudig maken om blokken uit te breiden en aan te passen, zodat ontwikkelaars de editorervaring kunnen aanpassen terwijl alles gestructureerd en gebruiksvriendelijk blijft.
Als je blokaanpassingen echt onder de knie wilt krijgen, is er nog veel meer om te ontdekken. Bekijk de officiële WordPress documentatie voor ontwikkelaars, bezoek WordCamps en meetups, en blijf leren van geweldige bronnen zoals de Kinsta blog, waar we regelmatig geavanceerde WordPress concepten uit de doeken doen.
Natuurlijk kun je met een goede hostingprovider moeiteloos experimenteren met deze veranderingen. Of je nu nieuwe blokmodificaties uitprobeert of een drukbezochte site beheert, betrouwbare hosting zorgt voor soepele prestaties en eenvoudige schaalbaarheid. Bij Kinsta hebben we ons platform gebouwd om precies dat aan te kunnen. Sterker nog, we zijn onlangs door G2 geplaatst als #1 in WordPress Hosting, dankzij meer dan 930 klantbeoordelingen.
Eén ding is zeker: Je kunt op ons vertrouwen voor jouw WordPress ervaring.
