Tipi di campi personalizzati
I tipi di campo personalizzati consentono a un tema o plugin di aggiungere nuovi controlli di campo Blockstudio. Sono diversi dai campi personalizzati:
custom/{name}fa riferimento a un gruppo riutilizzabile di campi esistenti.namespace/type-nameusa un tipo di campo registrato con un proprio controllo di modifica e una struttura del valore.
Blockstudio fornisce il sistema di registrazione. Il tema o plugin fornisce il controllo.
Quando usarli
Usate un tipo di campo personalizzato quando un progetto richiede un controllo di modifica specifico che debba comportarsi come un campo nativo Blockstudio ovunque:
- attributi dei blocchi
- gruppi di campi
custom/{name}riutilizzabili - gruppi, schede e repeater
- modelli PHP, Twig e Blade
- metadati dei contenuti e archiviazione delle opzioni
- modelli di estensione come
{attributes.margin.top}
Ad esempio, un controllo per la spaziatura può memorizzare un unico oggetto invece di quattro campi di testo separati:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Denominazione
I nomi dei tipi di campo personalizzati devono essere in minuscolo, includere uno spazio dei nomi e usare il formato dashcase:
namespace/type-name
Esempi validi:
acme/dimensionsacme/text-optionstheme/spacing-token
Spazi dei nomi riservati:
custom/è riservato ai gruppi di campi personalizzati riutilizzabili.blockstudio/è riservato al core di Blockstudio.
I nomi non validi vengono ignorati dal filtro API e rifiutati dall’helper API.
Registrazione di PHP
Registrate i metadati del tipo di campo in PHP:
add_action('init', function () {
wp_register_script(
'acme-field-dimensions',
get_stylesheet_directory_uri() . '/fields/dimensions.js',
['blockstudio-blocks', 'wp-components', 'wp-element'],
'1.0.0',
true
);
bs_register_field_type('acme/dimensions', [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
'storage' => [
'type' => 'object',
'rest_schema' => [
'type' => 'object',
'additionalProperties' => ['type' => 'string'],
],
],
]);
});
bs_register_field_type() restituisce true se la registrazione riesce e false
se il nome o la definizione non sono validi. È possibile annullare una
registrazione manuale con bs_unregister_field_type().
Potete anche usare il filtro API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Chiavi della definizione
| Chiave | Tipo | Descrizione |
|---|---|---|
attribute |
string, array, null |
Tipo di attributo WordPress. Usate string, number, boolean, object, array oppure un array di questi tipi. |
default |
mixed | Valore predefinito a livello di registro quando un campo non ne definisce uno proprio. |
source |
string | WordPress sorgente dell’attributo per i casi di serializzazione personalizzata. |
produces_attribute |
boolean | Impostate su false per i controlli di sola visualizzazione. Il valore predefinito è true. |
editor_script |
string or array | Handle di script registrato da accodare nell’editor dei blocchi quando viene usato il tipo. |
editor_style |
string or array | Handle di stile registrato da accodare nell’editor dei blocchi quando viene usato il tipo. |
storage |
array | Tipo del valore di archiviazione e indicazioni sullo schema REST per i meta e le opzioni dei post. |
supports |
array | Flag di capacità facoltativi per il proprio controllo. |
translate |
boolean | Impostate su true quando il valore è testo da tradurre con WPML. Richiede attribute string. |
Una definizione con un valore translate che non è booleano, oppure con
translate impostato su true e un attribute diverso da string, non è valida.
bs_register_field_type() restituisce false e il filtro API la ignora.
WPML
wp bs wpml config non può determinare dalla sola registrazione se il valore
di un tipo di campo personalizzato è testo, quindi esclude tali campi e stampa un
avviso per ciascuno. Impostate translate su true nella registrazione di un tipo di campo
che memorizza una stringa di testo semplice; il comando dichiara i suoi campi come
campi text. È comunque possibile escludere un campo con "translate": false. Consultate
WPMLTesto traducibile.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Registrazione di JavaScript
Lo script dell’editor registra il controllo React corrispondente:
const { createElement: el } = wp.element;
const { TextControl } = wp.components;
window.blockstudio.registerFieldType('acme/dimensions', {
component(props) {
const value =
props.value &&
typeof props.value === 'object' &&
!Array.isArray(props.value)
? props.value
: {};
const sides = props.sides || ['top', 'right', 'bottom', 'left'];
return el(
'div',
{},
sides.map((side) =>
el(TextControl, {
key: side,
label: side,
value: value[side] || '',
onChange(nextValue) {
props.onChange({
...value,
[side]: nextValue,
});
},
}),
),
);
},
});
registerFieldType() restituisce true quando la registrazione viene accettata. Rimuovete una registrazione client con:
window.blockstudio.unregisterFieldType('acme/dimensions');
Il componente riceve le proprietà della definizione del campo, oltre a queste proprietà stabili:
| Proprietà | Descrizione |
|---|---|
type |
Nome del tipo di campo. |
id |
ID del campo. |
field |
Definizione completa del campo da block.json. |
value |
Valore attualmente salvato. |
defaultValue |
Valore predefinito del campo. |
onChange |
Memorizza direttamente un nuovo valore. |
attributes |
Attributi del blocco corrente. |
block |
Definizione del tipo del blocco corrente. |
clientId |
ID client del blocco corrente nell’editor. |
inRepeater |
Indica se il campo si trova in una riga di repeater. |
repeaterId |
Percorso del repeater corrente, se presente. |
disabled |
Indica se il campo è disattivato nell’editor. |
I valori dei tipi di campo personalizzati vengono archiviati direttamente. Non passano attraverso la normalizzazione nativa delle opzioni di select, radio, color o gradient.
Rendering dei valori
I valori degli oggetti sono disponibili come qualsiasi altro attributo Blockstudio.
PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
<?php echo esc_html($a['title'] ?? ''); ?>
</div>
Twig
<div class="mt-{{ a.margin.top }}">
{{ a.title }}
</div>
Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
{{ $a['title'] ?? '' }}
</div>
Anche i percorsi degli oggetti annidati funzionano nei modelli di estensione:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Archiviazione
Quando un tipo di campo personalizzato viene usato con l’archiviazione postMeta o option,
Blockstudio usa il tipo di valore di archiviazione registrato e lo schema REST.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
Per i valori array e object, definite storage.rest_schema nella
registrazione del tipo di campo. Gli elementi discendenti dei repeater continuano a usare un’archiviazione basata su array perché un repeater memorizza righe.
Comportamento di riserva
Se PHP conosce il tipo di campo, ma lo script dell’editor non registra un controllo corrispondente, Blockstudio conserva il valore salvato e mostra una notifica non modificabile nell’editor. Il rendering frontend riceve comunque il valore salvato.
Se un tipo di campo non è registrato in PHP, Blockstudio lo esclude dagli attributi WordPress generati. Registrate la definizione PHP prima che venga eseguita l’individuazione dei blocchi, di solito su init prima che Blockstudio crei i blocchi.