Creare un tipo di campo personalizzato
Alcuni valori sono composti da più di un elemento primitivo. Un prezzo è formato da un importo e una valuta. Con i campi integrati lo si rappresenta con un campo numerico e uno di selezione affiancati, e ogni blocco che mostra un prezzo ripete la coppia, le etichette e la logica che li mantiene insieme. Nei metadati dell’articolo diventano due chiavi e, all’interno di un ripetitore, due elenchi paralleli.
Un tipo di campo personalizzato riunisce la coppia in un solo campo. Registrate una volta un tipo come
acme/price in PHP e in JavaScript, poi usatelo in qualsiasi
block.json come un campo nativo: al livello principale, all’interno di gruppi e
ripetitori, con i metadati dell’articolo o lo storage delle opzioni, e nei template PHP, Twig e Blade.
Blockstudio ricava l’attributo WordPress e lo schema di storage REST dalla registrazione.
È diverso da un campo personalizzato.
Un riferimento custom/{name} riutilizza un gruppo di campi esistenti. Un tipo di campo personalizzato
aggiunge un nuovo controllo con una propria struttura del valore.
Questa guida crea acme/price dall’inizio alla fine: la registrazione PHP, il controllo dell’editor,
un blocco per i prezzi che lo usa al livello principale e all’interno di un ripetitore,
lo storage nei metadati dell’articolo con uno schema REST rigoroso e l’output renderizzato.
Registrare il tipo in PHP
La parte PHP dichiara il tipo di attributo, il valore predefinito, lo script dell’editor che fornisce il controllo e il modo in cui il valore viene salvato fuori dal blocco:
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 è il tipo di attributo WordPress, qui object. storage.type è
il tipo di valore usato quando il campo viene salvato nei metadati dell’articolo o nelle opzioni, mentre
storage.rest_schema è lo schema WordPress con cui vengono convalidate le scritture di REST.
Senza un rest_schema, un valore oggetto riceve uno schema permissivo che accetta
qualsiasi proprietà.
Registrate su init con la priorità predefinita. Blockstudio rileva i blocchi in ritardo
su init e un tipo non registrato entro quel momento viene escluso dagli
attributi del blocco generati.
bs_register_field_type() restituisce true in caso di successo e false se il nome
o la definizione non sono validi. I nomi devono essere in minuscolo, con namespace e in formato dashcase;
sono riservati due namespace:
| Nome | Risultato |
|---|---|
acme/price |
true |
Acme/Price |
false, non in minuscolo |
custom/price |
false, riservato ai gruppi di campi riutilizzabili |
blockstudio/price |
false, riservato al core di Blockstudio |
bs_unregister_field_type() rimuove una registrazione; il filtro
blockstudio/field_types accetta le stesse definizioni in un array indicizzato per nome.
Creare il controllo dell’editor
Lo script registrato sopra fornisce il componente React. Usa i componenti WordPress già caricati nell’editor, quindi non richiede una fase di build:
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 });
},
}),
),
);
},
});
Il componente riceve tutte le proprietà della definizione del campo, quindi la chiave currencies inserita in block.json arriva come props.currencies. Riceve anche proprietà stabili: value, onChange, field, defaultValue,
attributes, block, clientId, disabled e inRepeater con
repeaterId quando viene renderizzato all’interno di una riga del ripetitore. onChange salva il valore
esattamente come fornito. I valori personalizzati saltano la normalizzazione delle opzioni applicata dai campi nativi select, radio, color e gradient.
Come nelle prime righe, gestite i valori che non sono oggetti. Un blocco salvato prima che il campo esistesse, o con una struttura diversa, dovrebbe comunque aprirsi nell’editor.
Blockstudio accoda acme-field-price nell’editor dei blocchi solo quando viene registrato un blocco
che usa acme/price. Se lo script non riesce a registrare il controllo, l’editor conserva il valore salvato e mostra un avviso non modificabile al posto del campo, mentre il frontend continua a renderizzare il valore.
Usarlo in un blocco
Un blocco per i prezzi usa il tipo due volte: una per un prezzo iniziale consultabile anche fuori dal blocco e una per ogni riga di un ripetitore per le fasce:
{
"$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"
}
}
]
}
]
}
}
Un default a livello di campo prevale sul valore predefinito del registro. Blockstudio trasforma entrambi i campi in attributi WordPress definiti dalla registrazione. Il tipo di blocco registrato contiene:
{
"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" }
}
]
}
}
Renderizzare il valore
Nel template, il valore è un normale array. Verificatene il tipo prima di usarlo, perché un valore salvato è affidabile solo quanto l’ultima operazione che lo ha scritto:
<?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>
La parte ?: array() è importante. Un ripetitore senza righe raggiunge il template come
false, non come array vuoto, e un foreach diretto su di esso genera un avviso PHP.
La riga @var è spiegata nella sezione analisi statica più avanti.
Rendering del blocco con un prezzo iniziale e due fasce:
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>
Senza dati, si applica il valore predefinito del campo e il blocco viene renderizzato From 19.00 EUR senza fasce. Twig e Blade leggono lo stesso valore di a.price.amount e $a['price']['amount'], e i template di estensione extension possono accedervi come {attributes.price.amount}.
Storage e schema REST
Entrambi i campi dichiarano lo storage postMeta, quindi Blockstudio registra due chiavi meta quando crea il blocco. Il campo di livello principale usa lo schema di storage registrato così com’è:
{
"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
}
}
}
Il campo all’interno del ripetitore salva un valore per riga, quindi la sua chiave meta è basata su un array e lo stesso schema diventa lo schema dell’elemento:
{
"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
}
}
}
}
Quando si salva un articolo che contiene il blocco, entrambe le chiavi vengono sincronizzate. Con le due fasce mostrate sopra, get_post_meta( $id, 'acme_price', true ) restituisce {"amount":19,"currency":"EUR"} e acme_tier_prices restituisce l’elenco dei prezzi delle righe:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Entrambe le chiavi compaiono nella risposta REST dell’articolo sotto meta, e le scritture REST vengono convalidate rispetto allo schema. Una scrittura con la valuta in minuscolo viene rifiutata:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
I metadati sono una copia. Gli attributi del blocco nel contenuto dell’articolo restano la fonte e ogni salvataggio li sincronizza nuovamente con le chiavi configurate; quindi, un valore scritto direttamente nei metadati viene sostituito al salvataggio successivo dell’articolo. Lo storage delle opzioni funziona allo stesso modo tramite register_setting(). I tipi di campo personalizzati, incluso lo storage basato su array nei ripetitori, sono disponibili da Blockstudio 7.5.0.
Analisi statica
L’estensione PHPStan conosce i tipi di campo integrati, non quelli registrati dal progetto in fase di esecuzione. In un blocco che usa acme/price indica il tipo di campo come sconosciuto e assegna al suo valore il tipo mixed:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
Ignorate questa diagnostica per i vostri tipi nella configurazione del progetto e mantenete il controllo del tipo nel template: è ciò che serve a PHPStan per accettare il valore mixed al livello max:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
Con questa configurazione e il template qui sopra, l’analisi ha esito positivo. Nella versione 7.6 il template richiede anche la riga @var, con mixed nelle posizioni dei campi personalizzati; dalla versione 7.7 Blockstudio deduce autonomamente questa struttura e la riga può essere rimossa. Consultate Template verificati con PHPStan per eseguire l’analisi.
Passaggi successivi
- Tipi di campo personalizzati: tutte le chiavi della definizione, il filtro API e l’elenco completo delle proprietà del componente.
- Storage: storage dei metadati degli articoli e delle opzioni per qualsiasi campo.
- Ricettario dei modelli di campo: gruppi, ripetitori e strutture di campi riutilizzabili.
- Campi personalizzati: gruppi di campi riutilizzabili tramite
custom/{name}.