Polja po meri
Polja po meri omogočajo določanje skupin polj za večkratno uporabo, na katere se lahko sklicuje več blokov. Predstavljajte si jih kot predloge polj: določite jih enkrat in uporabite povsod.
Polja po meri niso enaka vrstam polj po meri. Uporabite custom/{name} za skupine obstoječih polj za večkratno uporabo. Uporabite vrsto polja po meri z imenskim prostorom, kot je acme/dimensions, kadar tema ali vtičnik registrira nov kontrolnik urejevalnika in novo obliko vrednosti.
Registracija v datotečnem sistemu
Ustvarite datoteko field.json v imeniku fields/ znotraj imenika blockstudio:
theme/
└── blockstudio/
└── fields/
└── hero/
└── field.json
{
"$schema": "https://blockstudio.dev/schema/field",
"name": "hero",
"title": "Hero Section",
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Hello World"
},
{ "id": "description", "type": "textarea", "label": "Description" },
{ "id": "enabled", "type": "toggle", "label": "Enabled" }
]
}
Registracija s filtrom PHP
Polja po meri registrirajte programsko s filtrom blockstudio/fields:
add_filter('blockstudio/fields', function ($fields) {
$fields['cta'] = [
'title' => 'Call to Action',
'attributes' => [
['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
['id' => 'url', 'type' => 'text', 'label' => 'URL'],
],
];
return $fields;
});
Uporaba v block.json
Sklicujte se na polje po meri z vrsto custom/{name}:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
To se vstavi neposredno in razširi v polja, določena v definiciji polja po meri. Razširjena polja uporabljajo izvirne ID-je (heading, description, enabled).
Z uporabo polj po meri lahko znova uporabite tudi celotne definicije skupin:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"title": "Header",
"attributes": [
{ "id": "kicker", "type": "text", "label": "Kicker" },
{ "id": "title", "type": "text", "label": "Title" }
]
}
]
}
{
"blockstudio": {
"attributes": [{ "type": "custom/section-header" }]
}
}
Podrejeni elementi skupine se shranijo kot section-header_kicker,
section-header_title in tako naprej. V predlogah jih z bs_get_group()
izluščite v pregleden objekt skupine.
Struktura ID-jev
Uporabite idStructure za dodajanje predpone ID-jem polj ali njihovo pretvorbo. Nadomestni znak {id} se zamenja z izvirnim ID-jem polja:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
Tako nastanejo polja z ID-ji: hero_heading, hero_description, hero_enabled.
Preglasitve
Prilagodite posamezna polja za vsako instanco z uporabo overrides. Ključi so izvirni ID-ji polj iz definicije:
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
Lastnosti preglasitve se združijo z izvirno definicijo polja. Preglasitev id zaobide vzorec idStructure. V zgornjem primeru enabled postane active namesto hero_enabled.
Združevanje poteka samo eno raven globoko: lastnost, ki jo prepišete, v celoti nadomesti izvirno lastnost. Prepis options je celoten seznam možnosti, ne dodatek k njemu; enako velja za conditions in za attributes skupine. Pogoji iz reference se dodajo naknadno.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Ta blok ponuja samo belo in sivo, ne glede na to, koliko možnosti je navedenih v definiciji.
Pogoji
Pogoji v definicijah polj po meri se samodejno prepišejo, ko se uporabi idStructure. Polje, ki je pogojno odvisno od sorodnega polja, deluje tudi po razširitvi.
{
"name": "font-size",
"attributes": [
{ "id": "enable", "type": "toggle", "label": "Modify font size" },
{
"id": "min",
"type": "number",
"label": "Min Size",
"conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
},
{
"id": "max",
"type": "number",
"label": "Max Size",
"conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
}
]
}
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }
Blockstudio to razširi v title_font_enable, title_font_min,
title_font_max in prepiše pogoje tako, da se sklicujejo na
title_font_enable namesto na enable. Preklopni gumbi delujejo
povsem enako, kot če bi bila polja določena neposredno.
Pogoji na ravni sklica
Na sklic dodajte conditions, da jih uveljavite za vsako razširjeno polje. To
je uporabno za skrivanje celotne skupine za zunanjim preklopnim gumbom:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Ti pogoji se združijo z vsemi pogoji, ki so že določeni v definiciji polja. ID-ji pogojev se prav tako prepišejo prek idStructure.
Več polj po meri
V enem bloku lahko uporabite več polj po meri skupaj z običajnimi polji:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Gnezdenje
Polja po meri delujejo znotraj skupin, zavihkov in ponavljalnikov:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Dodatne poti za odkrivanje
S filtrom blockstudio/fields/paths dodajte dodatne imenike za odkrivanje polj:
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Statična analiza
Paket blockstudio/phpstan razširi sklice na datoteke custom/* pri preverjanju PHP, Twig, Blade, oznak blokov in sklepanju o oblikah atributov. Razširjanje upošteva enaka pravila za gnezdenje, idStructure in overrides, kot so opisana zgoraj.
Za definicije zunaj analiziranega projekta dodajte imenik knjižnice v blockstudioScanRoots v phpstan.neon. Polja, registrirana samo prek filtra blockstudio/fields PHP, obstajajo med izvajanjem in jih ni mogoče statično sklepati.