Vrste polj po meri
Vrste polj po meri omogočajo temi ali vtičniku dodajanje novih kontrolnikov polj Blockstudio. Razlikujejo se od polj po meri:
custom/{name}se nanaša na skupino obstoječih polj, ki jo je mogoče znova uporabiti.namespace/type-nameuporablja registrirano vrsto polja z lastnim kontrolnikom urejevalnika in obliko vrednosti.
Blockstudio zagotavlja sistem za registracijo. Vaša tema ali vtičnik zagotovi kontrolnik.
Kdaj jih uporabiti
Vrsto polja po meri uporabite, kadar projekt potrebuje namenski kontrolnik za urejanje, ki naj se povsod obnaša kot izvorno polje Blockstudio:
- atributi blokov
- skupine polj
custom/{name}za večkratno uporabo - skupine, zavihki in ponavljalniki
- predloge PHP, Twig in Blade
- metapodatki objav in shranjevanje možnosti
- razširitvene predloge, kot je
{attributes.margin.top}
Kontrolnik za razmik lahko na primer shrani en objekt namesto štirih ločenih besedilnih polj:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Poimenovanje
Imena vrst polj po meri morajo biti zapisana z malimi črkami, imeti imenski prostor in uporabljati zapis z vezaji:
namespace/type-name
Veljavni primeri:
acme/dimensionsacme/text-optionstheme/spacing-token
Rezervirani imenski prostori:
custom/je rezerviran za skupine polj po meri za večkratno uporabo.blockstudio/je rezerviran za jedro Blockstudio.
Neveljavna imena filter API prezre, pomožna funkcija API pa jih zavrne.
Registracija PHP
Metapodatke vrste polja registrirajte v 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() vrne true, če je registracija uspešna, in false,
če sta ime ali definicija neveljavna. Ročno registracijo lahko odjavite z bs_unregister_field_type().
Uporabite lahko tudi filter API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Ključi definicije
| Ključ | Vrsta | Opis |
|---|---|---|
attribute |
string, array, null |
Vrsta atributa WordPress. Uporabite string, number, boolean, object, array ali polje teh vrst. |
default |
mixed | Privzeta vrednost na ravni registra, kadar polje ne določa svoje privzete vrednosti. |
source |
string | Vir atributa WordPress za primere serializacije po meri. |
produces_attribute |
boolean | Za kontrolnike, namenjene samo prikazu, nastavite na false. Privzeta vrednost je true. |
editor_script |
string or array | Registriran ročaj skripta ali ročaji, ki jih je treba vključiti v urejevalnik blokov, ko je uporabljena ta vrsta. |
editor_style |
string or array | Registriran ročaj sloga ali ročaji, ki jih je treba vključiti v urejevalnik blokov, ko je uporabljena ta vrsta. |
storage |
array | Namigi za vrsto shranjene vrednosti in shemo REST za metapodatke objave in možnosti. |
supports |
array | Izbirne zastavice zmogljivosti za vaš kontrolnik. |
translate |
boolean | Nastavite na true, kadar je vrednost besedilo, ki ga mora prevesti WPML. Zahteva attribute string. |
Definicija z vrednostjo translate, ki ni logična, ali z nastavitvijo translate na true in vrednostjo attribute, ki ni string, je neveljavna.
bs_register_field_type() vrne false, filter API pa jo prezre.
WPML
wp bs wpml config samo na podlagi registracije ne more ugotoviti, ali je vrednost vrste polja po meri besedilo, zato taka polja izpusti in za vsako izpiše opozorilo. V registraciji vrste polja, ki shranjuje navadno besedilo, nastavite translate na true, in ukaz njegova polja obravnava kot polja text. Polje lahko to še vedno izključi z nastavitvijo "translate": false. Glejte WPML.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Registracija JavaScript
Skript urejevalnika registrira ustrezni kontrolnik 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() vrne true, če je registracija sprejeta. Registracijo v odjemalcu odstranite tako:
window.blockstudio.unregisterFieldType('acme/dimensions');
Komponenta prejme lastnosti definicije polja in te nespremenljive lastnosti:
| Lastnost | Opis |
|---|---|
type |
Ime vrste polja. |
id |
ID polja. |
field |
Celotna definicija polja iz block.json. |
value |
Trenutno shranjena vrednost. |
defaultValue |
Privzeta vrednost polja. |
onChange |
Neposredno shrani novo vrednost. |
attributes |
Trenutni atributi bloka. |
block |
Trenutna definicija vrste bloka. |
clientId |
Trenutni ID bloka v odjemalcu urejevalnika. |
inRepeater |
Ali je polje v vrstici ponavljalnika. |
repeaterId |
Trenutna pot ponavljalnika, če obstaja. |
disabled |
Ali je polje v urejevalniku onemogočeno. |
Vrednosti vrst polj po meri se shranijo neposredno. Ne gredo skozi normalizacijo možnosti za izvorna polja select, radio, color ali gradient.
Izrisovanje vrednosti
Vrednosti objektov so na voljo kot kateri koli drug atribut 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>
Gnezdene poti objektov delujejo tudi v razširitvenih predlogah:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Shranjevanje
Kadar se vrsta polja po meri uporablja s shranjevanjem postMeta ali option,
Blockstudio uporabi registrirano vrsto vrednosti za shranjevanje in shemo REST.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
Za vrednosti array in object določite storage.rest_schema pri registraciji vrste polja. Podrejeni elementi ponavljalnika še naprej uporabljajo shranjevanje na osnovi matrike, ker ponavljalnik shranjuje vrstice.
Nadomestno delovanje
Če PHP pozna vrsto polja, vendar skript urejevalnika ne registrira ustreznega kontrolnika, Blockstudio ohrani shranjeno vrednost in v urejevalniku prikaže obvestilo, ki ga ni mogoče urejati. Izrisovanje na sprednji strani še vedno prejme shranjeno vrednost.
Če vrsta polja ni registrirana v PHP, jo Blockstudio izpusti iz ustvarjenih atributov WordPress. Definicijo PHP registrirajte, preden se začne odkrivanje blokov, običajno v init, preden Blockstudio zgradi bloke.