Aangepaste veldtypen
Met aangepaste veldtypen kan een thema of plugin nieuwe Blockstudio-veldbedieningselementen toevoegen. Ze verschillen van aangepaste velden:
custom/{name}verwijst naar een herbruikbare groep bestaande velden.namespace/type-namegebruikt een geregistreerd veldtype met een eigen editorbedieningselement en waardestructuur.
Blockstudio levert het registratiesysteem. Je thema of plugin levert het bedieningselement.
Wanneer je ze gebruikt
Gebruik een aangepast veldtype wanneer een project een bedieningselement voor één specifiek doel nodig heeft dat zich overal als een native Blockstudio-veld moet gedragen:
- blokkenmerken
- herbruikbare
custom/{name}-veldgroepen - groepen, tabbladen en repeaters
- PHP, Twig en Blade-templates
- opslag van berichtmeta en opties
- extensietemplates zoals
{attributes.margin.top}
Een afstandsbediening kan bijvoorbeeld één object opslaan in plaats van vier afzonderlijke tekstvelden:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Naamgeving
Namen van aangepaste veldtypen moeten in kleine letters staan, een namespace hebben en dashcase gebruiken:
namespace/type-name
Geldige voorbeelden:
acme/dimensionsacme/text-optionstheme/spacing-token
Gereserveerde namespaces:
custom/is gereserveerd voor herbruikbare aangepaste veldgroepen.blockstudio/is gereserveerd voor de Blockstudio-core.
Ongeldige namen worden genegeerd door het filter API en afgewezen door de helper API.
Registratie van PHP
Registreer de metagegevens van het veldtype 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() retourneert true als de registratie slaagt en false als de naam of definitie ongeldig is. Je kunt een handmatige registratie ongedaan maken met bs_unregister_field_type().
Je kunt ook het filter API gebruiken:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Definitietoetsen
| Sleutel | Type | Beschrijving |
|---|---|---|
attribute |
string, array, null |
WordPress attribuuttype. Gebruik string, number, boolean, object, array of een array met die typen. |
default |
mixed | Standaard op registryniveau wanneer een veld geen eigen standaardwaarde definieert. |
source |
string | WordPress attribuutbron voor aangepaste serialisatiegevallen. |
produces_attribute |
boolean | Stel in op false voor bedieningselementen die alleen ter weergave dienen. Standaard is true. |
editor_script |
string or array | Geregistreerde script-handle(s) die in de blokeditor moeten worden geladen wanneer het type wordt gebruikt. |
editor_style |
string or array | Geregistreerde stijl-handle(s) die in de blokeditor moeten worden geladen wanneer het type wordt gebruikt. |
storage |
array | Opslagwaardetype en REST-schematips voor postmeta en opties. |
supports |
array | Optionele capability-vlaggen voor uw eigen bedieningselement. |
translate |
boolean | Stel in op true wanneer de waarde tekst is die WPML moet vertalen. Vereist attribute string. |
Een definitie met een translate-waarde die geen boolean is, of met
translate ingesteld op true en een attribute die niet string is, is ongeldig.
bs_register_field_type() retourneert false en het filter API negeert deze.
WPML
wp bs wpml config kan op basis van alleen de registratie niet vaststellen of de waarde van een aangepast veldtype tekst is. Daarom slaat het zulke velden over en geeft het voor elk ervan een waarschuwing. Stel translate in op true in de registratie van een veldtype dat een gewone tekstreeks opslaat; de opdracht declareert de velden dan als text-velden. Een veld kan zich nog steeds afmelden met "translate": false. Zie WPML.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Registratie van JavaScript
Het editorscript registreert het bijbehorende bedieningselement React:
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() retourneert true wanneer de registratie wordt geaccepteerd. Verwijder een clientregistratie met:
window.blockstudio.unregisterFieldType('acme/dimensions');
De component ontvangt de eigenschappen van de velddefinitie, plus deze stabiele props:
| Prop | Beschrijving |
|---|---|
type |
Naam van het veldtype. |
id |
Veld-ID. |
field |
Volledige velddefinitie uit block.json. |
value |
Huidige opgeslagen waarde. |
defaultValue |
Standaardwaarde van het veld. |
onChange |
Sla een nieuwe waarde rechtstreeks op. |
attributes |
Huidige blokkenmerken. |
block |
Huidige bloktypedefinitie. |
clientId |
Huidige client-ID van het editorblok. |
inRepeater |
Of het veld zich binnen een repeaterrij bevindt. |
repeaterId |
Huidig repeaterpad, indien van toepassing. |
disabled |
Of het veld is uitgeschakeld in de editor. |
Waarden van aangepaste veldtypen worden rechtstreeks opgeslagen. Ze doorlopen niet de normalisatie van native opties voor select, radio, color of gradient.
Waarden weergeven
Objectwaarden zijn beschikbaar zoals elk ander Blockstudio-kenmerk.
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>
Geneste objectpaden werken ook in extensietemplates:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Opslag
Wanneer een aangepast veldtype wordt gebruikt met postMeta– of option-opslag, gebruikt Blockstudio het geregistreerde opslagwaardetype en REST-schema.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
Definieer voor waarden van array en object storage.rest_schema bij de veldtyperegistratie. Afstammelingen van repeaters blijven array-gebaseerde opslag gebruiken, omdat een repeater rijen opslaat.
Terugvalgedrag
Als PHP het veldtype kent, maar het editorscript geen bijbehorend bedieningselement registreert, behoudt Blockstudio de opgeslagen waarde en toont het een melding die niet kan worden bewerkt in de editor. De frontend-weergave ontvangt nog steeds de opgeslagen waarde.
Als een veldtype niet is geregistreerd in PHP, laat Blockstudio het weg uit de gegenereerde kenmerken van WordPress. Registreer de definitie PHP voordat blokdetectie wordt uitgevoerd, meestal op init voordat Blockstudio blokken bouwt.