Preskoči na vsebino

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:

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

Registracija s filtrom PHP

Polja po meri registrirajte programsko s filtrom 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;
});

Uporaba v block.json

Sklicujte se na polje po meri z vrsto custom/{name}:

JSON
{
  "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:

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

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:

JSON
{
  "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:

JSON
{
  "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.

JSON
{
  "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.

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 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:

JSON
{
  "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:

JSON
{
  "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:

JSON
{
  "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:

PHP
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.