Pagine e pattern
Blockstudio consente di definire pagine WordPress, pattern di blocchi e template dell’Editor del sito come file nel tema. Scrivete template simili a HTML e il parser di Blockstudio li converte in blocchi nativi di WordPress.
- Pagine vengono sincronizzate con il database come post WordPress, mantenendo sincronizzati i template dei file e i contenuti delle pagine.
- Pattern vengono registrati in memoria tramite
register_block_pattern()e sono disponibili nell’inseritore di blocchi, dove gli utenti possono inserirli ovunque. - Template del sito forniscono fonti
wp_templateewp_template_partbasate su file per l’Editor del sito di WordPress.
Tutte e tre le funzionalità condividono lo stesso parser HTML e la stessa sintassi dei blocchi.
Creazione di pagine basate su file
Una guida pratica ai template di pagina basati su file, alla sincronizzazione e al blocco.
Struttura delle cartelle
theme/
├── pages/
│ ├── about/
│ │ ├── page.json
│ │ └── index.php
│ └── contact/
│ ├── page.json
│ └── index.twig
├── patterns/
├── hero/
│ ├── pattern.json
│ └── index.php
└── cta/
├── pattern.json
└── index.blade.php
├── templates/
└── front-page/
├── template.json
└── index.php
└── parts/
└── header/
├── part.json
└── index.php
Ogni sottocartella contiene un file di configurazione JSON (page.json, pattern.json, template.json oppure part.json) e un file template.
Motori di template
I template possono essere scritti come markup semplice in index.php oppure in Twig o Blade:
| File | Motore | Requisito |
|---|---|---|
index.php |
Nessuno (viene letto così com’è, il codice PHP non viene eseguito) | Nessuno |
index.twig |
Twig | Timber |
index.blade.php |
Blade | illuminate/view |
Se esistono più file template, l’ordine di priorità è: index.php > index.blade.php > index.twig.
Poiché i template vengono compilati al momento dell’inizializzazione (prima che sia disponibile il contesto di una richiesta), i template Twig e Blade non hanno accesso alle variabili dinamiche. Sono utili per funzioni e filtri integrati come {{ "text"|upper }} o {{ strtoupper("text") }}.
Mappatura da HTML ai blocchi
Gli elementi standard di HTML vengono convertiti automaticamente nei blocchi WordPress corrispondenti.
Testo
| HTML | Blocco |
|---|---|
<p> |
core/paragraph |
<h1> – <h6> |
core/heading |
<ul> |
core/list (non ordinato) |
<ol> |
core/list (ordinato) |
<li> |
core/list-item |
<blockquote> |
core/quote |
<code> |
core/code |
<pre> |
core/preformatted |
Gli elenchi mantengono la loro struttura. Un <ul> o un <ol> all’interno di un <li> diventa un blocco interno core/list di quell’core/list-item, la struttura salvata dall’editor, perciò gli elenchi possono annidarsi a qualsiasi profondità. Un class applicato a un elenco o a un elemento diventa il suo className, che consente di impostare uno stile di blocco come is-style-checks da un file di pagina; anche <block name="core/list" className="..."> fa lo stesso.
Contenuti multimediali
| HTML | Blocco |
|---|---|
<img> |
core/image |
<figure> |
core/image (con didascalia) |
<audio> |
core/audio |
<video> |
core/video |
Layout
| HTML | Blocco |
|---|---|
<div>, <section> |
core/group |
<main>, <header>, <footer>, <article>, <aside> |
core/group che mantiene l’elemento come proprio tagName |
<hr> |
core/separator |
<details> |
core/details |
<table> |
core/table |
Sintassi dei blocchi
Per i blocchi che non hanno un equivalente diretto in HTML, usate l’elemento <block>:
<block name="core/cover" url="https://example.com/hero.jpg">
<h1>Welcome</h1>
<p>Content inside the cover block.</p>
</block>
Blocchi principali
<!-- Pullquote -->
<block name="core/pullquote">
<p>An important quote.</p>
</block>
<!-- Verse -->
<block name="core/verse">Roses are red,
Violets are blue.</block>
<!-- Cover -->
<block name="core/cover" url="https://example.com/image.jpg">
<h2>Cover Title</h2>
</block>
<!-- Embed -->
<block name="core/embed" url="https://youtube.com/watch?v=..." providerNameSlug="youtube" />
<!-- Spacer -->
<block name="core/spacer" height="50px" />
<!-- Gallery -->
<block name="core/gallery">
<img src="https://example.com/1.jpg" alt="Image 1" />
<img src="https://example.com/2.jpg" alt="Image 2" />
</block>
<!-- Columns -->
<block name="core/columns">
<block name="core/column">
<h3>Column 1</h3>
</block>
<block name="core/column">
<h3>Column 2</h3>
</block>
</block>
<!-- Buttons -->
<block name="core/buttons">
<block name="core/button" url="/get-started">Get Started</block>
</block>
<!-- Row (flex layout) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
<p>Item 1</p>
<p>Item 2</p>
</block>
Blocchi personalizzati
La stessa sintassi funziona con qualsiasi blocco registrato:
<block name="blockstudio/section">
<h1>Welcome</h1>
</block>
<block name="acf/hero" title="Hero Title" background="dark">
<p>Inner content becomes InnerBlocks.</p>
</block>
Attributi
Gli attributi HTML sugli elementi <block> vengono passati come attributi del blocco. Sono supportati i valori JSON:
<block name="core/heading" level="3">Custom Heading</block>
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
<p>Stacked content.</p>
</block>
<img src="https://example.com/photo.jpg" alt="Photo" width="800" height="400" />
I valori degli attributi vengono decodificati una volta, come farebbe un browser leggendoli, quindi data-animate="[&>span]:fade" e data-animate="[&>span]:fade" memorizzano lo stesso valore.
Su un elemento associato a un blocco Blockstudio, ogni attributo viene memorizzato con il blocco. I campi dichiarati raggiungono il template; gli attributi globali che il blocco non dichiara (id, style, role, title, lang, dir, hidden, tabindex, aria-* e data-*) vengono inseriti nell’elemento radice del blocco al momento del rendering, esattamente come nei tag dei blocchi. Nei sorgenti di pagine e pattern, un prefisso html- indica solo uno di questi attributi globali, quindi html-role="note" viene inoltrato come role, mentre i gestori di eventi come html-onclick non vengono mai renderizzati. Tutto il resto, incluso un class non dichiarato, rimane nel contenuto dell’articolo senza raggiungere la pagina, e wp bs pages sync lo segnala per ogni pagina analizzata.
Renderer di blocchi personalizzati
Il parser HTML usa un’architettura basata su registri. Aggiungete un builder per un blocco personalizzato con blockstudio/block_tags/builders:
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
$builders['acf/hero'] = function( array $attrs, string $inner_content ) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );
return array(
'blockName' => 'acf/hero',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '',
'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
);
};
return $builders;
}, 10, 2 );
Poi usatelo in qualsiasi template:
<block name="acf/hero" background="dark">
<h1>Welcome</h1>
</block>
Potete anche sovrascrivere il rendering dei blocchi principali:
add_filter( 'blockstudio/parser/renderers', function( $renderers, $parser ) {
$renderers['core/paragraph'] = function( array $attrs, string $inner_content ) {
$content = trim( $inner_content );
$attrs['align'] = $attrs['align'] ?? 'center';
return array(
'blockName' => 'core/paragraph',
'attrs' => $attrs,
'innerBlocks' => array(),
'innerHTML' => '<p class="has-text-align-center">' . $content . '</p>',
'innerContent' => array( '<p class="has-text-align-center">' . $content . '</p>' ),
);
};
return $renderers;
}, 10, 2 );
Le callback del builder ricevono gli attributi analizzati e il contenuto interno grezzo. Devono restituire un array di blocchi WordPress. Consultate la sezione Renderer personalizzati per l’ordine completo dei filtri e un esempio di contenitore.
Firma della funzione builder
/**
* @param array $attrs Parsed element or block-tag attributes.
* @param string $inner_content Raw inner content.
* @return array WordPress block array.
*/
function my_builder( array $attrs, string $inner_content ): array {}
Mappatura degli elementi
Per impostazione predefinita, gli elementi standard HTML come <h1>, <p> e <img> vengono associati ai blocchi principali WordPress. Potete modificare questa mappatura per associare qualsiasi elemento HTML a un blocco diverso usando il filtro blockstudio/parser/element_mapping:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['h1'] = 'custom/heading';
$mapping['h2'] = 'custom/heading';
$mapping['p'] = 'custom/paragraph';
$mapping['img'] = 'custom/image';
return $mapping;
}, 10, 2 );
Con questo filtro attivo, ogni <h1> nei vostri template genererà un blocco custom/heading invece di core/heading. Gli attributi dell’elemento vengono passati al blocco di destinazione. Se è registrato un renderer per il nome del blocco di destinazione, verrà usato; altrimenti verrà creata una struttura di blocco generica.
È utile quando il vostro tema o plugin fornisce tipi di blocco personalizzati che devono sostituire quelli predefiniti in tutti i template di pagina e pattern.
Per semplici mappature <p>, Blockstudio può indirizzare i contenuti interni HTML direttamente all’attributo richtext content di un blocco Blockstudio registrato non appartenente al core. Il blocco di destinazione deve dichiarare un attributo con id: "content" e type: "richtext". La formattazione in linea (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) resta nel valore indirizzato anche quando lo stesso tag è mappato a un elemento, come avviene per impostazione predefinita con code e img. Un paragrafo il cui unico elemento figlio è un’immagine diventa il blocco a cui <img> lo associa, proprio come Markdown fa con un’immagine autonoma. I tag di blocco annidati e gli elementi HTML a livello di blocco continuano a essere analizzati come blocchi interni.
I valori di mappatura possono essere anche funzioni richiamabili quando il blocco di destinazione dipende dagli attributi dell’elemento:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['div'] = function( array $attrs ) {
if ( isset( $attrs['width'] ) ) {
return 'theme/row';
}
if ( isset( $attrs['gap'] ) ) {
return 'theme/flow';
}
return 'theme/div';
};
return $mapping;
} );
I blocchi personalizzati associati a elementi contenitore come <section> e <div> analizzano ricorsivamente gli elementi figli HTML annidati, trasformando intestazioni, immagini, tag di blocco e paragrafi interni in blocchi figli nativi.
Esempio completo
Un template di pagina completo che combina più tipi di blocco:
<div>
<h1>Welcome to Our Site</h1>
<p>This is an <strong>introduction</strong> with <em>formatting</em>.</p>
<block name="core/columns">
<block name="core/column">
<h3>Feature One</h3>
<p>First feature description.</p>
</block>
<block name="core/column">
<h3>Feature Two</h3>
<p>Second feature description.</p>
</block>
</block>
<block name="core/cover" url="https://example.com/hero.jpg">
<h2>Our Mission</h2>
<p>Building amazing things together.</p>
</block>
<details>
<summary>FAQ</summary>
<p>Answers to common questions.</p>
</details>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
<block name="core/button" url="/learn-more">Learn More</block>
</block>
</div>