Vai al contenuto

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_template e wp_template_part basate 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

Codice
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>:

HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h1>Welcome</h1>
  <p>Content inside the cover block.</p>
</block>

Blocchi principali

HTML
<!-- 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:

HTML
<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:

HTML
<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="[&amp;>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:

PHP
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:

HTML
<block name="acf/hero" background="dark">
  <h1>Welcome</h1>
</block>

Potete anche sovrascrivere il rendering dei blocchi principali:

PHP
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

PHP
/**
 * @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:

PHP
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:

PHP
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:

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