Preskočiť na obsah

Vlastné polia

Vlastné polia umožňujú definovať opätovne použiteľné skupiny polí, na ktoré možno odkazovať vo viacerých blokoch. Predstavte si ich ako šablóny polí: definujte ich raz a používajte všade.

Vlastné polia nie sú to isté ako vlastné typy polí. Použite custom/{name} na opätovne použiteľné skupiny existujúcich polí. Menný priestor pre vlastný typ poľa, napríklad acme/dimensions, použite vtedy, keď téma alebo plugin registruje nový ovládací prvok editora a štruktúru hodnoty.

Registrácia v súborovom systéme

Vytvorte súbor field.json v priečinku fields/ v adresári 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" }
  ]
}

Registrácia pomocou filtra PHP

Zaregistrujte vlastné polia programovo pomocou filtra 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žitie v block.json

Odkážte na vlastné pole pomocou typu custom/{name}:

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

Tým sa polia definované vo vlastnej definícii poľa vložia priamo sem. Rozbalené polia používajú svoje pôvodné ID (heading, description, enabled).

Vlastné polia môžu opätovne používať aj úplné definície skupín:

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

Podriadené prvky skupiny sa ukladajú ako section-header_kicker, section-header_title a tak ďalej. V šablónach ich pomocou bs_get_group() extrahujte do prehľadného objektu skupiny.

Štruktúra ID

Pomocou idStructure pridajte predponu k ID polí alebo ich transformujte. Zástupný symbol {id} sa nahradí pôvodným ID poľa:

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

Výsledkom sú polia s ID: hero_heading, hero_description, hero_enabled.

Prepísanie hodnôt

Prispôsobte jednotlivé polia pre každú inštanciu pomocou overrides. Kľúčmi sú pôvodné ID polí z definície:

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

Vlastnosti prepísania sa zlúčia s pôvodnou definíciou poľa a majú pred ňou prednosť. Prepísanie id obíde vzor idStructure. V príklade vyššie sa enabled zmení na active namiesto hero_enabled.

Zlúčenie prebieha iba o jednu úroveň: vlastnosť, ktorú prepíšete, nahradí celú pôvodnú vlastnosť. Prepísanie options predstavuje celý zoznam možností, nie jeho rozšírenie; to isté platí pre conditions a pre attributes skupiny. Podmienky na referencii sa pridávajú až následne.

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

Tento blok ponúka iba bielu a sivú farbu bez ohľadu na počet možností uvedených v definícii.

Podmienky

Podmienky vo vlastných definíciách polí sa pri použití idStructure automaticky prepíšu. Pole, ktorého podmienka závisí od susedného poľa, bude po rozbalení naďalej fungovať.

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 prepíše podmienky tak, aby odkazovali na title_font_enable namiesto enable. Prepínače fungujú presne tak, ako keby boli polia definované priamo.

Podmienky na úrovni odkazu

Pridajte conditions k odkazu, aby sa podmienky použili na každé rozbalené pole. Hodí sa to na skrytie celej skupiny za externým prepínačom:

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

Tieto podmienky sa zlúčia so všetkými podmienkami, ktoré už sú definované vo vnútri definície poľa. ID podmienok sa prepíšu aj prostredníctvom idStructure.

Viacero vlastných polí

V jednom bloku môžete spolu s bežnými poľami použiť aj viacero vlastných polí:

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

Vnáranie

Vlastné polia fungujú vnútri skupín, kariet a opakovačov:

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

Ďalšie cesty vyhľadávania

Pomocou filtra blockstudio/fields/paths pridajte ďalšie adresáre, v ktorých sa budú vyhľadávať polia:

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

Statická analýza

Balík blockstudio/phpstan pri overovaní súborovo založených odkazov custom/*, značiek blokov PHP, Twig, Blade a odvodených tvarov atribútov rozbaľuje odkazy na definície. Rozbalenie sa riadi rovnakými pravidlami vnárania, idStructure a overrides, ktoré sú opísané vyššie.

Pri definíciách mimo analyzovaného projektu pridajte adresár knižnice do blockstudioScanRoots v phpstan.neon. Polia zaregistrované iba pomocou filtra blockstudio/fields PHP existujú za behu a nemožno ich staticky odvodiť.