Izdelava vrste polja po meri
Nekatere vrednosti vsebujejo več kot en osnovni podatek. Cena je znesek in valuta. Z vgrajenimi polji jo modelirate kot številsko polje in izbirno polje drugo ob drugem, v vsakem bloku, ki prikazuje ceno, pa ponavljate ta par, oznake in logiko, ki ju povezuje. V meta podatkih objave postaneta dva ključa, v ponavljalniku pa dva vzporedna seznama.
Vrsta polja po meri ta par združi v eno polje. Vrsto, kot je acme/price, registrirate enkrat,
v PHP in JavaScript, nato pa jo uporabljate v katerem koli
block.json kot vgrajeno polje: na najvišji ravni, v skupinah in ponavljalnikih,
za shranjevanje meta podatkov objave ali možnosti ter v predlogah PHP, Twig in Blade.
Blockstudio iz registracije izpelje atribut WordPress in shranjevalno shemo REST.
To se razlikuje od polja po meri.
Sklic custom/{name} ponovno uporabi skupino obstoječih polj. Vrsta polja po meri doda nov kontrolnik z lastno obliko vrednosti.
Ta vodnik od začetka do konca izdela acme/price: registracijo PHP, kontrolnik urejevalnika, cenovni blok, ki ga uporablja na najvišji ravni in v ponavljalniku, shranjevanje v meta podatke objave s strogo shemo REST ter izrisano vsebino.
Registracija vrste v PHP
Del PHP določa vrsto atributa, privzeto vrednost, skript urejevalnika, ki zagotavlja kontrolnik, in način shranjevanja vrednosti zunaj bloka:
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 je vrsta atributa WordPress, tukaj object. storage.type je vrsta vrednosti,
ki se uporablja pri shranjevanju polja v meta podatke objave ali možnosti, storage.rest_schema pa je shema, po kateri WordPress preverja zapise REST.
Brez rest_schema dobi vrednost objekta ohlapno shemo, ki sprejme poljubne lastnosti.
Registracijo izvedite na init s privzeto prednostjo. Blockstudio pozno
odkrije bloke v init, zato vrste, ki do takrat ni registrirana, ni med ustvarjenimi atributi bloka.
bs_register_field_type() ob uspehu vrne true, ob neveljavnem imenu ali definiciji pa false. Imena morajo biti z malimi črkami, vključevati imenski prostor in uporabljati vezaje; dva imenska prostora sta rezervirana:
| Ime | Rezultat |
|---|---|
acme/price |
true |
Acme/Price |
false, ni zapisano z malimi črkami |
custom/price |
false, rezervirano za skupine polj za ponovno uporabo |
blockstudio/price |
false, rezervirano za jedro Blockstudio |
bs_unregister_field_type() znova odstrani registracijo, filter
blockstudio/field_types pa sprejme iste definicije v obliki polja z imeni kot ključi.
Izdelava kontrolnika urejevalnika
Zgoraj registrirani skript zagotavlja komponento React. Uporablja komponente WordPress, ki so že naložene v urejevalniku, zato gradnja ni potrebna:
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 });
},
}),
),
);
},
});
Komponenta prejme vse lastnosti definicije polja, zato ključ currencies, ki ga navedete v block.json, prejme kot props.currencies. Prejme tudi stabilne lastnosti: value, onChange, field, defaultValue, attributes, block, clientId, disabled in inRepeater z repeaterId, ko se izriše znotraj vrstice ponavljalnika. onChange shrani vrednost natančno tako, kot je podana. Vrednosti po meri preskočijo normalizacijo možnosti, ki jo uporabljajo vgrajena polja select, radio, color in gradient.
Kot v prvih vrsticah preverite, da vrednosti niso objekti. Blok, shranjen, preden je polje obstajalo, ali z drugačno obliko, bi se moral še vedno odpreti v urejevalniku.
Blockstudio doda acme-field-price v urejevalnik blokov samo, ko je registriran blok,
ki uporablja acme/price. Če skript ne registrira kontrolnika,
urejevalnik ohrani shranjeno vrednost in namesto polja prikaže obvestilo, ki ga ni mogoče urejati; vmesnik spletnega mesta vrednost še vedno izriše.
Uporaba v bloku
Cenovni blok uporabi vrsto dvakrat: enkrat za začetno ceno, po kateri je mogoče iskati zunaj bloka, in enkrat v vsaki vrstici ponavljalnika cenovnih razredov:
{
"$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"
}
}
]
}
]
}
}
Nastavitev na ravni polja default ima prednost pred privzeto nastavitvijo registra. Blockstudio obe
polji spremeni v atribute WordPress iz registracije. Registrirana vrsta bloka vsebuje:
{
"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" }
}
]
}
}
Izris vrednosti
V predlogi je vrednost navadno polje. Pred uporabo omejite njeno vrsto, saj je shranjena vrednost zanesljiva le toliko kot zadnja stvar, ki jo je zapisala:
<?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() je pomembna. Ponavljalnik brez vrstic v predlogo prispe kot false,
ne kot prazno polje; neposredni foreach nad njim sproži opozorilo PHP.
Pomen vrstice @var je razložen spodaj v razdelku statična analiza.
Izris bloka z začetno ceno in dvema cenovnima razredoma:
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>
Brez podatkov se uporabi privzeta vrednost polja in blok se izriše kot From 19.00 EUR brez cenovnih razredov. Twig in Blade prebereta isto vrednost kot a.price.amount in $a['price']['amount'], predloge za razširitev pa jo lahko navedejo kot {attributes.price.amount}.
Shranjevanje in shema REST
Obe polji določata shranjevanje postMeta, zato Blockstudio ob izdelavi bloka registrira dva ključa meta. Polje na najvišji ravni uporablja registrirano shranjevalno shemo takšno, kot je:
{
"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
}
}
}
Polje znotraj ponavljalnika shrani eno vrednost za vsako vrstico, zato njegov ključ meta uporablja polje, registrirana shema pa postane shema elementa:
{
"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
}
}
}
}
Shranjevanje objave, ki vsebuje blok, sinhronizira oba ključa. Z zgornjima cenovnima razredoma get_post_meta( $id, 'acme_price', true ) vrne {"amount":19,"currency":"EUR"}, acme_tier_prices pa vrne seznam cen vrstic:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Oba ključa sta v odgovoru REST objave pod meta, zapisi REST pa so preverjeni po shemi. Zapis z valuto z malimi črkami je zavrnjen:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Meta je kopija. Atributi bloka v vsebini objave ostanejo izvor, vsako shranjevanje pa jih znova sinhronizira z nastavljenimi ključi, zato se vrednost, zapisana neposredno v meta podatke, ob naslednjem shranjevanju objave prepiše. Shranjevanje možnosti deluje enako prek register_setting(). Vrste polj po meri, vključno s shranjevanjem z uporabo polja znotraj ponavljalnikov, so na voljo od različice Blockstudio 7.5.0.
Statična analiza
Razširitev PHPStanextension pozna vgrajene vrste polj, ne pa tistih, ki jih projekt registrira med izvajanjem. Pri bloku, ki uporablja acme/price, vrsto polja označi kot neznano, njegovo vrednost pa tipizira kot mixed:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
V konfiguraciji projekta prezrite to diagnostiko za lastne vrste, v predlogi pa ohranite omejevanje vrste, ki ga PHPStan potrebuje za sprejem vrednosti mixed na ravni max:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
S to konfiguracijo in zgornjo predlogo analiza uspe. Pri različici 7.6 predloga potrebuje tudi vrstico @var, pri čemer je mixed na mestih polj po meri; različica Blockstudio 7.7 to obliko sklepa sama, zato lahko vrstico odstranite. Za zagon analize glejte Preverjene predloge z PHPStan.
Naslednji koraki
- Vrste polj po meri: vsi ključi definicij, filter API in celoten seznam lastnosti komponent.
- Shranjevanje: shranjevanje meta podatkov objave in možnosti za poljubno polje.
- Zbirka vzorcev polj: skupine, ponavljalniki in strukture polj za ponovno uporabo.
- Polja po meri: skupine polj za ponovno uporabo prek
custom/{name}.