Pagine
Le pagine sono template basati su file che vengono sincronizzati con il database di WordPress come post. La sincronizzazione è esplicita: eseguite wp bs pages sync o richiamate API Pages quando intendete applicare le modifiche alla fonte. Il caricamento del frontend o dell’amministrazione di WordPress non esegue mai l’individuazione completa delle pagine né modifica i post delle pagine.
Le pagine possono essere definite in un’unica cartella page.json, come file Markdown autonomi oppure come raccolta con un manifest pages.json. Le raccolte sono utili per documentazione, basi di conoscenza, raccolte di landing page o qualsiasi insieme di pagine annidate da generare a partire da file.
page.json
Per una pagina definita da JSON, aggiungete un file di configurazione page.json:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
Proprietà
| Proprietà | Tipo | Predefinito | Descrizione |
|---|---|---|---|
name |
string |
obbligatorio | Identificatore univoco della pagina |
title |
string |
Automatico dal nome | Titolo della pagina |
slug |
string |
Uguale al nome | Slug URL della pagina |
path |
string |
"." |
Percorso logico all’interno di una raccolta |
order |
integer |
0 |
Ordine nel menu del post sincronizzato |
postType |
string |
"page" |
Tipo di post WordPress |
postStatus |
string |
"draft" |
Stato dei nuovi post (publish, draft, pending, private) |
postId |
integer |
– | Associa la pagina a un ID di post WordPress specifico |
blockEditingMode |
string |
– | Modalità di modifica dei blocchi: "default", "contentOnly" o "disabled" |
templateLock |
string|false |
"all" |
Modalità di blocco: "all", "insert", "contentOnly" o false |
templateFor |
string|null |
null |
Imposta come modello predefinito per un tipo di post |
sync |
boolean |
true |
Indica se la riconciliazione esplicita normale può creare o aggiornare il post |
render |
string|object|false |
– | Esegue il rendering della pagina con un renderer di pagine registrato (vedi Pagine dei componenti) |
Tra page.json, il frontmatter e le voci del loader, le chiavi riconosciute includono blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock e title. Ogni chiave non elencata sopra viene salvata nell’array meta della pagina.
Fonti dei contenuti
Una definizione di pagina stabilisce quale post WordPress deve esistere. La fonte del contenuto determina quale markup dei blocchi viene scritto in quel post.
Quando una cartella di pagina contiene un file page.json, Blockstudio cerca un file sorgente nella stessa cartella, seguendo quest’ordine:
| File | Utilizzo |
|---|---|
index.php |
Markup a blocchi simile a HTML, letto così com’è (il codice PHP non viene eseguito) |
index.blade.php |
Contenuto del template Blade |
index.twig |
Contenuto del template Twig |
index.md |
Contenuto Markdown |
page.json può anche fornire contenuti markdown o html in linea invece di un file nella stessa cartella:
{
"name": "intro",
"title": "Intro",
"markdown": "# Intro\n\nThis page is generated from inline markdown."
}
{
"name": "notice",
"title": "Notice",
"html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}
Le raccolte aggiungono altre due modalità di origine:
- File Markdown individuati direttamente nella struttura di cartelle della raccolta.
- Voci del loader restituite da
loader.php.
Le voci del loader possono usare markdown, html o content con contentType. Possono anche puntare a un file file o template locale. Il tipo delle fonti file e template viene dedotto dall’estensione, a meno che contentType non sia impostato esplicitamente.
I valori contentType supportati sono php, blade, twig, markdown e html. Markdown viene prima convertito in HTML, poi analizzato e trasformato in blocchi nativi WordPress. Le fonti PHP, Blade, Twig e HTML passano invece per il normale parser di pagine Blockstudio.
Classi nei blocchi core
Un class su un elemento HTML mappato a un blocco core diventa il suo className.
Un tag esplicito di blocco core può usare direttamente className. Entrambe le forme mantengono le classi nel wrapper salvato del blocco, insieme alle classi generate da WordPress:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
Se sono presenti entrambe le proprietà, className ha la precedenza. Questa conversione si applica solo ai blocchi core: una mappatura di blocchi personalizzati mantiene invariato il campo class. Le classi di stile dei pulsanti, come is-style-outline, appartengono al wrapper del pulsante, non al suo link.
Eseguite wp bs pages sync per applicare le correzioni del parser alle pagine sincronizzate in precedenza. Gli aggiornamenti del parser vengono rilevati alla successiva sincronizzazione esplicita, anche senza modifiche ai file sorgente. Le pagine bloccate e quelle con sync: false mantengono le normali protezioni; le richieste frontend non eseguono mai questa sincronizzazione.
Blocchi WordPress serializzati
Anche le fonti di pagine e pattern possono contenere blocchi serializzati copiati dall’editor di codice WordPress:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
Quando la sorgente contiene un delimitatore di blocco <!-- wp:... -->, Blockstudio
usa il parser di blocchi nativo di WordPress per l’intera sorgente. Gli attributi,
i blocchi annidati, i blocchi dinamici come Query Loop e i blocchi Blockstudio
mantengono la propria struttura serializzata. Il contenuto HTML al di fuori dei commenti di blocco resta HTML libero nativo; non viene mappato in blocchi aggiuntivi. Non mescolare i tag di blocco HTML di Blockstudio con questo formato aspettandosi che vengano convertiti. I normali commenti HTML non attivano la modalità a blocchi serializzati.
Pagine Markdown
Usate Markdown quando il testo deve risiedere nei file ma diventare comunque contenuto modificabile nei blocchi WordPress dopo la sincronizzazione. La fonte Markdown viene convertita in markup a blocchi durante la sincronizzazione. Il post sincronizzato memorizza i blocchi, non il corpo Markdown grezzo.
Markdown può essere usato in tre modi:
| Fonte | Dati iniziali obbligatori? | Note |
|---|---|---|
File pages/example/index.md autonomo |
Sì | I dati iniziali forniscono l’identità della pagina. |
page.json più index.md |
No | page.json definisce la pagina e Markdown fornisce il contenuto. |
| Markdown all’interno di una raccolta | No | La raccolta deduce name e path dalla posizione del file. |
Un file index.md autonomo senza dati iniziali viene ignorato perché Blockstudio non ha un’identità di pagina da sincronizzare. I file Markdown di una raccolta non richiedono dati iniziali, perché il manifest della raccolta e il percorso del file forniscono tale identità.
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
Potete anche abbinare page.json a index.md. In tal caso, page.json definisce la pagina e index.md ne fornisce il contenuto. I dati iniziali in index.md sostituiscono i valori corrispondenti di page.json.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
title: API Reference
order: 20
---
# Reference
This page uses `page.json` with Markdown content.
Per le pagine Markdown di una raccolta, il percorso del file diventa il percorso logico della pagina, a meno che non venga sostituito dai dati iniziali:
| File | Percorso predefinito |
|---|---|
pages/docs/index.md |
. |
pages/docs/getting-started.md |
getting-started |
pages/docs/guide/install/index.md |
guide/install |
pages/docs/guide/install.md |
guide/install |
Le chiavi dei dati iniziali sconosciute vengono conservate nell’array meta della pagina. In questo modo potete aggiungere dati come section o description e leggerli dal PHP API.
Markdown viene analizzato come GitHub Flavored Markdown. È consentito HTML grezzo, i link non sicuri vengono rimossi e alle intestazioni senza un ID esplicito ne viene assegnato uno stabile. I dati iniziali YAML annidati richiedono il parser YAML incluso.
Markdown grezzo
Le fonti da file Markdown possono esporre la fonte originale Markdown per strumenti esterni e sistemi che utilizzano la documentazione. Markdown in linea non ha un file sorgente, quindi viene sincronizzato in blocchi ma non produce una risposta .md grezza.
Richiedete la pagina con il suffisso .md, ad esempio https://example.com/docs/reference.md. In alternativa, inviate un’intestazione Accept: text/markdown alla normale pagina URL:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
I dati iniziali vengono rimossi dalla risposta. Le risposte Markdown grezze riuscite inviano Content-Type: text/markdown, X-Robots-Tag: noindex e un’intestazione Link canonica alla pagina HTML. Le route .md mancanti restituiscono un vero 404.
La negoziazione funziona con il prerendering statico: una richiesta la cui intestazione Accept contiene text/markdown non riceve mai risposta dall’archivio di prerendering né dal drop-in di risposta anticipata, quindi raggiunge WordPress e il gestore Markdown. Le risposte HTML prerenderizzate, la HTML di una pagina che negozia anche Markdown e la Markdown gestita tramite Accept inviano Vary: Accept, così le cache che rispettano Vary le mantengono separate. Un CDN che basa la cache solo su URL deve applicare una propria regola per ignorare la cache per queste richieste. Pages::negotiates_markdown( $post_id ) indica se una pagina risponde alle richieste Markdown.
Le pagine Markdown di una raccolta mantengono la stessa struttura URL per Markdown grezzo:
| Pagina URL | Markdown URL grezzo |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
Disabilitate le risposte Markdown grezze con il filtro blockstudio/pages/serve_markdown:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Una richiesta .md URL che non corrisponde a una pagina basata su Markdown restituisce un 404 solo quando il percorso rientra in una raccolta di pagine. Fuori da tutte le raccolte, Blockstudio lascia la richiesta a WordPress e agli altri plugin affinché la gestiscano.
Pagine dei componenti
Una pagina componente viene renderizzata da un renderer di pagine invece di essere salvata come blocchi. Blockstudio non include un renderer. Un tema o un plugin ne registra uno per i file di ingresso che gestisce, ad esempio un renderer React per page.tsx, e Blockstudio lo richiama passandogli la pagina, il post WordPress e il contenuto dello slot renderizzato.
pages/legal-notice/
page.json
page.tsx
data.php
{
"name": "legal-notice",
"title": "Legal Notice",
"slug": "legal-notice",
"postStatus": "publish",
"render": { "entry": "page.tsx", "data": "data.php" }
}
render è esplicito. Una directory con un index.php e un page.tsx ma senza render resta una normale pagina, quindi l’aggiunta di un renderer non renderizza due volte una pagina esistente. Le forme sono:
| Valore | Significato |
|---|---|
"page.tsx" |
Solo file di ingresso, senza loader di dati |
{ "entry": "page.tsx", "data": "data.php" } |
File di ingresso e loader di dati |
{ "entry": "page.tsx", "renderer": "react" } |
File di ingresso con un ID renderer esplicito |
false |
Nessun renderer, anche se un valore predefinito della raccolta ne specifica uno |
I percorsi vengono risolti in base alla directory della pagina oppure, per le voci del loader, alla radice della raccolta. Devono rimanere all’interno della sorgente di rilevamento, salvo autorizzazione di blockstudio/pages/allow_external_loader_path. In assenza di renderer, viene usato il renderer che gestisce l’estensione della voce. Una render che specifica una voce o un file di dati mancante, un renderer sconosciuto o un’estensione non gestita da alcun renderer causa un errore di rilevamento, che interrompe la riconciliazione prima che venga eliminato alcunché.
Cosa salva la sincronizzazione
La sincronizzazione salva un blocco blockstudio/page. Se nella directory della pagina è presente anche una sorgente index.*, questa viene analizzata come qualsiasi sorgente di pagina e diventa i blocchi interni del blocco, ovvero il suo slot:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
Mantenete nello slot i contenuti gestiti da WordPress, come gli shortcode. Una sorgente che contiene un solo shortcode, come [download_checkout], viene salvata come blocco core/shortcode, quindi il suo output non viene racchiuso in un paragrafo. Resta in post_content, così i controlli di has_shortcode() possono individuarlo, i blocchi con chiave nello slot si fondono con le modifiche dell’editor come gli altri blocchi annidati con chiave, e do_shortcode espande gli shortcode una sola volta, con la consueta priorità the_content, dopo che il renderer li ha racchiusi.
La definizione del rendering viene salvata con il post come percorsi theme: portabili. L’impronta digitale della pagina copre la definizione, non i byte del file di ingresso o del loader di dati: modificando page.tsx o data.php il post resta invariato e le modifiche arrivano ai visitatori tramite il rendering e il prerendering statico del grafo, che registra il file di ingresso, il loader di dati e ogni file segnalato dal renderer.
Registrare un renderer
Registrate i renderer nell’azione blockstudio/pages/renderers. Viene eseguita una volta per richiesta, prima del primo rilevamento o rendering, così wp bs pages sync e le richieste frontend vedono lo stesso registro.
add_action(
'blockstudio/pages/renderers',
static function (): void {
Blockstudio\Page_Renderers::register(
'react',
array(
'extensions' => array( 'tsx' ),
'layouts' => array( 'layout.tsx' ),
'render' => 'my_theme_render_page',
)
);
}
);
Gli ID dei renderer sono in minuscolo. Un’estensione o un nome di layout può appartenere a un solo renderer, e layout.php resta un layout di proprietà di Blockstudio. La funzione richiamabile riceve una richiesta:
| Chiave | Valore |
|---|---|
kind |
page, oppure layout per un layout del renderer layout |
renderer |
ID del renderer |
entry |
Percorso assoluto del file di ingresso |
data |
Percorso assoluto del loader di dati, oppure null |
page |
Dati canonici della pagina, inclusi meta |
post_id |
ID del post WordPress |
slot |
Contenuto renderizzato dello slot o contenuto della pagina per un layout |
context |
frontend, rest, feed o cli |
Restituisce HTML, i file letti durante il rendering e le risorse facoltative:
function my_theme_render_page( array $request ): array {
return array(
'html' => '<main>...</main>',
'dependencies' => array( '/abs/path/to/a/file/the/render/read.tsx' ),
'assets' => array( array( 'path' => '/abs/path/to/page.js' ) ),
);
}
context deriva dal tipo di richiesta e mai dal visitatore, quindi un renderer non può compromettere la parità di byte tra utenti autenticati e anonimi leggendolo. Se un renderer non riesce, genera un errore: la pagina non viene renderizzata con un corpo vuoto. In un’anteprima dell’editor REST, invece, il blocco mostra l’errore come avviso. Dopo il rendering riuscito, l’azione blockstudio/pages/rendered riceve la pagina, HTML e le relative dipendenze.
assets elenca i file di script e stile necessari alla pagina. Vengono elaborati come gli asset dei blocchi (con la convenzione *.inline.*, i moduli ES, la minimizzazione e ?ver) e stampati una sola volta dalla pagina tramite lo stesso buffer usato per gli asset dei blocchi, così sono inclusi anche nelle pagine prerenderizzate. Un asset può impostare version per sostituire il valore ?ver. Il codice esterno a un renderer può usare lo stesso canale tramite Blockstudio\Assets::register_owner(), che restituisce il commento marcatore da stampare.
Editor
Nell’editor, blockstudio/page mostra un’anteprima server-rendered della pagina, con lo slot come blocchi interni che seguono templateLock della pagina. Il blocco non può essere inserito, duplicato o annidato in un altro blocco.
Raccolte di pagine
Una raccolta è una cartella con un manifest pages.json. Riunisce molte fonti di pagina sotto un unico slug di raccolta, applica valori predefiniti, supporta percorsi annidati e può registrare automaticamente un tipo di post dedicato.
pages/
docs/
pages.json
layout.php
index.md
guide/
install/
index.md
reference/
page.json
index.md
loader.php
{
"collection": "docs",
"title": "Documentation",
"postType": "bs_docs",
"postTypeArgs": {
"label": "Docs",
"rewrite": {
"slug": "docs"
},
"supports": ["title", "editor", "page-attributes"]
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
| Proprietà | Tipo | Descrizione |
|---|---|---|
collection / slug / name |
string |
Slug della raccolta. collection è la forma più chiara e diventa la base pubblica di URL. |
title |
string |
Titolo leggibile della raccolta. |
postType |
string |
Tipo di contenuto per le pagine generate. Il valore predefinito è page. Se non esiste, Blockstudio lo registra. |
postTypeArgs |
object |
Argomenti passati a register_post_type() quando Blockstudio registra il tipo di contenuto della raccolta. |
defaults |
object |
Proprietà predefinite della pagina applicate a ogni pagina della raccolta. Un render predefinito viene applicato a una pagina solo se la relativa voce esiste nella directory delle pagine. |
scope |
string |
collection (predefinito) oppure site. Consultate Raccolte del sito. |
meta |
object |
Metadati personalizzati della raccolta. Anche le chiavi del manifest sconosciute vengono memorizzate in meta. |
I percorsi delle pagine di una raccolta sono percorsi logici. Una pagina con path: "guide/install" viene sincronizzata come figlia di guide, mentre guide viene sincronizzata come figlia della radice della raccolta, se quelle pagine principali esistono.
Se una raccolta gerarchica contiene una pagina annidata ma la fonte di una pagina intermedia non esiste, Blockstudio genera una pagina contenitore vuota per quel percorso, mantenendo completa la gerarchia WordPress. I tipi di post non gerarchici (quelli senza supporto per page-attributes) non generano contenitori vuoti. Usano il percorso della raccolta memorizzato per instradare le richieste, quindi percorsi annidati come guide/install e setup/install possono coesistere anche se terminano entrambi con install.
Tipi di post e URL delle raccolte
Impostate postType nel manifest della raccolta per sincronizzare ogni pagina della raccolta con quel tipo di post. Non è necessario ripetere lo stesso valore in defaults. Le singole pagine possono comunque sovrascrivere postType nei dati iniziali o in page.json.
Quando il tipo di post non esiste, Blockstudio lo registra con show_in_rest: true, una configurazione dell’editor simile a quella delle pagine e lo slug della raccolta come base pubblica URL. postTypeArgs può sovrascrivere gli argomenti di registrazione. Le regole di riscrittura del tipo di post della raccolta vengono aggiornate automaticamente quando cambiano i tipi di post registrati o gli argomenti di riscrittura, quindi non è necessario salvare di nuovo i permalink di WordPress.
Gli URL delle raccolte usano lo slug della raccolta seguito dal percorso logico di ogni pagina path:
| Percorso sorgente | Pubblico URL |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
Questo modello URL funziona sia con i tipi di contenuto delle raccolte gerarchici sia con quelli non gerarchici. Blockstudio reindirizza anche gli URL duplicati, come /docs/docs/ o /docs/docs/getting-started/, all’URL canonico URL.
Le pagine delle raccolte espongono Markdown grezzi agli stessi URL (vedere Markdowngrezzi).
Se trasformate una raccolta da postType: "page" in un tipo di contenuto personalizzato, Blockstudio migra sul posto i contenuti della raccolta già sincronizzati, se la loro identità di pagina memorizzata corrisponde. In questo modo conserva gli ID dei contenuti, i metadati e i contenuti esistenti, evitando al contempo i duplicati con il vecchio tipo. I contenuti obsoleti della raccolta vengono ripuliti in tutti gli stati, secondo il filtro blockstudio/pages/orphan_action.
Raccolte del sito
Un manifest con "scope": "site" raggruppa tutte le pagine sottostanti senza trasformarle in pagine di raccolta. Usatelo nella radice dell’albero delle pagine di un sito per applicare impostazioni predefinite condivise e per elencare le pagine del sito con blockstudio_page_tree( 'my-site' ).
{
"collection": "my-site",
"title": "My Site",
"scope": "site",
"defaults": {
"postStatus": "publish",
"templateLock": "all",
"render": { "entry": "page.tsx", "data": "data.php" }
}
}
Le pagine di una raccolta del sito mantengono esattamente la stessa identità che hanno senza il manifest, quindi aggiungerne una a un albero esistente non aggiorna le righe dei post e non crea né elimina nulla:
- Le chiavi restano globali:
Pages::get_page( 'home' )e le chiavi delle pagine memorizzate continuano a corrispondere. - Gli URL restano URL di pagina WordPress. Non si applicano regole di riscrittura della raccolta, filtri dei permalink o reindirizzamenti con URL raddoppiato, e non vengono generate pagine contenitore vuote.
- I percorsi logici, gli slug, le pagine genitrici e le identità delle sorgenti restano quelli delle pagine autonome; i layout vengono risolti in base all’antenato più vicino.
- I manifest
pages.jsonannidati mantengono le proprie raccolte e i relativi sottoalberi vengono esclusi dalla raccolta del sito. - I valori predefiniti vengono applicati a ogni pagina: un
renderpredefinito viene applicato solo alle pagine la cui directory contiene la relativa voce, quindi le pagine shortcode e Markdown conservano le proprie sorgenti.
Caricatori delle raccolte
Le raccolte possono includere un loader.php locale attendibile. Usatelo quando le pagine della raccolta provengono da un’altra origine locale, ad esempio una cartella di documentazione esterna, un pacchetto o un manifest generato.
Il caricatore viene eseguito durante l’individuazione e la sincronizzazione esplicite delle pagine. Deve essere deterministico e locale. Evitate di recuperare contenuti remoti da loader.php, perché la sincronizzazione della distribuzione dipenderebbe da quel servizio.
<?php
return array(
'meta' => array(
'source' => 'loader',
),
'paths' => array(
__DIR__ . '/external-docs',
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
'pages' => array(
array(
'name' => 'docs-api',
'title' => 'API',
'path' => 'api',
'content' => "# API\n\nGenerated markdown content.",
'contentType' => 'markdown',
),
array(
'name' => 'docs-template',
'title' => 'Template',
'path' => 'template',
'file' => __DIR__ . '/template.md',
),
),
);
Un caricatore può restituire un array con le chiavi pages, meta e paths:
| Chiave | Descrizione |
|---|---|
pages |
Elenco di array di pagine. Ogni pagina supporta le stesse chiavi riconosciute del frontmatter page.json e Markdown. |
meta |
Metadati uniti all’array meta di ogni pagina generata dal loader. |
paths |
Directory locali aggiuntive da individuare come parte di questa raccolta. Le voci possono essere stringhe o oggetti percorso. |
render |
Una definizione di rendering per ogni pagina Markdown individuata a partire da paths. |
Come scorciatoia, il caricatore può restituire un semplice elenco di array di pagine.
Le voci delle pagine del caricatore possono fornire contenuti nei modi seguenti:
| Forma | Descrizione |
|---|---|
markdown |
Contenuto Markdown incorporato. |
html |
Contenuto HTML incorporato. |
content + contentType |
Contenuto incorporato generico. contentType deve risolversi in markdown o html. |
file |
Origine da file locale. Il tipo viene dedotto dall’estensione, salvo quando è impostato contentType. |
template |
Alias di file. |
I riferimenti ai file del caricatore possono puntare a origini PHP, Blade, Twig, Markdown o HTML. I percorsi relativi vengono risolti rispetto alla radice della raccolta. I percorsi assoluti e quelli esterni alla radice della raccolta sono consentiti solo se il filtro blockstudio/pages/allow_external_loader_path lo permette.
Per impostazione predefinita, le pagine del caricatore sono generated: true. Quando una pagina generata dal caricatore scompare dall’output, alla sincronizzazione successiva Blockstudio tratta il contenuto sincronizzato come orfano e lo ripulisce secondo il filtro blockstudio/pages/orphan_action.
Le directory elencate in paths vengono individuate come le normali cartelle delle raccolte. Possono contenere file Markdown o cartelle page.json. Se questi percorsi sono esterni alla radice della raccolta, si applica lo stesso filtro per i percorsi esterni.
Usate una voce stringa quando la directory esterna deve mantenere i propri percorsi logici. Usate una voce oggetto quando la directory deve essere montata sotto un prefisso di percorso della raccolta:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
Con questa configurazione, nella raccolta cli-docs/index.md diventa path: "cli" e cli-docs/getting-started.md diventa path: "cli/getting-started". I prefissi rendono inoltre univoci i nomi delle pagine generate, consentendo a più directory montate di contenere ciascuna index.md o getting-started.md. Impostate preserveNames su true nell’oggetto percorso se volete mantenere i valori name espliciti dal frontmatter page.json o Markdown.
Proprietà dell’oggetto percorso:
| Proprietà | Tipo | Descrizione |
|---|---|---|
path |
string |
Directory locale da individuare. I percorsi relativi vengono risolti a partire dalla radice della raccolta. |
prefix |
string |
Prefisso facoltativo del percorso logico all’interno della raccolta. |
preserveNames |
boolean |
Mantiene i nomi espliciti delle pagine invece di generarli dal percorso con prefisso. Il valore predefinito è false quando è impostato prefix. |
meta |
object |
Metadati uniti a ogni pagina individuata a partire da questo percorso. I metadati della pagina prevalgono in caso di chiavi duplicate. |
render |
string|object |
Definizione di rendering per le pagine Markdown di questo percorso, che sostituisce quella del loader render. |
Rendering di Markdown tramite un componente
Con render, le pagine Markdown individuate da un loader vengono renderizzate tramite un renderer di pagina invece di essere memorizzate come blocchi:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
Restano pagine Markdown: il tipo di contenuto, il percorso del contenuto, le risposte .md e il frontmatter non cambiano. La sincronizzazione memorizza un blocco blockstudio/page il cui HTML interno è il Markdown convertito, sanificato se la raccolta sanifica i propri contenuti, al posto dei blocchi analizzati. In questo modo post_content conserva il testo del documento. Il renderer riceve questo HTML come slot e può leggere la sorgente da page.content_path. I percorsi relativi vengono risolti a partire dalla radice della raccolta; il filtro dei percorsi esterni si applica come per i percorsi. Una pagina il cui frontmatter imposta un proprio render o render: false viene esclusa.
Layout
Un file layout.php avvolge il rendering frontend di una pagina basata su file. Non sostituisce il post_content sincronizzato memorizzato in WordPress e non avvolge l’area di modifica. Il layout viene eseguito solo nelle richieste frontend di pagine singole.
Per le raccolte, posizionate layout.php accanto a pages.json per avvolgere tutte le pagine frontend della raccolta:
<?php $current = blockstudio_current_page(); ?>
<main class="docs-layout">
<aside>
<?php foreach (blockstudio_page_tree('docs') as $item) : ?>
<?php $is_current = ($item['post_id'] ?? null) === ($current['post_id'] ?? null); ?>
<a
href="<?php echo esc_url($item['permalink'] ?? '#'); ?>"
<?php echo $is_current ? 'aria-current="page"' : ''; ?>
>
<?php echo esc_html($item['title']); ?>
</a>
<?php endforeach; ?>
</aside>
<article>
<?php echo blockstudio_page_content(); ?>
</article>
</main>
blockstudio_page_content() stampa il corpo della pagina che WordPress normalmente eseguirebbe tramite the_content. Se un layout non produce blockstudio_page_content(), il contenuto della pagina viene nascosto intenzionalmente.
I layout possono usare le funzioni helper della pagina:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
Anche le pagine nidificate non appartenenti a una raccolta possono ereditare il layout.php antenato più vicino all’interno dell’albero pages. Per le pagine delle raccolte, il layout della radice della raccolta viene memorizzato in ogni contenuto sincronizzato e monitorato come parte dell’impronta della pagina, perciò le modifiche al layout vengono recepite alla sincronizzazione successiva.
Layout del renderer
Un layout può anche essere una voce del renderer, ad esempio layout.tsx per un renderer che registra layouts: ["layout.tsx"]. Si trova nelle stesse posizioni di layout.php e, se presente, il file layout.data.php accanto ad esso funge da loader dei dati. Al momento del rendering, il renderer riceve kind: "layout" e il contenuto renderizzato della pagina come slot, con la stessa priorità the_content di layout.php. Una directory può contenere layout.php oppure un layout del renderer, ma non entrambi; se li contiene entrambi, si verifica un errore di individuazione. In caso di errore del layout viene attivato blockstudio/pages/layout_error e il contenuto della pagina resta senza wrapper, come avviene per layout.php.
Modalità di modifica dei blocchi
La proprietà blockEditingMode controlla come si possono modificare i blocchi nell’editor. Impostate un valore predefinito a livello di pagina in page.json e sovrascrivetelo per ogni elemento nel template:
{
"name": "about",
"title": "About Us",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
| Valore | Descrizione |
|---|---|
"default" |
Modifica completa. È possibile selezionare, spostare e modificare i blocchi |
"contentOnly" |
Solo modifica del testo. Il testo dei blocchi è modificabile, ma le impostazioni e la struttura sono bloccate |
"disabled" |
Nessuna modifica. I blocchi sono completamente non interattivi |
Le sovrascritture per elemento si impostano come attributi HTML su qualsiasi elemento (<h1>, <p>, <div> ecc.) o sugli elementi <block>. I blocchi contenitore antenati degli elementi sovrascritti vengono impostati automaticamente su contentOnly, così i relativi elementi figlio restano accessibili. Questa propagazione risale dall’elemento sovrascritto fino alla radice della pagina: dovete quindi impostare blockEditingMode solo sugli elementi che volete rendere modificabili.
Blocco del template
La proprietà templateLock controlla come gli utenti possono modificare la pagina nell’editor:
| Valore | Aggiunta/Rimozione | Spostamento | Modifica del contenuto |
|---|---|---|---|
"all" |
No | No | No |
"insert" |
No | Sì | Sì |
"contentOnly" |
No | No | Sì |
false |
Sì | Sì | Sì |
Quando è impostato templateLock, Blockstudio disabilita la possibilità di sbloccare i blocchi tramite UI dell’editor.
Percorsi virtuali
Alcuni documenti non hanno un contenuto associato: un riferimento a componenti generato dai dati, un catalogo o un’area account. Registrateli come percorsi virtuali invece di agganciare voi stessi template_redirect:
add_action( 'init', function () {
Blockstudio\Virtual_Routes::register(
'components',
function ( $component, string $rest ) {
get_header();
echo my_component_page( $component );
get_footer();
},
[
'prefix' => true,
'match' => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
'title' => fn ( $component ) => my_component_title( $component ),
'urls' => fn () => my_component_paths(),
]
);
} );
Il percorso è relativo alla home del sito. Con prefix, il percorso serve anche tutte le posizioni al di sotto di esso e match riceve la parte restante (una stringa vuota per il percorso stesso) e restituisce il valore ricevuto dalla callback di rendering oppure null per lasciare la URL a WordPress, che risponde quindi a 404 come al solito. La callback di rendering stampa il documento o lo restituisce come stringa; title è una stringa o una closure che riceve il valore corrispondente.
Per una richiesta corrispondente, Blockstudio impedisce a WordPress di segnalare una 404 e a redirect_canonical di reindirizzarla, azzera lo stato di pagina singola riportato dalla query principale, invia lo stato (status, 200 per impostazione predefinita) ed esegue il rendering con priorità template_redirect Virtual_Routes::PRIORITY. Ciò avviene subito dopo l’apertura del buffer di output di Blockstudio a Assets::BUFFER_PRIORITY, così il documento completato riceve gli asset dei blocchi, gli asset aggregati di UI e il Tailwind compilato, proprio come qualsiasi pagina, e prima di redirect_canonical con priorità 10. Un handler che esegue autonomamente il rendering di un intero documento deve essere eseguito anche dopo Assets::BUFFER_PRIORITY, altrimenti l’elaborazione viene saltata. I percorsi in urls (per impostazione predefinita il percorso della route stessa, quando non è una route con prefisso) vengono aggiunti alle build statiche prerenderizzate e Virtual_Routes::urls() li restituisce come URL assoluti per una sitemap.
Virtual_Routes::match( $path ) risolve un percorso come farebbe una richiesta.
Comportamento della sincronizzazione
I contenuti delle pagine cambiano solo tramite un’operazione di sincronizzazione esplicita:
wp bs pages sync
Il comando individua l’inventario completo delle origini, crea o aggiorna i contenuti modificati, elimina gli orfani confermati, aggiorna il routing delle raccolte e la configurazione compilata di templateFor, quindi segnala le modifiche. Aggiungete --authoritative per sostituire i contenuti gestiti invece di conservare i contenuti dell’editor associati a una chiave, e --full per indicare il passaggio come riconciliazione completa indipendentemente dall’identità dell’origine memorizzata:
wp bs pages sync --authoritative --full
Le normali richieste di bootstrap frontend, amministrazione, AJAX, REST, cron e WP-CLI generiche non avviano l’individuazione completa delle pagine, non consultano l’inventario di riconciliazione gestito e non scrivono contenuti di pagina. Usano i contenuti WordPress già sincronizzati e la configurazione compatta delle raccolte e dei template per tipo di contenuto, salvata dall’ultima operazione esplicita. Un’installazione o un aggiornamento senza dati possono esaminare una volta i manifest delle raccolte per ripristinare i metadati di routing; questo bootstrap in sola lettura non sincronizza mai i contenuti. L’endpoint di aggiornamento Canvas autenticato e facoltativo è un’operazione esplicita di creazione API: Canvas lo chiama una volta all’apertura dell’area di lavoro, così le origini nuove o modificate compaiono nell’inventario iniziale. La modalità Live chiama lo stesso punto di accesso quando rileva una modifica all’origine della pagina.
Blockstudio\Pages::init() ora registra solo gli hook al momento della richiesta. Le integrazioni che prima passavano un argomento force a questo metodo devono invece chiamare Blockstudio\Pages::reconcile() o eseguire wp bs pages sync.
Per evitare che una pagina venga sovrascritta dopo modifiche manuali, impostate "sync": false in page.json.
Percorsi sorgente portabili
I file del tema sincronizzati vengono memorizzati come percorsi relativi al tema anziché come percorsi assoluti dell’installazione. I file del tema figlio e quelli del tema genitore mantengono identità separate, anche quando hanno lo stesso nome di file relativo. Gli helper della pagina restituiscono comunque valori assoluti risolti di template_path, content_path, layout_path e directory per la richiesta corrente.
Questo consente alla sincronizzazione CLI e alle richieste web di usare radici del filesystem diverse, come negli hosting con directory jail, senza compromettere le risposte Markdown, i layout, la scansione Tailwind o il tracciamento delle sorgenti prerenderizzate. I percorsi assoluti dei temi esistenti vengono ricalcolati in lettura quando il nome della directory del tema non cambia. Non è necessaria alcuna sincronizzazione, migrazione del database o scrittura di metadati al momento della richiesta per leggerli; la successiva sincronizzazione esplicita salva i percorsi portabili.
Una directory del tema che è un symlink, per esempio verso una copia di sviluppo, salva gli stessi percorsi theme: sia quando una sorgente viene letta tramite il symlink sia quando viene letta tramite il percorso di destinazione, e li risolve rispetto alla directory del tema configurata.
I file esterni ai temi child e parent attivi continuano a essere supportati nei rispettivi percorsi assoluti configurati, nel rispetto delle restrizioni PHP di open_basedir. Non sono automaticamente trasferibili: dopo aver spostato una sorgente esterna, aggiornate il percorso configurato ed eseguite una sincronizzazione esplicita.
Proprietà dei campi del post
postStatus imposta lo stato iniziale. Le sincronizzazioni successive mantengono gli stati di bozza, in sospeso, privato, pubblicato e programmato già esistenti, anche con --authoritative. Una bozza non viene ripubblicata solo perché il suo file indica postStatus: "publish". Il comportamento esistente di ripristino degli orfani non cambia: una sincronizzazione esplicita ripristina un post gestito nel cestino se la relativa sorgente è presente. Bloccate la pagina o disabilitate la sincronizzazione per impedire il ripristino.
Il file continua a essere la fonte autorevole per titolo, slug, tipo di post, elemento genitore e ordine configurato nel menu. Modificarli in WordPress non cambia la definizione della sorgente. La successiva sincronizzazione esplicita riapplica i valori del file e indica i campi interessati in pages.<name>.overwritten, con un avviso nell’output della tabella CLI. Restano valide le autorizzazioni native di WordPress, incluso lo slug vuoto per i post in sospeso quando l’utente che sincronizza non può pubblicarli.
Usate blockstudio/pages/update_post_data per un’integrazione che gestisce esplicitamente una policy di stato diversa. I blocchi con chiave preservano il contenuto dei blocchi gestito dall’editor; le chiavi non modificano la proprietà del titolo o dello slug del post.
Per le pagine delle raccolte, le impronte comprendono il manifest, il caricatore, l’origine della pagina, il file di layout, i metadati e i relativi percorsi di origine. La successiva sincronizzazione esplicita applica le modifiche a questi input.
Quando un’origine della raccolta viene rimossa, Blockstudio rimuove la pagina generata, così le vecchie pagine della raccolta non restano nel sito dopo la cancellazione del file sorgente. Per impostazione predefinita, le pagine orfane della raccolta vengono spostate nel cestino. Usate blockstudio/pages/orphan_action per restituire trash, delete o keep.
Nelle richieste frontend, Blockstudio inizializza il registro delle pagine usando i contenuti pubblicati già sincronizzati. Le pagine in bozza e private sono disponibili nell’amministrazione e nei contesti di sincronizzazione, ma gli helper frontend inizializzano solo le pagine pubblicate.
Riconciliazione della distribuzione
Blockstudio\Pages::reconcile() è il punto di ingresso PHP per la distribuzione. Individua l’inventario desiderato completo, confronta le impronte dell’origine e del motore di sincronizzazione e restituisce un resoconto leggibile da una macchina:
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
'renames' => [
[
'from' => 'pages/old/index.php',
'to' => 'pages/new/index.php',
],
],
]);
Il report contiene discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, i risultati per pagina, gli errori di rilevamento e un sourceIdentity deterministico.
Le pagine bloccate hanno status: "locked" e vengono conteggiate separatamente dalle pagine invariate. removedPages elenca per ogni pagina rimossa il relativo name, key, postId e l’effettivo action (trash o delete); i post mantenuti o già nel cestino non vengono conteggiati tra quelli rimossi di recente. Anche l’output della tabella CLI indica le pagine create, aggiornate, bloccate, rimosse e con contenuto preservato, insieme ai relativi ID dei post.
Dopo l’analisi e l’unione basata sulle chiavi, se il post finale è identico non viene chiamato wp_update_post(), non viene modificato post_modified, non viene creata una revisione e non vengono attivati gli hook di aggiornamento del post. Il risultato è unchanged. Se il contenuto della sorgente differisce da quello gestito dall’editor nei blocchi con chiave, preserved: true identifica tale decisione e il conteggio di primo livello preserved la include. La nuova impronta della sorgente e i metadati di gestione vengono comunque registrati, così la successiva sincronizzazione senza modifiche non esegue operazioni. preserved è un flag aggiuntivo, non uno stato esclusivo: una pagina può preservare il contenuto con chiave e aggiornare comunque un titolo gestito dal file o aggiungere un altro blocco.
authoritative: true può rimuovere un blocco di Page Sync e sostituisce i contenuti con quelli della definizione del file invece di conservare i contenuti dell’editor associati a una chiave. Lasciatelo false per una normale sincronizzazione esplicita. plan_valid: false, full: true, broad: true, l’assenza dell’identità dell’origine precedente o una modifica all’impronta del motore di sincronizzazione contrassegnano il passaggio come riconciliazione completa (fullReconciliation nel resoconto). In entrambi i casi, ogni passaggio confronta l’inventario completo. I record di rinomina Git sono solo indizi per l’identità. Non sostituiscono mai il confronto dell’inventario completo.
Le impronte identiche, in assenza di modifiche ai percorsi in uso, non generano scritture nei contenuti o nei metadati dei contenuti né attivano hook di aggiornamento. Quando un’origine invariata si sposta in una nuova directory di release, la riconciliazione aggiorna solo i percorsi persistiti di template, contenuto, layout e directory; non aggiorna post_content né la data di modifica del contenuto. Le pagine gestite mancanti vengono eliminate solo dopo che il passaggio completo di riconciliazione termina senza errori di individuazione o di scrittura delle pagine.
La riconciliazione diretta API non contrassegna una distribuzione come completata. Dopo aver attivato e verificato l’artefatto statico corrispondente e le route, salvate esplicitamente l’identità restituita:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync salva l’identità restituita dopo un passaggio riuscito. Il normale bootstrap WP-CLI registra solo i tipi di contenuto delle raccolte persistiti e le regole di riscrittura. Non individua né sincronizza pagine.
Blocco degli ID dei contenuti
Per impostazione predefinita, WordPress assegna automaticamente gli ID ai contenuti. Se una pagina viene eliminata e ricreata, l’ID cambia, interrompendo riferimenti esterni come i menu o i link inseriti nel codice.
Usate postId per bloccare una pagina su un ID specifico:
{
"name": "about",
"title": "About Us",
"postId": 42
}
Quando crea la pagina, Blockstudio passa l’ID a WordPress tramite import_id. Se l’ID è disponibile, WordPress lo usa esattamente. Se l’ID è già assegnato a un contenuto non correlato, WordPress ne assegna automaticamente uno nuovo senza segnalarlo.
Quando cerca le pagine esistenti, Blockstudio controlla prima l’ID bloccato, poi i metadati o lo slug. In questo modo, se una pagina viene eliminata e sincronizzata di nuovo, recupera lo stesso ID.
Unione dei blocchi associati a una chiave
Per impostazione predefinita, quando cambia un file di template, Blockstudio sostituisce l’intero contenuto della pagina con il nuovo template. Ciò significa che tutte le modifiche apportate nell’editor WordPress vanno perse.
Aggiungete ai blocchi un attributo key per conservare le modifiche degli utenti tra le sincronizzazioni dei template. Se un template contiene blocchi associati a una chiave, Blockstudio unisce le modifiche al template con il contenuto della pagina esistente, invece di sostituirlo.
Aggiunta delle chiavi
Usate l’attributo key su qualsiasi elemento HTML o <block>:
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>
<div key="features">
<p>First feature.</p>
<p>Second feature.</p>
</div>
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h2>Hero Title</h2>
<p>Hero description.</p>
</block>
<block
name="acme/testimonial"
key="featured-quote"
quote="Default quote"
/>
Le chiavi devono essere univoche nell’intero template. Una chiave protegge l’intero blocco e tutti i suoi contenuti. Non occorre assegnare chiavi ai singoli elementi figlio all’interno di un blocco con chiave. Tra un aggiornamento e l’altro del template, i blocchi con chiave possono essere spostati in qualsiasi posizione o livello di nidificazione e i contenuti inseriti dagli utenti vengono comunque conservati.
Le chiavi funzionano allo stesso modo per i blocchi personalizzati Blockstudio. key è un metadato strutturale di Page Sync; i valori dei campi personalizzati restano normali attributi Blockstudio. Quando un utente modifica questi campi nell’editor, una sincronizzazione successiva del template conserva i valori inseriti dall’utente e applica comunque le modifiche indipendenti al template. Le pagine create con versioni precedenti, che avevano la chiave nei dati dei campi personalizzati, vengono migrate automaticamente alla sincronizzazione successiva.
Come funziona l’unione
Quando cambia un file di template e la pagina viene sincronizzata di nuovo:
| Blocco | Comportamento |
|---|---|
| Blocco con chiave | I contenuti inseriti dall’utente e i valori dei campi Blockstudio vengono conservati. Vengono applicati gli attributi e la struttura gestiti dal template. |
| Blocco senza chiave | Viene sostituito interamente con la versione del template, come quando non si usano chiavi |
Esempi
Le modifiche degli utenti vengono conservate nei blocchi con chiave:
- Il template definisce
<p key="intro">Default intro.</p> - L’utente modifica il paragrafo nell’editor inserendo "Testo introduttivo personalizzato."
- Lo sviluppatore aggiorna il template, aggiunge un nuovo blocco e modifica il layout
- Alla sincronizzazione: il paragrafo mantiene "Testo introduttivo personalizzato." e viene applicato il nuovo layout
Gli attributi del template continuano ad applicarsi:
- Il template contiene un blocco di copertina con
key="hero"e un attributourl - Lo sviluppatore modifica l’attributo
urldella copertina impostando una nuova immagine di sfondo - Alla sincronizzazione viene applicata la nuova immagine di sfondo, ma le modifiche dell’utente al contenuto della copertina vengono conservate
Casi limite
| Scenario | Comportamento |
|---|---|
| Aggiunta di un nuovo blocco con chiave al template | Compare con il contenuto predefinito del template |
| Rimozione di un blocco con chiave dal template | Viene eliminato dal contenuto |
| Modifica del tipo di blocco (stessa chiave) | Il template prevale interamente, senza unione dei contenuti |
| Chiavi duplicate | La seconda occorrenza viene trattata come un blocco senza chiave |
| Template senza chiavi | Sostituzione completa, come quando non si usano chiavi |
| Sincronizzazione forzata | Sostituzione completa; le chiavi vengono ignorate |
| Contenuto bloccato | Nessuna sincronizzazione |
Combinazione con i controlli di modifica
Chiavi, templateLock e blockEditingMode si combinano per darvi un controllo preciso su ciò che i clienti possono e non possono fare. Ecco alcuni schemi di lavoro comuni.
Pagina completamente bloccata
Lo sviluppatore controlla tutto. La pagina è un layout statico che i clienti non possono modificare. È utile per pagine legali, termini di servizio o qualsiasi pagina che deve cambiare solo tramite codice.
{
"name": "terms",
"title": "Terms of Service",
"templateLock": "all"
}
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>
Non servono chiavi. Il template è l’unica fonte di verità. Ogni sincronizzazione sovrascrive completamente la pagina.
Layout bloccato con contenuti modificabili
È lo schema più comune. Bloccate la struttura della pagina affinché i clienti non possano aggiungere, rimuovere o riordinare i blocchi, ma consentite loro di modificare il testo in punti specifici. Le chiavi fanno sì che le loro modifiche sopravvivano agli aggiornamenti del template.
{
"name": "landing",
"title": "Landing Page",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h1 blockEditingMode="contentOnly">Edit This Title</h1>
<p blockEditingMode="contentOnly">Edit this description.</p>
</block>
<div key="features">
<h2>Features</h2>
<p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
</block>
Il cliente può modificare il titolo dell’hero, la descrizione e l’introduzione alle funzionalità. Nient’altro. Il testo del pulsante, URL e l’immagine di sfondo della copertina sono controllati dallo sviluppatore. Quando lo sviluppatore aggiorna il template (e.g, aggiunge un secondo pulsante), le sezioni con chiave mantengono il testo del cliente.
Template in evoluzione con contenuti preservati
Per le pagine che crescono nel tempo. Lo sviluppatore aggiunge nuove sezioni al template e ogni sincronizzazione aggiunge i nuovi contenuti senza modificare quelli che il cliente ha già personalizzato.
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<div key="testimonials">
<h2>Testimonials</h2>
<p>What our clients say.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
</block>
La nuova sezione delle testimonianze e il pulsante compaiono con la sincronizzazione. Le modifiche del cliente a titolo, introduzione e servizi restano intatte.
Struttura iniziale una tantum
Create una pagina con una struttura iniziale, quindi affidatela interamente al cliente. Impostate sync su false affinché la sincronizzazione normale non crei né aggiorni mai la pagina, e createla una sola volta con Blockstudio\Pages::force_sync('blog'). Dopodiché, la pagina è interamente del cliente.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
wp bs pages sync ignora questa pagina, quindi force_sync() la crea una sola volta. Dopodiché, il cliente può aggiungere, rimuovere e riordinare liberamente i blocchi. Le modifiche al template vengono ignorate.
Associazioni dei blocchi
Un’alternativa all’unione tramite chiavi consiste nell’usare WordPress core Associazioni dei blocchiAPI per collegare i blocchi ai metadati dei post. Non è una funzionalità di Blockstudio, ma una funzionalità nativa di WordPress API. Blockstudio si limita a passare l’attributo metadata al markup del blocco generato. Il contenuto risiede nei metadati del post anziché nel markup del blocco, quindi le sincronizzazioni del template possono sovrascrivere liberamente il markup: l’editor legge i dati dai metadati, non da innerHTML.
Passate l’attributo metadata a qualsiasi elemento HTML o <block>:
<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 text.
</p>
<img
metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>
Le chiavi dei metadati devono essere registrate con show_in_rest abilitato:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Chiavi e associazioni
| Aspetto | Chiavi | Associazioni |
|---|---|---|
| Contenuto memorizzato in | Markup del blocco (post_content) |
Metadati del post (wp_postmeta) |
| Sopravvive alla sincronizzazione del template | Sì (unito per chiave) | Sì (i dati risiedono nei metadati) |
Interrogabile tramite WP_Query |
No | Sì (meta_query) |
| Disponibile in REST API | No | Sì |
| Richiede registrazione | No | Sì (register_post_meta) |
| L’utente può spostare i blocchi | No (il template reimpone la struttura) | No (il template reimpone la struttura) |
È possibile usare entrambi gli approcci nello stesso template. Usate le chiavi per le sezioni in cui la struttura dei blocchi è importante (e.g, un gruppo con più elementi figlio). Usate le associazioni per i singoli campi quando volete rendere i dati accessibili anche al di fuori dell’editor dei blocchi.
Template per tipi di post
Usate templateFor per impostare una pagina come template predefinito per un tipo di post:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
Tutti i nuovi post di quel tipo inizieranno con la struttura di blocchi definita.
Percorsi personalizzati
Per impostazione predefinita, Blockstudio esegue la scansione di get_template_directory() . '/pages'. Aggiungete altri percorsi con il filtro:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
Le integrazioni runtime che compongono file da più radici possono sostituire la scansione del file system con una fonte di rilevamento logico. I manifest delle pagine, i layout, i loader e i template sorgente vengono quindi risolti tramite percorso logico, anche quando i file selezionati si trovano in radici diverse.
Filtri e azioni
Il rilevamento delle pagine, la sincronizzazione e l’instradamento delle raccolte espongono i seguenti punti di estensione:
| Hook | Tipo | Descrizione |
|---|---|---|
blockstudio/pages/paths |
Filtro | Aggiunge directory in cui Blockstudio cerca le sorgenti delle pagine. |
blockstudio/pages/collection_post_type_args |
Filtro | Modifica gli argomenti di register_post_type() per un CPT di raccolta. |
blockstudio/pages/template_candidates |
Filtro | Modifica i nomi dei file di template considerati per una sorgente di pagina. |
blockstudio/pages/serve_markdown |
Filtro | Abilita o disabilita le risposte Markdown grezze. |
blockstudio/pages/orphan_action |
Filtro | Restituisce trash, delete o keep per la pulizia degli orfani. |
blockstudio/pages/docs_allowed_html |
Filtro | Modifica i HTML consentiti per il contenuto della documentazione Markdown generata. |
blockstudio/pages/allow_external_loader_path |
Filtro | Consente al loader paths di trovarsi fuori dalla radice della raccolta. |
blockstudio/pages/manifest_scan_interval |
Filtro | Imposta l’età massima di una cache del manifest legacy precedente a 7.6.2 che può fornire la configurazione runtime persistita durante un aggiornamento. |
blockstudio/pages/create_post_data |
Filtro | Modifica i dati del post prima della creazione di una pagina sincronizzata. |
blockstudio/pages/update_post_data |
Filtro | Modifica i dati del post prima dell’aggiornamento di una pagina sincronizzata. |
blockstudio/pages/sync_engine_inputs |
Filtro | Aggiunge una versione di parser, mapping o migrazione che deve ampliare intenzionalmente la riconciliazione una volta. |
blockstudio/pages/post_created |
Azione | Viene eseguita dopo la creazione del post di una pagina sincronizzata. |
blockstudio/pages/post_updated |
Azione | Viene eseguita dopo l’aggiornamento del post di una pagina sincronizzata. |
blockstudio/pages/synced |
Azione | Viene eseguita al termine della sincronizzazione del registro delle pagine. |
blockstudio/pages/reconciled |
Azione | Viene eseguita dopo una riconciliazione esplicita e riceve il relativo report leggibile da una macchina. |
blockstudio/pages/renderers |
Azione | Registra i renderer delle pagine con Blockstudio\Page_Renderers::register(). Viene eseguita una volta per richiesta. |
blockstudio/pages/rendered |
Azione | Viene eseguita dopo il rendering di una pagina componente, con la pagina, il suo HTML e le relative dipendenze. |
blockstudio/pages/layout_error |
Azione | Viene eseguita quando non è possibile eseguire il rendering di un layout; riceve l’errore, il percorso del layout e la pagina. |
PHP API
// Get all registered pages.
$pages = Blockstudio\Pages::pages();
// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');
// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');
// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');
// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');
// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');
// Get a specific page.
$page = Blockstudio\Pages::get_page('about');
// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');
// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');
// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();
// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
]);
// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);
// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');
// Unlock a page.
Blockstudio\Pages::unlock('about');
// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
'extensions' => ['tsx'],
'layouts' => ['layout.tsx'],
'render' => 'my_theme_render_page',
]);
// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');
// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);
Consultate Riconciliazione del deployment per la semantica degli argomenti, i campi del report e i limiti verificati dell’identità dell’origine.
Le funzioni helper globali sono disponibili per template e layout:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
Gli array di pagine restituiti da Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() e dalle funzioni helper globali includono l’identità del post sincronizzato, i percorsi dell’origine e del template, i metadati della raccolta e del percorso, il tipo di contenuto, i criteri di sincronizzazione, il tipo e lo stato del post, i criteri di modifica, i metadati personalizzati e una chiave permalink. I metadati della raccolta vengono caricati dall’ultima riconciliazione esplicita riuscita. Le richieste normali ricostruiscono questi dati runtime dalla configurazione persistita e dai metadati dei post sincronizzati senza leggere gli alberi delle origini delle pagine. La classe Pages non espone un metodo permalink separato.
Creazione di pagine basate su file
Blocco dei template, modalità di modifica dei blocchi, unione tramite chiavi e controllo degli elementi modificabili dai clienti.