Към съдържанието

Персонализирани полета

Персонализираните полета ви позволяват да дефинирате групи от полета за повторна употреба, към които могат да препращат различни блокове. Представете си ги като шаблони за полета: дефинирате веднъж, използвате навсякъде.

Персонализираните полета не са същото като типовете персонализирани полета. Използвайте custom/{name} за групи от съществуващи полета за повторна употреба. Използвайте персонализиран тип поле с пространство от имена, като acme/dimensions, когато тема или добавка регистрира нова контрола в редактора и структура на стойността.

Регистрация във файловата система

Създайте файл field.json в директория fields/ във вашата директория blockstudio:

Код
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

Регистрирайте персонализирани полета програмно чрез филтъра 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;
});

Употреба в block.json

Препратете към персонализирано поле чрез типа custom/{name}:

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

Това вгражда полетата, дефинирани в дефиницията на персонализираното поле. Разширените полета използват оригиналните си ID-та (heading, description, enabled).

Персонализираните полета могат също да използват повторно пълни дефиниции на групи:

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

Дъщерните елементи на групата се съхраняват като section-header_kicker, section-header_title и т.н. В шаблоните използвайте bs_get_group(), за да ги извлечете в чист обект на група.

Структура на ID-тата

Използвайте idStructure, за да добавите префикс или да преобразувате ID-тата на полетата. Заместителят {id} се заменя с оригиналното ID на полето:

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

Това създава полета със следните ID-та: hero_heading, hero_description, hero_enabled.

Замени

Персонализирайте отделни полета за всяка инстанция чрез overrides. Ключовете са оригиналните ID-та на полетата от дефиницията:

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

Заместващите свойства се сливат с оригиналната дефиниция на полето. Замяна на id заобикаля шаблона idStructure. В примера по-горе enabled става active вместо hero_enabled.

Сливането е само на едно ниво: свойство, което заменяте, замества оригиналното свойство изцяло. Една подмяна с options е целият списък с опции, а не добавка към него; същото важи за conditions и за attributes на група. Условията на препратката продължават да се добавят след това.

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

Този блок предлага само White и Grey, независимо колко опции са изброени в дефиницията.

Условия

Условията в дефинициите на персонализирани полета се пренаписват автоматично при прилагане на idStructure. Поле, чието условие зависи от съседно поле, продължава да работи след разширяването.

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 разширява това до title_font_enable, title_font_min, title_font_max и пренаписва условията така, че да сочат към title_font_enable вместо към enable. Превключвателите работят точно както ако полетата бяха дефинирани вградени.

Условия на ниво препратка

Добавете conditions към препратката, за да ги приложите към всяко разширено поле. Това е полезно за скриване на цяла група зад външен превключвател:

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

Тези условия се сливат с всички условия, вече дефинирани в самата дефиниция на полето. ID-тата на условията също се пренаписват чрез idStructure.

Няколко персонализирани полета

Можете да използвате няколко персонализирани полета в един блок, заедно с обикновени полета:

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

Влагане

Персонализираните полета работят в групи, раздели и повторители:

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

Допълнителни пътища за откриване

Използвайте филтъра blockstudio/fields/paths, за да добавите допълнителни директории за откриване на полета:

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

Статичен анализ

Пакетът blockstudio/phpstan разширява препратките custom/* от файлове при валидиране на PHP, Twig, Blade, блокови тагове и изведени структури на атрибутите. Разширяването му следва същите правила за влагане, idStructure и overrides, описани по-горе.

За дефиниции извън анализирания проект добавете директорията на библиотеката към blockstudioScanRoots в phpstan.neon. Полета, регистрирани само чрез филтъра blockstudio/fields PHP, съществуват по време на изпълнение и не могат да бъдат изведени статично.