Przejdź do treści

Renderowanie programowe

Ponieważ Gutenberg staje się głównym narzędziem do tworzenia łatwych w edycji stron internetowych dla klientów, warto tworzyć wszystkie niezbędne części witryny jako bloki. To podejście sprawdzi się w większości przypadków, ale zaawansowani użytkownicy i osoby pracujące w określonych scenariuszach mogą potrzebować używać istniejących bloków poza edytorem.

Blockstudio udostępnia dwa sposoby programowego renderowania bloków:

  • Funkcje PHP: bs_render_block i bs_block do renderowania z kodu PHP
  • Znaczniki HTML: znaczniki <bs:block-name> zastępowane wynikiem renderowania bloku w dowolnym miejscu na stronie

Obsługiwane są wszystkie funkcje charakterystyczne dla Blockstudio, takie jak style wbudowane, skrypty i style ograniczone do zakresu.

Wyspy działają również w tych ścieżkach renderowania. Dynamiczna wyspa renderowana za pomocą bs_render_block(), bs_block() lub znacznika bloku zwraca ten sam znacznik zastępczy co blok renderowany z treści wpisu, a kod środowiska uruchomieniowego interfejsu witryny jest wstrzykiwany, gdy ten znacznik pojawia się w odpowiedzi.

Ustrukturyzowane kompozycje i kompletne dokumenty

W przypadku narzędzi używanych przez długi czas, podglądów, eksportów i galerii komponentów użyj wersjonowanego Blockstudio\Render API. Przyjmuje pojedynczą deklarację lub uporządkowaną listę i renderuje wynik bez wypisywania go:

PHP
use Blockstudio\Render;

$composition = [
  'root' => 'theme/card',
  'example' => [
    'data' => [
      'heading' => 'Example card',
    ],
    'layers' => [
      [
        'name' => 'theme/button',
        'data' => [
          'label' => 'Continue',
        ],
      ],
    ],
  ],
];

$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
  'title' => 'Component preview',
  'contentElement' => 'main',
  'contentClasses' => ['component-preview'],
]);

Kanoniczna, znormalizowana deklaracja zawiera cztery klucze:

PHP
[
  'name' => 'theme/card',
  'attributes' => [],
  'content' => '',
  'children' => [],
]

data, inner, innerBlocks, root, layers i example to udogodnienia wejściowe, które są usuwane podczas normalizacji. Zagnieżdżone deklaracje są renderowane rekurencyjnie za pomocą tego samego potoku Blockstudio.

Render::document() zwraca schemaVersion, html, body, blocks, assets, warnings i errors. Wartość assets rozdziela head, footer, styles, scripts, modules, interactivity, ui i tailwind. Lista bloków i zasoby obejmują zależności używane przez wybrane szablony, ale pomijają niezwiązane i dostępne tylko w edytorze zasoby.

Kompletne dokumenty mogą ustawiać bodyClasses/bodyAttributes i opcjonalnie otaczać wyrenderowaną treść elementami contentElement, contentClasses i contentAttributes. Kontener może mieć tylko bezpieczną nazwę elementu; zwracana wartość body pozostaje wyrenderowaną treścią bez kontenera. Opcje head i footer dodają zaufane znaczniki dokumentu w odpowiednich miejscach i są uwzględniane w zbiorze zwracanych zasobów.

Aby złożyć dokument wokół już wyrenderowanego elementu HTML, podaj znane nazwy jego bloków głównych:

PHP
$document = Render::document_from_html(
  $rendered_html,
  ['theme/hero', 'theme/button'],
  ['title' => 'Homepage preview']
);

Użyj Render::content() dla serializowanej zawartości bloku WordPress. Odbiorcy renderujący kilka niezależnych dokumentów w jednym żądaniu powinni wywołać między nimi Blockstudio\Batch_Render::reset(); Canvas::documents() robi to automatycznie.

Renderowanie poza stroną

Blockstudio umieszcza komentarz <!--blockstudio/namespace/slug--> przed każdym renderowanym blokiem. Na stronie witryny bufor odczytuje te komentarze, aby sprawdzić, które bloki są obecne, wczytać ich zasoby i usunąć komentarze przed wysłaniem odpowiedzi.

Wynik, który nie przechodzi przez ten bufor, zachowuje komentarze. Dotyczy to odpowiedzi REST, kanałów, procedur AJAX oraz HTML, które przechowujesz lub wysyłasz gdzie indziej po użyciu do_blocks(), Render::content() lub bs_render_block(). Użyj bs_strip_render_markers(), aby je usunąć:

PHP
$html = bs_strip_render_markers(do_blocks($post->post_content));

Funkcja usuwa komentarze zarejestrowanych bloków Blockstudio i pozostawia wszystko inne bez zmian, w tym inne komentarze HTML. Rozpoznaje te same znaczniki, które usuwa bufor strony. Wywołaj ją po rejestracji bloków (init lub później).

Nie usuwaj znaczników z kodu, który nadal jest wyświetlany na buforowanej stronie witryny. Strona potrzebuje komentarzy, aby wiedzieć, które zasoby bloków wczytać, a Blockstudio usuwa je na końcu.

Usunięcie komentarzy nie dodaje zasobów. Pliki bloków CSS i JavaScript są wstrzykiwane wyłącznie przez bufor strony. Użyj bs_block_assets() lub Render::document(), jeśli odbiorca również ich potrzebuje.

Sprawdzanie bloków

Użyj bs_block_fields() po rejestracji bloków (na init lub później), aby pobrać rozwiązane definicje pól bez odczytywania rejestrów wewnętrznych:

PHP
$fields = bs_block_fields('theme/card');

if ($fields === null) {
  // Unknown block, or not a Blockstudio block.
}

Wartość zwracana to zarejestrowana tablica definicji pól, obejmująca filtry atrybutów, rozwinięte pola niestandardowe, nadpisania oraz zagnieżdżone grupy, karty i powtarzacze. Blok Blockstudio bez pól zwraca []. Wynik jest kopią: jego zmiana nie modyfikuje zarejestrowanego bloku.

To definicje, a nie zapisane wartości. Aby walidować zapisane znaczniki, użyj bs_validate_block() zamiast utrzymywać osobny mechanizm przechodzenia po polach. Aby opisać wartości akceptowane przez blok, użyj bs_block_schema(). Atrybuty należące do WordPress pozostają odrębne.

Pola dodane przez rozszerzenia nie są częścią bs_block_fields(). Użyj bs_block_extension_fields(), aby je pobrać. Dopasowuje rozszerzenia według nazwy bloku, więc działa również w przypadku bloków podstawowych i innych firm:

PHP
$fields = array_merge(
  bs_block_fields('core/paragraph') ?? [],
  bs_block_extension_fields('core/paragraph')
);

Wartość zwracana zawiera definicje pól każdego pasującego rozszerzenia, w kolejności rejestracji rozszerzeń i w takiej samej strukturze jak bs_block_fields(). Blok, do którego nie pasuje żadne rozszerzenie, zwraca []. Wartości rozszerzeń są zapisywane w tym samym obiekcie attrs.blockstudio.attributes co wartości pól bloku, dlatego wszystkie identyfikatory współdzielą jedną przestrzeń nazw. Jeśli dwa rozszerzenia definiują ten sam identyfikator, zwracane są obie definicje i obie edytują tę samą wartość; podczas renderowania obowiązuje definicja zarejestrowanego później rozszerzenia.

Aby odczytać wartości zapisanego bloku w postaci przekazywanej do jego szablonu, użyj bs_block_values().

Użyj bs_block_assets(), aby sprawdzić wykryte CSS i JavaScript bloku. Aby uzyskać kompletny dokument podglądu, obejmujący zagnieżdżone bloki i współdzielone zależności środowiska uruchomieniowego, użyj Render::document(), jak opisano powyżej.

Weryfikowanie zapisanych wartości

Użyj bs_validate_block() po rejestracji bloków (init lub później), aby przed zapisaniem programowo wygenerowanych lub zaimportowanych atrybutów bloków sprawdzić je:

PHP
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);

if ($findings === null) {
  // No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
  // No stored-value problems were found.
} else {
  // Review the findings before saving.
}

Przekaż kompletną tablicę attrs, a nie tylko blockstudio.attributes. Renderowanie Blockstudio akceptuje również zadeklarowane pola na najwyższym poziomie, a wartości zagnieżdżone mają pierwszeństwo, gdy podano oba rodzaje. Rozszerzenia bloków podstawowych i innych firm odczytują wyłącznie blockstudio.attributes. Pusty blok Blockstudio jest zarządzany i zwraca [], a nie null.

Weryfikacja jest jawna i tylko do odczytu. Nie renderuje szablonów, nie zmienia wartości, nie zapisuje wpisów, nie odpytuje o multimedia ani nie uruchamia funkcji zwrotnych wypełniania. Nie odbywa się automatycznie podczas zapisywania, synchronizacji stron ani renderowania. Nie jest funkcją oczyszczającą, kontrolą uprawnień ani sprawdzeniem, czy załącznik istnieje.

Każde ustalenie zawiera następujące stałe klucze:

PHP
[
  'code' => 'unknown_option',
  'path' => 'steps/1/style',
  'source' => 'block',
  'message' => 'This value is not among the field options.',
  'value' => 'c',
  'expected' => ['a', 'b'],
]

W narzędziach używaj code, a nie przetłumaczonego message. source to block lub extension. Ścieżki używają kluczy przechowywania oraz indeksów wierszy repeatera lub wyboru liczonych od zera, bez początkowego ukośnika. Dosłowne znaki ~ i / w kluczu są zapisywane jako ~0 i ~1. Grupa najwyższego poziomu dodaje prefiks do swoich elementów podrzędnych (cta_title); grupy anonimowe i karty nie dodają poziomu. Grupy z identyfikatorem wewnątrz innej grupy lub repeatera nie są obsługiwane przez kreator, więc ich klucze nie są akceptowane. Pola wiadomości nie mają zapisanej wartości. Pole plików dopuszcza towarzyszące mu pole <id>__size. U korzenia bloku Blockstudio klucze porządkowe i globalne atrybuty HTML przekazywane do renderowanego elementu nie są nieznanymi polami. Nie oznacza to zgody na dowolne klucze w wierszach repeatera ani rozszerzenia bloków podstawowych.

Kod Znaczenie expected
unknown_field Żadne zachowane pole nie deklaruje tego klucza przechowywania. Znane klucze przechowywania.
unknown_option Wybrana wartość nie należy do znanych opcji. Dozwolone wartości opcji.
wrong_type Zapisana struktura nie jest obsługiwana przez to pole. Oczekiwana rodzina lub typ przechowywanych danych.
too_few_rows, too_many_rows Istniejący repeater wykracza poza min lub max. Granica liczby wierszy.
definition_conflict Definicje mające zastosowanie do jednego klucza wymagają różnych struktur przechowywania. Źródło i typ pola każdej definicji.
shadowed_value Zagnieżdżona wartość zastępuje inną wartość pola najwyższego poziomu. Zwycięska zagnieżdżona wartość.
extension_top_level Szablon może odczytać wartość najwyższego poziomu, ale powiązania rozszerzeń nie. Wymagana ścieżka pod blockstudio/attributes.
unknown_attribute Klucz najwyższego poziomu bloku Blockstudio nie jest odczytywany przez ścieżkę renderowania i zostaje pominięty. Zarejestrowane nazwy atrybutów, pola rozszerzeń i blockstudio.
missing_container attributes, disabled, name lub editor jest zapisane na najwyższym poziomie, a brakuje blockstudio. Wymagana ścieżka pod blockstudio.
invalid_container blockstudio lub blockstudio.attributes nie jest obiektem. object.

Komunikat dotyczący znaleziska unknown_field podaje najbliższy klucz pamięci masowej z tego samego poziomu, jeśli różni się on o maksymalnie trzy edycje — zgodnie z regułą stosowaną dla nieznanych ustawień: This storage key is not declared by the block or its extensions. Did you mean "title"? expected nadal wymienia wszystkie znane klucze. Dopasowanie nie uwzględnia wielkości liter i obejmuje tylko klucze pamięci masowej z danego kontenera. Komunikaty są tłumaczone; integracje powinny używać code, path i expected zamiast analizować tekst komunikatu.

Klucz najwyższego poziomu bloku Blockstudio, który nie jest zarejestrowanym atrybutem (jego pola ani atrybuty dodawane przez WordPress dla supports, lock i metadata), polem pasującego rozszerzenia, blockstudio, kluczem porządkowym ani przekazywanym atrybutem HTML, zostaje pominięty przed uruchomieniem szablonu. Taki klucz, na przykład błędnie wpisany identyfikator pola lub obiekt wartości zapisany bez opakowania blockstudio, powoduje zgłoszenie, ponieważ blok jest renderowany bez tej wartości. Bloki zawierające wyłącznie pola rozszerzeń nie są sprawdzane pod kątem kluczy najwyższego poziomu.

Akceptowane struktury odpowiadają renderowaniu: pola wyboru wielokrotnego i pola wyboru mogą zawierać listę, obiekt jednej opcji lub zaimportowaną wartość skalarną, w tym zero liczbowe. W przypadku liczb akceptowane są ciągi znaków reprezentujące liczby. Pola plików mogą zawierać identyfikatory załączników, obiekty identyfikatorów, listy lub odwołania tekstowe. Wartości linków i ikon muszą być obiektami; niestandardowe typy pól używają zarejestrowanego typu atrybutu. Pole attributes przechowuje listę par z niepustą nazwą attribute i skalarną wartością value; opcjonalne metadane, takie jak data.media, są zachowywane.

WordPress sprawdza zarejestrowane atrybuty najwyższego poziomu przed renderowaniem, przez co może odrzucić strukturę akceptowaną wewnątrz blockstudio.attributes. Na przykład wartość pola radio "a" działa w zagnieżdżonym obiekcie, ale na najwyższym poziomie zostaje pominięta, ponieważ jej zarejestrowany typ to object. Taka wartość powoduje zgłoszenie wrong_type. Użyj zagnieżdżonego obiektu, aby zastosować tę samą strukturę przechowywania, którą zapisuje edytor.

Brakujące pola nie są wymagane. Puste wartości zagnieżdżone (null, false, '', []) oraz wyłączone pola nie powodują błędów wartości. Jawnie pusty repeater nadal jest sprawdzany względem min; nie sprawdza się nieobecnego ani wyłączonego repeatera. Pusta wartość najwyższego poziomu jest zgłaszana, jeśli WordPress ją pomija i przywraca niepustą wartość domyślną. Ta sama wartość w zagnieżdżonym obiekcie może ją wyczyścić. Konflikty definicji są zgłaszane nawet wtedy, gdy klucz nie ma zapisanej wartości.

Opcje statyczne i opcje populate rozstrzygnięte podczas rejestracji są sprawdzane bez ponownego wywoływania populate. Pomijane są zdalne opcje fetch oraz argumenty populate zawierające {attributes.*}. Wartości kolorów i gradientów mogą być niestandardowe, chyba że ustawiono disableCustomColors lub disableCustomGradients. To sprawdza zapisane wartości, a nie default, fallback ani reguły walidacji edytora.

Pasujące pola rozszerzeń są uwzględniane dla każdego bloku, którego dotyczą. Późniejsze definicje mają pierwszeństwo w bloku lub jego rozszerzeniach na poziomie głównym, tak jak podczas renderowania. Własne pole bloku i pole rozszerzenia pozostają odrębnymi definicjami tego samego klucza i obie mają zastosowanie. W wierszach repeatera renderer odczytuje pierwsze pole o pasującym identyfikatorze w każdym źródle, więc obowiązują jego opcje i ograniczenia. Zduplikowane definicje są zachowywane na potrzeby diagnostyki konfliktów: niezgodne struktury przechowywania powodują definition_conflict, nawet jeśli późniejszy duplikat nie jest odczytywany podczas renderowania.

Funkcja sprawdza jeden blok. Podczas walidacji dokumentu przejdź przez innerBlocks; zsynchronizowane wzorce i inne odwołania nie są automatycznie rozwijane. Polecenie wp bs blocks validate przechodzi przez bloki jednego lub większej liczby wpisów i zgłasza ich ścieżki bloków.

Witryny z niestandardowym resolverem działającym podczas renderowania mogą dostosować zgłoszenia bez zmiany zapisanych danych:

PHP
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
  if ($name !== 'my-theme/card') {
    return $findings;
  }

  return array_values(array_filter($findings, function($finding) {
    return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
  }));
}, 10, 3);

Zawsze zwracaj listę zgłoszeń; zwrócenie [] akceptuje blok. Ten filtr działa tylko dla zarządzanych bloków, nigdy dla wyniku null.

Opisywanie zapisanych wartości

Użyj bs_block_schema() po zarejestrowaniu bloku (init lub później), aby opisać wartości zapisywane przez blok, na przykład w celu wygenerowania znaczników bloku w narzędziu lub integracji AI albo sprawdzenia danych wejściowych w trasie REST:

PHP
$schema = bs_block_schema('theme/card');

if ($schema === null) {
  // No Blockstudio fields or matching extensions apply.
}

Wynikiem jest schemat JSON obiektu zapisanego w attrs.blockstudio.attributes. Obejmuje pola bloku i pola pasujących rozszerzeń, wraz z kluczami pamięci masowej używanymi podczas walidacji: grupa najwyższego poziomu dodaje prefiks do swoich elementów podrzędnych, grupy anonimowe i karty nie dodają poziomu, a pole plików dodaje powiązane pole <id>__size. Pola powtarzalne to listy obiektów wierszy z minItems i maxItems pochodzącymi z min i max. additionalProperties ma wartość false w głównym poziomie przechowywania pól i w wierszach pól powtarzalnych. Pola o wartościach obiektowych, takie jak odnośniki i obiekty niestandardowe, mogą mieć własne metadane. Blok bez pól nie ma properties, więc pasuje tylko pusty obiekt.

Każde pole jest opisane w postaci kanonicznej akceptowanej przez bs_validate_block():

Pole Schemat
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block Ciąg znaków.
number, range Liczba z wartościami minimum i maximum pochodzącymi z min i max.
toggle Wartość logiczna.
select, radio, checkbox Wartość opcji lub lista wartości opcji dla checkbox i multiple, z enum.
color, gradient Ciąg znaków, z enum, gdy ustawiono disableCustomColors lub disableCustomGradients.
token Lista ciągów znaków.
files Nieujemna liczba całkowita będąca identyfikatorem załącznika lub lista identyfikatorów z multiple.
link Obiekt z url, title i opensInNewTab; wymagane jest url.
icon Obiekt z set, subSet i icon; wymagane są set i icon.
attributes Lista obiektów z niepustym attribute i skalarnym value.
repeater Lista obiektów wierszy.
Niestandardowe typy pól Zarejestrowany typ atrybutu.

enum zawiera opcje sprawdzane podczas walidacji: opcje statyczne i opcje wypełniania rozwiązane już podczas rejestracji. Zdalne opcje fetch i argumenty wypełniania zawierające {attributes.*} nie mają enum. Klucz z definicjami o różnych kształtach przechowywania jest pomijany, ponieważ walidacja zgłasza każdą zapisaną pod nim wartość. Gdy pole bloku i pole rozszerzenia współdzielą klucz, enum zawiera wartości akceptowane przez oba. Współdzielone pola powtarzalne łączą swoje pola podrzędne i stosują bardziej restrykcyjne limity wierszy z obu definicji. W wierszach pól powtarzalnych obowiązuje pierwsze pole o pasującym identyfikatorze z każdego źródła, tak jak podczas renderowania. Jawnie nazwane pole <id>__size ma pierwszeństwo przed automatycznie dodanym polem towarzyszącym zawierającym rozmiar pliku.

Gdy zamknięte pole nie ma dostępnych opcji lub gdy dwa pasujące zestawy opcji nie mają części wspólnej, jego wartością kanoniczną jest null dla pojedynczego wyboru albo pusta lista dla wielu wyborów. Pusta lista opcji nie zmienia pola w pole bez ograniczeń. Zdalne opcje i opcje zależne od atrybutów pozostają otwarte.

Wartość label pola staje się wartością title, jego help staje się description, a default pozostaje adnotacją. Własna wartość title schematu to tytuł bloku. Pola nigdy nie są wymagane, a logika warunkowa nie jest częścią schematu.

Ograniczenia używają wyłącznie słów kluczowych sprawdzanych przez rest_validate_value_from_schema(), więc schemat może bez zmian służyć jako schemat danych wejściowych trasy REST lub uprawnienia:

PHP
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
  $result = rest_validate_value_from_schema($values, $schema);
}

Schemat opisuje jeden formularz dla każdego pola; walidacja akceptuje również zaimportowane struktury, takie jak obiekty opcji, ciągi liczbowe i obiekty identyfikatorów. Nie zastępuje bs_validate_block(): konflikty definicji są problemami konfiguracji i mogą nadal powodować wykrycia, nawet gdy sprzeczny klucz zostanie pominięty. Filtry walidacji mogą też narzucać reguły specyficzne dla witryny. Użyj bs_validate_block(), aby sprawdzić zapisaną treść. Witryny z własnym mechanizmem rozstrzygania podczas renderowania mogą dostosować schemat za pomocą filtra blockstudio/blocks/attributes/schema.

Funkcje PHP

Bez danych

W najprostszej postaci funkcja przyjmuje jedną wartość, czyli identyfikator bloku, który ma zostać wyrenderowany na stronie.

PHP
bs_render_block('blockstudio/cta');

Z danymi

Aby wyrenderować blok z własnymi danymi, zamiast pojedynczej wartości jako pierwszego parametru należy użyć tablicy. Wartość z klucza data zostanie przekazana do zmiennej $attributes i $a w szablonie bloku.

PHP
bs_render_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
]);

Zagnieżdżanie

Bloki można zagnieżdżać w sobie, używając funkcji bs_block w połączeniu z potężną zmienną $content w szablonach bloków.

PHP
<div>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => bs_block([
    'id' => 'blockstudio/button',
    'data' => [
      'text' => 'Button Text',
    ]
  ])
]);

Blok przycisku zostanie wyrenderowany w miejscu zmiennej $content w szablonie bloku.

Osadzone bloki renderowane za pomocą bs_render_block() lub bs_block() zawsze zwracają wynik rozwiązany dla frontendu HTML, nawet gdy blok nadrzędny renderuje podgląd w edytorze. Pseudokomponenty szablonu, takie jak <RichText /> i <InnerBlocks />, są rozwiązywane przed zwróceniem osadzonego bloku.

Wiele slotów

Można też utworzyć wiele slotów treści, po prostu zmieniając zmienną $content na tablicę asocjacyjną i wywołując odpowiednie klucze w funkcji bs_block.

PHP
<div>
  <?php echo $content['beforeContent']; ?>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content['afterContent']; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => [
    'beforeContent' => bs_block([
      'id' => 'blockstudio/badge',
      'data' => ['text' => 'Before Content']
    ]),
    'afterContent' => bs_block([
      'id' => 'blockstudio/button',
      'data' => ['text' => 'Button Text']
    ])
  ]
]);

Tagi bloków

Osadź dowolny blok za pomocą składni tagu HTML. Obsługiwane są dwa formaty:

HTML
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />

Oba sposoby renderują ten sam blok. W składni <bs:> łącznik zamienia się w separator przestrzeni nazw (acme-hero staje się acme/hero). Łączniki są sprawdzane od lewej do prawej, a pierwsza zarejestrowana pasująca nazwa wygrywa, dlatego rozwiązują się też przestrzenie nazw zawierające łączniki: <bs:acme-ui-button> sprawdza acme/ui-button, a następnie acme-ui/button. Składnia <block> przyjmuje pełną nazwę bloku jako atrybut name.

Działają zarówno bloki Blockstudio, jak i bloki core WordPress. Bloki Blockstudio renderują się przez cały potok (szablony, Tailwind, zasoby). Bloki core renderują się za pomocą systemu renderowania bloków WordPress, który korzysta z wbudowanych rendererów bloków.

Jak to działa

Tagi bloków zachowują się inaczej w zależności od miejsca użycia:

W szablonach bloków i treści wpisów tagi są zastępowane wyrenderowanym HTML w czasie działania. Wynik to końcowy kod znaczników wskazanego bloku, osadzony bezpośrednio na stronie. W edytorze nie ma dla nich bloku WordPress. Służą wyłącznie do renderowania.

W Stronach, wzorcach i szablonach witryny tagi są konwertowane na natywne bloki WordPress, zanim źródło pliku zostanie zsynchronizowane lub zarejestrowane w WordPress. Dzięki temu bloki pojawiają się w edytorze, można je edytować, jeśli miejsce docelowe to obsługuje, i przechodzą pełny cykl życia bloku WordPress. Składnia tagów to skrót służący do definiowania zawartości bloków w plikach szablonów.

To rozróżnienie ma znaczenie: tagi bloków w szablonach generują wynik, a tagi bloków na stronach, we wzorcach i w szablonach witryny tworzą natywne bloki.

W szablonach bloków

Tagi bloków są automatycznie renderowane w szablonach Twig i PHP. Nie trzeba nic konfigurować. Dotyczy to również składni <bs:> i <block>, a także wszystkich zarejestrowanych tagów z prefiksem i aliasów. Szablon może więc emitować je bezpośrednio zamiast wywoływać bs_render_block(). Wynik jest renderowany HTML, bezpośrednio osadzony w wyniku szablonu bloku:

Twig
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
  <block name="core/heading" level="2">Also WordPress</block>
  <theme-card title="Prefix shorthand" />
</div>

W treści wpisu

Renderowanie na poziomie strony (treść wpisu, obszary widżetów) jest opcjonalne:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

Lub za pomocą filtra:

PHP
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');

Składnia

Tagi samozamykające:

HTML
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />

Tagi sparowane z wewnętrzną zawartością:

HTML
<bs:mytheme-section layout="wide">
  <p>Content inside the block.</p>
</bs:mytheme-section>

<block name="core/group">
  <block name="core/paragraph">Inside a group.</block>
</block>

Można dowolnie łączyć oba rodzaje. Każda składnia może być zagnieżdżona w drugiej:

HTML
<bs:mytheme-section>
  <block name="core/heading" level="2">Title</block>
  <bs:mytheme-card title="Features" />
  <block name="core/paragraph">Description text.</block>
</bs:mytheme-section>

Skróty prefiksów

Tagi bloków mogą też używać skrótów prefiksów specyficznych dla projektu. Zarejestruj prefiks z jedną lub większą liczbą przestrzeni nazw, a Blockstudio rozwiąże <prefix-slug> do pierwszego zarejestrowanego bloku w podanej kolejności przestrzeni nazw:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
HTML
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />

W powyższym przykładzie <theme-card> rozwiązuje się do theme-components/card, <theme-button> korzysta z zapasowego bsui/button, gdy theme-components/button nie jest zarejestrowany, a <theme-ui-feature-matrix> rozwiązuje się do theme-components/ui-feature-matrix.

Prefiksy można też łączyć. Jeśli tag z prefiksem nie zostanie bezpośrednio rozwiązany, a pozostała część identyfikatora jest sama w sobie zarejestrowanym tagiem z prefiksem, rozwiązywanie jest wykonywane rekurencyjnie. Dzięki temu prefiks marki może być nałożony na prefiks przestrzeni nazw:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components'];
  $prefixes['ui'] = ['bsui'];

  return $prefixes;
});
HTML
<theme-ui-input />

<theme-ui-input> nie ma bloku theme-components/ui-input, więc przechodzi do prefiksu ui i rozwiązuje się do bsui/input. Bezpośrednie dopasowania mają zawsze pierwszeństwo przed rozwiązywaniem zagnieżdżonym, a reguły zezwalania i blokowania stosuje się do ostatecznie rozwiązanego bloku.

Prefiksy można też skonfigurować w blockstudio.json:

JSON
{
  "blockTags": {
    "prefixes": {
      "theme": ["theme-components", "bsui"]
    }
  }
}

Prefiksy mogą zawierać tylko małe litery i cyfry, muszą zaczynać się od litery i nie mogą zawierać łączników. Jawne aliasy z blockstudio/block_tags/tag_aliases mają pierwszeństwo przed rozwiązywaniem prefiksów. Nieznane tagi z prefiksem pozostają bez zmian.

Tagi z prefiksem i aliasy nadal są wygodnym skrótem dla autorów. Kanoniczna, przenośna forma zapisu to zawsze <bs:namespace-slug>, ponieważ zawiera prawdziwą nazwę bloku i nie zależy od filtrów projektu:

HTML
<bs:theme-components-card />
<bs:bsui-input />

Przykłady Blockstudio, generowane komunikaty diagnostyczne i wynik programowy używają tej kanonicznej formy zapisu. Projekty, które chcą usunąć starszy skrót, mogą użyć samodzielnej migracji tagów kanonicznych bez uruchamiania WordPress.

Bloki podstawowe

Można użyć dowolnego bloku z zarejestrowanym rendererem:

HTML
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
  <bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>

Lub użyć składni <block>:

HTML
<block name="core/group">
  <block name="core/columns">
    <block name="core/column">
      <block name="core/paragraph">Left column</block>
    </block>
    <block name="core/column">
      <block name="core/paragraph">Right column</block>
    </block>
  </block>
</block>

Listy dozwolonych i zablokowanych

Określ, które bloki mogą być renderowane za pomocą tagów:

JSON
{
  "blockTags": {
    "enabled": true,
    "allow": ["mytheme/*", "core/*"],
    "deny": ["mytheme/internal-*"]
  }
}

allow ogranicza wybór do pasujących wzorców. deny wyklucza pasujące wzorce i ma pierwszeństwo. Oba obsługują symbole wieloznaczne * za pośrednictwem fnmatch(). Zasady te dotyczą obu składni oraz renderowania na poziomie szablonu i strony.

Filtry: blockstudio/block_tags/allow i blockstudio/block_tags/deny.

Przekazywanie HTML

Atrybuty z prefiksem data- są przekazywane do elementu głównego wyrenderowanego bloku. Przekazywane są również atrybuty z prefiksem html-, ale bez tego prefiksu. Działa to w obu składniach. Przekazany atrybut zastępuje istniejącą wartość elementu głównego, zamiast ją łączyć. Dlatego html-class zastępuje własne klasy bloku.

Blok Blockstudio umieszcza również na swoim elemencie głównym globalne atrybuty, których nie deklaruje jako pól: id, style, role, title, lang, dir, hidden, tabindex i każdy atrybut aria-*. Zadeklarowane pole ma zawsze pierwszeństwo, więc blok z polem title otrzymuje wartość z $a['title']. Przekazywane style przechodzą przez safecss_filter_attr(); filtr WordPress stosuje się do atrybutów stylu w treści wpisu, a style te są dopisywane do stylu już ustawionego przez szablon.

Wartości atrybutów są HTML, więc encje są dekodowane raz podczas analizowania tagu: title="Tom &amp; Jerry" dociera do szablonu jako Tom & Jerry i jest ponownie kodowane przy wyjściu. Wartości w cudzysłowach mogą zawierać >, co jest potrzebne między innymi wariantom Tailwind i selektorom animacji, zarówno w tagach samozamykających, jak i sparowanych.

Żaden inny atrybut, którego blok nie deklaruje, w tym class, nie trafia do HTML. Gdy włączono WP_DEBUG, Blockstudio zgłasza każdy taki atrybut raz na żądanie za pośrednictwem _doing_it_wrong(). Zadeklaruj dla niego pole albo zapisz go jako atrybut data-, aria- lub html-.

HTML
<bs:mytheme-card
  title="My Card"
  html-class="featured-card"
  html-id="main-card"
  data-analytics="card-click"
/>

<block name="core/paragraph" html-class="highlight" data-section="intro">
  Highlighted paragraph.
</block>

Własne renderery

Zarejestruj własne renderery bloków dla dodatkowych typów bloków. Renderery przyjmują tablicę atrybutów i ciąg znaków z zawartością wewnętrzną, a zwracają tablicę bloków WordPress:

PHP
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
    $builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
        $html = '<div class="my-block">' . $inner_content . '</div>';
        return [
            'blockName'    => 'myplugin/custom-block',
            'attrs'        => $attrs,
            'innerBlocks'  => [],
            'innerHTML'    => $html,
            'innerContent' => [$html],
        ];
    };
    return $builders;
}, 10, 2);

W przypadku bloków kontenerowych, które muszą analizować zawartość wewnętrzną, aby utworzyć bloki podrzędne, dodaj drugi wpis w tym samym filtrze:

PHP
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
    $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
    $content = ['<div class="my-wrapper">'];
    foreach ($inner_blocks as $block) {
        $content[] = null;
    }
    $content[] = '</div>';
    return [
        'blockName'    => 'myplugin/wrapper',
        'attrs'        => $attrs,
        'innerBlocks'  => $inner_blocks,
        'innerHTML'    => '<div class="my-wrapper"></div>',
        'innerContent' => $content,
    ];
};

blockstudio/block_tags/builders dotyczy zarówno tagów bloków, jak i bloków własnych wybranych przez blockstudio/parser/element_mapping. To odpowiedni punkt rozszerzeń, gdy blok projektu mapowany na element musi przenieść tekst wewnętrzny do pola Blockstudio lub utworzyć własną tablicę bloków.

blockstudio/block_tags/renderers i blockstudio/parser/renderers otrzymują ten sam rejestr i ten sam kształt funkcji zwrotnej. Pozostają dostępne ze względu na zgodność i końcowe nadpisania na poziomie parsera. Filtry są uruchamiane w tej kolejności:

  1. blockstudio/block_tags/builders
  2. blockstudio/block_tags/renderers
  3. blockstudio/parser/renderers

Późniejszy filtr może zastąpić renderer zarejestrowany przez wcześniejszy filtr.

Użycie programowe

Zastosuj renderowanie tagów do dowolnego ciągu znaków z PHP:

PHP
$html = apply_filters('blockstudio/block_tags/render', $content);

Komponenty

Tagi bloków dobrze współpracują z komponentami Components. Komponenty to bloki renderowane wyłącznie programowo, które nigdy nie pojawiają się w edytorze.

HTML
<bs:mytheme-card title="My Card" description="Card content." />

Parser

Tagi bloków są przetwarzane przez lekki skaner ciągów znaków, który zastępuje DOMDocument. Parser obsługuje składnię <bs:> i <block>, zagnieżdżone tagi o tej samej nazwie ze śledzeniem głębokości, wartości atrybutów w cudzysłowach oraz rekurencyjne bloki kontenerowe. Został stworzony specjalnie do tego zastosowania. Działa szybciej niż zarówno DOMDocument, jak i WordPress WP_HTML_Tag_Processor, a także omija znane problemy DOMDocument z usuwaniem prefiksów przestrzeni nazw i zamianą nazw atrybutów na małe litery.

W przypadku Stron, wzorców i szablonów witryny ten sam parser obsługuje też surowe elementy HTML (<p>, <div>, <h1> itd.), mapując je na odpowiadające im bloki podstawowe WordPress.

Gdy mapowanie elementu przypisuje <p> do zarejestrowanego bloku innego niż podstawowy Blockstudio, który deklaruje atrybut richtext content, zawartość wewnętrzna HTML jest automatycznie przekazywana do tego atrybutu content, w tym tagi inline, takie jak code i img, które są mapowane na poziomie bloku. Akapit, którego jedynym elementem podrzędnym jest obraz, staje się blokiem wskazanym przez <img>. Zagnieżdżone tagi bloków lub elementy HTML na poziomie bloku nadal korzystają ze zwykłego analizowania bloków wewnętrznych. <block name="core/shortcode"> zachowuje tekst shortcode jako zawartość bloku.