Treci la conținut

Randare programatică

Pe măsură ce Gutenberg devine instrumentul principal pentru crearea de site-uri ușor de editat pentru clienți, este firesc să creați toate zonele necesare ale site-ului ca blocuri. Această abordare va satisface nevoile majorității, însă utilizatorii avansați și cazurile de utilizare specifice pot necesita folosirea blocurilor existente în afara editorului.

Blockstudio oferă două metode de randare programatică a blocurilor:

  • Funcții PHP: bs_render_block și bs_block pentru randarea din cod PHP
  • Etichete HTML: etichete <bs:block-name> care sunt înlocuite cu rezultatul blocului oriunde pe pagină

Sunt acceptate toate funcționalitățile specifice Blockstudio, precum stilurile inline, scripturile și stilurile cu domeniu de aplicare limitat.

Și insulele funcționează prin aceste căi de randare. O insulă dinamică redată cu bs_render_block(), bs_block() sau o etichetă de bloc returnează același marcaj de substituent ca un bloc redat din conținutul unei postări, iar mediul de execuție frontend este injectat când marcajul respectiv este prezent în răspuns.

Compoziții structurate și documente complete

Pentru instrumente, previzualizări, exporturi și galerii de componente folosite pe termen lung, utilizați Blockstudio\Render API cu versiune. Acceptă o declarație sau o listă ordonată și redă rezultatul fără echo:

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

Declarația normalizată canonică are patru chei:

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

data, inner, innerBlocks, root, layers și example sunt valori opționale de intrare și sunt eliminate în timpul normalizării. Declarațiile imbricate se randează recursiv prin aceeași conductă Blockstudio.

Render::document() returnează schemaVersion, html, body, blocks, assets, warnings și errors. Valoarea assets separă head, footer, styles, scripts, modules, interactivity, ui și tailwind. Lista de blocuri și resursele includ dependențele referite de șabloanele selectate, dar exclud resursele fără legătură și pe cele disponibile doar în editor.

Documentele complete pot seta bodyClasses/bodyAttributes și, opțional, pot înveli corpul redat cu contentElement, contentClasses și contentAttributes. Învelișul este limitat la un nume de element sigur; valoarea body returnată rămâne conținutul redat fără înveliș. Opțiunile head și footer adaugă marcajul de document de încredere în pozițiile respective și sunt incluse în setul de resurse returnat.

Pentru a asambla un document în jurul valorii HTML deja randate, specificați numele cunoscute ale blocurilor rădăcină:

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

Folosiți Render::content() pentru conținutul blocului WordPress serializat. Consumatorii care redau mai multe documente independente într-o singură solicitare ar trebui să apeleze Blockstudio\Batch_Render::reset() între ele; Canvas::documents() face acest lucru automat.

Randarea în afara paginii

Blockstudio adaugă un comentariu <!--blockstudio/namespace/slug--> înaintea fiecărui bloc randat. Pe o pagină din interfața publică, bufferul citește aceste comentarii pentru a vedea ce blocuri sunt prezente, le încarcă resursele și elimină comentariile înainte de a trimite răspunsul.

Ieșirea care nu trece prin acel buffer păstrează comentariile. Acest lucru se aplică răspunsurilor REST, fluxurilor, handlerelor AJAX și HTML pe care le stocați sau le trimiteți în altă parte după do_blocks(), Render::content() sau bs_render_block(). Folosiți bs_strip_render_markers() pentru a le elimina:

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

Funcția elimină comentariile blocurilor Blockstudio înregistrate și lasă tot restul neatins, inclusiv alte comentarii HTML. Aceasta identifică aceiași marcatori pe care îi elimină bufferul paginii. Apelați-o după înregistrarea blocurilor (init sau ulterior).

Nu eliminați marcajele care sunt încă afișate pe o pagină din interfața publică trecută prin buffer. Pagina are nevoie de comentarii pentru a ști ce resurse de blocuri să încarce, iar Blockstudio le elimină la final.

Eliminarea comentariilor nu adaugă resurse. Fișierele blocurilor CSS și JavaScript sunt injectate numai de bufferul paginii. Folosiți bs_block_assets() sau Render::document() când și consumatorul are nevoie de ele.

Inspectarea blocurilor

Folosiți bs_block_fields() după înregistrarea blocurilor (pe init sau ulterior) pentru a obține definițiile rezolvate ale câmpurilor fără a citi registre interne:

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

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

Valoarea returnată este matricea definițiilor câmpurilor înregistrate, inclusiv filtrele atributelor, câmpurile personalizate extinse, suprascrierile și grupurile, filele și repetoarele imbricate. Un bloc Blockstudio fără câmpuri returnează []. Rezultatul este o copie: modificarea lui nu schimbă blocul înregistrat.

Acestea sunt definiții, nu valori salvate. Pentru a valida marcajul salvat, folosiți bs_validate_block() în loc să întrețineți un vizitator separat al câmpurilor. Pentru a descrie valorile acceptate de un bloc, folosiți bs_block_schema(). Atributele deținute de WordPress rămân separate.

Câmpurile adăugate de extensii nu fac parte din bs_block_fields(). Folosiți bs_block_extension_fields() pentru a le obține. Funcția identifică extensiile după numele blocului, deci funcționează și pentru blocurile de bază și cele terțe:

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

Valoarea returnată enumeră definițiile câmpurilor din fiecare extensie care corespunde, în ordinea înregistrării extensiilor, cu aceeași structură ca bs_block_fields(). Pentru un bloc fără extensii corespunzătoare se returnează []. Valorile extensiilor sunt salvate în același obiect attrs.blockstudio.attributes ca valorile propriilor câmpuri ale blocului, astfel încât toate ID-urile folosesc același spațiu de nume. Dacă două extensii definesc același ID, sunt returnate ambele definiții și acestea editează aceeași valoare; la randare se aplică definiția extensiei înregistrate mai târziu.

Pentru a citi valorile unui bloc salvat așa cum le primește șablonul său, folosiți bs_block_values().

Folosiți bs_block_assets() pentru a inspecta CSS și JavaScript descoperite pentru bloc. Pentru un document complet de previzualizare, care include blocurile imbricate și dependențele partajate la execuție, folosiți Render::document(), așa cum este descris mai sus.

Validarea valorilor stocate

Folosiți bs_validate_block() după înregistrarea blocurilor (init sau ulterior) pentru a verifica atributele blocurilor generate programatic sau importate înainte de a le salva:

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

Transmiteți matricea completă attrs, nu doar blockstudio.attributes. O randare Blockstudio acceptă și câmpurile declarate la nivelul superior, iar valorile imbricate au prioritate când sunt furnizate ambele. Extensiile blocurilor de bază și ale celor terțe citesc doar blockstudio.attributes. Un bloc Blockstudio gol este gestionat și returnează [], nu null.

Validarea este explicită și doar pentru citire. Nu randează șabloane, nu modifică valori, nu salvează articole, nu interoghează fișiere media și nu execută funcții de populare. Nu rulează automat la salvare, la sincronizarea paginilor sau la randare. Nu este un mecanism de sanitizare, o verificare a autorizării sau o verificare a existenței unui atașament.

Fiecare constatare conține următoarele chei stabile:

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

Folosiți code, nu message tradus, în instrumentele de dezvoltare. source este block sau extension. Căile folosesc chei de stocare și indici bazați pe zero pentru rândurile repetitoare sau selecții, fără bară oblică inițială. Caracterele literale ~ și / dintr-o cheie sunt escape-uite ca ~0 și ~1. Un grup de nivel superior adaugă un prefix copiilor săi (cta_title); grupurile anonime și filele nu adaugă niciun nivel. Builderul nu acceptă grupuri cu un ID în interiorul altui grup sau al unui repetitor, așadar nici cheile acestora nu sunt acceptate. Câmpurile de mesaj nu au nicio valoare stocată. Un câmp de fișiere permite elementul asociat <id>__size. La rădăcina unui bloc Blockstudio, cheile de evidență și atributele globale HTML transmise elementului redat nu sunt câmpuri necunoscute. Aceasta nu permite chei arbitrare în rândurile repetitoare sau extinderi ale blocurilor de bază.

Cod Semnificație expected
unknown_field Niciun câmp păstrat nu declară această cheie de stocare. Chei de stocare cunoscute.
unknown_option O selecție nu se află printre opțiunile cunoscute. Valori de opțiune permise.
wrong_type Structura valorii stocate nu este acceptată de câmp. Familia sau tipul de stocare așteptat.
too_few_rows, too_many_rows Un repetitor prezent depășește limita sa min sau max. Limita rândurilor.
definition_conflict Definițiile aplicabile pentru o cheie necesită structuri de stocare diferite. Sursa și tipul câmpului pentru fiecare definiție.
shadowed_value O valoare imbricată suprascrie valoarea unui câmp diferit de la nivelul superior. Valoarea imbricată care are prioritate.
extension_top_level Șablonul poate citi o valoare de nivel superior, dar legăturile extensiilor nu. Calea necesară sub blockstudio/attributes.
unknown_attribute O cheie de nivel superior a unui bloc Blockstudio nu este citită de calea de redare și este eliminată. Numele atributelor înregistrate, câmpurile extensiilor și blockstudio.
missing_container attributes, disabled, name sau editor este stocat la nivelul superior, iar blockstudio lipsește. Calea necesară sub blockstudio.
invalid_container blockstudio sau blockstudio.attributes nu este un obiect. object.

Mesajul unei constatări unknown_field indică cheia de stocare cea mai apropiată, de la același nivel, dacă diferența este de cel mult trei editări, conform regulii folosite pentru setările necunoscute: This storage key is not declared by the block or its extensions. Did you mean "title"? expected enumeră în continuare toate cheile cunoscute. Potrivirea ignoră diferențele dintre majuscule și minuscule și ia în considerare doar cheile de stocare din containerul respectiv. Mesajele sunt traduse; integrările ar trebui să folosească code, path și expected în loc să analizeze textul mesajului.

O cheie de nivel superior a unui bloc Blockstudio, care nu este un atribut înregistrat (câmpurile sale, atributele pe care WordPress le adaugă pentru supports, lock și metadata), un câmp al unei extensii corespunzătoare, blockstudio, o cheie de evidență sau un atribut HTML transmis, este eliminată înainte de rularea șablonului. O astfel de cheie, de exemplu un ID de câmp scris greșit sau un obiect de valori stocat fără învelișul blockstudio, generează o constatare, deoarece blocul este redat fără acea valoare. Blocurile care conțin doar câmpuri de extensii nu sunt verificate pentru chei de nivel superior.

Structurile acceptate corespund redării: selecțiile multiple și casetele de selectare pot conține o listă, un obiect cu o singură opțiune sau o valoare scalară importată, inclusiv zero numeric. Pentru numere sunt acceptate șirurile numerice. Fișierele pot conține ID-uri de atașamente, obiecte ID, liste sau referințe sub formă de șir. Valorile pentru linkuri și pictograme trebuie să fie obiecte; tipurile de câmpuri personalizate folosesc tipul de atribut înregistrat. Un câmp attributes conține o listă de perechi cu un nume attribute nevid și o valoare scalară value; metadatele opționale, precum data.media, sunt păstrate.

WordPress validează atributele de nivel superior înregistrate înainte de redare, ceea ce poate respinge o structură acceptată în blockstudio.attributes. De exemplu, o valoare radio "a" funcționează în obiectul imbricat, dar este eliminată la nivelul superior, unde tipul său înregistrat este object. O astfel de valoare generează wrong_type. Folosiți obiectul imbricat pentru aceeași structură de stocare pe care o scrie editorul.

Câmpurile lipsă nu sunt obligatorii. Valorile imbricate goale (null, false, '', []) și câmpurile dezactivate nu generează erori de valoare. Un repetitor explicit gol este totuși verificat în raport cu min; un repetitor absent sau dezactivat nu este verificat. O valoare goală de nivel superior este semnalată dacă WordPress o elimină și restabilește în schimb o valoare implicită nevidă. Aceeași valoare din obiectul imbricat o poate goli. Conflictele dintre definiții sunt semnalate chiar și atunci când cheia nu are o valoare salvată.

Opțiunile statice și opțiunile populate deja rezolvate la înregistrare sunt verificate fără a invoca din nou popularea. Opțiunile fetch la distanță și argumentele de populare care conțin {attributes.*} sunt omise. Valorile pentru culori și degradeuri pot fi personalizate dacă nu este setat disableCustomColors sau disableCustomGradients. Această verificare vizează valorile stocate, nu default, fallback sau regulile de validare ale editorului.

Câmpurile extensiilor corespunzătoare sunt incluse pentru fiecare bloc vizat. Definițiile ulterioare au prioritate în bloc sau în extensiile sale, la rădăcină, ca la redare. Un câmp al blocului și un câmp al unei extensii rămân definiții separate pentru aceeași cheie și ambele se aplică. În rândurile repetitoare, redarea citește primul câmp cu un ID corespunzător din fiecare sursă, așadar se aplică opțiunile și limitele acestuia. Definițiile duplicate sunt păstrate pentru diagnosticarea conflictelor: structurile de stocare incompatibile generează definition_conflict, chiar dacă o definiție duplicată ulterioară nu este citită la redare.

Funcția verifică un singur bloc. Parcurgeți innerBlocks când validați un document; modelele sincronizate și celelalte referințe nu sunt expandate automat. Comanda wp bs blocks validate parcurge blocurile uneia sau mai multor articole și raportează căile blocurilor.

Site-urile cu un resolver personalizat la momentul redării pot adapta constatările fără a modifica datele stocate:

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

Returnați întotdeauna o listă de constatări; returnarea valorii [] acceptă blocul. Acest filtru rulează numai pentru blocurile gestionate, niciodată pentru rezultatul null.

Descrierea valorilor stocate

Folosiți bs_block_schema() după înregistrarea blocului (init sau o versiune ulterioară) pentru a descrie valorile stocate de un bloc, de exemplu pentru a genera marcajul blocului într-un instrument sau într-o integrare AI, ori pentru a verifica datele de intrare într-o rută REST:

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

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

Rezultatul este o schemă JSON a obiectului salvat în attrs.blockstudio.attributes. Aceasta include câmpurile blocului și câmpurile extensiilor corespunzătoare, împreună cu cheile de stocare folosite la validare: un grup de nivel superior adaugă un prefix copiilor săi, grupurile anonime și filele nu adaugă niciun nivel, iar un câmp de fișier adaugă componenta sa complementară <id>__size. Repetitoarele sunt liste de obiecte rând, cu minItems și maxItems din min și max. additionalProperties este false la rădăcina stocării câmpurilor și în rândurile repetitoarelor. Câmpurile cu valori de tip obiect, precum linkurile și obiectele personalizate, pot avea propriile metadate. Un bloc fără câmpuri nu are properties, așadar doar un obiect gol corespunde.

Fiecare câmp este descris într-o formă canonică acceptată de bs_validate_block():

Câmp Schemă
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block Un șir.
number, range Un număr, cu minimum și maximum din min și max.
toggle O valoare booleană.
select, radio, checkbox O valoare de opțiune sau o listă de valori de opțiune pentru checkbox și multiple, cu enum.
color, gradient Un șir, cu enum când este setat disableCustomColors sau disableCustomGradients.
token O listă de șiruri.
files Un ID de atașament întreg nenegativ sau o listă de ID-uri cu multiple.
link Un obiect cu url, title și opensInNewTab; url este obligatoriu.
icon Un obiect cu set, subSet și icon; set și icon sunt obligatorii.
attributes O listă de obiecte cu un attribute nevid și un value scalar.
repeater O listă de obiecte rând.
Tipuri de câmpuri personalizate Tipul atributului înregistrat.

enum enumeră opțiunile verificate la validare: opțiunile statice și opțiunile de populare deja rezolvate la înregistrare. Opțiunile fetch la distanță și argumentele de populare care conțin {attributes.*} nu au enum. O cheie cu definiții de forme de stocare diferite este omisă, deoarece validarea raportează fiecare valoare stocată sub ea. Când un câmp al blocului și un câmp al extensiei au aceeași cheie, enum enumeră valorile acceptate de ambele. Repetitoarele partajate combină câmpurile copil și aplică limitele de rând mai stricte dintre cele două definiții. În rândurile repetitoarelor, se aplică primul câmp cu un ID corespunzător din fiecare sursă, ca la randare. Un câmp explicit numit <id>__size are prioritate față de componenta pentru dimensiunea fișierului adăugată automat.

Când un câmp cu opțiuni închise nu are alegeri disponibile sau când două seturi de opțiuni aplicabile nu au valori comune, valoarea canonică este null pentru o selecție unică sau o listă goală pentru selecții multiple. O listă de opțiuni goală nu transformă câmpul într-unul fără restricții. Alegerile la distanță și cele dependente de atribute rămân deschise.

label al unui câmp devine title, help devine description, iar default este păstrat ca adnotare. title propriu schemei este titlul blocului. Câmpurile nu sunt niciodată obligatorii, iar logica condițională nu face parte din schemă.

Constrângerile folosesc doar cuvintele cheie verificate de rest_validate_value_from_schema(), astfel încât schema poate fi folosită ca schemă de intrare a unei rute REST sau a unei abilități:

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

Schema descrie câte un formular pentru fiecare câmp; validarea acceptă și structuri importate, precum obiecte option, șiruri numerice și obiecte ID. Nu înlocuiește bs_validate_block(): conflictele de definiție sunt probleme de configurare și pot genera în continuare constatări chiar și atunci când cheia conflictuală este omisă. Filtrele de validare pot impune și reguli specifice site-ului. Folosiți bs_validate_block() pentru a verifica conținutul stocat. Site-urile cu un resolver personalizat la momentul randării pot adapta schema cu filtrul blockstudio/blocks/attributes/schema.

Funcții PHP

Fără date

În forma sa cea mai simplă, funcția acceptă o singură valoare, care este ID-ul blocului ce trebuie redat pe pagină.

PHP
bs_render_block('blockstudio/cta');

Cu date

Pentru a reda blocul cu date personalizate, primul parametru trebuie să fie un tablou în locul unei singure valori. Valoarea din cheia data va fi transmisă variabilelor $attributes și $a din șablonul blocului.

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

Imbricare

Blocurile pot fi imbricate unele în altele folosind funcția bs_block împreună cu variabila puternică $content din șabloanele blocurilor.

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

Blocul buton va fi redat în locul variabilei $content din șablonul blocului.

Blocurile încorporate, redate cu bs_render_block() sau bs_block(), afișează întotdeauna HTML rezolvat pentru frontend, chiar și atunci când blocul părinte redă în acel moment o previzualizare a editorului. Pseudocomponentele șablonului, precum <RichText /> și <InnerBlocks />, sunt rezolvate înainte ca blocul încorporat să fie returnat.

Sloturi multiple

De asemenea, puteți crea mai multe sloturi de conținut transformând variabila $content într-un tablou asociativ și apelând cheile corespunzătoare în funcția 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']
    ])
  ]
]);

Etichete de bloc

Încorporați orice bloc folosind sintaxa de etichetă HTML. Sunt acceptate două formate:

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

Ambele redau același bloc. Sintaxa <bs:> transformă o cratimă în separator de spații de nume (acme-hero devine acme/hero). Cratimele sunt încercate de la stânga la dreapta, iar primul candidat înregistrat este ales, astfel încât se rezolvă și spațiile de nume care conțin cratime: <bs:acme-ui-button> încearcă acme/ui-button, apoi acme-ui/button. Sintaxa <block> folosește numele complet al blocului ca atribut name.

Funcționează atât blocurile Blockstudio, cât și blocurile de bază WordPress. Blocurile Blockstudio sunt redate prin întregul flux de procesare (șabloane, Tailwind, resurse). Blocurile de bază sunt redate prin sistemul de redare a blocurilor al WordPress, folosind rederele de blocuri încorporate.

Cum funcționează

Etichetele blocurilor se comportă diferit în funcție de locul în care apar:

În șabloanele blocurilor și în conținutul articolelor, etichetele sunt înlocuite la rulare cu HTML redat. Rezultatul este marcajul final al blocului referit, încorporat direct în pagină. Pentru acestea nu există niciun bloc WordPress în editor. Sunt doar un mecanism de redare.

În Pagini, modele și șabloane de site, etichetele sunt convertite în blocuri WordPress native înainte ca sursa fișierului să fie sincronizată sau înregistrată cu WordPress. Astfel, blocurile apar în editor, pot fi editate dacă destinația permite editarea și parcurg întregul ciclu de viață al blocurilor din WordPress. Sintaxa etichetelor este o prescurtare pentru definirea conținutului blocurilor în fișierele șablon.

Această distincție contează: etichetele blocurilor din șabloane produc rezultat, iar cele din pagini, modele și șabloane de site produc blocuri native.

În șabloanele blocurilor

Etichetele blocurilor sunt redate automat în șabloanele Twig și PHP. Nu este necesară nicio configurare. Sunt incluse sintaxele <bs:> și <block>, precum și orice etichete cu prefix și alias înregistrate, astfel încât un șablon le poate emite direct în loc să apeleze bs_render_block(). Rezultatul este redat HTML și încorporat direct în rezultatul șablonului blocului:

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>

În conținutul articolelor

Redarea la nivel de pagină (conținutul articolelor, zonele pentru widgeturi) este opțională:

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

Sau printr-un filtru:

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

Sintaxă

Etichete fără închidere:

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

Etichete pereche cu conținut între ele:

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>

Combinați-le liber. Ambele sintaxe se pot imbrica una în cealaltă:

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>

Prescurtări pentru prefixe

Etichetele blocurilor pot folosi și prescurtări de prefix specifice proiectului. Înregistrați un prefix cu unul sau mai multe spații de nume, iar Blockstudio rezolvă <prefix-slug> la primul bloc înregistrat în ordinea acelor spații de nume:

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

Cu exemplul de mai sus, <theme-card> se rezolvă la theme-components/card, <theme-button> revine la bsui/button dacă theme-components/button nu este înregistrat, iar <theme-ui-feature-matrix> se rezolvă la theme-components/ui-feature-matrix.

Prefixele se pot și combina. Dacă o etichetă cu prefix nu se rezolvă direct, iar slugul rămas este el însuși o etichetă cu prefix înregistrată, rezolvarea se repetă recursiv, astfel încât un prefix de brand poate fi suprapus peste un prefix de spațiu de nume:

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> nu are niciun bloc theme-components/ui-input, așa că trece la prefixul ui și se rezolvă la bsui/input. Potrivirile directe au întotdeauna prioritate față de rezolvarea imbricată, iar regulile de permitere și blocare se aplică blocului rezolvat în final.

Puteți configura prefixe și în blockstudio.json:

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

Prefixele trebuie să conțină litere mici sau cifre, să înceapă cu o literă și să nu conțină cratime. Aliasurile explicite din blockstudio/block_tags/tag_aliases au prioritate față de rezolvarea prefixelor. Etichetele cu prefix necunoscute sunt lăsate neschimbate.

Etichetele cu prefix și cele cu alias rămân convenții utile pentru redactare. Forma canonică și portabilă este întotdeauna <bs:namespace-slug>, deoarece înregistrează numele real al blocului fără a depinde de filtrele proiectului:

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

Exemplele Blockstudio, diagnosticele generate și rezultatul programatic folosesc această formă canonică. Proiectele care doresc să elimine o sintaxă prescurtată mai veche pot folosi migrarea canonică a etichetelor independentă, cu simulare prealabilă, fără a porni WordPress.

Blocuri de bază

Poate fi folosit orice bloc cu un render înregistrat:

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>

Sau cu sintaxa <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>

Liste de permitere și blocare

Controlați ce blocuri pot fi redate prin etichete:

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

allow permite doar modelele care corespund. deny exclude modelele care corespund și are prioritate. Ambele acceptă metacaractere * prin fnmatch(). Aceste reguli se aplică ambelor sintaxe și atât redării la nivel de șablon, cât și celei la nivel de pagină.

Filtre: blockstudio/block_tags/allow și blockstudio/block_tags/deny.

Transmitere directă HTML

Atributele cu prefixul data- sunt transmise elementului rădăcină al blocului redat. Și atributele cu prefixul html- sunt transmise, dar prefixul este eliminat. Funcționează cu ambele sintaxe. Un atribut transmis direct înlocuiește valoarea existentă a elementului rădăcină, în loc să o combine cu aceasta, astfel încât html-class înlocuiește clasele proprii ale blocului.

Un bloc Blockstudio plasează și atributele globale pe care nu le declară ca câmpuri pe elementul său rădăcină: id, style, role, title, lang, dir, hidden, tabindex și fiecare atribut aria-*. Un câmp declarat are întotdeauna prioritate, astfel încât un bloc cu un câmp title primește în schimb valoarea din $a['title']. Stilurile transmise trec prin safecss_filter_attr(), filtrul WordPress se aplică atributelor de stil din conținutul articolelor, iar acestea sunt adăugate la stilul deja setat de șablon.

Valorile atributelor sunt HTML, așa că entitățile sunt decodificate o dată la analizarea unei etichete: title="Tom &amp; Jerry" ajunge în șablon ca Tom & Jerry și este escapata din nou la ieșire. Valorile între ghilimele pot conține >, așa cum se întâmplă cu variantele Tailwind și selectorii de animație, atât în etichetele fără închidere, cât și în cele pereche.

Orice alt atribut pe care blocul nu îl declară, inclusiv class, nu ajunge niciodată la HTML. Când WP_DEBUG este activat, Blockstudio raportează fiecare astfel de atribut o singură dată per solicitare prin _doing_it_wrong(). Declarați un câmp pentru atribut sau scrieți-l ca atribut data-, aria- ori 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>

Renderere personalizate

Înregistrați renderere de blocuri personalizate pentru tipuri suplimentare de blocuri. Rendererele primesc un tablou de atribute și un șir cu conținutul interior și returnează un tablou de blocuri 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);

Pentru blocurile container care trebuie să analizeze conținutul interior în blocuri copil, adăugați o a doua intrare în același filtru:

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 aplică atât etichetelor de bloc, cât și blocurilor personalizate selectate prin blockstudio/parser/element_mapping. Acesta este cârligul potrivit când un bloc de proiect cu mapare la element trebuie să mute textul interior într-un câmp Blockstudio sau să construiască un tablou de blocuri personalizat.

blockstudio/block_tags/renderers și blockstudio/parser/renderers primesc același registru și aceeași structură a funcției de callback. Rămân disponibile pentru compatibilitate și pentru suprascrieri finale la nivelul analizatorului. Filtrele rulează în această ordine:

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

Un filtru ulterior poate înlocui un renderer înregistrat de unul anterior.

Utilizare programatică

Aplicați redarea etichetelor oricărui șir din PHP:

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

Componente

Etichetele blocurilor se potrivesc bine cu Componente. Componentele sunt blocuri care se redau numai programatic și nu apar niciodată în editor.

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

Analizator

Etichetele blocurilor sunt procesate de un scaner simplu de șiruri care înlocuiește DOMDocument. Analizatorul gestionează atât sintaxa <bs:>, cât și <block>, etichetele imbricate cu același nume prin urmărirea adâncimii, valorile atributelor între ghilimele și blocurile container recursive. Este creat special pentru acest caz de utilizare, funcționează mai rapid decât DOMDocument și WordPress din WP_HTML_Tag_Processor și evită problemele cunoscute ale DOMDocument cu eliminarea prefixelor spațiilor de nume și transformarea atributelor în litere mici.

Pentru Pagini, modele și șabloane de site, același analizator gestionează și elementele brute HTML (<p>, <div>, <h1> etc.), mapându-le la blocurile de bază WordPress corespunzătoare.

Când o mapare de element indică <p> către un bloc Blockstudio non-core înregistrat, care declară un atribut richtext content, conținutul interior HTML este direcționat automat în atributul content, inclusiv etichetele inline precum code și img, mapate la nivel de bloc. Un paragraf al cărui singur copil este o imagine devine blocul către care mapează <img>. Etichetele imbricate de bloc sau elementele HTML la nivel de bloc revin la analizarea normală a blocurilor interioare. <block name="core/shortcode"> își păstrează textul shortcode-ului drept conținut al blocului.