Přejít k obsahu

Vlastní pole

Vlastní pole umožňují definovat opakovaně použitelné skupiny polí, na které lze odkazovat z více bloků. Představte si je jako šablony polí: definujte jednou, používejte všude.

Vlastní pole nejsou totéž co vlastní typy polí. Pro opakovaně použitelné skupiny existujících polí použijte custom/{name}. Pokud šablona nebo plugin registruje nový ovládací prvek editoru a tvar hodnoty, použijte vlastní typ pole se jmenným prostorem, například acme/dimensions.

Registrace v systému souborů

Vytvořte soubor field.json v adresáři fields/ uvnitř adresáře blockstudio:

Kód
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" }
  ]
}

Registrace pomocí filtru PHP

Zaregistrujte vlastní pole programově pomocí 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;
});

Použití v block.json

Odkazujte na vlastní pole pomocí typu custom/{name}:

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

Tím se vloží pole definovaná ve vlastní definici pole. Rozbalená pole používají svá původní ID (heading, description, enabled).

Vlastní pole mohou znovu použít také úplné definice skupin:

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" }]
  }
}

Podřízené položky skupiny se ukládají jako section-header_kicker, section-header_title atd. V šablonách je pomocí bs_get_group() převeďte na přehledný objekt skupiny.

Struktura ID

Pomocí idStructure můžete předřadit prefix ID polí nebo je transformovat. Zástupný symbol {id} se nahradí původním ID pole:

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

Výsledkem budou pole s ID: hero_heading, hero_description, hero_enabled.

Přepisování hodnot

Upravte jednotlivá pole pro každou instanci pomocí overrides. Klíče jsou původní ID polí z definice:

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

Přepsané vlastnosti se sloučí s původní definicí pole. Přepsání id obchází vzor idStructure. Ve výše uvedeném příkladu se enabled změní na active místo hero_enabled.

Sloučení probíhá pouze o jednu úroveň: přepsaná vlastnost nahradí původní vlastnost jako celek. Přepsání options představuje úplný seznam možností, nikoli jeho rozšíření; totéž platí pro conditions a pro attributes skupiny. Podmínky uvedené v referenci se přidají až poté.

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

Tento blok nabízí pouze bílou a šedou barvu, bez ohledu na počet možností uvedených v definici.

Podmínky

Podmínky ve vlastních definicích polí se automaticky přepíší při použití idStructure. Pole, jehož podmínka závisí na sourozeneckém poli, bude po rozbalení dál fungovat.

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 to rozbalí na title_font_enable, title_font_min, title_font_max a přepíše podmínky tak, aby odkazovaly na title_font_enable místo enable. Přepínače fungují přesně tak, jako kdyby byla pole definována přímo.

Podmínky na úrovni odkazu

Přidejte conditions do odkazu a použijte je na každé rozbalené pole. Hodí se to, když chcete skrýt celou skupinu pomocí externího přepínače:

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

Tyto podmínky se sloučí se všemi podmínkami, které už jsou definované uvnitř definice pole. ID podmínek se také přepíší pomocí idStructure.

Více vlastních polí

V jednom bloku můžete použít více vlastních polí společně s běžnými poli:

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

Vnořování

Vlastní pole fungují uvnitř skupin, karet a opakovačů:

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

Další cesty pro vyhledávání

Pomocí filtru blockstudio/fields/paths přidejte další adresáře pro vyhledávání polí:

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

Statická analýza

Balíček blockstudio/phpstan rozbaluje odkazy custom/* na soubory při ověřování PHP, Twig, Blade, značek bloků a odvozených tvarů atributů. Při rozbalování se řídí stejnými pravidly pro vnořování, idStructure a overrides, která jsou popsána výše.

U definic mimo analyzovaný projekt přidejte adresář knihovny do blockstudioScanRoots v phpstan.neon. Pole registrovaná pouze přes filtr blockstudio/fields PHP existují za běhu a nelze je staticky odvodit.