Mukautetut kentät
Mukautettujen kenttien avulla voit määrittää uudelleenkäytettäviä kenttäryhmiä, joihin voidaan viitata useissa lohkoissa. Ne ovat kuin kenttämalleja: määritä kerran ja käytä kaikkialla.
Mukautetut kentät eivät ole sama asia kuin
mukautetut kenttätyypit. Käytä
custom/{name}-määritystä olemassa olevien kenttien uudelleenkäytettäviin ryhmiin. Käytä nimiavaruudellista mukautettua kenttätyyppiä, kuten acme/dimensions, kun teema tai lisäosa rekisteröi uuden editorin ohjaimen ja arvomuodon.
Rekisteröinti tiedostojärjestelmässä
Luo field.json-tiedosto fields/-hakemiston sisälle blockstudio-hakemistossasi:
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" }
]
}
Rekisteröinti PHP-suodattimella
Rekisteröi mukautetut kentät ohjelmallisesti blockstudio/fields-suodattimella:
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;
});
Käyttö kohteessa block.json
Viittaa mukautettuun kenttään käyttämällä tyyppiä custom/{name}:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Tämä laajennetaan suoraan mukautetun kentän määrityksessä määritettyihin kenttiin. Laajennetut kentät käyttävät alkuperäisiä tunnuksiaan (heading, description, enabled).
Mukautetuissa kentissä voidaan käyttää uudelleen myös täydellisiä ryhmämäärityksiä:
{
"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" }]
}
}
Ryhmän alikohteet tallennetaan arvoina section-header_kicker,
section-header_title ja niin edelleen. Voit poimia ne siistiksi ryhmäobjektiksi mallissa käyttämällä arvoa bs_get_group().
Tunnusrakenne
Käytä arvoa idStructure kenttätunnusten etuliitteenä tai niiden muuntamiseen. Paikkamerkki {id} korvataan alkuperäisellä kenttätunnuksella:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
Näin syntyvät tunnukset: hero_heading, hero_description, hero_enabled.
Ylikirjoitukset
Voit mukauttaa yksittäisiä kenttiä instanssikohtaisesti käyttämällä arvoa overrides. Avaimet ovat määrityksestä peräisin olevia alkuperäisiä kenttätunnuksia:
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
Ohitusominaisuudet yhdistetään alkuperäiseen kenttämääritykseen. id-ohitus ohittaa mallin idStructure. Yllä olevassa esimerkissä arvosta enabled tulee active arvon hero_enabled sijaan.
Yhdistäminen tapahtuu vain yhden tason syvyydeltä: yliajamasi ominaisuus korvaa alkuperäisen ominaisuuden kokonaan. options-yliajo on koko vaihtoehtoluettelo, ei sen täydennys, ja sama pätee ryhmän conditions– ja attributes-kohtiin. Viitteen ehdot lisätään silti jälkikäteen.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Tämä lohko tarjoaa vain valkoisen ja harmaan, vaikka määritelmässä olisi kuinka monta vaihtoehtoa.
Ehdot
Mukautettujen kenttämääritysten ehdot kirjoitetaan automaattisesti uudelleen, kun idStructure otetaan käyttöön. Kenttä, jonka näyttäminen riippuu ehdollisesti sisarkentästä, toimii edelleen laajentamisen jälkeen.
{
"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 laajentaa tämän muotoon title_font_enable, title_font_min,
title_font_max ja kirjoittaa ehdot uudelleen viittaamaan arvoon
title_font_enable arvon enable sijaan. Kytkimet toimivat
juuri niin kuin kentät olisi määritetty suoraan.
Viitetason ehdot
Lisää viitteeseen conditions, jotta ehdot koskevat jokaista laajennettua kenttää. Tästä on hyötyä, kun haluat piilottaa koko ryhmän ulkoisen kytkimen taakse:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Nämä ehdot yhdistetään kaikkiin kenttämäärityksessä jo oleviin ehtoihin. Ehtojen tunnukset kirjoitetaan myös uudelleen arvon idStructure avulla.
Useita mukautettuja kenttiä
Voit käyttää samassa lohkossa useita mukautettuja kenttiä tavallisten kenttien rinnalla:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Sisäkkäisyys
Mukautetut kentät toimivat ryhmien, välilehtien ja toistimien sisällä:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Muita etsintäpolkuja
Lisää kenttien etsintähakemistoja käyttämällä suodatinta blockstudio/fields/paths:
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Staattinen analyysi
blockstudio/phpstan-paketti laajentaa tiedostoihin perustuvat
custom/*-viittaukset, kun se tarkistaa PHP-, Twig- ja Blade-arvot, lohkotunnisteet sekä päätellyt määritearvojen muodot. Laajennuksessa noudatetaan yllä kuvattuja sisäkkäisyys-, idStructure– ja overrides-sääntöjä.
Lisää analysoidun projektin ulkopuoliset kirjastohakemistot kohteeseen blockstudioScanRoots tiedostossa phpstan.neon. Vain ajonaikaisesti rekisteröidyt blockstudio/fields PHP-suodattimen kautta tehdyt rekisteröinnit eivät ole pääteltävissä staattisesti.