Vai al contenuto

Creare pagine basate su file

La creazione tradizionale di pagine WordPress avviene nell’editor dei blocchi: si trascinano blocchi, si configurano le impostazioni e si fa clic su Salva. Funziona per i clienti che creano le proprie pagine, ma crea problemi agli sviluppatori che realizzano pagine strutturate e versionate. Il layout della pagina risiede nel database, non nel codice. Non puoi esaminarlo in una pull request, ripristinarlo con git o riprodurlo in una nuova installazione.

Le pagine basate su file di Blockstudio risolvono questo problema. Definisci le pagine come file nel tema, scrivi template HTML che vengono convertiti in blocchi WordPress e controlla con precisione ciò che i clienti possono modificare. Un comando esplicito sincronizza questi file con normali post WordPress, mentre i template restano la fonte attendibile.

Questa guida illustra come creare pagine da zero, concentrandosi in particolare sui controlli di blocco e modifica che rendono pratiche le pagine basate su file per i progetti dei clienti.

La tua prima pagina

Crea una cartella pages nel tema, poi aggiungi una sottocartella con due file:

Codice
theme/
└── pages/
    └── about/
        ├── page.json
        └── index.php
JSON
{
  "name": "about",
  "title": "About Us",
  "postStatus": "publish"
}
HTML
<h1>About Us</h1>
<p>We build things for the web.</p>

Esegui il comando di sincronizzazione delle pagine:

Shell
wp bs pages sync

Blockstudio analizza HTML in blocchi WordPress e crea una pagina chiamata “About Us” con lo slug about. Aprila nell’editor e vedrai un titolo e un paragrafo, proprio come se li avessi aggiunti manualmente.

Modifica index.php, cambia il testo ed esegui di nuovo il comando. Ricarica l’editor per vedere l’aggiornamento. Questo è il ciclo di base: scrivi HTML, sincronizza intenzionalmente e ottieni blocchi.

Il linguaggio dei template

Il parser HTML di Blockstudio converte elementi standard HTML in blocchi WordPress. Scrivi un <p> per ottenere un blocco paragrafo. Scrivi un <h2> per ottenere un blocco titolo. La corrispondenza è intuitiva:

HTML Blocco
<p> Paragrafo
Da <h1> a <h6> Titolo (il livello corrisponde al tag)
<ul>, <ol> Elenco
<blockquote> Citazione
<img> Immagine
<div>, <section> Gruppo
<hr> Separatore
<details> Dettagli
<table> Tabella

Per i blocchi senza un equivalente diretto HTML, usa l’elemento <block> con un attributo name:

HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h2>Hero Title</h2>
  <p>Content over the background image.</p>
</block>

<block name="core/spacer" height="80px" />

<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
  <block name="core/button" url="/work">See Our Work</block>
</block>

Gli attributi degli elementi <block> vengono passati come attributi del blocco. I valori vengono convertiti automaticamente: "true" diventa un booleano, "3" diventa un intero e le stringhe JSON come '{"type":"flex"}' vengono decodificate in oggetti.

Layout

I gruppi supportano diverse modalità di layout tramite l’attributo layout:

HTML
<!-- Default group (stacked) -->
<div>
  <p>Stacked by default.</p>
</div>

<!-- Row (horizontal flex) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
  <p>Side</p>
  <p>by side</p>
</block>

<!-- Stack (vertical flex) -->
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
  <p>Stacked</p>
  <p>with flex</p>
</block>

<!-- Columns -->
<block name="core/columns">
  <block name="core/column">
    <p>Left column.</p>
  </block>
  <block name="core/column">
    <p>Right column.</p>
  </block>
</block>

Blocchi personalizzati

La sintassi <block> funziona con qualsiasi blocco registrato, compresi i tuoi blocchi Blockstudio:

HTML
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />

Gli attributi vengono associati automaticamente ai valori dei campi Blockstudio del blocco.

Creare una landing page

Ecco una landing page completa che usa i blocchi principali per la struttura e il layout:

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "slug": "landing",
  "postStatus": "publish",
  "templateLock": "all"
}
HTML
<block name="core/cover" url="https://images.unsplash.com/photo-1497366216548-37526070297c?w=1600">
  <h1>Build faster with Blockstudio</h1>
  <p>File-based blocks. Zero build step. Full editor integration.</p>
  <block name="core/buttons">
    <block name="core/button" url="/get-started">Get Started</block>
    <block name="core/button" url="/docs">Documentation</block>
  </block>
</block>

<div>
  <h2>Why developers love it</h2>
  <block name="core/columns">
    <block name="core/column">
      <h3>No build step</h3>
      <p>Write PHP, CSS, and JavaScript. No webpack, no bundler, no transpiler.</p>
    </block>
    <block name="core/column">
      <h3>File-based</h3>
      <p>Every block is a folder. Every page is a template. Version control everything.</p>
    </block>
    <block name="core/column">
      <h3>Full editor support</h3>
      <p>Fields, previews, and InnerBlocks work in the block editor out of the box.</p>
    </block>
  </block>
</div>

<block name="core/media-text" mediaurl="https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=800" mediatype="image">
  <h2>Ship entire sites from your IDE</h2>
  <p>Define pages, blocks, and patterns as files. Blockstudio handles the rest.</p>
</block>

<div>
  <h2>Frequently asked questions</h2>
  <details>
    <summary>Do I need to learn React?</summary>
    <p>No. Templates are PHP. Fields are JSON. Interactivity is optional.</p>
  </details>
  <details>
    <summary>Does it work with my existing theme?</summary>
    <p>Yes. Drop a blockstudio folder into any theme and start creating blocks.</p>
  </details>
</div>

<div>
  <block name="core/buttons">
    <block name="core/button" url="/get-started">Start Building</block>
  </block>
</div>

Questa pagina include una sezione hero di copertina, una griglia di funzionalità a tre colonne, una sezione di testo e media, fisarmoniche FAQ e una CTA. Tutto in un unico file HTML. templateLock: "all" in page.json indica che il cliente non può modificare nulla. La sezione successiva spiega come allentare questo vincolo.

Controllare l’editor

È qui che le pagine basate su file mostrano tutto il loro potenziale. Blockstudio offre due controlli indipendenti: blocco del template e modalità di modifica dei blocchi. Insieme, permettono di definire con precisione quali parti di una pagina i clienti possono modificare. Bloccate la struttura, ma lasciate che modifichino il testo. Bloccate alcune sezioni lasciandone altre completamente libere. Create una pagina in cui l’unica cosa che un cliente può fare è inserire testo in tre titoli specifici.

Blocco del template

La proprietà templateLock in page.json controlla le modifiche strutturali: se è possibile aggiungere, rimuovere o riordinare i blocchi.

"all" (predefinito)

JSON
{
  "name": "terms",
  "templateLock": "all"
}

Il blocco più rigido. I clienti non possono aggiungere, rimuovere o spostare blocchi. Non possono nemmeno modificarne il contenuto (a meno che non sia combinato con blockEditingMode). È il valore predefinito se non ne specificate uno.

Quando usarlo: Pagine legali, termini di servizio, informative sulla privacy. Qualsiasi pagina i cui contenuti dovrebbero cambiare solo tramite codice.

"insert"

JSON
{
  "name": "about",
  "templateLock": "insert"
}

I clienti non possono aggiungere o rimuovere blocchi, ma possono spostare quelli esistenti e modificarne il contenuto. Il numero di blocchi rimane invariato, ma l’ordine è flessibile.

Quando usarlo: Pagine con un insieme fisso di sezioni che il cliente può riordinare. Una pagina portfolio con un numero di sezioni prestabilito, ma il cui ordine è deciso dal cliente.

"contentOnly"

JSON
{
  "name": "homepage",
  "templateLock": "contentOnly"
}

I clienti possono modificare il testo, ma non aggiungere, rimuovere o spostare blocchi. La differenza rispetto a "all" è che "all" impedisce anche di modificare i contenuti, mentre "contentOnly" lo consente esplicitamente.

Quando usarlo: La scelta più comune per le pagine destinate ai clienti. Lo sviluppatore controlla il layout. Il cliente inserisce il testo.

false

JSON
{
  "name": "blog",
  "templateLock": false
}

Nessun blocco. I clienti hanno il controllo completo: possono aggiungere, rimuovere, spostare e modificare qualsiasi blocco. Il template fornisce una struttura iniziale, che poi passa sotto il controllo del cliente.

Quando usarlo: Pagine indice del blog, pagine con contenuti liberi o qualsiasi pagina in cui il cliente dovrebbe avere piena libertà editoriale.

Modalità di modifica dei blocchi

Mentre templateLock controlla la struttura (aggiunta, rimozione e spostamento), blockEditingMode controlla l’interazione con i singoli blocchi: se è possibile selezionarli, configurarli o modificarli.

Impostate un valore predefinito a livello di pagina in page.json:

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

"default"

Modifica completa. È possibile selezionare i blocchi, modificarne le impostazioni e i contenuti. È la normale esperienza dell’editor.

"contentOnly"

I blocchi sono modificabili, ma solo per quanto riguarda il testo. Non è possibile aprire le impostazioni dei blocchi, cambiare i colori, regolare la spaziatura interna o modificare attributi che non riguardano i contenuti. La barra degli strumenti del blocco mostra solo le opzioni di formattazione del testo.

"disabled"

I blocchi sono completamente non interattivi. Vengono visualizzati nell’editor, ma non è possibile fare clic su di essi, selezionarli o modificarli in alcun modo. Il cliente vede i contenuti, ma non può intervenire.

Eccezioni per singolo elemento

Ecco la parte interessante. Il valore blockEditingMode a livello di pagina imposta un valore predefinito per ogni blocco della pagina, ma è possibile sovrascriverlo sui singoli elementi del template:

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Heading</h1>
  <p blockEditingMode="contentOnly">Edit this paragraph too.</p>
</block>

<div>
  <h2>Features</h2>
  <p>This paragraph cannot be edited (inherits "disabled").</p>
  <p blockEditingMode="contentOnly">But this one can.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">This button is frozen</block>
</block>

Il valore predefinito della pagina è "disabled", quindi tutti i blocchi sono inizialmente non interattivi. Poi alcuni elementi specifici attivano "contentOnly", rendendo modificabile solo il loro testo. Il risultato è una pagina in cui il cliente può inserire testo esattamente in due campi di testo (il titolo e il paragrafo principale) e in un paragrafo delle caratteristiche. Tutto il resto è bloccato.

Funziona con qualsiasi elemento HTML (<h1>, <p>, <div> e così via) e con gli elementi <block>. È anche possibile impostare blockEditingMode="default" su elementi specifici per consentire la modifica completa:

HTML
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>

Ora il cliente può modificare il testo del pulsante, URL, gli stili e qualsiasi altra impostazione. Tutto il resto della pagina rimane bloccato.

Propagazione agli elementi antenati

C’è un dettaglio importante su come le eccezioni per singolo elemento interagiscono con i blocchi contenitore. Se il valore predefinito della pagina è "disabled" e impostate blockEditingMode="contentOnly" su un titolo all’interno di un gruppo, il titolo deve essere raggiungibile. Ma il gruppo che lo contiene è "disabled", quindi non è possibile accedervi.

Blockstudio gestisce automaticamente questo caso. Quando un blocco figlio ha una modalità di modifica sovrascritta, tutti i suoi blocchi antenati vengono impostati su "contentOnly", così il figlio rimane accessibile. Non serve impostare manualmente le modalità sui contenitori genitori. Basta impostare l’eccezione sul blocco che si vuole rendere modificabile: il percorso per raggiungerlo viene aperto.

HTML
<!-- page default: "disabled" -->
<div>
  <!-- this group is auto-set to "contentOnly" because it contains an override -->
  <div>
    <!-- this group is also auto-set to "contentOnly" -->
    <p blockEditingMode="contentOnly">Deeply nested but still editable.</p>
  </div>
</div>

La propagazione agli antenati porta i contenitori solo a "contentOnly", mai a "default". Ciò significa che è possibile navigare nei gruppi antenati (accedervi), ma non modificarli completamente (non è possibile cambiarne le impostazioni).

Matrice delle opzioni

Combinando templateLock e blockEditingMode si ottengono diversi livelli di controllo. Ecco le combinazioni più utili:

Lo sviluppatore controlla tutto

JSON
{ "templateLock": "all" }

Non serve blockEditingMode. Il valore predefinito templateLock: "all" impedisce qualsiasi modifica. Usatelo per le pagine gestite interamente tramite codice.

Il cliente modifica tutto il testo

JSON
{ "templateLock": "contentOnly" }

Il cliente può modificare il testo in qualsiasi blocco, ma non può cambiare la struttura della pagina. Semplice e permissivo.

Il cliente modifica solo testi specifici

JSON
{
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

Da combinare con blockEditingMode="contentOnly" su elementi specifici del template. È l’opzione più precisa: il cliente può modificare solo i blocchi indicati.

Il cliente riordina sezioni fisse

JSON
{ "templateLock": "insert" }

Il cliente può riordinare le sezioni e modificare i contenuti, ma non aggiungere o eliminare blocchi. È adatto alle pagine con un insieme fisso di sezioni in un ordine flessibile.

Il cliente ha il controllo completo

JSON
{ "templateLock": false }

Il template è un punto di partenza. Da lì il cliente può fare ciò che vuole.

Conservare le modifiche dei clienti

Per impostazione predefinita, quando aggiornate un file di template, Blockstudio sostituisce l’intero contenuto della pagina. Se il cliente ha modificato un titolo nell’editor, la modifica scompare alla sincronizzazione successiva. Va bene per le pagine controllate dallo sviluppatore, ma per quelle a cui contribuiscono i clienti serve un modo per conservare il loro lavoro.

Chiavi

Aggiungete l’attributo key a qualsiasi elemento per indicare che deve essere unito, anziché sostituito:

HTML
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
  <h1>Default Hero Title</h1>
  <p>Default hero description.</p>
</block>

<div key="features">
  <h2>Features</h2>
  <p>Feature introduction text.</p>
</div>

<div>
  <h2>Unkeyed Section</h2>
  <p>This gets replaced on every sync.</p>
</div>

Quando il template cambia e la pagina viene sincronizzata di nuovo:

  • I blocchi con chiave mantengono i contenuti del cliente (testo, blocchi interni, formattazione). Gli attributi strutturali del template (come url della copertina) vengono comunque aggiornati.
  • I blocchi senza chiave vengono sostituiti interamente con la versione del template.

Una chiave protegge l’intero blocco e tutti i suoi elementi figli. Non serve assegnare una chiave ai singoli paragrafi all’interno di un gruppo con chiave: la chiave del gruppo protegge tutto ciò che contiene.

Le chiavi devono essere univoche

Le chiavi devono essere univoche in tutto il template. Se due elementi condividono la stessa chiave, il secondo viene trattato come privo di chiave (e viene emesso un avviso PHP). Usate nomi descrittivi: "hero", "features", "cta", "testimonial-section".

Evoluzione dei template

Le chiavi permettono di aggiungere nuove sezioni a un template senza alterare i contenuti esistenti del cliente:

HTML
<h1 key="title">Welcome</h1>
<div key="services">
  <h2>Our Services</h2>
  <p>We do great work.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<div key="services">
  <h2>Our Services</h2>
  <p>We do great work.</p>
</div>
<div key="testimonials">
  <h2>What Clients Say</h2>
  <p>Default testimonial text.</p>
</div>

Durante la sincronizzazione, il titolo e i servizi mantengono le modifiche del cliente. La nuova sezione delle testimonianze viene aggiunta con i contenuti predefiniti del template. Se in seguito rimuovete un blocco con chiave dal template, viene eliminato anche dalla pagina.

Il flusso di lavoro completo con il cliente

Ecco come mettere tutto insieme in un progetto reale:

JSON
{
  "name": "homepage",
  "title": "Home",
  "slug": "home",
  "postStatus": "publish",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
  <h1 blockEditingMode="contentOnly">Your Company Name</h1>
  <p blockEditingMode="contentOnly">Your tagline goes here.</p>
  <block name="core/buttons">
    <block name="core/button" url="/contact">Contact Us</block>
  </block>
</block>

<div key="features">
  <h2 blockEditingMode="contentOnly">What We Do</h2>
  <block name="core/columns">
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service One</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service Two</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service Three</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
  </block>
</div>

<block name="core/media-text" key="about" mediaurl="https://example.com/team.jpg" mediatype="image">
  <h2 blockEditingMode="contentOnly">About Us</h2>
  <p blockEditingMode="contentOnly">Tell your story here.</p>
</block>

<div key="cta">
  <h2 blockEditingMode="contentOnly">Ready to get started?</h2>
  <block name="core/buttons">
    <block name="core/button" url="/contact">Get in Touch</block>
  </block>
</div>

Questa pagina ha quattro sezioni con chiave. Il cliente può modificare i titoli e i paragrafi contrassegnati con blockEditingMode="contentOnly", e le modifiche vengono mantenute dopo gli aggiornamenti del template. Lo sviluppatore controlla il layout, le immagini, gli URL dei pulsanti e la struttura generale. Se in seguito lo sviluppatore aggiunge una sezione delle testimonianze tra “about” e “cta”, questa appare alla sincronizzazione successiva senza alterare i testi del cliente.

Associazioni dei blocchi: un’alternativa alle chiavi

WordPress 6.5 ha introdotto Associazioni dei blocchi API, che collegano gli attributi dei blocchi ai metadati dei post. Invece di salvare i contenuti modificabili nel markup del blocco, dove sono protetti dalle chiavi, i contenuti risiedono in wp_postmeta, dove la sincronizzazione dei template non può modificarli.

HTML
<h1 metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'>
  Default Title
</h1>

<p metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'>
  Default description.
</p>

Le chiavi dei metadati devono essere registrate in PHP:

PHP
register_post_meta( 'page', 'hero_title', array(
    'show_in_rest' => true,
    'single'       => true,
    'type'         => 'string',
    'default'      => 'Default Title',
) );

Le associazioni dei blocchi hanno due vantaggi rispetto alle chiavi: i dati sono consultabili con WP_Query tramite meta_query e sono disponibili nel REST API. Il compromesso è che bisogna registrare ogni chiave dei metadati in PHP e che le associazioni funzionano solo con singoli attributi dei blocchi (non con contenuti annidati complessi).

Usate le chiavi per le sezioni con contenuti articolati, quando la struttura del blocco è importante (un gruppo con titoli, paragrafi e immagini). Usate le associazioni per i singoli valori di testo che devono anche essere consultabili o visualizzati altrove.

Template per tipi di post

Usate templateFor per impostare una struttura di blocchi predefinita per tutti i nuovi post di un determinato tipo:

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}
HTML
<h1>Product Name</h1>

<block name="core/columns">
  <block name="core/column">
    <img src="" alt="Product image" />
  </block>
  <block name="core/column">
    <p>Product description goes here.</p>
    <block name="core/buttons">
      <block name="core/button" url="#">Buy Now</block>
    </block>
  </block>
</block>

<div>
  <h2>Specifications</h2>
  <table>
    <thead>
      <tr><th>Feature</th><th>Value</th></tr>
    </thead>
    <tbody>
      <tr><td>Weight</td><td>1.2 kg</td></tr>
    </tbody>
  </table>
</div>

Ogni nuovo post di tipo “product” inizia con questa struttura. Il valore templateLock: "insert" permette agli editor di riordinare le sezioni e modificare i contenuti, ma non di aggiungere o rimuovere blocchi.

Suggerimenti

Sincronizzate in corrispondenza di un momento di rilascio pianificato. Eseguite wp bs pages sync dopo aver modificato o distribuito le sorgenti delle pagine. Le visite al frontend e all’area di amministrazione non sincronizzano mai le pagine. Gli strumenti di distribuzione PHP possono chiamare Blockstudio\Pages::reconcile() e analizzarne il rapporto leggibile dalle macchine.

Bloccate gli ID dei post importanti. Usate postId in page.json per le pagine richiamate da menu, link hardcoded o sistemi esterni. Senza bloccare l’ID, una pagina eliminata e ricreata ne riceve uno nuovo, interrompendo tali riferimenti.

Usate sync: false per le strutture iniziali. Se volete creare una pagina una sola volta e poi affidarla interamente al cliente, impostate "sync": false e createla con Blockstudio\Pages::force_sync(). La riconciliazione normale la ignorerà.

Bloccate e sbloccate con PHP. Chiamate Blockstudio\Pages::lock('about') per impedire la sincronizzazione di una pagina specifica (utile durante i periodi di modifica da parte del cliente). Chiamate Blockstudio\Pages::unlock('about') per riattivare la sincronizzazione.

Motori di template. Oltre a PHP, è possibile scrivere template in Twig (richiede Timber) o in Blade (richiede illuminate/view). Sono utili per cicli e filtri, ma i template delle pagine vengono compilati durante la sincronizzazione esplicita, non durante la richiesta frontend. Scegliete PHP se la compilazione delle sorgenti richiede helper esclusivi di PHP.

La sincronizzazione forzata ignora le chiavi. La chiamata a Pages::force_sync('about') sostituisce l’intero contenuto della pagina, ignorando le chiavi e i controlli sulla data di modifica. Usatela quando volete riportare intenzionalmente una pagina allo stato del template.

Passaggi successivi

  • Riferimento di Pages: tutte le proprietà page.json, il PHP API e l’algoritmo di unione tramite chiavi, nel dettaglio.
  • Panoramica di Pages e Patterns: il parser HTML, il riferimento alla sintassi dei blocchi, i renderer personalizzati e la mappatura degli elementi.
  • Patterns: la stessa sintassi dei template per i pattern di blocchi riutilizzabili, anziché per le pagine.