Přejít k obsahu

Programové vykreslování

Protože se Gutenberg stává hlavním nástrojem pro tvorbu snadno upravitelných webů pro klienty, dává smysl vytvářet všechny potřebné části webu jako bloky. Tento přístup vyhovuje většině uživatelů, pokročilí uživatelé a specifické případy použití však mohou vyžadovat využití stávajících bloků mimo editor.

Blockstudio nabízí dva způsoby programového vykreslování bloků:

  • Funkce PHP: bs_render_block a bs_block pro vykreslování z kódu PHP
  • Značky HTML: značky <bs:block-name>, které se kdekoli na stránce nahradí výstupem bloku

Podporovány jsou všechny specifické funkce Blockstudio, například vložené styly, skripty a styly omezené na konkrétní oblast.

Islands fungují i při těchto způsobech vykreslování. Dynamický ostrov vykreslený pomocí bs_render_block(), bs_block() nebo značky bloku vrací stejnou značku zástupného prvku jako blok vykreslený z obsahu příspěvku. Pokud je tato značka v odpovědi přítomna, vloží se do ní běhové prostředí frontendu.

Strukturované kompozice a úplné dokumenty

U nástrojů s dlouhou životností, náhledů, exportů a galerií komponent použijte verzované Blockstudio\Render API. Přijímá jednu deklaraci nebo uspořádaný seznam a vykresluje bez výpisu:

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'],
]);

Kanonická normalizovaná deklarace má čtyři klíče:

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

data, inner, innerBlocks, root, layers a example jsou zkratky pro vstup a při normalizaci se odstraní. Vnořené deklarace se vykreslují rekurzivně stejným postupem Blockstudio.

Render::document() vrací schemaVersion, html, body, blocks, assets, warnings a errors. Hodnota assets odděluje head, footer, styles, scripts, modules, interactivity, ui a tailwind. Seznam bloků a prostředky zahrnují závislosti, na které odkazují vybrané šablony, ale nezahrnují nesouvisející prostředky ani prostředky určené pouze pro editor.

Úplné dokumenty mohou nastavit bodyClasses/bodyAttributes a volitelně obalit vykreslené tělo pomocí contentElement, contentClasses a contentAttributes. Obal je omezen na bezpečný název prvku; vrácený body zůstává nevnořeným vykresleným obsahem. Možnosti head a footer přidávají důvěryhodné značky dokumentu na příslušná místa a jsou zahrnuty do vráceného souboru závislých prostředků.

Chcete-li sestavit dokument kolem již vykresleného HTML, zadejte názvy jeho známých kořenových bloků:

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

Pro serializovaný obsah bloku WordPress použijte Render::content(). Volání, která v jednom požadavku vykreslují několik nezávislých dokumentů, by mezi nimi měla zavolat Blockstudio\Batch_Render::reset(); Canvas::documents() to dělá automaticky.

Vykreslování mimo stránku

Blockstudio vkládá komentář <!--blockstudio/namespace/slug--> před každý blok, který vykreslí. Na stránce frontendu vyrovnávací paměť tyto komentáře přečte, zjistí přítomné bloky, načte jejich prostředky a před odesláním odpovědi komentáře odstraní.

Výstup, který touto vyrovnávací pamětí neprojde, komentáře zachová. Platí to pro odpovědi REST, kanály, obslužné rutiny AJAX a HTML, které po do_blocks(), Render::content() nebo bs_render_block() uložíte či odešlete jinam. K jejich odstranění použijte bs_strip_render_markers():

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

Funkce odstraní komentáře registrovaných bloků Blockstudio a vše ostatní ponechá beze změny, včetně dalších komentářů HTML. Rozpoznává stejné značky, které odstraňuje vyrovnávací paměť stránky. Zavolejte ji po registraci bloků (init nebo později).

Neodstraňujte značky z kódu, který se stále vypisuje na stránku frontendu obsluhovanou vyrovnávací pamětí. Stránka tyto komentáře potřebuje, aby zjistila, které prostředky bloků má načíst, a Blockstudio je odstraní sama na konci.

Odstraněním komentářů se prostředky nepřidají. Soubory bloků CSS a JavaScript vkládá pouze vyrovnávací paměť stránky. Pokud je potřebuje také konzument, použijte bs_block_assets() pro nebo Render::document().

Prohlížení bloků

Po registraci bloků (od init výše) použijte bs_block_fields() k získání vyřešených definic polí, aniž byste museli číst interní registry:

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

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

Vrácená hodnota je pole registrovaných definic polí, včetně filtrů atributů, rozšířených vlastních polí, přepsání a vnořených skupin, karet a opakovačů. Blok Blockstudio bez polí vrací []. Výsledek je kopie: jeho změnou registrovaný blok nezměníte.

Jde o definice, nikoli o uložené hodnoty. Chcete-li ověřit uložené značky, použijte bs_validate_block() místo údržby samostatného procházení polí. Chcete-li popsat hodnoty, které blok přijímá, použijte bs_block_schema(). Atributy spravované pomocí WordPress zůstávají oddělené.

Pole přidaná rozšířeními nejsou součástí bs_block_fields(). Získáte je pomocí bs_block_extension_fields(). Rozšíření páruje podle názvu bloku, takže funguje také pro základní bloky a bloky třetích stran:

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

Vrácená hodnota obsahuje definice polí všech odpovídajících rozšíření v pořadí jejich registrace a ve stejné struktuře jako bs_block_fields(). Pokud žádné rozšíření bloku neodpovídá, vrátí se []. Hodnoty rozšíření se ukládají do stejného objektu attrs.blockstudio.attributes jako vlastní hodnoty polí bloku, takže všechna ID sdílejí jeden jmenný prostor. Pokud dvě rozšíření definují stejné ID, vrátí se obě definice a upravují stejnou hodnotu; při vykreslení se použije definice později registrovaného rozšíření.

Chcete-li načíst hodnoty uloženého bloku tak, jak je přijímá jeho šablona, použijte bs_block_values().

Pomocí bs_block_assets() prohlédnete nalezené CSS a JavaScript bloku. Úplný dokument náhledu včetně vnořených bloků a sdílených běhových závislostí získáte pomocí Render::document(), jak je popsáno výše.

Ověřování uložených hodnot

Po registraci bloků (init nebo později) použijte bs_validate_block() k programovému ověření atributů bloků vytvořených nebo importovaných před jejich uložením:

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

Předejte celé pole attrs, nikoli pouze blockstudio.attributes. Vykreslení bloku Blockstudio přijímá deklarovaná pole také na nejvyšší úrovni a pokud jsou zadána obě, přednost mají vnořené hodnoty. Rozšíření základních bloků a bloků třetích stran čtou pouze blockstudio.attributes. Prázdný blok Blockstudio je spravovaný a vrací [], nikoli null.

Ověření je výslovné a pouze pro čtení. Nevyrenderuje šablony, nezmění hodnoty, neuloží příspěvky, nevyhledá média ani nespustí callbacky pro naplnění. Nespouští se automaticky při ukládání, synchronizaci stránek ani vykreslování. Nejde o sanitizaci, kontrolu oprávnění ani ověření existence přílohy.

Každý nález obsahuje tyto stabilní klíče:

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

V nástrojích používejte code, nikoli přeložené message. source je block nebo extension. Cesty používají úložné klíče a indexy řádků opakovače nebo výběru číslované od nuly, bez úvodního lomítka. Doslovné ~ a / v klíči se escapují jako ~0 a ~1. Skupina na nejvyšší úrovni předřazuje svým potomkům svůj prefix (cta_title); anonymní skupiny a karty nepřidávají žádnou úroveň. Skupiny s ID uvnitř jiné skupiny nebo opakovače nejsou nástrojem podporovány, proto jejich klíče nejsou přijímány. Pole zpráv nemají uloženou hodnotu. Pole souborů povoluje svůj doprovodný klíč <id>__size. V kořeni bloku Blockstudio nejsou evidenční klíče a globální atributy HTML předávané vykreslenému prvku neznámými poli. To nepovoluje libovolné klíče v řádcích opakovače ani rozšíření základních bloků.

Kód Význam expected
unknown_field Žádné zachované pole nedefinuje tento úložný klíč. Známé úložné klíče.
unknown_option Výběr není mezi známými možnostmi. Povolené hodnoty možností.
wrong_type Uložená struktura není polem podporována. Očekávaná rodina nebo typ úložiště.
too_few_rows, too_many_rows Přítomný opakovač je mimo své min nebo max. Hranice počtu řádků.
definition_conflict Použitelné definice jednoho klíče vyžadují různé struktury úložiště. Zdroj a typ pole každé definice.
shadowed_value Vnořená hodnota přepisuje jinou hodnotu pole na nejvyšší úrovni. Vítězná vnořená hodnota.
extension_top_level Šablona může číst hodnotu na nejvyšší úrovni, ale rozšiřující vazby nikoli. Její povinná cesta pod blockstudio/attributes.
unknown_attribute Klíč na nejvyšší úrovni bloku Blockstudio se v cestě vykreslení nečte a zahodí se. Registrované názvy atributů, rozšiřující pole a blockstudio.
missing_container attributes, disabled, name nebo editor je uloženo na nejvyšší úrovni a chybí blockstudio. Jeho povinná cesta pod blockstudio.
invalid_container blockstudio nebo blockstudio.attributes není objekt. object.

Zpráva o nálezu unknown_field uvádí nejbližší úložný klíč na stejné úrovni, pokud se od něj liší nejvýše třemi úpravami; toto pravidlo se používá u neznámých nastavení: This storage key is not declared by the block or its extensions. Did you mean "title"? expected stále uvádí všechny známé klíče. Při porovnávání se ignoruje velikost písmen a zohledňují se pouze úložné klíče z daného kontejneru. Zprávy jsou přeložené; integrace by měly používat code, path a expected místo parsování textu zprávy.

Klíč na nejvyšší úrovni bloku Blockstudio, který není registrovaným atributem (jeho poli, atributy, které WordPress přidává pro supports, lock a metadata), polem odpovídajícího rozšíření, blockstudio, evidenčním klíčem ani předávaným atributem HTML, se před spuštěním šablony zahodí. Takový klíč, například chybně zadané ID pole nebo objekt hodnot uložený bez obalu blockstudio, vyvolá nález, protože se blok vykreslí bez této hodnoty. Bloky, které obsahují pouze pole rozšíření, se u klíčů na nejvyšší úrovni nekontrolují.

Přijímané struktury odpovídají vykreslování: vícenásobné výběry a zaškrtávací pole mohou obsahovat seznam, objekt jedné možnosti nebo importovanou skalární hodnotu, včetně číselné nuly. Číselné řetězce jsou pro čísla přijímány. Pole souborů mohou obsahovat ID příloh, objekty ID, seznamy nebo řetězcové odkazy. Hodnoty odkazů a ikon musí být objekty; vlastní typy polí používají svůj registrovaný typ atributu. Pole attributes obsahuje seznam dvojic s neprázdným názvem attribute a skalární hodnotou value; volitelná metadata, například data.media, se zachovávají.

WordPress před vykreslením ověřuje registrované atributy na nejvyšší úrovni, což může odmítnout strukturu, která je uvnitř blockstudio.attributes přijímána. Například hodnota přepínače "a" funguje ve vnořeném objektu, ale na nejvyšší úrovni se zahodí, protože její registrovaný typ je object. Taková hodnota vyvolá wrong_type. Pro stejnou strukturu úložiště, jakou zapisuje editor, použijte vnořený objekt.

Chybějící pole nejsou povinná. Prázdné vnořené hodnoty (null, false, '', []) a zakázaná pole nevyvolávají chyby hodnot. Výslovně prázdný opakovač se přesto kontroluje podle min; chybějící nebo zakázaný opakovač nikoli. Prázdná hodnota na nejvyšší úrovni se nahlásí, pokud ji WordPress zahodí a obnoví neprázdnou výchozí hodnotu. Stejná hodnota ve vnořeném objektu ji může vymazat. Konflikty definic se hlásí i tehdy, když klíč nemá uloženou hodnotu.

Statické možnosti a možnosti populate vyřešené už při registraci se kontrolují bez opětovného volání populate. Vzdálené možnosti fetch a argumenty populate obsahující {attributes.*} se přeskakují. Hodnoty barev a přechodů mohou být vlastní, pokud není nastaveno disableCustomColors nebo disableCustomGradients. Kontrolují se uložené hodnoty, nikoli default, fallback ani pravidla ověřování editoru.

Odpovídající pole rozšíření se zahrnou do každého bloku, na který cílí. Pozdější definice mají přednost v bloku nebo jeho rozšířeních v kořeni, stejně jako při vykreslení. Vlastní pole bloku a pole rozšíření zůstávají samostatnými definicemi stejného klíče a platí obě. V řádcích opakovače vykreslovač čte první pole s odpovídajícím ID v každém zdroji, takže platí jeho možnosti a limity. Duplicitní definice se zachovávají pro diagnostiku konfliktů: nekompatibilní struktury úložiště vyvolají definition_conflict, i když se pozdější duplicita při vykreslování nenačte.

Funkce kontroluje jeden blok. Při ověřování dokumentu projděte innerBlocks; synchronizované vzory a další odkazy se nerozbalují automaticky. Příkaz wp bs blocks validate prochází bloky jednoho nebo více příspěvků a hlásí jejich cesty k blokům.

Weby s vlastním resolverem při vykreslování mohou upravit nálezy, aniž by měnily uložená data:

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);

Vždy vracejte seznam nálezů; vrácením [] se blok přijme. Tento filtr se spouští pouze pro spravované bloky, nikdy pro výsledek null.

Popis uložených hodnot

Pomocí bs_block_schema() po registraci bloku (init nebo novější verze) popište hodnoty, které blok ukládá, například pro generování značek bloku v nástroji nebo integraci AI nebo pro kontrolu vstupu v trase REST:

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

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

Výsledkem je schéma JSON objektu uloženého v attrs.blockstudio.attributes. Zahrnuje pole bloku i pole odpovídajících rozšíření spolu s úložnými klíči, které používá validace: skupina nejvyšší úrovně přidá dětem předponu, anonymní skupiny a karty nepřidávají žádnou úroveň a souborové pole přidává doprovodné pole <id>__size. Opakovače jsou seznamy řádkových objektů s minItems a maxItems z min a max. additionalProperties je false v kořeni úložiště polí i v řádcích opakovače. Pole s hodnotami typu objekt, například odkazy a vlastní objekty, mohou mít vlastní metadata. Blok bez polí nemá žádné properties, takže mu odpovídá pouze prázdný objekt.

Každé pole je popsáno v kanonickém formátu, který přijímá bs_validate_block():

Pole Schéma
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block Řetězec.
number, range Číslo s minimum a maximum z min a max.
toggle Logická hodnota.
select, radio, checkbox Hodnota možnosti nebo seznam hodnot možností pro checkbox a multiple s enum.
color, gradient Řetězec s enum, pokud je nastaveno disableCustomColors nebo disableCustomGradients.
token Seznam řetězců.
files ID přílohy jako nezáporné celé číslo nebo seznam ID s multiple.
link Objekt s url, title a opensInNewTab; url je povinné.
icon Objekt s set, subSet a icon; set a icon jsou povinné.
attributes Seznam objektů s neprázdným attribute a skalárním value.
repeater Seznam řádkových objektů.
Vlastní typy polí Jejich registrovaný typ atributu.

enum uvádí možnosti, které validace kontroluje: statické možnosti a možnosti naplnění vyhodnocené už při registraci. Vzdálené možnosti fetch a argumenty naplnění obsahující {attributes.*} nemají enum. Klíč s definicemi různých tvarů úložiště se vynechá, protože validace hlásí každou hodnotu uloženou pod tímto klíčem. Pokud pole bloku a pole rozšíření sdílejí klíč, enum uvádí hodnoty, které přijímají obě. Sdílené opakovače slučují svá podřízená pole a uplatňují přísnější limity řádků z obou definic. V řádcích opakovače se použije první pole s odpovídajícím ID v každém zdroji, stejně jako při vykreslování. Výslovně pojmenované pole <id>__size má přednost před automaticky přidaným doprovodným polem velikosti souboru.

Pokud uzavřené pole nemá dostupné možnosti nebo se dvě použitelné sady možností nepřekrývají, jeho kanonickou hodnotou je null pro jeden výběr nebo prázdný seznam pro více výběrů. Prázdný seznam možností nezmění pole na neomezené. Vzdálené možnosti a možnosti závislé na atributech zůstávají otevřené.

Z label pole se stane title, z jeho help se stane description a default zůstane jako anotace. Vlastní title schématu je název bloku. Žádná pole nejsou povinná a podmíněná logika není součástí schématu.

Omezení používají pouze klíčová slova, která kontroluje rest_validate_value_from_schema(), takže schéma lze přímo použít jako vstupní schéma trasy REST nebo schopnosti:

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

Schéma popisuje jeden formulář pro každé pole; validace přijímá také importované formáty, například objekty možností, číselné řetězce a objekty ID. Nenahrazuje bs_validate_block(): konflikty definic jsou problémy konfigurace a mohou stále vést k nálezům, i když je konfliktní klíč vynechán. Validační filtry mohou také zavádět pravidla specifická pro daný web. Pomocí bs_validate_block() zkontrolujte uložený obsah. Weby s vlastním resolverem při vykreslování mohou schéma upravit pomocí filtru blockstudio/blocks/attributes/schema.

Funkce PHP

Bez dat

V nejjednodušší podobě funkce přijímá jedinou hodnotu, kterou je ID bloku určeného k vykreslení na stránce.

PHP
bs_render_block('blockstudio/cta');

S daty

Chcete-li blok vykreslit s vlastními daty, použijte místo jediné hodnoty pro první parametr pole. Hodnota v klíči data se předá proměnné $attributes a $a uvnitř šablony bloku.

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

Vnořování

Bloky lze vnořovat do sebe pomocí funkce bs_block v kombinaci s výkonnou proměnnou $content uvnitř šablon bloků.

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 tlačítka se vykreslí namísto proměnné $content uvnitř šablony bloku.

Vložené bloky vykreslené pomocí bs_render_block() nebo bs_block() vždy vracejí HTML vyřešené pro front end, i když nadřazený blok právě vykresluje náhled v editoru. Pseudokomponenty šablon, například <RichText /> a <InnerBlocks />, se vyřeší před vrácením vloženého bloku.

Více slotů

Více obsahových slotů lze vytvořit také tak, že se z proměnné $content udělá asociativní pole a v rámci funkce bs_block se zavolají příslušné klíče.

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']
    ])
  ]
]);

Značky bloků

Vložte libovolný blok pomocí syntaxe značky HTML. Podporovány jsou dva formáty:

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

Oba způsoby vykreslí stejný blok. Syntaxe <bs:> mění pomlčku na oddělovač jmenného prostoru (acme-hero se změní na acme/hero). Pomlčky se zkoušejí zleva doprava a vyhraje první zaregistrovaný kandidát, takže se rozpoznají i jmenné prostory obsahující pomlčky: <bs:acme-ui-button> zkouší acme/ui-button a poté acme-ui/button. Syntaxe <block> předává celý název bloku jako atribut name.

Fungují bloky Blockstudio i základní bloky WordPress. Bloky Blockstudio se vykreslují přes celý proces (šablony, Tailwind, prostředky). Základní bloky se vykreslují pomocí systému vykreslování bloků v WordPress, který používá vestavěné vykreslovače bloků.

Jak to funguje

Značky bloků se chovají různě podle toho, kde se nacházejí:

V šablonách bloků a obsahu příspěvků se značky za běhu nahrazují vykreslenými bloky HTML. Výstupem je konečná značka odkazovaného bloku vložená přímo do stránky. V editoru se pro ně nenachází žádný blok WordPress. Slouží výhradně k vykreslení.

V Pages, Patterns, and Site Templates se značky před synchronizací zdroje souboru nebo registrací v WordPress převádějí na nativní bloky WordPress. Bloky se tak zobrazí v editoru, lze je upravovat, pokud to cílové prostředí podporuje, a projdou celým životním cyklem bloků WordPress. Syntaxe značek je zkratkou pro definování obsahu bloků v souborech šablon.

Tento rozdíl je důležitý: značky bloků v šablonách vytvářejí výstup, zatímco značky bloků na stránkách, ve vzorech a v šablonách webu vytvářejí nativní bloky.

V šablonách bloků

Značky bloků se vykreslují automaticky uvnitř šablon Twig a PHP. Není potřeba nic nastavovat. Patří sem syntaxe <bs:> a <block> i všechny zaregistrované značky prefixu a aliasy, takže je šablona může přímo vypsat místo volání bs_render_block(). Výstup se vykreslí jako HTML a vloží přímo do výstupu šablony 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>

V obsahu příspěvků

Vykreslování na úrovni stránky (obsah příspěvku, oblasti widgetů) je třeba výslovně zapnout:

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

Nebo pomocí filtru:

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

Syntaxe

Samouzavírací značky:

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

Párové značky s vnitřním obsahem:

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>

Kombinujte je libovolně. Obě syntaxe lze vzájemně vnořovat:

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>

Zkratky prefixů

Značky bloků mohou používat také zkratky prefixů specifické pro projekt. Zaregistrujte prefix s jedním nebo více jmennými prostory a Blockstudio vyhledá <prefix-slug> jako první zaregistrovaný blok v pořadí těchto jmenných prostorů:

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

V uvedeném příkladu se <theme-card> vyřeší jako theme-components/card, <theme-button> přejde na bsui/button, pokud theme-components/button není zaregistrován, a <theme-ui-feature-matrix> se vyřeší jako theme-components/ui-feature-matrix.

Prefixy lze také skládat. Pokud se značka s prefixem přímo nevyřeší a zbývající část slug-u je sama zaregistrovanou značkou prefixu, vyhledávání pokračuje rekurzivně. Prefix značky tak může navazovat na prefix jmenného prostoru:

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> nemá blok theme-components/ui-input, a proto se použije prefix ui a vyřeší se bsui/input. Přímé shody mají vždy přednost před vnořeným vyhledáváním a pravidla povolení a zákazu se vztahují na konečný vyřešený blok.

Prefixy lze nastavit také v blockstudio.json:

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

Prefixy mohou obsahovat pouze malá písmena nebo číslice, musí začínat písmenem a nesmějí obsahovat pomlčky. Výslovné aliasy z blockstudio/block_tags/tag_aliases mají přednost před vyhledáváním prefixů. Neznámé značky s prefixem zůstávají beze změny.

Značky prefixů a aliasů zůstávají praktickými pomůckami při tvorbě obsahu. Kanonický a přenositelný zápis je vždy <bs:namespace-slug>, protože zaznamenává skutečný název bloku bez závislosti na projektových filtrech:

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

Příklady Blockstudio, generovaná diagnostická hlášení a programový výstup používají tento kanonický zápis. Projekty, které chtějí odstranit starší zkratkovou syntaxi, mohou použít samostatnou migraci na kanonické značky, která nejprve spustí kontrolní režim a funguje bez spuštění WordPress.

Základní bloky

Lze použít libovolný blok se zaregistrovaným vykreslovačem:

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>

Nebo pomocí syntaxe <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>

Seznamy povolených a zakázaných bloků

Určete, které bloky lze vykreslovat pomocí značek:

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

allow omezuje výběr pouze na odpovídající vzory. deny odpovídající vzory vylučuje a má přednost. Oba podporují zástupné znaky * pomocí fnmatch(). Tato pravidla platí pro obě syntaxe i pro vykreslování na úrovni šablon a stránek.

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

Předávání atributů HTML

Atributy s prefixem data- se předávají kořenovému prvku vykresleného bloku. Atributy s prefixem html- se také předávají, ale prefix se odstraní. Funguje to s oběma syntaktickými zápisy. Předaný atribut nahradí stávající hodnotu kořenového prvku místo toho, aby se s ní sloučil; například html-class nahradí třídy nastavené samotným blokem.

Blok Blockstudio také přidá na svůj kořenový prvek globální atributy, které nejsou deklarované jako pole: id, style, role, title, lang, dir, hidden, tabindex a každý atribut aria-*. Deklarované pole má vždy přednost, takže blok s polem title místo toho dostane hodnotu z $a['title']. Předávané styly procházejí přes safecss_filter_attr(), filtr WordPress se vztahuje na atributy stylu v obsahu příspěvků a předávané styly se připojí ke stylu, který už šablona nastavuje.

Hodnoty atributů jsou HTML, proto se entity dekódují jednou při parsování značky: title="Tom &amp; Jerry" se dostane do šablony jako Tom & Jerry a při výstupu se znovu escapuje. Hodnoty v uvozovkách mohou obsahovat >, například varianty Tailwind a selektory animací, a to v samouzavíracích i párových značkách.

Každý další atribut, který blok nedeklaruje, včetně class, se nikdy nedostane do HTML. Je-li zapnuté WP_DEBUG, Blockstudio o každém takovém atributu jednou za požadavek informuje prostřednictvím _doing_it_wrong(). Deklarujte pro něj pole nebo jej zapište jako atribut data-, aria- či 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>

Vlastní vykreslovače

Zaregistrujte vlastní vykreslovače pro další typy bloků. Vykreslovače přijímají pole atributů a řetězec vnitřního obsahu a vracejí pole bloku 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);

U kontejnerových bloků, které potřebují parsovat vnitřní obsah na podřízené bloky, přidejte do stejného filtru druhou položku:

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 se vztahuje na značky bloků i vlastní bloky vybrané pomocí blockstudio/parser/element_mapping. Tento hook je vhodný, když je třeba v projektu s mapováním prvků přesunout vnitřní text do pole Blockstudio nebo vytvořit vlastní pole bloku.

blockstudio/block_tags/renderers a blockstudio/parser/renderers dostávají stejný registr i tvar callbacku. Kvůli kompatibilitě a závěrečným přepsáním na úrovni parseru zůstávají dostupné. Filtry se spouštějí v tomto pořadí:

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

Pozdější filtr může nahradit vykreslovač zaregistrovaný dřívějším filtrem.

Programové použití

Použijte vykreslování značek na libovolný řetězec z PHP:

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

Komponenty

Značky bloků se dobře kombinují s komponentami. Komponenty jsou bloky, které se vykreslují pouze programově a nikdy se nezobrazují v editoru.

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

Parser

Značky bloků zpracovává lehký skener řetězců, který nahrazuje DOMDocument. Parser zvládá syntaxi <bs:> i <block>, vnořené značky se stejným názvem pomocí sledování hloubky, hodnoty atributů v uvozovkách a rekurzivní kontejnerové bloky. Je navržený přímo pro tento případ použití, v testech výkonu překonává DOMDocument i WordPress WP_HTML_Tag_Processor a obchází známé problémy DOMDocument s odstraňováním prefixů jmenných prostorů a převodem názvů atributů na malá písmena.

Pro Pages, Patterns, and Site Templates stejný parser zpracovává také nezpracované prvky HTML (<p>, <div>, <h1> atd.) a mapuje je na odpovídající základní bloky WordPress.

Pokud mapování prvku přiřadí <p> registrovanému bloku Blockstudio, který není základní a deklaruje atribut content typu richtext, vnitřní obsah HTML se automaticky předá do tohoto atributu content, včetně vložených značek, jako jsou code a img, které jsou mapovány na úrovni prvků bloku. Odstavec, jehož jediným potomkem je obrázek, se změní na blok, na který mapuje <img>. Vnořené značky bloků a prvky HTML na úrovni bloku se nadále zpracovávají běžným parsováním vnitřních bloků. <block name="core/shortcode"> zachová svůj text shortcode jako obsah bloku.