Przejdź do treści

Pola niestandardowe

Pola niestandardowe pozwalają definiować wielokrotnego użytku grupy pól, do których można się odwoływać w wielu blokach. Można o nich myśleć jak o szablonach pól: zdefiniuj raz, używaj wszędzie.

Pola niestandardowe różnią się od niestandardowych typów pól. Używaj custom/{name} w przypadku grup istniejących pól wielokrotnego użytku. Używaj niestandardowego typu pola z przestrzenią nazw, takiego jak acme/dimensions, gdy motyw lub wtyczka rejestruje nową kontrolkę edytora i strukturę wartości.

Rejestracja w systemie plików

Utwórz plik field.json w katalogu fields/ w katalogu blockstudio:

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

Rejestracja filtra PHP

Zarejestruj pola niestandardowe programowo za pomocą 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;
});

Użycie w block.json

Odwołaj się do pola niestandardowego za pomocą typu custom/{name}:

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

Ta definicja jest rozwijana bezpośrednio do zdefiniowanych w niej pól. Rozwinięte pola zachowują swoje oryginalne identyfikatory (heading, description, enabled).

Pola niestandardowe mogą również ponownie wykorzystywać pełne definicje grup:

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

Elementy podrzędne grupy są przechowywane jako section-header_kicker, section-header_title itd. W szablonach użyj bs_get_group(), aby wyodrębnić je do przejrzystego obiektu grupy.

Struktura ID

Użyj idStructure, aby dodać prefiks do identyfikatorów pól lub je przekształcić. Symbol zastępczy {id} zostanie zastąpiony oryginalnym identyfikatorem pola:

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

Wynikiem będą pola o identyfikatorach: hero_heading, hero_description, hero_enabled.

Nadpisywanie

Dostosuj poszczególne pola dla każdej instancji za pomocą overrides. Klucze to oryginalne identyfikatory pól z definicji:

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

Właściwości nadpisujące są scalane z oryginalną definicją pola. Nadpisanie id omija wzorzec idStructure. W powyższym przykładzie enabled przyjmuje wartość active zamiast hero_enabled.

Scalanie jest jednopoziomowe: nadpisywana właściwość zastępuje całą oryginalną właściwość. Nadpisanie options oznacza kompletną listę opcji, a nie jej rozszerzenie; to samo dotyczy conditions oraz attributes grupy. Warunki dotyczące referencji są dodawane później.

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

Ten blok oferuje tylko kolor biały i szary, niezależnie od liczby opcji wymienionych w definicji.

Warunki

Warunki w niestandardowych definicjach pól są automatycznie przepisywane po zastosowaniu idStructure. Pole zależne warunkowo od pola sąsiedniego nadal działa po rozwinięciu.

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 rozwija to do title_font_enable, title_font_min, title_font_max i przepisuje warunki tak, by odwoływały się do title_font_enable zamiast enable. Przełączniki działają identycznie jak w przypadku pól zdefiniowanych bezpośrednio.

Warunki na poziomie odwołania

Dodaj conditions do odwołania, aby zastosować je do każdego rozwiniętego pola. Przydaje się to do ukrywania całej grupy za zewnętrznym przełącznikiem:

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

Warunki te są scalane z warunkami już zdefiniowanymi w definicji pola. Identyfikatory warunków są również przepisywane przez idStructure.

Wiele pól niestandardowych

W jednym bloku możesz używać wielu pól niestandardowych obok zwykłych pól:

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

Zagnieżdżanie

Pola niestandardowe działają wewnątrz grup, kart i powtarzaczy:

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

Dodatkowe ścieżki wykrywania

Użyj filtra blockstudio/fields/paths, aby dodać kolejne katalogi do wykrywania pól:

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

Analiza statyczna

Pakiet blockstudio/phpstan rozwija odwołania custom/* oparte na plikach podczas weryfikacji PHP, Twig, Blade, tagów bloków i wywnioskowanych struktur atrybutów. Rozwinięcie przebiega zgodnie z opisanymi powyżej regułami zagnieżdżania, idStructure i overrides.

W przypadku definicji spoza analizowanego projektu dodaj katalog biblioteki do blockstudioScanRoots w phpstan.neon. Pola rejestrowane wyłącznie za pomocą filtra blockstudio/fields PHP istnieją w czasie wykonywania i nie można ich wywnioskować statycznie.