Vai al contenuto

Rendering programmatico

Poiché Gutenberg è diventato lo strumento principale per creare siti web facilmente modificabili per i clienti, ha senso realizzare tutte le aree necessarie del sito come blocchi. Questo approccio è adatto alla maggior parte dei casi, ma gli utenti esperti e alcuni casi d’uso specifici potrebbero richiedere l’uso di questi blocchi al di fuori dell’editor.

Blockstudio offre due modalità per renderizzare i blocchi a livello di codice:

  • Funzioni PHP: bs_render_block e bs_block per il rendering da codice PHP
  • Tag HTML: tag <bs:block-name> sostituiti con l’output del blocco ovunque nella pagina

Sono supportate tutte le funzionalità specifiche di Blockstudio, come gli stili in linea, gli script e gli stili con ambito limitato.

Isole funziona anche con questi percorsi di rendering. Un’isola dinamica renderizzata con bs_render_block(), bs_block() o un tag di blocco restituisce lo stesso marcatore segnaposto di un blocco renderizzato dal contenuto di un articolo; il runtime frontend viene iniettato quando il marcatore è presente nella risposta.

Composizioni strutturate e documenti completi

Per strumenti, anteprime, esportazioni e gallerie di componenti destinati a durare nel tempo, usate l’Blockstudio\Render API versionato. Accetta una dichiarazione o un elenco ordinato e renderizza senza stampare l’output:

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

La dichiarazione normalizzata canonica contiene quattro chiavi:

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

data, inner, innerBlocks, root, layers e example sono semplificazioni dell’input e vengono normalizzate e rimosse. Le dichiarazioni annidate vengono renderizzate ricorsivamente tramite la stessa pipeline Blockstudio.

Render::document() restituisce schemaVersion, html, body, blocks, assets, warnings e errors. Il valore assets separa head, footer, styles, scripts, modules, interactivity, ui e tailwind. L’elenco dei blocchi e le risorse includono le dipendenze richiamate dai template selezionati, ma escludono le risorse non correlate e quelle riservate all’editor.

I documenti completi possono impostare bodyClasses/bodyAttributes e, facoltativamente, racchiudere il corpo renderizzato con contentElement, contentClasses e contentAttributes. Il wrapper è limitato al nome di un elemento sicuro; il valore body restituito rimane il contenuto renderizzato senza wrapper. Le opzioni head e footer aggiungono markup attendibile del documento nelle rispettive posizioni e vengono incluse nell’insieme delle risorse restituite.

Per assemblare un documento attorno a HTML già renderizzato, specificate i nomi noti dei blocchi radice:

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

Usate Render::content() per i contenuti del blocco WordPress serializzati. I consumer che renderizzano più documenti indipendenti in una singola richiesta devono chiamare Blockstudio\Batch_Render::reset() tra un documento e l’altro; Canvas::documents() lo fa automaticamente.

Rendering al di fuori della pagina

Blockstudio inserisce un commento <!--blockstudio/namespace/slug--> prima di ogni blocco di cui esegue il rendering. In una pagina frontend, il buffer legge questi commenti per individuare i blocchi presenti, caricarne gli asset e rimuovere i commenti prima di inviare la risposta.

L’output che non passa attraverso quel buffer mantiene i commenti. Questo vale per le risposte REST, i feed, gli handler AJAX e i dati HTML che memorizzate o inviate altrove dopo do_blocks(), Render::content() o bs_render_block(). Usate bs_strip_render_markers() per rimuoverli:

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

La funzione rimuove i commenti dei blocchi Blockstudio registrati e lascia tutto il resto intatto, compresi gli altri commenti HTML. Corrisponde agli stessi marcatori rimossi dal buffer della pagina. Chiamatela dopo la registrazione dei blocchi (init o successivamente).

Non rimuovete il markup che viene ancora stampato in una pagina frontend gestita dal buffer. La pagina ha bisogno dei commenti per sapere quali asset dei blocchi caricare, e Blockstudio li rimuove al termine.

La rimozione dei commenti non aggiunge asset. I file CSS e JavaScript dei blocchi vengono inseriti solo dal buffer della pagina. Usate bs_block_assets() oppure Render::document() quando servono anche al consumer.

Esaminare i blocchi

Usate bs_block_fields() dopo la registrazione dei blocchi (su init o successivamente) per ottenere le definizioni dei campi risolte senza leggere i registri interni:

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

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

Il valore restituito è l’array delle definizioni dei campi registrati, inclusi filtri degli attributi, campi personalizzati espansi, override e gruppi, schede e repeater annidati. Un blocco Blockstudio senza campi restituisce []. Il risultato è una copia: modificarla non cambia il blocco registrato.

Queste sono definizioni, non valori salvati. Per convalidare il markup salvato, usate bs_validate_block() invece di mantenere un walker di campi separato. Per descrivere i valori accettati da un blocco, usate bs_block_schema(). Gli attributi gestiti da WordPress restano separati.

I campi aggiunti dalle estensioni non fanno parte di bs_block_fields(). Usate bs_block_extension_fields() per ottenerli. La funzione individua le estensioni in base al nome del blocco, quindi funziona anche con blocchi core e di terze parti:

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

Il valore restituito elenca le definizioni dei campi di ogni estensione corrispondente, nell’ordine in cui le estensioni sono state registrate e con la stessa struttura di bs_block_fields(). Se nessuna estensione corrisponde a un blocco, viene restituito []. I valori delle estensioni vengono salvati nello stesso oggetto attrs.blockstudio.attributes dei valori dei campi propri del blocco, quindi tutti gli ID condividono lo stesso spazio dei nomi. Se due estensioni definiscono lo stesso ID, vengono restituite entrambe le definizioni e modificano lo stesso valore; durante il rendering si applica la definizione dell’estensione registrata più tardi.

Per leggere i valori di un blocco salvato così come vengono ricevuti dal suo template, usate bs_block_values().

Usate bs_block_assets() per esaminare CSS e JavaScript individuati per il blocco. Per un documento di anteprima completo, che includa blocchi annidati e dipendenze runtime condivise, usate Render::document() come descritto sopra.

Convalidare i valori memorizzati

Usate bs_validate_block() dopo la registrazione dei blocchi (init o successivamente) per verificare gli attributi dei blocchi generati programmaticamente o importati prima di salvarli:

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

Passate l’intero array attrs, non soltanto blockstudio.attributes. Il rendering di Blockstudio accetta anche i campi dichiarati al livello superiore, e i valori annidati hanno la precedenza se vengono forniti entrambi. Le estensioni dei blocchi core e di terze parti leggono solo blockstudio.attributes. Un blocco Blockstudio vuoto è gestito e restituisce [], non null.

La convalida è esplicita e in sola lettura. Non esegue il rendering dei template, non modifica i valori, non salva gli articoli, non interroga i media e non esegue callback di popolamento. Non viene eseguita automaticamente durante i salvataggi, la sincronizzazione delle pagine o il rendering. Non è un sanitizer, un controllo di autorizzazione né una verifica dell’esistenza di un allegato.

Ogni risultato contiene queste chiavi stabili:

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

Usate code, non il tradotto message, negli strumenti. source è block oppure extension. I percorsi usano chiavi di archiviazione e indici a base zero delle righe del ripetitore o delle selezioni, senza barra iniziale. I caratteri letterali ~ e / in una chiave vengono sottoposti a escape come ~0 e ~1. Un gruppo di primo livello antepone un prefisso ai propri elementi secondari (cta_title); i gruppi anonimi e le schede non aggiungono livelli. Il builder non supporta gruppi con un ID all’interno di un altro gruppo o di un ripetitore, quindi le relative chiavi non sono accettate. I campi messaggio non hanno un valore archiviato. Un campo file consente il relativo campo <id>__size. Alla radice di un blocco Blockstudio, le chiavi di gestione e gli attributi globali HTML inoltrati all’elemento renderizzato non sono campi sconosciuti. Questo non consente chiavi arbitrarie nelle righe dei ripetitori né estensioni dei blocchi core.

Codice Significato expected
unknown_field Nessun campo mantenuto dichiara questa chiave di archiviazione. Chiavi di archiviazione note.
unknown_option Una selezione non è tra le opzioni note. Valori delle opzioni consentiti.
wrong_type La struttura archiviata non è supportata dal campo. Famiglia o tipo di archiviazione previsto.
too_few_rows, too_many_rows Un ripetitore presente non rientra nel suo limite min o max. Limite delle righe.
definition_conflict Le definizioni applicabili a una chiave richiedono strutture di archiviazione diverse. Origine e tipo di campo di ciascuna definizione.
shadowed_value Un valore annidato sostituisce un valore diverso di un campo di primo livello. Il valore annidato prevalente.
extension_top_level Il template può leggere un valore di primo livello, ma i binding delle estensioni no. Il percorso richiesto sotto blockstudio/attributes.
unknown_attribute Una chiave di primo livello di un blocco Blockstudio non viene letta dal percorso di rendering e viene eliminata. Nomi degli attributi registrati, campi delle estensioni e blockstudio.
missing_container attributes, disabled, name o editor è archiviato al primo livello e manca blockstudio. Il percorso richiesto sotto blockstudio.
invalid_container blockstudio o blockstudio.attributes non è un oggetto. object.

Il messaggio di una segnalazione unknown_field indica la chiave di archiviazione più vicina allo stesso livello, se la distanza è al massimo di tre modifiche, come nella regola delle impostazioni sconosciute: This storage key is not declared by the block or its extensions. Did you mean "title"? expected elenca comunque tutte le chiavi note. La corrispondenza ignora le maiuscole e considera solo le chiavi di archiviazione di quel contenitore. I messaggi vengono tradotti; le integrazioni dovrebbero usare code, path e expected invece di analizzare il testo del messaggio.

Una chiave di primo livello di un blocco Blockstudio che non è un attributo registrato (i suoi campi, gli attributi che WordPress aggiunge per supports, lock e metadata), né un campo di un’estensione corrispondente, né blockstudio, né una chiave di gestione o un attributo HTML inoltrato, viene eliminata prima dell’esecuzione del template. Una chiave simile, ad esempio l’ID di un campo scritto in modo errato o un oggetto di valori archiviato senza il relativo wrapper blockstudio, genera una segnalazione perché il blocco viene renderizzato senza quel valore. I blocchi che contengono solo campi di estensione non vengono controllati per le chiavi di primo livello.

Le strutture accettate seguono il rendering: le selezioni multiple e le caselle di controllo possono contenere un elenco, un oggetto opzione o un valore scalare importato, incluso lo zero numerico. Per i numeri sono accettate le stringhe numeriche. I campi file possono contenere ID di allegati, oggetti ID, elenchi o riferimenti stringa. I valori di collegamenti e icone devono essere oggetti; i tipi di campo personalizzati usano il tipo di attributo registrato. Un campo attributes contiene un elenco di coppie con un nome attribute non vuoto e un value scalare; i metadati facoltativi, come data.media, vengono mantenuti.

WordPress convalida gli attributi registrati di primo livello prima del rendering e può quindi rifiutare una struttura accettata all’interno di blockstudio.attributes. Ad esempio, un valore radio "a" funziona nell’oggetto annidato, ma viene eliminato al primo livello, dove il tipo registrato è object. Un valore simile genera wrong_type. Usate l’oggetto annidato per la stessa struttura di archiviazione scritta dall’editor.

I campi mancanti non sono obbligatori. I valori annidati vuoti (null, false, '', []) e i campi disabilitati non generano errori di valore. Un ripetitore esplicitamente vuoto viene comunque controllato rispetto a min; un ripetitore assente o disabilitato no. Un valore vuoto di primo livello viene segnalato se WordPress lo elimina e ripristina un valore predefinito non vuoto. Lo stesso valore nell’oggetto annidato può azzerarlo. I conflitti tra definizioni vengono segnalati anche quando la chiave non ha un valore salvato.

Le opzioni statiche e quelle di popolamento già risolte al momento della registrazione vengono controllate senza invocare di nuovo il popolamento. Le opzioni remote fetch e gli argomenti di popolamento contenenti {attributes.*} vengono ignorati. I valori di colore e gradiente possono essere personalizzati, a meno che non sia impostato disableCustomColors o disableCustomGradients. Questo controllo riguarda i valori archiviati, non default, fallback o le regole di convalida dell’editor.

I campi delle estensioni corrispondenti vengono inclusi per ogni blocco a cui si applicano. Le definizioni successive prevalgono all’interno del blocco o delle sue estensioni alla radice, come avviene nel rendering. Il campo di un blocco e quello di un’estensione restano definizioni separate della stessa chiave ed entrambi si applicano. Nelle righe dei ripetitori, il renderer legge il primo campo con un ID corrispondente in ciascuna origine, quindi si applicano le relative opzioni e i relativi limiti. Le definizioni duplicate vengono mantenute per diagnosticare i conflitti: strutture di archiviazione incompatibili generano definition_conflict, anche quando un duplicato successivo non viene letto durante il rendering.

La funzione controlla un blocco. Esaminate innerBlocks quando convalidate un documento; i pattern sincronizzati e gli altri riferimenti non vengono espansi automaticamente. Il comando wp bs blocks validate esamina i blocchi di uno o più articoli e ne segnala i percorsi.

I siti con un resolver personalizzato in fase di rendering possono adattare le segnalazioni senza modificare i dati archiviati:

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

Restituite sempre un elenco di segnalazioni; restituire [] significa accettare il blocco. Questo filtro viene eseguito solo per i blocchi gestiti, mai per il risultato null.

Descrizione dei valori archiviati

Usate bs_block_schema() dopo la registrazione del blocco (init o versioni successive) per descrivere i valori archiviati da un blocco, ad esempio per generare il markup del blocco in uno strumento o in un’integrazione AI, oppure per controllare l’input in una route REST:

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

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

Il risultato è uno Schema JSON dell’oggetto salvato in attrs.blockstudio.attributes. Comprende i campi del blocco e quelli delle estensioni corrispondenti, con le chiavi di archiviazione usate dalla convalida: un gruppo di primo livello aggiunge un prefisso ai figli, i gruppi anonimi e le schede non aggiungono livelli, e un campo file aggiunge il relativo campo associato <id>__size. I ripetitori sono elenchi di oggetti riga con minItems e maxItems ricavati da min e max. additionalProperties è false alla radice dei dati archiviati nei campi e nelle righe dei ripetitori. I campi con valori oggetto, come i link e gli oggetti personalizzati, possono avere metadati propri. Un blocco senza campi non ha properties, quindi corrisponde solo un oggetto vuoto.

Ogni campo è descritto in una forma canonica accettata da bs_validate_block():

Campo Schema
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block Una stringa.
number, range Un numero, con minimum e maximum ricavati da min e max.
toggle Un valore booleano.
select, radio, checkbox Un valore opzione, oppure un elenco di valori opzione per checkbox e multiple, con enum.
color, gradient Una stringa, con enum se è impostato disableCustomColors o disableCustomGradients.
token Un elenco di stringhe.
files Un ID allegato intero non negativo, oppure un elenco di ID con multiple.
link Un oggetto con url, title e opensInNewTab; url è obbligatorio.
icon Un oggetto con set, subSet e icon; set e icon sono obbligatori.
attributes Un elenco di oggetti con un attribute non vuoto e un value scalare.
repeater Un elenco di oggetti riga.
Tipi di campo personalizzati Il tipo di attributo registrato.

enum elenca le opzioni controllate dalla convalida: le opzioni statiche e quelle di popolamento già risolte al momento della registrazione. Le opzioni remote fetch e gli argomenti di popolamento che contengono {attributes.*} non hanno enum. Una chiave con definizioni di forme di archiviazione diverse viene esclusa, perché la convalida segnala ogni valore archiviato con quella chiave. Quando un campo del blocco e un campo di un’estensione condividono una chiave, enum elenca i valori accettati da entrambi. I ripetitori condivisi combinano i campi figli e applicano i limiti di riga più restrittivi tra le due definizioni. Nelle righe dei ripetitori, si applica il primo campo con un ID corrispondente in ciascuna origine, come durante il rendering. Un campo esplicito chiamato <id>__size ha la precedenza sul campo associato alla dimensione del file aggiunto automaticamente.

Quando un campo a scelte chiuse non ha opzioni disponibili o due insiemi di opzioni applicabili non hanno elementi in comune, il suo valore canonico è null per una selezione singola oppure un elenco vuoto per le selezioni multiple. Un elenco di opzioni vuoto non rende il campo privo di restrizioni. Le scelte remote e quelle dipendenti dagli attributi restano aperte.

Il campo label diventa title, il suo help diventa description e il suo default viene mantenuto come annotazione. title dello schema è il titolo del blocco. I campi non sono mai obbligatori e la logica condizionale non fa parte dello schema.

I vincoli usano solo le parole chiave controllate da rest_validate_value_from_schema(), quindi lo schema può essere usato direttamente come schema di input di una route REST o di un’abilità:

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

Lo schema descrive un modulo per ogni campo; la convalida accetta anche strutture importate come oggetti opzione, stringhe numeriche e oggetti ID. Non sostituisce bs_validate_block(): i conflitti nelle definizioni sono problemi di configurazione e possono comunque generare segnalazioni anche quando la chiave in conflitto viene omessa. I filtri di convalida possono inoltre imporre regole specifiche del sito. Usate bs_validate_block() per controllare i contenuti salvati. I siti con un resolver personalizzato in fase di rendering possono adattare lo schema con il filtro blockstudio/blocks/attributes/schema.

Funzioni PHP

Senza dati

Nella sua forma più semplice, la funzione accetta un singolo valore, ovvero l’ID del blocco da renderizzare nella pagina.

PHP
bs_render_block('blockstudio/cta');

Con dati

Per renderizzare il blocco con dati personalizzati, come primo parametro va usato un array al posto di un singolo valore. Il valore nella chiave data viene passato a $attributes e alla variabile $a nel template del blocco.

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

Nidificazione

È possibile nidificare i blocchi usando la funzione bs_block insieme alla potente variabile $content nei template dei blocchi.

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

Il blocco pulsante verrà renderizzato al posto della variabile $content nel template del blocco.

I blocchi incorporati renderizzati con bs_render_block() o bs_block() producono sempre HTML risolto dal frontend, anche quando il blocco genitore sta renderizzando un’anteprima nell’editor. I componenti segnaposto dei template come <RichText /> e <InnerBlocks /> vengono risolti prima che il blocco incorporato venga restituito.

Slot multipli

È anche possibile creare più slot di contenuto trasformando semplicemente la variabile $content in un array associativo e richiamandone le chiavi appropriate nella funzione 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']
    ])
  ]
]);

Tag dei blocchi

Incorporate qualsiasi blocco usando la sintassi dei tag HTML. Sono supportati due formati:

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

Entrambi renderizzano lo stesso blocco. La sintassi <bs:> trasforma un trattino nel separatore del namespace (acme-hero diventa acme/hero). I trattini vengono provati da sinistra a destra e vince il primo candidato registrato, perciò vengono risolti anche i namespace che contengono trattini: <bs:acme-ui-button> prova acme/ui-button, poi acme-ui/button. La sintassi <block> usa il nome completo del blocco come attributo name.

Funzionano sia i blocchi Blockstudio sia i blocchi core WordPress. I blocchi Blockstudio vengono renderizzati tramite l’intera pipeline (template, Tailwind, asset). I blocchi core vengono renderizzati tramite il sistema di rendering dei blocchi di WordPress, usando i renderer dei blocchi integrati.

Come funziona

I tag dei blocchi si comportano in modo diverso a seconda di dove compaiono:

Nei template dei blocchi e nel contenuto dei post, i tag vengono sostituiti in fase di esecuzione con HTML renderizzato. Il risultato è il markup finale del blocco indicato, incorporato direttamente nella pagina. Nell’editor non esiste alcun blocco WordPress per questi tag. Servono esclusivamente per il rendering.

Nelle Pagine, nei pattern e nei template del sito, i tag vengono convertiti in blocchi WordPress nativi prima che il sorgente del file venga sincronizzato o registrato con WordPress. Ciò significa che i blocchi compaiono nell’editor, possono essere modificati se la destinazione supporta la modifica e seguono l’intero ciclo di vita dei blocchi di WordPress. La sintassi dei tag è una forma abbreviata per definire il contenuto dei blocchi nei file template.

Questa distinzione è importante: i tag dei blocchi nei template producono output, mentre quelli nelle pagine, nei pattern e nei template del sito producono blocchi nativi.

Nei template dei blocchi

I tag dei blocchi vengono renderizzati automaticamente nei template Twig e PHP. Non serve alcuna impostazione. Sono incluse le sintassi <bs:> e <block>, oltre a qualsiasi tag registrato con prefisso e alias, perciò un template può generarli direttamente invece di chiamare bs_render_block(). L’output viene renderizzato HTML, incorporato direttamente nel risultato del template del blocco:

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>

Nel contenuto dei post

Il rendering a livello di pagina (contenuto dei post, aree widget) è facoltativo:

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

Oppure tramite un filtro:

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

Sintassi

Tag senza chiusura:

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

Tag con apertura e chiusura e contenuto interno:

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>

Combinate liberamente i due formati. Entrambe le sintassi possono essere nidificate tra loro:

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>

Abbreviazioni dei prefissi

I tag dei blocchi possono usare anche abbreviazioni di prefisso specifiche del progetto. Registrate un prefisso con uno o più namespace e Blockstudio risolve <prefix-slug> nel primo blocco registrato nell’ordine dei namespace:

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

Con l’esempio precedente, <theme-card> viene risolto in theme-components/card, <theme-button> usa bsui/button come alternativa se theme-components/button non è registrato, e <theme-ui-feature-matrix> viene risolto in theme-components/ui-feature-matrix.

È anche possibile comporre i prefissi. Quando un tag con prefisso non viene risolto direttamente e lo slug restante è a sua volta un tag con prefisso registrato, la risoluzione procede ricorsivamente: un prefisso del brand può quindi sovrapporsi a un prefisso del namespace:

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> non ha alcun blocco theme-components/ui-input, quindi passa al prefisso ui e viene risolto in bsui/input. Le corrispondenze dirette hanno sempre la precedenza sulla risoluzione nidificata; le regole di consentiti e negati si applicano al blocco risolto finale.

Potete configurare i prefissi anche in blockstudio.json:

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

I prefissi devono contenere solo lettere minuscole o numeri, iniziare con una lettera e non contenere trattini. Gli alias espliciti definiti in blockstudio/block_tags/tag_aliases hanno la precedenza sulla risoluzione dei prefissi. I tag con prefisso sconosciuto restano invariati.

I tag con prefisso e gli alias restano pratiche utili per la composizione. La forma canonica e portabile è sempre <bs:namespace-slug>, perché registra il vero nome del blocco senza dipendere dai filtri del progetto:

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

Gli esempi Blockstudio, i diagnostici generati e l’output programmatico usano questa forma canonica. I progetti che vogliono rimuovere una vecchia sintassi abbreviata possono usare la migrazione canonica dei tag standalone, che esegue prima una simulazione, senza avviare WordPress.

Blocchi core

È possibile usare qualsiasi blocco con un renderer registrato:

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>

Oppure con la sintassi <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>

Elenchi di consentiti e negati

Controllate quali blocchi possono essere renderizzati tramite i tag:

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

allow limita l’elenco ai soli pattern corrispondenti. deny esclude i pattern corrispondenti e ha la precedenza. Entrambi supportano i caratteri jolly * tramite fnmatch(). Si applicano a entrambe le sintassi e al rendering sia nei template sia nelle pagine.

Filtri: blockstudio/block_tags/allow e blockstudio/block_tags/deny.

Passaggio diretto di HTML

Gli attributi con prefisso data- vengono passati all’elemento radice del blocco renderizzato. Vengono passati anche gli attributi con prefisso html-, rimuovendone il prefisso. Funziona con entrambe le sintassi. Un attributo passato direttamente sostituisce il valore esistente dell’elemento radice anziché unirsi a esso, quindi html-class sostituisce le classi del blocco.

Un blocco Blockstudio aggiunge inoltre al proprio elemento radice gli attributi globali non dichiarati come campi: id, style, role, title, lang, dir, hidden, tabindex e ogni attributo aria-*. Un campo dichiarato ha sempre la precedenza: quindi, se un blocco ha un campo title, riceve invece il valore di $a['title']. Gli stili inoltrati passano attraverso safecss_filter_attr(); il filtro WordPress si applica agli attributi style nel contenuto dei post e questi stili vengono aggiunti a quelli già impostati dal template.

I valori degli attributi sono HTML, quindi le entità vengono decodificate una volta quando si analizza un tag: title="Tom &amp; Jerry" arriva al template come Tom & Jerry e viene nuovamente sottoposto a escape in output. I valori tra virgolette possono contenere >, come nelle varianti Tailwind e nei selettori di animazione, sia nei tag senza chiusura sia in quelli con contenuto.

Qualsiasi altro attributo non dichiarato dal blocco, incluso class, non raggiunge mai HTML. Quando WP_DEBUG è attivo, Blockstudio segnala ciascuno di questi attributi una volta per richiesta tramite _doing_it_wrong(). Dichiarate un campo per l’attributo oppure scrivetelo come attributo data-, aria- o 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>

Renderer personalizzati

Registrate renderer personalizzati per tipi di blocco aggiuntivi. I renderer accettano un array di attributi e una stringa con il contenuto interno e restituiscono un array di blocco 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);

Per i blocchi contenitore che devono analizzare il contenuto interno per ricavarne i blocchi figli, aggiungete una seconda voce nello stesso filtro:

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 si applica sia ai tag dei blocchi sia ai blocchi personalizzati selezionati tramite blockstudio/parser/element_mapping. È il hook appropriato quando un blocco di progetto mappato a un elemento deve spostare il testo interno in un campo Blockstudio o creare un array di blocco personalizzato.

blockstudio/block_tags/renderers e blockstudio/parser/renderers ricevono lo stesso registro e la stessa struttura di callback. Restano disponibili per compatibilità e per le sostituzioni finali a livello di parser. I filtri vengono eseguiti in questo ordine:

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

Un filtro successivo può sostituire un renderer registrato da un filtro precedente.

Uso programmatico

Applicate il rendering dei tag a qualsiasi stringa proveniente da PHP:

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

Componenti

I tag dei blocchi si abbinano bene ai Componenti. I componenti sono blocchi renderizzati solo a livello programmatico e non compaiono mai nell’editor.

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

Parser

I tag dei blocchi vengono elaborati da uno scanner leggero di stringhe che sostituisce DOMDocument. Il parser gestisce la sintassi <bs:> e <block>, i tag nidificati con lo stesso nome tracciandone la profondità, i valori degli attributi tra virgolette e i blocchi contenitore ricorsivi. È progettato appositamente per questo caso d’uso, ha prestazioni migliori sia di DOMDocument sia di WordPress WP_HTML_Tag_Processor ed evita i problemi noti di DOMDocument con la rimozione dei prefissi dei namespace e la conversione degli attributi in minuscolo.

Per Pagine, pattern e template del sito, lo stesso parser gestisce anche gli elementi HTML grezzi (<p>, <div>, <h1> ecc.), associandoli ai corrispondenti blocchi core WordPress.

Quando un’associazione di elementi collega <p> a un blocco Blockstudio non core registrato che dichiara un attributo richtext content, il contenuto interno HTML viene instradato automaticamente a tale attributo content, inclusi i tag inline come code e img associati a livello di blocco. Un paragrafo il cui unico elemento figlio è un’immagine diventa il blocco a cui corrisponde <img>. I tag dei blocchi nidificati o gli elementi HTML a livello di blocco continuano a usare l’analisi standard dei blocchi interni. <block name="core/shortcode"> mantiene il testo dello shortcode come contenuto del blocco.