Een aangepast veldtype bouwen
Sommige waarden bestaan uit meer dan één primitief gegeven. Een prijs bestaat uit een bedrag en een valuta. Met ingebouwde velden modelleer je dit met een getalveld en een keuzelijst naast elkaar. Elk blok dat een prijs toont, herhaalt dan het paar velden, de labels en de logica die ze bij elkaar houdt. In berichtmetadata worden dit twee sleutels en in een herhaler twee parallelle lijsten.
Een aangepast veldtype maakt van het paar één veld. Je registreert een type zoals
acme/price één keer, in PHP en in JavaScript, en gebruikt het vervolgens in elke
block.json zoals een ingebouwd veld: op het hoogste niveau, in groepen en
herhalers, met opslag in berichtmetadata of opties, en in templates voor PHP, Twig en Blade.
Blockstudio leidt het WordPress-attribuut en het opslag-REST-schema af van de registratie.
Dit verschilt van een aangepast veld.
Een custom/{name}-verwijzing hergebruikt een groep bestaande velden. Een aangepast veldtype voegt een nieuw besturingselement met een eigen waardestructuur toe.
Deze gids bouwt acme/price van begin tot eind: de registratie van PHP, het editorbesturingselement, een prijsblok dat het veld op het hoogste niveau en in een herhaler gebruikt, opslag in berichtmetadata met een strikt REST-schema en de gerenderde uitvoer.
Het type registreren in PHP
De PHP-kant declareert het attribuuttype, de standaardwaarde, het editorscript dat het besturingselement levert en hoe de waarde buiten het blok wordt opgeslagen:
add_action( 'init', function () {
wp_register_script(
'acme-field-price',
get_stylesheet_directory_uri() . '/fields/price.js',
array( 'blockstudio-blocks', 'wp-components', 'wp-element' ),
'1.0.0',
true
);
bs_register_field_type( 'acme/price', array(
'attribute' => 'object',
'default' => array(),
'editor_script' => 'acme-field-price',
'storage' => array(
'type' => 'object',
'rest_schema' => array(
'type' => 'object',
'properties' => array(
'amount' => array( 'type' => 'number', 'minimum' => 0 ),
'currency' => array( 'type' => 'string', 'pattern' => '^[A-Z]{3}$' ),
),
'additionalProperties' => false,
),
),
) );
} );
attribute is het attribuuttype van WordPress, hier object. storage.type is
het waardetype dat wordt gebruikt wanneer het veld wordt opgeslagen in berichtmetadata of opties, en
storage.rest_schema is het schema waarmee WordPress schrijfbewerkingen van REST valideert.
Zonder een rest_schema krijgt een objectwaarde een toegeeflijk schema dat
alle eigenschappen accepteert.
Registreer op init met de standaardprioriteit. Blockstudio detecteert blokken laat
op init. Een type dat op dat moment niet is geregistreerd, wordt weggelaten uit de
gegenereerde blokattributen.
bs_register_field_type() retourneert true bij succes en false als de naam
of definitie ongeldig is. Namen moeten uit kleine letters bestaan, een namespace hebben en in dashcase zijn geschreven. Twee namespaces zijn gereserveerd:
| Naam | Resultaat |
|---|---|
acme/price |
true |
Acme/Price |
false, geen kleine letters |
custom/price |
false, gereserveerd voor herbruikbare veldgroepen |
blockstudio/price |
false, gereserveerd voor Blockstudio core |
bs_unregister_field_type() verwijdert een registratie weer, en het
blockstudio/field_types-filter accepteert dezelfde definities als een array met de namen als sleutels.
Het editorbesturingselement bouwen
Het hierboven geregistreerde script levert de component React. Deze gebruikt de WordPress-componenten die al in de editor zijn geladen, dus is er geen buildstap nodig:
const { createElement: el } = wp.element;
const { Flex, FlexBlock, FlexItem, SelectControl, TextControl } = wp.components;
window.blockstudio.registerFieldType('acme/price', {
component(props) {
const value =
props.value && typeof props.value === 'object' && !Array.isArray(props.value)
? props.value
: {};
const currencies = props.currencies || ['EUR'];
return el(
Flex,
{ align: 'flex-end' },
el(
FlexBlock,
{},
el(TextControl, {
label: props.label,
type: 'number',
min: 0,
step: 0.01,
disabled: props.disabled,
value: value.amount ?? '',
onChange(next) {
props.onChange({ ...value, amount: next === '' ? 0 : Number(next) });
},
}),
),
el(
FlexItem,
{},
el(SelectControl, {
label: 'Currency',
hideLabelFromVision: true,
disabled: props.disabled,
value: value.currency || currencies[0],
options: currencies.map((code) => ({ label: code, value: code })),
onChange(next) {
props.onChange({ ...value, currency: next });
},
}),
),
);
},
});
De component ontvangt elke eigenschap van de velddefinitie. De sleutel currencies die je in block.json opgeeft, komt dus binnen als props.currencies. Daarnaast ontvangt de component stabiele props: value, onChange, field, defaultValue,
attributes, block, clientId, disabled en inRepeater, met
repeaterId wanneer deze in een rij van een herhaler wordt weergegeven. onChange slaat de waarde precies op zoals opgegeven. Aangepaste waarden slaan de normalisatie van opties over die ingebouwde velden zoals select, radio, color en gradient toepassen.
Controleer op waarden die geen objecten zijn, zoals in de eerste regels. Een blok dat is opgeslagen voordat het veld bestond of met een andere structuur, moet nog steeds in de editor kunnen worden geopend.
Blockstudio voegt acme-field-price alleen toe aan de blokeditor als er een blok is geregistreerd dat acme/price gebruikt. Als het script het besturingselement niet registreert, behoudt de editor de opgeslagen waarde en toont deze een niet-bewerkbare melding op de plek van het veld. De frontend geeft de waarde nog steeds weer.
Gebruiken in een blok
Een prijsblok gebruikt het type twee keer: één keer voor een beginprijs die buiten het blok doorzoekbaar moet zijn, en één keer per rij in een herhaler voor staffels:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/pricing",
"title": "Pricing",
"blockstudio": {
"attributes": [
{
"id": "price",
"type": "acme/price",
"label": "Starting price",
"currencies": ["EUR", "USD"],
"default": { "amount": 19, "currency": "EUR" },
"storage": {
"type": "postMeta",
"postMetaKey": "acme_price"
}
},
{
"id": "tiers",
"type": "repeater",
"label": "Tiers",
"min": 0,
"max": 4,
"attributes": [
{ "id": "name", "type": "text", "label": "Name", "default": "" },
{
"id": "price",
"type": "acme/price",
"label": "Price",
"currencies": ["EUR", "USD"],
"default": { "amount": 0, "currency": "EUR" },
"storage": {
"type": "postMeta",
"postMetaKey": "acme_tier_prices"
}
}
]
}
]
}
}
Een veldniveau-default heeft voorrang op de standaardwaarde uit het register. Blockstudio maakt van beide velden WordPress-attributen op basis van de registratie. Het geregistreerde bloktype bevat:
{
"price": {
"blockstudio": true,
"type": "object",
"field": "acme/price",
"id": "price",
"default": { "amount": 19, "currency": "EUR" },
"storage": { "type": "postMeta", "postMetaKey": "acme_price" }
},
"tiers": {
"blockstudio": true,
"type": "array",
"field": "repeater",
"id": "tiers",
"attributes": [
{ "blockstudio": true, "type": "string", "field": "text", "default": "", "id": "name" },
{
"blockstudio": true,
"type": "object",
"field": "acme/price",
"id": "price",
"default": { "amount": 0, "currency": "EUR" },
"storage": { "type": "postMeta", "postMetaKey": "acme_tier_prices" }
}
]
}
}
De waarde weergeven
In de template is de waarde een gewone array. Beperk die eerst tot het verwachte type, want een opgeslagen waarde is slechts zo betrouwbaar als de laatste bewerking die deze heeft weggeschreven:
<?php
/** @var array{price: mixed, tiers: array<int, array{name: string, price: mixed}>} $a */
$format = static function ( mixed $price ): string {
if ( ! is_array( $price ) ) {
return '';
}
$amount = is_numeric( $price['amount'] ?? null ) ? (float) $price['amount'] : 0.0;
$currency = is_string( $price['currency'] ?? null ) ? $price['currency'] : '';
return number_format_i18n( $amount, 2 ) . ' ' . $currency;
};
?>
<section useBlockProps class="acme-pricing">
<p>From <?php echo esc_html( $format( $a['price'] ) ); ?></p>
<?php foreach ( $a['tiers'] ?: array() as $tier ) : ?>
<div class="acme-tier">
<h3><?php echo esc_html( $tier['name'] ); ?></h3>
<p><?php echo esc_html( $format( $tier['price'] ?? null ) ); ?></p>
</div>
<?php endforeach; ?>
</section>
?: array() is van belang. Een herhaler zonder rijen wordt in de template weergegeven als false, niet als een lege array. Een kale foreach hierop veroorzaakt een PHP-waarschuwing. De regel @var wordt hieronder toegelicht onder statische analyse.
Het blok weergeven met een beginprijs en twee staffels:
echo bs_block( array(
'name' => 'acme/pricing',
'data' => array(
'price' => array( 'amount' => 19, 'currency' => 'EUR' ),
'tiers' => array(
array( 'name' => 'Starter', 'price' => array( 'amount' => 19, 'currency' => 'EUR' ) ),
array( 'name' => 'Team', 'price' => array( 'amount' => 49, 'currency' => 'EUR' ) ),
),
),
) );
<!--blockstudio/acme/pricing--><section class="acme-pricing wp-block-acme-pricing">
<p>From 19.00 EUR</p>
<div class="acme-tier">
<h3>Starter</h3>
<p>19.00 EUR</p>
</div>
<div class="acme-tier">
<h3>Team</h3>
<p>49.00 EUR</p>
</div>
</section>
Zonder gegevens wordt de standaardwaarde van het veld gebruikt en wordt het blok From 19.00 EUR weergegeven zonder staffels. Twig en Blade lezen dezelfde waarde als a.price.amount en $a['price']['amount']. Templates voor de uitbreiding kunnen er ook bij met {attributes.price.amount}.
Opslag en het REST-schema
Beide velden declareren opslag in postMeta, dus Blockstudio registreert twee metadatumsleutels bij het bouwen van het blok. Het veld op het hoogste niveau gebruikt het geregistreerde opslagschema ongewijzigd:
{
"type": "object",
"single": true,
"show_in_rest": {
"schema": {
"type": "object",
"properties": {
"amount": { "type": "number", "minimum": 0 },
"currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
},
"additionalProperties": false
}
}
}
Het veld in de herhaler slaat één waarde per rij op. De bijbehorende metadatasleutel wordt daarom ondersteund door een array, en hetzelfde schema wordt het itemschema:
{
"type": "array",
"single": true,
"show_in_rest": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": { "type": "number", "minimum": 0 },
"currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
},
"additionalProperties": false
}
}
}
}
Als je een bericht opslaat dat het blok bevat, worden beide sleutels gesynchroniseerd. Met de twee staffels van hierboven retourneert get_post_meta( $id, 'acme_price', true )
{"amount":19,"currency":"EUR"} en retourneert acme_tier_prices de lijst met
staffelprijzen:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Beide sleutels verschijnen in het antwoord van REST voor het bericht onder meta, en schrijfbewerkingen van REST worden gevalideerd aan de hand van het schema. Een schrijfbewerking met een valuta in kleine letters wordt geweigerd:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Metadata is een kopie. De blokattributen in de berichtinhoud blijven de bron en bij elke opslag worden ze opnieuw gesynchroniseerd met de geconfigureerde sleutels. Een waarde die rechtstreeks naar metadata is geschreven, wordt dus vervangen wanneer het bericht de volgende keer wordt opgeslagen. Opslag van opties werkt op dezelfde manier via register_setting(). Aangepaste veldtypen, waaronder opslag op basis van arrays in herhalers, zijn beschikbaar sinds Blockstudio 7.5.0.
Statische analyse
De PHPStan-uitbreiding kent de ingebouwde veldtypen, maar niet de typen die een project tijdens runtime registreert. Bij een blok dat acme/price gebruikt, meldt deze dat het veldtype onbekend is en dat de waarde het type mixed heeft:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
Negeer deze melding voor je eigen typen in de projectconfiguratie en behoud de typebeperking in de template. Die is nodig zodat PHPStan de waarde mixed op niveau max accepteert:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
Met die configuratie en de template hierboven slaagt de analyse. In versie 7.6 heeft de template ook de regel @var nodig, met mixed op de posities van de aangepaste velden. In versie 7.7 leidt Blockstudio die structuur zelf af en kan de regel weg. Zie Gecontroleerde templates met PHPStan voor informatie over het uitvoeren van de analyse.
Volgende stappen
- Aangepaste veldtypen: alle definitiesleutels, het filter API en de volledige lijst met componentprops.
- Opslag: opslag in berichtmetadata en opties voor elk veld.
- Kookboek met veldpatronen: groepen, herhalers en herbruikbare veldstructuren.
- Aangepaste velden: herbruikbare veldgroepen via
custom/{name}.