Pāriet uz saturu

Pielāgotie lauki

Pielāgotie lauki ļauj definēt atkārtoti izmantojamas lauku grupas, uz kurām var atsaukties vairākos blokos. Uztveriet tās kā lauku veidnes: definējiet vienreiz un izmantojiet visur.

Pielāgotie lauki nav tas pats, kas pielāgotie lauku tipi. Izmantojiet custom/{name} atkārtoti izmantojamām esošo lauku grupām. Izmantojiet nosaukumtelpā iekļautu pielāgotu lauka tipu, piemēram, acme/dimensions, ja tēma vai spraudnis reģistrē jaunu redaktora vadīklu un vērtības struktūru.

Reģistrācija failu sistēmā

Izveidojiet failu field.json direktorijā fields/, kas atrodas jūsu blockstudio direktorijā:

Kods
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
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" }
  ]
}

PHP filtra reģistrācija

Reģistrējiet pielāgotos laukus programmiski, izmantojot filtru blockstudio/fields:

PHP
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;
});

Lietošana block.json

Atsaucieties uz pielāgotu lauku, izmantojot tipu custom/{name}:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero" }]
  }
}

Tas izvērš definētā pielāgotā lauka laukus tieši šeit. Izvērstie lauki saglabā savus sākotnējos ID (heading, description, enabled).

Pielāgotajos laukos var atkārtoti izmantot arī pilnas grupu definīcijas:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/section-header" }]
  }
}

Grupas apakšelementi tiek saglabāti kā section-header_kicker, section-header_title un tā tālāk. Veidnēs izmantojiet bs_get_group(), lai izvilktu tos sakārtotā grupas objektā.

ID struktūra

Izmantojiet idStructure lauku ID prefiksa pievienošanai vai pārveidošanai. Vietturis {id} tiek aizstāts ar sākotnējo lauka ID:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
  }
}

Tādējādi tiek izveidoti lauki ar ID: hero_heading, hero_description, hero_enabled.

Pārrakstīšana

Pielāgojiet atsevišķus laukus katrā instancē, izmantojot overrides. Atslēgas ir sākotnējie lauku ID no definīcijas:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "default": "Welcome", "label": "Title" },
          "enabled": { "id": "active" }
        }
      }
    ]
  }
}

Pārrakstīto rekvizītu vērtības tiek apvienotas ar sākotnējo lauka definīciju. Pārrakstot id, tiek apiets raksts idStructure. Iepriekš minētajā piemērā enabled kļūst par active, nevis hero_enabled.

Apvienošana notiek tikai vienā līmenī: pārrakstīts rekvizīts aizstāj visu sākotnējo rekvizītu. options pārrakstīšana norāda pilnu opciju sarakstu, nevis tā papildinājumu; tas pats attiecas uz conditions un grupas attributes. Atsauces nosacījumi joprojām tiek pievienoti pēc tam.

JSON
{
  "type": "custom/background",
  "overrides": {
    "background": {
      "options": [
        { "value": "white", "label": "White" },
        { "value": "grey", "label": "Grey" }
      ]
    }
  }
}

Šis bloks piedāvā tikai balto un pelēko krāsu neatkarīgi no tā, cik opciju ir norādīts definīcijā.

Nosacījumi

Nosacījumi pielāgoto lauku definīcijās tiek automātiski pārveidoti, kad tiek lietots idStructure. Lauks, kura nosacījums ir atkarīgs no blakus lauka, turpina darboties arī pēc izvēršanas.

JSON
{
  "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 }]]
    }
  ]
}
JSON
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }

Blockstudio izvērš to par title_font_enable, title_font_min, title_font_max un pārraksta nosacījumus, lai tie atsauktos uz title_font_enable, nevis enable. Pārslēgi darbojas tieši tāpat kā tad, ja lauki būtu definēti iekļauti.

Atsauces līmeņa nosacījumi

Pievienojiet conditions atsaucei, lai tos piemērotu katram izvērstajam laukam. Tas noder, lai paslēptu veselu grupu aiz ārēja pārslēga:

JSON
{
  "type": "custom/font-size",
  "idStructure": "subtitle_font_{id}",
  "conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}

Šie nosacījumi tiek apvienoti ar visiem nosacījumiem, kas jau definēti lauka definīcijā. Nosacījumu ID arī tiek pārrakstīti, izmantojot idStructure.

Vairāki pielāgotie lauki

Vienā blokā varat izmantot vairākus pielāgotos laukus kopā ar parastajiem laukiem:

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "intro", "type": "text", "label": "Intro" },
      { "type": "custom/hero", "idStructure": "hero_{id}" },
      { "type": "custom/cta", "idStructure": "cta_{id}" }
    ]
  }
}

Ligzdošana

Pielāgotie lauki darbojas grupās, cilnēs un atkārtotājos:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "id": "content",
        "title": "Content",
        "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
      }
    ]
  }
}

Papildu noteikšanas ceļi

Izmantojiet filtru blockstudio/fields/paths, lai pievienotu papildu direktorijus lauku noteikšanai:

PHP
add_filter('blockstudio/fields/paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/blockstudio/fields';
    return $paths;
});

Statiskā analīze

Pakotne blockstudio/phpstan izvērš failos definētas custom/* atsauces, validējot PHP, Twig, Blade, bloku tagus un secinot atribūtu struktūras. Izvēršana ievēro tās pašas ligzdošanas, idStructure un overrides kārtulas, kas aprakstītas iepriekš.

Ārpus analizētā projekta esošām definīcijām pievienojiet bibliotēkas direktoriju blockstudioScanRoots failā phpstan.neon. Lauki, kas reģistrēti tikai ar filtru blockstudio/fields PHP, darbojas izpildlaikā, un to tipu nevar noteikt statiski.