Programové vykresľovanie
Keďže Gutenberg je čoraz dôležitejším nástrojom na tvorbu webových stránok, ktoré si klienti môžu jednoducho upravovať, má zmysel vytvoriť všetky potrebné časti stránky ako bloky. Tento prístup vyhovuje väčšine používateľov, no pokročilí používatelia a špecifické prípady použitia môžu vyžadovať použitie existujúcich blokov mimo editora.
Blockstudio ponúka dva spôsoby programového vykresľovania blokov:
- Funkcie PHP:
bs_render_blockabs_blockna vykresľovanie z kódu PHP - Značky HTML: značky
<bs:block-name>, ktoré sa kdekoľvek na stránke nahradia výstupom bloku
Podporované sú všetky funkcie špecifické pre Blockstudio, ako sú vložené štýly, skripty a štýly s obmedzeným rozsahom.
Islands fungujú aj prostredníctvom týchto spôsobov vykresľovania. Dynamický ostrov vykreslený pomocou bs_render_block(), bs_block() alebo značky bloku vráti rovnaký zástupný marker ako blok vykreslený z obsahu príspevku. Ak sa tento marker nachádza v odpovedi, vloží sa runtime pre frontend.
Štruktúrované kompozície a úplné dokumenty
Pri nástrojoch s dlhou životnosťou, ukážkach, exportoch a galériách komponentov použite verzovaný Blockstudio\Render API. Prijíma jedno vyhlásenie alebo usporiadaný zoznam a vykresľuje ho bez vypísania:
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'],
]);
Štandardizované normalizované vyhlásenie má štyri kľúče:
[
'name' => 'theme/card',
'attributes' => [],
'content' => '',
'children' => [],
]
data, inner, innerBlocks, root, layers a example slúžia na uľahčenie zadávania a pri normalizácii sa odstránia. Vnorené vyhlásenia sa vykresľujú rekurzívne cez ten istý proces Blockstudio.
Render::document() vracia schemaVersion, html, body, blocks,
assets, warnings a errors. Hodnota assets oddeľuje head,
footer, styles, scripts, modules, interactivity, ui a tailwind.
Zoznam blokov a zdroje obsahujú závislosti, na ktoré odkazujú vybrané šablóny,
ale vylučujú nesúvisiace zdroje a zdroje určené iba pre editor.
Kompletné dokumenty môžu nastaviť bodyClasses/bodyAttributes a voliteľne obaliť vykreslené telo pomocou contentElement, contentClasses a contentAttributes. Obal môže používať iba bezpečný názov prvku; vrátené body zostáva neobaleným vykresleným obsahom. Možnosti head a footer pripájajú dôveryhodné značky dokumentu na príslušné pozície a sú zahrnuté v uzávere vrátených assetov.
Ak chcete zostaviť dokument okolo už vykresleného HTML, zadajte známe názvy koreňových blokov:
$document = Render::document_from_html(
$rendered_html,
['theme/hero', 'theme/button'],
['title' => 'Homepage preview']
);
Pre serializovaný obsah bloku WordPress použite Render::content(). Ak príjemcovia vykresľujú viacero nezávislých dokumentov v jednej požiadavke, mali by medzi nimi zavolať Blockstudio\Batch_Render::reset(); Canvas::documents() to robí automaticky.
Vykresľovanie mimo stránky
Blockstudio vkladá komentár <!--blockstudio/namespace/slug--> pred každý blok, ktorý vykreslí. Na stránke v rozhraní pre návštevníkov vyrovnávacia pamäť prechádza tieto komentáre, zisťuje prítomné bloky, načítava ich zdroje a pred odoslaním odpovede komentáre odstraňuje.
Výstup, ktorý neprechádza cez túto vyrovnávaciu pamäť, si komentáre ponechá. Platí to pre odpovede REST, kanály, obslužné rutiny AJAX a HTML, ktoré uložíte alebo odošlete inam po použití do_blocks(), Render::content() alebo bs_render_block(). Na ich odstránenie použite bs_strip_render_markers():
$html = bs_strip_render_markers(do_blocks($post->post_content));
Funkcia odstráni komentáre registrovaných blokov Blockstudio a všetko ostatné ponechá nedotknuté vrátane ďalších komentárov HTML. Rozpoznáva rovnaké značky, aké odstraňuje vyrovnávacia pamäť stránky. Zavolajte ju po registrácii blokov (init alebo neskôr).
Neodstraňujte značky, ktoré sa ešte vypisujú na stránke spracovanej vyrovnávacou pamäťou. Stránka potrebuje komentáre, aby zistila, ktoré zdroje blokov má načítať, a Blockstudio ich sama odstráni na konci.
Odstránením komentárov sa nepridajú žiadne zdroje. Súbory blokov CSS a JavaScript vkladá iba vyrovnávacia pamäť stránky. Ak ich potrebuje aj konzument, použite bs_block_assets() alebo Render::document().
Kontrola blokov
Po registrácii blokov (na init alebo neskôr) použite bs_block_fields(), aby ste získali vyriešené definície polí bez čítania interných registrov:
$fields = bs_block_fields('theme/card');
if ($fields === null) {
// Unknown block, or not a Blockstudio block.
}
Vrátenou hodnotou je pole registrovaných definícií polí vrátane filtrov atribútov, rozšírených vlastných polí, prepisov a vnorených skupín, kariet a opakovačov. Blok Blockstudio bez polí vráti []. Výsledok je kópia: jeho zmenou sa registrovaný blok nezmení.
Ide o definície, nie o uložené hodnoty. Na validáciu uloženého značkovania použite bs_validate_block() namiesto udržiavania samostatného prechodu cez polia. Ak chcete opísať hodnoty, ktoré blok prijíma, použite bs_block_schema(). Atribúty spravované WordPress zostávajú oddelené.
Polia pridané pomocou rozšírení nie sú súčasťou bs_block_fields(). Na ich získanie použite bs_block_extension_fields(). Rozšírenia páruje podľa názvu bloku, takže funguje aj pre základné bloky a bloky tretích strán:
$fields = array_merge(
bs_block_fields('core/paragraph') ?? [],
bs_block_extension_fields('core/paragraph')
);
Vrátená hodnota obsahuje definície polí každého zodpovedajúceho rozšírenia v poradí registrácie rozšírení a s rovnakou štruktúrou ako bs_block_fields(). Ak bloku nezodpovedá žiadne rozšírenie, vráti sa []. Hodnoty rozšírení sa ukladajú do toho istého objektu attrs.blockstudio.attributes ako vlastné hodnoty polí bloku, takže všetky ID zdieľajú jeden menný priestor. Ak dve rozšírenia definujú rovnaké ID, vrátia sa obe definície a upravujú tú istú hodnotu; pri vykresľovaní sa uplatní definícia rozšírenia zaregistrovaného neskôr.
Ak chcete načítať hodnoty uloženého bloku tak, ako ich dostáva jeho šablóna, použite bs_block_values().
Na kontrolu zistených CSS a JavaScript bloku použite bs_block_assets(). Ak potrebujete úplný dokument náhľadu vrátane vnorených blokov a zdieľaných závislostí za behu, použite Render::document(), ako je uvedené vyššie.
Overovanie uložených hodnôt
Po registrácii blokov (init alebo neskôr) použite bs_validate_block() na kontrolu atribútov programovo vytvorených alebo importovaných blokov pred ich uložením:
$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.
}
Odovzdajte celé pole attrs, nielen blockstudio.attributes. Vykreslenie Blockstudio prijíma deklarované polia aj na najvyššej úrovni a vnorené hodnoty majú prednosť, ak sú zadané obe. Rozšírenia základných blokov a blokov tretích strán čítajú iba blockstudio.attributes. Prázdny blok Blockstudio je spravovaný a vracia [], nie null.
Overovanie je explicitné a iba na čítanie. Nevyrenderuje šablóny, nemení hodnoty, neukladá príspevky, nevyhľadáva médiá ani nespúšťa spätné volania na doplnenie údajov. Nespúšťa sa automaticky pri ukladaní, synchronizácii stránok ani vykresľovaní. Nie je to sanitizér, kontrola oprávnení ani overenie, či príloha existuje.
Každý nález obsahuje tieto stabilné kľúče:
[
'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ástrojoch používajte code, nie preložené message. source je block alebo
extension. Cesty používajú úložné kľúče a indexy riadkov opakovača alebo výberov
číslované od nuly, bez úvodnej lomky. Doslovné ~ a / v kľúči sa escapujú ako ~0 a
~1. Skupina najvyššej úrovne pridáva predponu svojim potomkom (cta_title); anonymné skupiny
a karty nepridávajú žiadnu úroveň. Skupiny s ID vo vnútri inej skupiny alebo opakovača
zostavovač nepodporuje, preto sa ich kľúče neprijímajú. Polia správ nemajú uloženú hodnotu. Pole súborov povoľuje svoj sprievodný údaj <id>__size.
V koreňovej úrovni bloku Blockstudio sa účtovné kľúče a globálne atribúty HTML
posielané vykreslenému prvku nepovažujú za neznáme polia. To však nepovoľuje ľubovoľné kľúče v riadkoch opakovača ani rozšírenia základných blokov.
| Kód | Význam | expected |
|---|---|---|
unknown_field |
Žiadne zachované pole nedefinuje tento úložný kľúč. | Známe úložné kľúče. |
unknown_option |
Výber nepatrí medzi známe možnosti. | Povolené hodnoty možností. |
wrong_type |
Uložená štruktúra nie je podporovaná týmto poľom. | Očakávaná skupina alebo typ úložiska. |
too_few_rows, too_many_rows |
Prítomný opakovač prekračuje svoj limit min alebo max. |
Hranica počtu riadkov. |
definition_conflict |
Použiteľné definície jedného kľúča vyžadujú rôzne štruktúry úložiska. | Zdroj a typ poľa každej definície. |
shadowed_value |
Vnorená hodnota prepisuje inú hodnotu poľa najvyššej úrovne. | Víťazná vnorená hodnota. |
extension_top_level |
Šablóna dokáže čítať hodnotu najvyššej úrovne, ale väzby rozšírení nie. | Požadovaná cesta pod blockstudio/attributes. |
unknown_attribute |
Kľúč najvyššej úrovne bloku Blockstudio sa pri vykresľovaní nečíta a zahodí sa. | Registrované názvy atribútov, polia rozšírení a blockstudio. |
missing_container |
attributes, disabled, name alebo editor je uložené na najvyššej úrovni a chýba blockstudio. |
Požadovaná cesta pod blockstudio. |
invalid_container |
blockstudio alebo blockstudio.attributes nie je objekt. |
object. |
Správa pri náleze unknown_field uvádza najbližší kľúč úložiska na rovnakej úrovni, ak sa od neho líši najviac o tri úpravy; takto funguje pravidlo pre neznáme nastavenia: This storage key is not declared by the block or its extensions. Did you mean "title"?
expected naďalej uvádza všetky známe kľúče.
Pri porovnávaní sa ignoruje veľkosť písmen a zohľadňujú sa iba kľúče úložiska z daného kontajnera. Správy sú preložené; integrácie by mali používať code, path a expected namiesto analyzovania textu správy.
Kľúč najvyššej úrovne bloku Blockstudio sa pred spustením šablóny zahodí, ak nejde o registrovaný atribút
(jeho polia, atribúty, ktoré WordPress pridáva pre supports, lock a
metadata), pole zodpovedajúceho rozšírenia, blockstudio, účtovný kľúč ani preposielaný atribút HTML. Takýto kľúč, napríklad nesprávne zadané ID poľa alebo objekt hodnôt uložený
bez obalu blockstudio, vytvorí nález, pretože blok sa vykreslí bez danej hodnoty. Bloky, ktoré obsahujú iba polia rozšírenia, sa nekontrolujú na kľúče najvyššej úrovne.
Prijímané štruktúry zodpovedajú vykresľovaniu: viacnásobné výbery a začiarkavacie políčka môžu
obsahovať zoznam, objekt jednej možnosti alebo importovanú skalárnu hodnotu vrátane číselnej nuly. Číselné reťazce sa prijímajú pre čísla. Súbory môžu obsahovať ID príloh, objekty ID, zoznamy alebo reťazcové odkazy. Hodnoty odkazov a ikon musia byť objekty; vlastné typy polí používajú svoj registrovaný typ atribútu.
Pole attributes obsahuje zoznam dvojíc s neprázdnym názvom attribute
a skalárnou hodnotou value; voliteľné metadáta, ako napríklad data.media, sa zachovajú.
WordPress pred vykreslením overuje registrované atribúty najvyššej úrovne, takže môže odmietnuť štruktúru prijatú vnútri blockstudio.attributes. Napríklad hodnota prepínača "a" funguje vo vnorenom objekte, ale na najvyššej úrovni sa zahodí,
pretože jej registrovaný typ je object. Takáto hodnota vytvorí nález wrong_type.
Pre rovnakú štruktúru úložiska, akú zapisuje editor, použite vnorený objekt.
Chýbajúce polia nie sú povinné. Prázdne vnorené hodnoty (null, false, '',
[]) a vypnuté polia nevytvárajú chyby hodnôt. Prázdny
opakovač sa stále kontroluje podľa min; neprítomný alebo vypnutý opakovač nie.
Prázdna hodnota najvyššej úrovne sa nahlási, ak ju WordPress zahodí a obnoví
neprázdnu predvolenú hodnotu. Rovnaká hodnota vo vnorenom objekte ju môže vymazať.
Konflikty definícií sa nahlasujú, aj keď kľúč nemá uloženú hodnotu.
Statické možnosti a možnosti načítané pri registrácii sa kontrolujú bez opätovného volania funkcie načítania. Vzdialené možnosti fetch a argumenty funkcie načítania obsahujúce {attributes.*} sa preskočia. Farby a prechody môžu mať vlastné hodnoty, pokiaľ nie je nastavené disableCustomColors alebo disableCustomGradients.
Kontrolujú sa uložené hodnoty, nie default, fallback ani pravidlá overovania editora.
Zodpovedajúce polia rozšírení sa zahrnú pre každý blok, na ktorý sa vzťahujú. Neskoršie
definície majú v bloku alebo jeho rozšíreniach v koreňovej úrovni prednosť, rovnako ako pri vykresľovaní.
Vlastné pole bloku a pole rozšírenia zostávajú samostatnými definíciami
toho istého kľúča a uplatňujú sa obe. V riadkoch opakovača vykresľovač v každom zdroji číta
prvé pole so zodpovedajúcim ID, takže sa uplatnia jeho možnosti a limity.
Duplicitné definície sa zachovajú na diagnostiku konfliktov:
nekompatibilné štruktúry úložiska vytvoria definition_conflict, aj keď sa neskoršia duplicita pri vykresľovaní nenačíta.
Funkcia kontroluje jeden blok. Pri overovaní dokumentu prejdite innerBlocks;
synchronizované vzory a iné referencie sa nerozbaľujú automaticky. Príkaz
wp bs blocks validate prechádza
bloky jedného alebo viacerých príspevkov a nahlasuje ich cesty k blokom.
Weby s vlastným resolverom pri vykresľovaní môžu upraviť nálezy bez zmeny uložených údajov:
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 vráťte zoznam nálezov; vrátením [] sa blok prijme. Tento
filter sa spúšťa iba pre spravované bloky, nikdy pre výsledok null.
Opis uložených hodnôt
Po registrácii bloku (init alebo novšej) použite bs_block_schema() na opis hodnôt, ktoré blok ukladá, napríklad na generovanie značkovania bloku v nástroji alebo integrácii s umelou inteligenciou, prípadne na kontrolu vstupu v trase REST:
$schema = bs_block_schema('theme/card');
if ($schema === null) {
// No Blockstudio fields or matching extensions apply.
}
Výsledkom je schéma JSON objektu uloženého v attrs.blockstudio.attributes. Zahŕňa polia bloku aj polia zodpovedajúcich rozšírení vrátane kľúčov úložiska, ktoré používa validácia: skupina na najvyššej úrovni pridáva deťom prefix, anonymné skupiny a karty nepridávajú úroveň a pole súboru pridáva sprievodnú položku <id>__size. Opakovače sú zoznamy objektov riadkov s minItems a maxItems z min a max. additionalProperties je false v koreňovom úložisku polí aj v riadkoch opakovača. Polia s hodnotou objektu, napríklad odkazy a vlastné objekty, môžu mať vlastné metadáta. Blok bez polí nemá properties, takže vyhovuje iba prázdny objekt.
Každé pole je opísané v kanonickom tvare, ktorý prijíma bs_validate_block():
| Pole | Schéma |
|---|---|
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block |
Reťazec. |
number, range |
Číslo s minimum a maximum z min a max. |
toggle |
Logická hodnota. |
select, radio, checkbox |
Hodnota možnosti alebo zoznam hodnôt možností pre checkbox a multiple s enum. |
color, gradient |
Reťazec s enum, keď je nastavené disableCustomColors alebo disableCustomGradients. |
token |
Zoznam reťazcov. |
files |
Nezáporné celé číslo ID prílohy alebo zoznam ID s multiple. |
link |
Objekt s url, title a opensInNewTab; url je povinné. |
icon |
Objekt s set, subSet a icon; set a icon sú povinné. |
attributes |
Zoznam objektov s neprázdnym attribute a skalárnym value. |
repeater |
Zoznam objektov riadkov. |
| Vlastné typy polí | Ich registrovaný typ atribútu. |
enum uvádza možnosti, ktoré validácia kontroluje: statické možnosti a možnosti naplnenia vyriešené už pri registrácii. Vzdialené možnosti fetch a argumenty naplnenia obsahujúce {attributes.*} nemajú enum. Kľúč s definíciami rôznych tvarov úložiska sa vynechá, pretože validácia hlási každú hodnotu uloženú pod ním. Ak blokové pole a pole rozšírenia zdieľajú kľúč, enum uvádza hodnoty, ktoré prijímajú obe. Zdieľané opakovače spájajú svoje podradené polia a uplatňujú prísnejšie hranice počtu riadkov z oboch definícií. V riadkoch opakovača sa použije prvé pole so zodpovedajúcim ID v každom zdroji, rovnako ako pri vykresľovaní. Výslovne pomenované pole <id>__size má prednosť pred automaticky pridanou sprievodnou položkou veľkosti súboru.
Ak uzavreté pole nemá dostupné možnosti alebo sa dve použiteľné množiny možností neprekrývajú, jeho kanonickou hodnotou null je pri jednom výbere alebo prázdny zoznam pri viacerých výberoch. Prázdny zoznam možností nezmení pole na neobmedzené. Vzdialené možnosti a možnosti závislé od atribútov zostávajú otvorené.
Hodnota label poľa sa zmení na title, hodnota help sa zmení na description a default sa zachová ako anotácia. Vlastné title schémy je názov bloku. Polia nikdy nie sú povinné a podmienená logika nie je súčasťou schémy.
Obmedzenia používajú iba kľúčové slová, ktoré kontroluje rest_validate_value_from_schema(), takže schému možno použiť priamo ako vstupnú schému trasy REST alebo schopnosti:
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
$result = rest_validate_value_from_schema($values, $schema);
}
Schéma opisuje jeden formulár pre každé pole; validácia prijíma aj importované tvary, ako sú objekty možností, číselné reťazce a objekty ID. Nenahrádza bs_validate_block(): konflikty definícií sú problémy konfigurácie a môžu stále viesť k nálezom, aj keď je konfliktný kľúč vynechaný. Filtre validácie môžu tiež vynucovať pravidlá špecifické pre daný web. Pomocou bs_validate_block() môžete kontrolovať uložený obsah. Weby s vlastným resolverom pri vykresľovaní môžu prispôsobiť schému pomocou filtra blockstudio/blocks/attributes/schema.
Funkcie PHP
Bez údajov
V najjednoduchšej podobe funkcia prijíma jednu hodnotu, ktorou je ID bloku, ktorý sa má vykresliť na stránke.
bs_render_block('blockstudio/cta');
S údajmi
Ak chcete blok vykresliť s vlastnými údajmi, namiesto jednej hodnoty treba ako prvý parameter použiť pole. Hodnota v kľúči data sa odovzdá do premennej $attributes a $a v šablóne bloku.
bs_render_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
]);
Vnáranie
Bloky možno vnárať do seba pomocou funkcie bs_block v kombinácii s výkonnou premennou $content v šablónach blokov.
<div>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content; ?>
</div>
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čidla sa vykreslí namiesto premennej $content v šablóne bloku.
Vložené bloky vykreslené pomocou bs_render_block() alebo bs_block() vždy vypíšu hodnotu HTML vyriešenú pre frontend, aj keď nadradený blok práve vykresľuje ukážku v editore. Pseudokomponenty šablóny, ako sú <RichText /> a <InnerBlocks />, sa vyriešia ešte pred vrátením vloženého bloku.
Viacero slotov
Viacero obsahových slotov možno vytvoriť aj tak, že premennú $content zmeníte na asociatívne pole a v rámci funkcie bs_block zavoláte príslušné kľúče.
<div>
<?php echo $content['beforeContent']; ?>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content['afterContent']; ?>
</div>
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 blokov
Vložte ľubovoľný blok pomocou syntaxe značiek HTML. Podporované sú dva formáty:
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
Oba vykreslia ten istý blok. Syntax <bs:> mení pomlčku na oddeľovač menného priestoru (acme-hero sa zmení na acme/hero). Pomlčky sa skúšajú zľava doprava a vyhrá prvý zaregistrovaný kandidát, takže sa vyriešia aj menné priestory obsahujúce pomlčky: <bs:acme-ui-button> skúsi acme/ui-button a potom acme-ui/button. Syntax <block> používa celý názov bloku ako atribút name.
Fungujú bloky Blockstudio aj základné bloky WordPress. Bloky Blockstudio sa vykresľujú cez celý proces spracovania (šablóny, Tailwind, prostriedky). Základné bloky sa vykresľujú pomocou systému na vykresľovanie blokov v WordPress prostredníctvom vstavaných vykresľovačov blokov.
Ako to funguje
Značky blokov sa správajú odlišne podľa toho, kde sa nachádzajú:
V šablónach blokov a obsahu príspevkov sa značky za behu nahrádzajú vykresleným HTML. Výstupom je konečné označenie odkazovaného bloku vložené priamo na stránke. V editore pre ne neexistuje blok WordPress. Slúžia výhradne na vykresľovanie.
V Stránkach, vzoroch a šablónach webu sa značky pred synchronizáciou zdrojového súboru alebo registráciou v WordPress konvertujú na natívne bloky WordPress. To znamená, že bloky sa zobrazia v editore, možno ich upravovať tam, kde to cieľ podporuje, a prejdú celým životným cyklom blokov v WordPress. Syntax značiek je skrátený zápis na definovanie obsahu bloku v súboroch šablón.
Tento rozdiel je dôležitý: značky blokov v šablónach vytvárajú výstup, zatiaľ čo značky blokov na stránkach, vo vzoroch a v šablónach webu vytvárajú natívne bloky.
V šablónach blokov
Značky blokov sa vykresľujú automaticky v šablónach Twig a PHP. Nie je potrebné žiadne nastavenie. Platí to aj pre syntaxe <bs:> a <block>, ako aj pre všetky registrované značky s prefixom a aliasové značky, takže ich šablóna môže vypísať priamo namiesto volania bs_render_block(). Výstup sa vykreslí HTML priamo vo výstupe šablóny bloku:
<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 príspevkov
Vykresľovanie na úrovni stránky (obsah príspevkov, oblasti widgetov) je voliteľné:
{
"blockTags": {
"enabled": true
}
}
Alebo pomocou filtra:
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');
Syntax
Samouzavieracie značky:
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />
Párové značky s vnútorným obsahom:
<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>
Ľubovoľne kombinujte oba zápisy. Obe syntaxe možno vnárať do seba:
<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átené zápisy predpôn
Značky blokov môžu používať aj skrátené predpony špecifické pre projekt. Zaregistrujte predponu s jedným alebo viacerými mennými priestormi a Blockstudio rozlíši <prefix-slug> na prvý zaregistrovaný blok v poradí menných priestorov:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components', 'bsui'];
return $prefixes;
});
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />
V uvedenom príklade sa <theme-card> rozlíši na theme-components/card, <theme-button> prejde na bsui/button, ak theme-components/button nie je zaregistrované, a <theme-ui-feature-matrix> sa rozlíši na theme-components/ui-feature-matrix.
Predpony možno aj skladať. Ak sa značka s predponou nevyrieši priamo a zvyšný slug je sám zaregistrovanou značkou s predponou, rozlíšenie sa rekurzívne opakuje, takže predpona značky môže nadväzovať na predponu menného priestoru:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components'];
$prefixes['ui'] = ['bsui'];
return $prefixes;
});
<theme-ui-input />
<theme-ui-input> nemá blok theme-components/ui-input, preto sa skúsi predpona ui a rozlíši sa na bsui/input. Priame zhody majú vždy prednosť pred vnoreným rozlíšením a pravidlá povolenia a zákazu sa uplatňujú na konečný rozlíšený blok.
Predpony možno nastaviť aj v blockstudio.json:
{
"blockTags": {
"prefixes": {
"theme": ["theme-components", "bsui"]
}
}
}
Predpony môžu obsahovať iba malé písmená alebo číslice, musia sa začínať písmenom a nesmú obsahovať pomlčky. Explicitné aliasy z blockstudio/block_tags/tag_aliases majú prednosť pred rozlíšením predpôn. Neznáme značky s predponou zostanú nezmenené.
Značky s predponou a aliasové značky sú naďalej podporované ako pohodlné možnosti na tvorbu obsahu. Kanonický, prenositeľný zápis je vždy <bs:namespace-slug>, pretože zaznamenáva skutočný názov bloku bez závislosti od filtrov projektu:
<bs:theme-components-card />
<bs:bsui-input />
V Blockstudio príkladoch, generovanej diagnostike a programovom výstupe sa používa tento kanonický zápis. Projekty, ktoré chcú odstrániť staršiu skrátenú podobu, môžu použiť samostatnú migráciu značiek s režimom nanečisto ako prvým krokom: kanonická migrácia značiek, ktorá nevyžaduje spustenie WordPress.
Základné bloky
Možno použiť každý blok s registrovaným vykresľovačom:
<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>
Alebo pomocou syntaxe <block>:
<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>
Zoznamy povolených a zakázaných blokov
Určite, ktoré bloky možno vykresliť pomocou značiek:
{
"blockTags": {
"enabled": true,
"allow": ["mytheme/*", "core/*"],
"deny": ["mytheme/internal-*"]
}
}
allow obmedzuje výber iba na zodpovedajúce vzory. deny vylučuje zodpovedajúce vzory a má prednosť. Obe možnosti podporujú zástupné znaky * pomocou fnmatch(). Uplatňujú sa na obe syntaxe aj na vykresľovanie na úrovni šablón aj stránok.
Filtre: blockstudio/block_tags/allow a blockstudio/block_tags/deny.
Odovzdávanie HTML
Atribúty s predponou data- sa odovzdávajú koreňovému prvku vykresleného bloku. Odovzdávajú sa aj atribúty s predponou html-, pričom sa z nich predpona odstráni. Funguje to s oboma syntaxami. Odovzdaný atribút nahrádza existujúcu hodnotu koreňového prvku namiesto toho, aby sa s ňou zlúčil, takže html-class nahrádza vlastné triedy bloku.
Blok Blockstudio pridáva na svoj koreňový prvok aj globálne atribúty, ktoré nedefinuje ako polia: id, style, role, title, lang, dir, hidden, tabindex a každý atribút aria-*. Deklarované pole má vždy prednosť, takže blok s poľom title namiesto toho dostane hodnotu z $a['title']. Odovzdané štýly prechádzajú cez safecss_filter_attr(), filter WordPress sa uplatňuje na atribúty štýlu v obsahu príspevkov a odovzdané štýly sa pripájajú k štýlu, ktorý už nastavuje šablóna.
Hodnoty atribútov sú HTML, takže entity sa dekódujú raz pri parsovaní značky: title="Tom & Jerry" sa do šablóny dostane ako Tom & Jerry a pri výstupe sa znova escapuje. Úvodzovky môžu obsahovať aj >, napríklad varianty Tailwind a selektory animácií, a to v samouzavieracích aj párových značkách.
Každý iný atribút, ktorý blok nedefinuje, vrátane class, sa do HTML nikdy nedostane. Keď je zapnuté WP_DEBUG, Blockstudio hlási každý takýto atribút raz za požiadavku prostredníctvom _doing_it_wrong(). Deklarujte preň pole alebo ho zapíšte ako atribút data-, aria- alebo 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é vykresľovače
Zaregistrujte vlastné vykresľovače blokov pre ďalšie typy blokov. Vykresľovače prijímajú pole atribútov a reťazec vnútorného obsahu a vracajú pole bloku WordPress:
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);
Ak kontajnerové bloky potrebujú parsovať vnútorný obsah na podriadené bloky, pridajte druhú položku do toho istého filtra:
$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 sa uplatňuje na značky blokov aj na vlastné bloky vybrané cez blockstudio/parser/element_mapping. Toto je vhodný hook, keď blok projektu mapovaný na prvok potrebuje presunúť vnútorný text do poľa Blockstudio alebo vytvoriť vlastné pole bloku.
blockstudio/block_tags/renderers a blockstudio/parser/renderers dostávajú rovnaký register aj tvar callbacku. Z dôvodu kompatibility a na konečné prepísania na úrovni parsera zostávajú dostupné. Filtre sa spúšťajú v tomto poradí:
blockstudio/block_tags/buildersblockstudio/block_tags/renderersblockstudio/parser/renderers
Neskorší filter môže nahradiť vykresľovač zaregistrovaný skorším filtrom.
Programové použitie
Použite vykresľovanie značiek na ľubovoľný reťazec z PHP:
$html = apply_filters('blockstudio/block_tags/render', $content);
Komponenty
Značky blokov sa dobre dopĺňajú s komponentmi. Komponenty sú bloky, ktoré sa vykresľujú iba programovo a nikdy sa nezobrazujú v editore.
<bs:mytheme-card title="My Card" description="Card content." />
Parser
Značky blokov spracúva ľahký skener reťazcov, ktorý nahrádza DOMDocument. Parser spracúva syntaxe <bs:> aj <block>, vnorené značky s rovnakým názvom pomocou sledovania hĺbky, hodnoty atribútov v úvodzovkách a rekurzívne kontajnerové bloky. Je vytvorený špeciálne na tento prípad použitia, v benchmarkoch je rýchlejší než DOMDocument aj WordPress WP_HTML_Tag_Processor a vyhýba sa známym problémom DOMDocumentu s odstraňovaním predpôn menných priestorov a prevodom názvov atribútov na malé písmená.
V Stránkach, vzoroch a šablónach webu ten istý parser spracúva aj surové prvky HTML (<p>, <div>, <h1> atď.) a mapuje ich na zodpovedajúce základné bloky WordPress.
Keď mapovanie prvku priradí <p> k zaregistrovanému nezákladnému bloku Blockstudio, ktorý deklaruje atribút richtext content, vnútorný obsah HTML sa automaticky presmeruje do tohto atribútu content vrátane vložených značiek, ako sú code a img, ktoré sú mapované na úrovni prvkov. Odsek, ktorého jediným potomkom je obrázok, sa zmení na blok, na ktorý mapuje <img>. Vnorené značky blokov alebo prvky HTML na úrovni bloku sa naďalej spracúvajú štandardným parsovaním vnútorných blokov. <block name="core/shortcode"> zachová text krátkeho kódu ako obsah bloku.