Pagini
Paginile sunt șabloane bazate pe fișiere, sincronizate cu baza de date WordPress sub formă de articole.
Sincronizarea este explicită: rulați wp bs pages sync sau apelați API Pages când doriți să aplicați modificările sursei. Încărcarea interfeței publice sau a panoului de administrare WordPress nu descoperă toate paginile și nu modifică articolele pagină.
Paginile pot fi definite într-un singur folder page.json, ca fișiere Markdown independente sau ca o colecție cu un manifest pages.json. Colecțiile sunt utile pentru documentație, baze de cunoștințe, biblioteci de pagini de destinație sau orice set de pagini imbricate care ar trebui generat din fișiere.
page.json
Pentru o pagină definită prin JSON, adăugați un fișier de configurare page.json:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
Proprietăți
| Proprietate | Tip | Implicit | Descriere |
|---|---|---|---|
name |
string |
obligatoriu | Identificator unic al paginii |
title |
string |
Automat din nume | Titlul paginii |
slug |
string |
La fel ca numele | URL slug pentru pagină |
path |
string |
"." |
Cale logică în cadrul unei colecții |
order |
integer |
0 |
Ordinea în meniu a articolului sincronizat |
postType |
string |
"page" |
Tipul de articol WordPress |
postStatus |
string |
"draft" |
Starea articolelor noi (publish, draft, pending, private) |
postId |
integer |
– | Fixați pagina la un anumit ID de articol WordPress |
blockEditingMode |
string |
– | Modul de editare a blocurilor: "default", "contentOnly" sau "disabled" |
templateLock |
string|false |
"all" |
Modul de blocare: "all", "insert", "contentOnly" sau false |
templateFor |
string|null |
null |
Setați ca șablon implicit pentru un tip de articol |
sync |
boolean |
true |
Dacă reconcilierea explicită obișnuită poate crea sau actualiza articolul |
render |
string|object|false |
– | Redați pagina cu un motor de redare a paginilor înregistrat (consultați Pagini de componente) |
Între page.json, frontmatter și intrările loaderului, cheile recunoscute includ blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock și title. Orice cheie care nu este enumerată mai sus este stocată în tabloul meta al paginii.
Surse de conținut
Definiția unei pagini stabilește ce articol WordPress ar trebui să existe. Sursa de conținut stabilește ce marcaj de blocuri este scris în acel articol.
Când un folder de pagină are un page.json, Blockstudio caută un fișier sursă alăturat, în această ordine:
| Fișier | Utilizare |
|---|---|
index.php |
Marcaj de blocuri de tip HTML, citit ca atare (codul PHP nu este executat) |
index.blade.php |
Conținut de șablon Blade |
index.twig |
Conținut de șablon Twig |
index.md |
Conținut Markdown |
page.json poate furniza și conținut markdown sau html în linie, în locul unui fișier alăturat:
{
"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>"
}
Colecțiile adaugă încă două moduri de sursă:
- Fișiere Markdown descoperite direct în structura arborescentă a colecției.
- Intrări de încărcare returnate de
loader.php.
Intrările de încărcare pot folosi markdown, html sau content cu contentType. De asemenea, pot indica un fișier local file sau template. Tipul surselor de fișiere și șabloane este dedus din extensie, cu excepția cazului în care contentType este setat explicit.
Valorile contentType acceptate sunt php, blade, twig, markdown și html. Markdown este convertit mai întâi în HTML, apoi analizat în blocuri native WordPress. Sursele PHP, Blade, Twig și HTML trec prin analizatorul obișnuit de pagini Blockstudio.
Clasele blocurilor de bază
Un class de pe un element HTML mapat la un bloc de bază devine className al acestuia.
O etichetă explicită pentru blocul de bază poate folosi direct className. Ambele forme păstrează clasele de pe wrapperul salvat al blocului, alături de clasele generate de WordPress:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
Dacă sunt prezente ambele proprietăți, className are prioritate. Această conversie se aplică doar blocurilor de bază: o mapare de bloc personalizat păstrează neschimbat câmpul class. Clasele de stil ale butonului, precum is-style-outline, aparțin wrapperului butonului, nu linkului.
Rulați wp bs pages sync pentru a aplica corecțiile parserului paginilor sincronizate anterior. Actualizările parserului sunt recunoscute la următoarea sincronizare explicită, fără a edita fișierul sursă. Paginile blocate și paginile cu sync: false își păstrează protecțiile obișnuite; solicitările frontend nu efectuează niciodată această sincronizare.
Blocuri WordPress serializate
Sursele paginilor și modelelor pot conține, de asemenea, blocuri serializate copiate din editorul de cod WordPress:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
Când sursa conține un delimitator de bloc <!-- wp:... -->, Blockstudio folosește parserul nativ de blocuri al WordPress pentru întreaga sursă. Atributele, blocurile imbricate, blocurile dinamice precum Query Loop și blocurile Blockstudio își păstrează structura serializată. HTML din afara comentariilor de bloc rămâne HTML nativă, în format liber; nu este mapată în blocuri suplimentare. Nu combinați etichetele de bloc Blockstudio HTML cu acest format așteptându-vă să fie convertite. Comentariile obișnuite HTML nu activează modul cu blocuri serializate.
Pagini Markdown
Folosiți Markdown când textul ar trebui să rămână în fișiere, dar să devină conținut de blocuri WordPress editabil după sincronizare. Sursa Markdown este convertită în marcaj de blocuri în timpul sincronizării. Articolul sincronizat stochează blocuri, nu corpul brut Markdown.
Markdown poate fi folosit în trei moduri:
| Sursă | Este necesar frontmatter? | Note |
|---|---|---|
Fișier pages/example/index.md independent |
Da | Frontmatter-ul oferă identitatea paginii. |
page.json plus index.md |
Nu | page.json definește pagina, iar Markdown furnizează conținutul. |
| Markdown într-o colecție | Nu | Colecția deduce name și path din locația fișierului. |
Un fișier index.md independent fără frontmatter este omis, deoarece Blockstudio nu are identitatea unei pagini de sincronizat. Markdown dintr-o colecție nu necesită frontmatter, deoarece manifestul colecției și calea fișierului furnizează identitatea.
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
Puteți asocia și page.json cu index.md. În acest caz, page.json definește pagina, iar index.md furnizează conținutul. Frontmatter-ul din index.md suprascrie valorile page.json corespunzătoare.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
title: API Reference
order: 20
---
# Reference
This page uses `page.json` with Markdown content.
Pentru Markdown dintr-o colecție, calea fișierului devine calea logică a paginii, cu excepția cazului în care frontmatter-ul o suprascrie:
| Fișier | Cale implicită |
|---|---|
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 |
Cheile necunoscute din frontmatter sunt păstrate în tabloul meta al paginii. Astfel, puteți atașa date precum section sau description și le puteți citi din PHP API.
Markdown este analizat ca GitHub Flavored Markdown. Este permis HTML brut, linkurile nesigure sunt eliminate, iar titlurilor fără un ID explicit li se atribuie unul stabil. Frontmatter-ul YAML imbricat necesită analizatorul YAML inclus.
Markdown brut
Sursele de fișier Markdown pot expune sursa originală Markdown pentru instrumente externe și aplicații de documentație. Sursa Markdown în linie nu are un fișier sursă, așa că se sincronizează în blocuri, dar nu generează un răspuns .md brut.
Solicitați pagina folosind sufixul .md, de exemplu https://example.com/docs/reference.md. Sau trimiteți un antet Accept: text/markdown către URL normal al paginii:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
Frontmatter-ul este eliminat din răspuns. Răspunsurile brute Markdown reușite trimit antetele Content-Type: text/markdown, X-Robots-Tag: noindex și Link canonic înapoi către pagina HTML. Rutele .md inexistente returnează un 404 real.
Negocierea funcționează cu pre-randarea statică: un răspuns a cărui antet Accept conține text/markdown nu este niciodată furnizat din stocarea pre-randată sau din extensia timpurie de servire, așa că ajunge la WordPress și la gestionarul Markdown. Răspunsurile HTML pre-randate, HTML unei pagini care negociază și Markdown, precum și Markdown furnizat prin Accept trimit Vary: Accept, astfel încât cache-urile care respectă Vary le păstrează separate. Un CDN care își organizează cache-ul doar după URL are nevoie de propria regulă pentru a ocoli cache-ul în cazul acestor cereri. Pages::negotiates_markdown( $post_id ) raportează dacă o pagină răspunde la cereri Markdown.
Colecția Markdown păstrează aceeași structură URL pentru Markdown brut:
| URL paginii | Markdown URL brut |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
Dezactivați răspunsurile Markdown brute cu filtrul blockstudio/pages/serve_markdown:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
O cerere .md URL care nu corespunde unei pagini bazate pe Markdown returnează 404 numai dacă acea cale se află într-o colecție de pagini. În afara tuturor colecțiilor, Blockstudio lasă cererea nealterată, pentru ca WordPress și alte pluginuri să o gestioneze.
Pagini de componente
O pagină de componente este redată de un motor de redare a paginilor, în loc să fie stocată ca blocuri. Blockstudio nu include un motor de redare. O temă sau un modul îl înregistrează pentru fișierele de intrare pe care le gestionează, cum ar fi un motor de redare React pentru page.tsx, iar Blockstudio îl apelează cu pagina, articolul WordPress și conținutul redat al slotului.
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 este explicită. Un director cu un index.php și un page.tsx, dar fără render, rămâne o pagină obișnuită, astfel încât adăugarea unui motor de redare nu redă de două ori o pagină existentă. Formele sunt:
| Valoare | Semnificație |
|---|---|
"page.tsx" |
Doar intrare, fără loader de date |
{ "entry": "page.tsx", "data": "data.php" } |
Intrare și loader de date |
{ "entry": "page.tsx", "renderer": "react" } |
Intrare cu un ID explicit al motorului de redare |
false |
Fără motor de redare, chiar dacă o valoare implicită a colecției indică unul |
Căile se rezolvă în raport cu directorul paginii sau cu rădăcina colecției pentru intrările loaderului. Acestea trebuie să rămână în interiorul sursei de descoperire, cu excepția cazului în care blockstudio/pages/allow_external_loader_path permite acest lucru. Fără renderer, se folosește motorul de redare care gestionează extensia intrării. Un render care indică o intrare sau un fișier de date lipsă, un motor de redare necunoscut ori o extensie gestionată de niciun motor de redare reprezintă o eroare de descoperire, care oprește reconcilierea înainte de eliminarea oricărui element.
Ce stochează sincronizarea
Sincronizarea stochează un singur bloc blockstudio/page. Dacă directorul paginii are și o sursă index.*, aceasta este analizată ca orice sursă de pagină și devine blocurile interioare ale blocului, adică slotul său:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
Păstrați în slot conținutul gestionat de WordPress, cum ar fi scurtcodurile. O sursă care conține un singur scurtcod, precum [download_checkout], este stocată ca bloc core/shortcode, astfel încât rezultatul său să nu fie încadrat într-un paragraf. Rămâne în post_content, astfel încât verificările has_shortcode() să o detecteze, blocurile cu chei din slot să se îmbine cu modificările din editor la fel ca blocurile imbricate cu chei, iar do_shortcode să extindă scurtcodurile o singură dată, la prioritatea obișnuită the_content, după ce motorul de redare le-a încadrat.
Definiția redării este stocată împreună cu articolul, folosind căi portabile theme:. Amprenta paginii acoperă definiția, nu octeții intrării sau ai loaderului de date: editarea fișierelor page.tsx sau data.php lasă articolul neschimbat, iar modificările ajung la vizitatori prin redare și prin graful prerandării statice, care înregistrează intrarea, loaderul de date și fiecare fișier raportat de motorul de redare.
Înregistrarea unui motor de redare
Înregistrați motoarele de redare pe acțiunea blockstudio/pages/renderers. Aceasta se declanșează o singură dată pentru fiecare cerere, înainte de prima descoperire sau redare, astfel încât wp bs pages sync și cererile frontend să vadă același registru.
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',
)
);
}
);
ID-urile motoarelor de redare sunt scrise cu litere mici. O extensie sau un nume de aspect poate aparține unui singur motor de redare, iar layout.php rămâne propriul aspect al Blockstudio. Funcția apelabilă primește o cerere:
| Cheie | Valoare |
|---|---|
kind |
page sau layout pentru un aspect de tip motor de redare |
renderer |
ID-ul motorului de redare |
entry |
Calea absolută a intrării |
data |
Calea absolută a loaderului de date sau null |
page |
Datele canonice ale paginii, inclusiv meta |
post_id |
ID-ul articolului WordPress |
slot |
Conținutul redat al slotului sau conținutul paginii pentru un aspect |
context |
frontend, rest, feed sau cli |
Returnează HTML, fișierele citite de redare și resurse opționale:
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 provine din tipul cererii, niciodată de la vizitator, astfel că un renderer nu poate compromite paritatea octeților între utilizatorii autentificați și cei anonimi citindu-l. Dacă un renderer eșuează, aruncă o excepție: pagina nu este redată cu un corp gol. Într-o previzualizare REST din editor, blocul afișează eroarea ca notificare. După o redare reușită, acțiunea blockstudio/pages/rendered primește pagina, HTML și dependențele acesteia.
assets enumeră fișierele de script și de stil necesare paginii. Acestea trec prin procesarea activelor blocurilor (convenția *.inline.*, modulele ES, minificarea și ?ver), iar pagina le afișează o singură dată, prin același buffer care afișează activele blocurilor, astfel încât o pagină prerandată le include. Un activ poate seta version pentru a-i înlocui valoarea ?ver. Codul din afara unui renderer poate folosi același canal prin Blockstudio\Assets::register_owner(), care returnează comentariul marcator ce trebuie afișat.
Editor
În editor, blockstudio/page afișează o previzualizare a paginii randată pe server, cu slotul drept blocuri interioare, care urmează templateLock paginii. Blocul nu poate fi inserat, duplicat sau imbricat într-un alt bloc.
Colecții de pagini
O colecție este un folder cu un manifest pages.json. Acesta grupează multe surse de pagini sub un singur identificator de colecție, aplică valori implicite, acceptă căi imbricate și poate înregistra automat un tip de articol dedicat.
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"
}
}
| Proprietate | Tip | Descriere |
|---|---|---|
collection / slug / name |
string |
Slugul colecției. collection este forma cea mai clară și devine baza publică URL. |
title |
string |
Titlul colecției, ușor de înțeles. |
postType |
string |
Tipul de articol pentru paginile generate. Valoarea implicită este page. Dacă nu există, Blockstudio îl înregistrează. |
postTypeArgs |
object |
Argumente transmise către register_post_type() când Blockstudio înregistrează tipul de articol al colecției. |
defaults |
object |
Proprietăți implicite ale paginii, aplicate fiecărei pagini din colecție. O valoare implicită render se aplică unei pagini doar dacă intrarea sa există în directorul de pagini. |
scope |
string |
collection (implicit) sau site. Consultați Colecții de site. |
meta |
object |
Metadate personalizate ale colecției. Cheile necunoscute din manifest sunt stocate și în meta. |
Căile paginilor din colecție sunt căi logice. O pagină cu path: "guide/install" este sincronizată ca subpagină a guide, iar guide este sincronizată ca subpagină a rădăcinii colecției dacă aceste pagini părinte există.
Dacă o colecție ierarhică are o pagină imbricată, dar sursa unui părinte intermediar nu există, Blockstudio generează o pagină-container goală pentru acea cale, păstrând completă ierarhia WordPress. Tipurile de articol neierarhice (cele fără suport pentru părinte page-attributes) nu generează containere goale. Acestea folosesc calea de colecție stocată, astfel încât căi imbricate precum guide/install și setup/install pot coexista, chiar dacă ambele se termină în install.
Tipuri de articole și URL-uri ale colecției
Setați postType în manifestul colecției pentru a sincroniza fiecare pagină din colecție cu acel tip de articol. Nu este nevoie să repetați aceeași valoare în defaults. Paginile individuale pot în continuare să suprascrie postType în frontmatter sau în page.json.
Dacă tipul de articol nu există, Blockstudio îl înregistrează folosind show_in_rest: true, o configurare de editor similară unei pagini și identificatorul colecției ca bază publică URL. postTypeArgs poate suprascrie argumentele de înregistrare. Regulile de rescriere pentru tipurile de articole ale colecției sunt reinițializate automat când se schimbă tipurile de articole înregistrate ale colecției sau argumentele de rescriere, astfel că nu trebuie să salvați din nou legăturile permanente WordPress.
URL-urile colecției folosesc identificatorul colecției urmat de path logică a fiecărei pagini:
| Calea sursă | Public URL |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
Acest model URL funcționează atât pentru tipurile de postări de colecție ierarhice, cât și pentru cele non-ierarhice. Blockstudio redirecționează și URL-urile duplicate, precum /docs/docs/ sau /docs/docs/getting-started/, către URL canonic.
Paginile colecțiilor expun conținut Markdown brut la aceleași URL-uri (consultați Markdown brut).
Dacă schimbați o colecție din postType: "page" într-un tip de postare personalizat, Blockstudio migrează pe loc postările de colecție deja sincronizate, dacă identitatea paginii stocată corespunde. Astfel, ID-urile postărilor, metadatele și conținutul existent se păstrează, fără a crea duplicate cu vechiul tip de postare. Postările de colecție învechite sunt curățate din toate stările postărilor, conform filtrului blockstudio/pages/orphan_action.
Colecții de site
Un manifest cu "scope": "site" grupează toate paginile aflate sub el, fără a le transforma în pagini de colecție. Folosiți-l la rădăcina arborelui de pagini al unui site pentru a aplica valori implicite comune și pentru a lista paginile site-ului cu 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" }
}
}
Paginile unei colecții de site își păstrează exact identitatea pe care o aveau fără manifest, astfel că adăugarea unuia la un arbore existent nu modifică niciun rând de articol și nu creează și nu șterge nimic:
- Cheile rămân globale:
Pages::get_page( 'home' )și cheile paginilor stocate continuă să corespundă. - URL-urile rămân URL-urile paginilor WordPress. Nu se aplică reguli de rescriere pentru colecții, filtre de permalink sau redirecționări cu URL dublat și nu se generează pagini container goale.
- Căile logice, slugurile, părinții și identitățile sursă sunt cele ale paginilor independente, iar machetele sunt rezolvate în funcție de cel mai apropiat strămoș.
- Manifestele
pages.jsonimbricate își păstrează propriile colecții, iar subarborii lor sunt excluși din colecția site-ului. - Valorile implicite se aplică fiecărei pagini: o valoare implicită
renderse aplică doar paginilor a căror intrare există în director, astfel că paginile cu shortcode și cele Markdown își păstrează sursele.
Încărcătoare de colecții
Colecțiile pot include un loader.php local de încredere. Folosiți-l când paginile colecției provin dintr-o altă sursă locală, precum un dosar extern cu documentație, un pachet sau un manifest generat.
Încărcătorul rulează în timpul descoperirii și sincronizării explicite a paginilor. Acesta ar trebui să fie determinist și local. Evitați să preluați conținut la distanță din loader.php, deoarece sincronizarea implementării ar depinde astfel de acel serviciu.
<?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 încărcător poate returna un tablou cu cheile pages, meta și paths:
| Cheie | Descriere |
|---|---|
pages |
O listă de tablouri de pagini. Fiecare pagină acceptă aceleași chei recunoscute ca metadatele inițiale page.json și Markdown. |
meta |
Metadate îmbinate în tabloul meta al fiecărei pagini generate de încărcător. |
paths |
Directoare locale suplimentare care trebuie detectate ca parte a acestei colecții. Intrările pot fi șiruri sau obiecte de cale. |
render |
O definiție de redare pentru fiecare pagină Markdown detectată din paths. |
Ca prescurtare, încărcătorul poate returna o listă simplă de tablouri de pagini.
Intrările paginilor încărcătorului pot furniza conținut în următoarele moduri:
| Formă | Descriere |
|---|---|
markdown |
Conținut Markdown inline. |
html |
Conținut HTML inline. |
content + contentType |
Conținut generic inline. contentType trebuie să se rezolve la markdown sau html. |
file |
Sursă dintr-un fișier local. Tipul este dedus din extensie, dacă nu este setat contentType. |
template |
Alias pentru file. |
Referințele la fișiere ale încărcătorului pot indica surse PHP, Blade, Twig, Markdown sau HTML. Căile relative se rezolvă pornind de la rădăcina colecției. Căile absolute și cele din afara rădăcinii colecției sunt permise numai dacă filtrul blockstudio/pages/allow_external_loader_path le permite.
Paginile încărcătorului au implicit valoarea generated: true. Când o pagină generată de încărcător dispare din rezultatul acestuia, Blockstudio tratează postarea sincronizată ca orfană la următoarea sincronizare și o curăță conform filtrului blockstudio/pages/orphan_action.
Directoarele listate în paths sunt descoperite ca dosarele normale ale colecției. Acestea pot conține fișiere Markdown sau dosare page.json. Dacă aceste căi sunt în afara rădăcinii colecției, se aplică același filtru pentru căi externe.
Folosiți o intrare de tip șir când directorul extern trebuie să-și păstreze propriile căi logice. Folosiți o intrare de tip obiect când directorul trebuie montat sub un prefix de cale al colecției:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
Cu această configurație, cli-docs/index.md devine path: "cli", iar cli-docs/getting-started.md devine path: "cli/getting-started" în colecție. Prefixele previn și coliziunile dintre numele paginilor generate, astfel încât fiecare dintre mai multe directoare montate să poată conține index.md sau getting-started.md. Setați preserveNames la true în obiectul de cale dacă trebuie păstrate valorile explicite name din metadatele frontmatter page.json sau Markdown.
Proprietățile obiectului de cale:
| Proprietate | Tip | Descriere |
|---|---|---|
path |
string |
Director local de detectat. Căile relative sunt rezolvate pornind de la rădăcina colecției. |
prefix |
string |
Prefix opțional al căii logice în cadrul colecției. |
preserveNames |
boolean |
Păstrează numele explicite ale paginilor în loc să generezi nume din calea prefixată. Valoarea implicită este false când prefix este setat. |
meta |
object |
Metadate îmbinate în fiecare pagină detectată din această cale. Metadatele paginii au prioritate pentru cheile duplicate. |
render |
string|object |
O definiție de redare pentru paginile Markdown ale acestei căi, care înlocuiește render al încărcătorului. |
Redarea Markdown printr-o componentă
Cu render, paginile Markdown descoperite de un încărcător sunt randate printr-un renderer de pagini, în loc să fie stocate ca blocuri:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
Rămân pagini Markdown: tipul de conținut, calea conținutului, răspunsurile .md și metadatele inițiale rămân neschimbate. Sincronizarea stochează un singur bloc blockstudio/page, al cărui conținut interior HTML este Markdown convertit și igienizat atunci când colecția își igienizează conținutul, în locul blocurilor analizate, astfel că post_content păstrează textul documentului. Rendererul primește acel HTML drept slot și poate citi sursa din page.content_path. Căile relative sunt rezolvate pornind de la rădăcina colecției; filtrul căilor externe se aplică la fel ca pentru căi. O pagină ale cărei metadate inițiale setează propriul render sau render: false este exclusă.
Aspecte
Un fișier layout.php încadrează randarea în interfața publică a unei pagini bazate pe fișier. Nu înlocuiește post_content sincronizat, stocat în WordPress, și nici nu încadrează zona de editare. Aspectul rulează doar la solicitările individuale din interfața publică.
Pentru colecții, plasați layout.php lângă pages.json pentru a încadra fiecare pagină din colecție în interfața publică:
<?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() afișează corpul paginii pe care WordPress l-ar reda în mod normal prin the_content. Dacă un aspect nu afișează blockstudio_page_content(), conținutul paginii este ascuns intenționat.
Aspectele pot folosi funcțiile auxiliare pentru pagini:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
Paginile imbricate care nu fac parte din colecții pot moșteni și cel mai apropiat layout.php părinte din arborele pages. Pentru paginile colecțiilor, aspectul rădăcinii colecției este stocat în fiecare postare sincronizată și urmărit ca parte a amprentei paginii, astfel încât modificările aspectului sunt preluate la următoarea sincronizare.
Machete pentru renderer
O machetă poate fi și o intrare de renderer, cum ar fi layout.tsx pentru un renderer care înregistrează layouts: ["layout.tsx"]. Este găsită în aceleași locuri ca layout.php, iar un fișier opțional layout.data.php alăturat este încărcătorul său de date. La redare, rendererul primește kind: "layout" și conținutul randat al paginii ca slot, la aceeași prioritate the_content ca layout.php. Un director poate conține layout.php sau o machetă de renderer, dar nu ambele; prezența ambelor este o eroare de detectare. Eșecul machetei declanșează blockstudio/pages/layout_error și lasă conținutul paginii fără înveliș, la fel ca în cazul layout.php.
Modul de editare a blocurilor
Proprietatea blockEditingMode controlează modul în care pot fi editate blocurile în editor. Setați o valoare implicită la nivel de pagină în page.json și suprascrieți-o pentru fiecare element în șablon:
{
"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>
| Valoare | Descriere |
|---|---|
"default" |
Editare completă. Blocurile pot fi selectate, mutate și editate |
"contentOnly" |
Doar editarea textului. Textul blocului poate fi editat, însă setările și structura sunt blocate |
"disabled" |
Fără editare. Blocurile sunt complet neinteractive |
Suprascrierile pentru fiecare element se setează ca atribute HTML pe orice element (<h1>, <p>, <div> etc.) sau pe elemente <block>. Blocurile container părinte ale elementelor suprascrise sunt setate automat la contentOnly, astfel încât elementele copil să rămână accesibile. Această propagare urcă de la elementul suprascris până la rădăcina paginii, așa că trebuie să setați blockEditingMode doar pentru elementele pe care doriți să le faceți editabile.
Blocarea șablonului
Proprietatea templateLock controlează modul în care utilizatorii pot edita pagina în editor:
| Valoare | Adăugare/Eliminare | Mutare | Editare conținut |
|---|---|---|---|
"all" |
Nu | Nu | Nu |
"insert" |
Nu | Da | Da |
"contentOnly" |
Nu | Nu | Da |
false |
Da | Da | Da |
Când este setat un templateLock, Blockstudio dezactivează posibilitatea de a debloca blocurile prin UI editorului.
Rute virtuale
Unele documente nu au o postare asociată: o referință la componente generată din date, un catalog sau o zonă de cont. Înregistrați-le ca rute virtuale în loc să vă ocupați personal de 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(),
]
);
} );
Calea este relativă la pagina principală a site-ului. Cu prefix, ruta deservește și toate căile de sub ea, iar match primește restul căii (un șir gol pentru ruta însăși) și returnează valoarea primită de funcția de randare sau null pentru a lăsa URL să gestioneze WordPress, care apoi răspunde cu 404 ca de obicei. Funcția de randare afișează documentul sau îl returnează ca șir; title este un șir sau o funcție de închidere care primește valoarea potrivirii.
Pentru o solicitare potrivită, Blockstudio împiedică WordPress să semnaleze un 404 și redirect_canonical să o redirecționeze, șterge starea singulară raportată de interogarea principală, trimite codul de stare (status, 200 implicit) și redă conținutul cu prioritatea Virtual_Routes::PRIORITY pentru template_redirect. Aceasta are loc imediat după ce se deschide bufferul de ieșire al Blockstudio la Assets::BUFFER_PRIORITY, astfel încât documentul final să primească resursele blocurilor, resursele UI incluse în pachet și Tailwind compilat, ca orice pagină, și înainte de redirect_canonical la prioritatea 10. Un gestionar care redă singur un document întreg trebuie să ruleze și după Assets::BUFFER_PRIORITY, altfel procesarea respectivă este omisă. Căile din urls (implicit, calea rutei însăși, când nu este o rută prefix) sunt adăugate la generările prerandate static, iar Virtual_Routes::urls() le returnează ca URL-uri absolute pentru un sitemap. Virtual_Routes::match( $path ) rezolvă o cale în același mod ca o solicitare.
Comportamentul sincronizării
Postările de pagină se modifică doar printr-o operațiune explicită de sincronizare:
wp bs pages sync
Comanda descoperă inventarul complet al surselor, creează sau actualizează postările modificate, elimină orfanii confirmați, reîmprospătează rutarea colecțiilor și configurația compilată templateFor și raportează ce s-a schimbat. Adăugați --authoritative pentru a înlocui conținutul gestionat în loc să păstrați conținutul editat în editor și asociat cheilor, iar --full pentru a raporta rularea ca reconciliere completă, indiferent de identitatea sursei stocată:
wp bs pages sync --authoritative --full
Solicitările obișnuite de inițializare a interfeței publice, a zonei de administrare, AJAX, REST, cron și WP-CLI generică nu efectuează descoperirea completă a paginilor, nu consultă inventarul gestionat pentru reconciliere și nu scriu postări de pagină. Acestea folosesc postările WordPress deja sincronizate, alături de configurația compactă a colecțiilor și a șabloanelor de tipuri de postări, salvată de ultima operațiune explicită. La o instalare nouă sau după o actualizare, este posibil să se scaneze manifestele colecțiilor o singură dată pentru a restaura metadatele de rutare; această inițializare doar citește datele și nu sincronizează conținutul. Punctul final de reîmprospătare Canvas autentificat și opțional este o API explicită pentru creare: Canvas îl apelează o dată la deschiderea spațiului de lucru, astfel încât sursele adăugate sau modificate să apară în inventarul inițial. Modul Live apelează aceeași interfață când detectează o modificare a sursei paginii.
Blockstudio\Pages::init() înregistrează acum doar hook-uri la momentul solicitării. Integrările care transmiteau anterior un argument force acestei metode trebuie să apeleze Blockstudio\Pages::reconcile() sau să ruleze wp bs pages sync.
Pentru a împiedica suprascrierea unei pagini după editări manuale, setați "sync": false în page.json.
Locații portabile ale sursei
Fișierele de temă sincronizate sunt stocate ca locații relative la temă, nu ca căi absolute de instalare. Fișierele temei copil și ale temei părinte își păstrează identitățile distincte, chiar și când au același nume de fișier relativ. Ajutoarele paginii returnează în continuare valorile absolute rezolvate template_path, content_path, layout_path și directory pentru cererea curentă.
Astfel, CLI sincronizarea și solicitările web pot folosi rădăcini diferite ale sistemului de fișiere, ca pe găzduirea cu acces restricționat, fără a afecta răspunsurile Markdown, machetele, scanarea Tailwind sau urmărirea sursei de pre-randare. Căile absolute existente ale temei sunt redefinite la citire atunci când numele directorului temei nu s-a schimbat. Pentru a le citi, nu este necesară sincronizarea, migrarea bazei de date sau scrierea metadatelor la momentul solicitării; următoarea sincronizare explicită salvează locațiile portabile.
Un director de temă care este o legătură simbolică, de exemplu către o copie de lucru pentru dezvoltare, stochează aceleași locații theme: indiferent dacă sursa a fost citită prin legătura simbolică sau prin ținta acesteia și le rezolvă în directorul de temă configurat.
Fișierele din afara temelor copil și părinte active sunt în continuare acceptate la căile lor absolute configurate, sub rezerva restricțiilor open_basedir ale PHP. Acestea nu pot fi relocate automat: după mutarea unei surse externe, actualizați calea configurată și rulați o sincronizare explicită.
Gestionarea câmpurilor articolelor
postStatus setează starea inițială. Sincronizările ulterioare păstrează stările existente de ciornă, în așteptare, privată, publicată și programată, inclusiv cu --authoritative. O ciornă nu este republicată doar pentru că fișierul indică postStatus: "publish". Comportamentul existent de recuperare a elementelor orfane rămâne neschimbat: o sincronizare explicită restaurează un articol gestionat, mutat la gunoi, dacă sursa acestuia există. Blocați pagina sau dezactivați sincronizarea pentru a împiedica restaurarea.
Fișierul continuă să controleze titlul, slugul, tipul articolului, părintele și ordinea configurată în meniu. Modificarea acestora în WordPress nu schimbă definiția sursei. Următoarea sincronizare explicită reaplică valorile din fișier și enumeră câmpurile afectate în pages.<name>.overwritten, cu un avertisment în rezultatul tabelar CLI. Se aplică în continuare permisiunile native ale WordPress, inclusiv slugul gol pentru articolele în așteptare atunci când utilizatorul care sincronizează nu le poate publica.
Folosiți blockstudio/pages/update_post_data pentru o integrare care gestionează în mod explicit o politică diferită privind starea. Blocurile cu chei păstrează conținutul blocurilor gestionat de editor; cheile nu schimbă cine gestionează titlul sau slugul articolului.
Pentru paginile colecțiilor, amprentele includ manifestul, încărcătorul, sursa paginii, fișierul de aspect, metadatele și căile surselor asociate. Următoarea sincronizare explicită aplică modificările acestor intrări.
Când o sursă a colecției este eliminată, Blockstudio șterge pagina generată, astfel încât paginile vechi ale colecției să nu rămână după dispariția fișierului sursă. În mod implicit, paginile orfane ale colecției sunt mutate la coșul de gunoi. Folosiți blockstudio/pages/orphan_action pentru a returna trash, delete sau keep.
La solicitările interfeței publice, Blockstudio încarcă registrul paginilor din postările publicate și deja sincronizate. Paginile în starea ciornă și cele private sunt disponibile în zonele de administrare și sincronizare, dar funcțiile auxiliare din interfața publică încarcă doar paginile publicate.
Reconcilierea implementării
Blockstudio\Pages::reconcile() este punctul de intrare pentru PHP implementării. Descoperă întregul inventar dorit, compară amprentele surselor și ale motorului de sincronizare și returnează un raport care poate fi citit de mașini:
$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',
],
],
]);
Raportul conține discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, rezultate pentru fiecare pagină, erori de descoperire și un sourceIdentity determinist.
Paginile blocate au status: "locked" și sunt numărate separat de paginile neschimbate. removedPages enumeră pentru fiecare pagină eliminată name, key, postId și valoarea efectivă action (trash sau delete); articolele păstrate sau deja mutate la gunoi nu sunt numărate ca nou eliminate. Rezultatul tabelar CLI enumeră și paginile create, actualizate, blocate, eliminate și cu conținut păstrat, împreună cu ID-urile articolelor.
După analizare și combinarea pe baza cheilor, un articol final identic nu apelează wp_update_post(), nu modifică post_modified, nu creează o revizie și nu declanșează hook-uri de actualizare a articolului. Rezultatul său este unchanged. Când conținutul sursei diferă de conținutul gestionat de editor pentru blocurile cu chei, preserved: true identifică acea decizie, iar contorul de nivel superior preserved o include. Amprenta nouă a sursei și metadatele gestionate sunt totuși înregistrate, astfel încât următoarea sincronizare fără modificări să nu facă nimic. preserved este un indicator suplimentar, nu o stare exclusivă: o pagină poate păstra conținutul blocurilor cu chei și, în același timp, poate actualiza un titlu gestionat de fișier sau adăuga un alt bloc.
authoritative: true poate elimina o blocare Page Sync și înlocuiește conținutul cu cel din definiția fișierului, în loc să păstreze conținutul editat în editor și asociat cheilor. Lăsați-l false pentru o sincronizare explicită obișnuită. plan_valid: false, full: true, broad: true, lipsa unei identități anterioare a sursei sau modificarea amprentei motorului de sincronizare marchează rularea drept o reconciliere completă (fullReconciliation în raport). Fiecare rulare compară oricum inventarul complet. Înregistrările de redenumire Git sunt doar indicii de identitate. Acestea nu înlocuiesc niciodată compararea inventarului complet.
Amprentele identice, cu căile de rulare neschimbate, nu generează scrieri în postări sau metadatele acestora și nu declanșează hook-uri de actualizare. Când o sursă neschimbată este mutată într-un director nou al versiunii, reconcilierea reîmprospătează doar căile salvate pentru șablon, conținut, aspect și director; nu actualizează post_content sau marcajul temporal al modificării postării. Paginile gestionate lipsă sunt eliminate numai după ce rularea completă a reconcilierii se încheie fără erori de descoperire sau de scriere a paginilor.
Reconcilierea directă API nu marchează implementarea ca reușită. După activarea și verificarea artefactului static și a rutelor corespunzătoare, salvați explicit identitatea returnată:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync salvează identitatea returnată după o rulare reușită. Inițializarea obișnuită WP-CLI înregistrează doar tipurile de postări ale colecțiilor și regulile de rescriere salvate. Nu descoperă și nu sincronizează pagini.
Fixarea ID-urilor postărilor
În mod implicit, WordPress atribuie automat ID-uri postărilor. Dacă o pagină este ștearsă și recreată, ID-ul se schimbă, întrerupând referințele externe precum meniurile sau linkurile hardcodate.
Folosiți postId pentru a fixa o pagină la un anumit ID:
{
"name": "about",
"title": "About Us",
"postId": 42
}
La crearea paginii, Blockstudio transmite ID-ul către WordPress prin import_id. Dacă ID-ul este disponibil, WordPress îl folosește întocmai. Dacă ID-ul este deja ocupat de o postare fără legătură, WordPress atribuie automat un ID nou, fără notificare.
La căutarea paginilor existente, Blockstudio verifică mai întâi ID-ul fixat, înainte să verifice metadatele sau slug-ul. Asta înseamnă că, dacă o pagină este ștearsă și sincronizată din nou, își recapătă același ID.
Îmbinarea blocurilor cu chei
În mod implicit, când se modifică un fișier șablon, Blockstudio înlocuiește întregul conținut al postării cu noul șablon. Asta înseamnă că se pierd toate editările făcute în editorul WordPress.
Adăugați atributul key blocurilor pentru a păstra editările utilizatorilor între sincronizările șablonului. Dacă un șablon conține blocuri cu chei, Blockstudio îmbină modificările șablonului cu conținutul existent al postării, în loc să îl înlocuiască.
Adăugarea cheilor
Folosiți atributul key pe orice element HTML sau <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"
/>
Cheile trebuie să fie unice la nivel global în întregul șablon. O cheie protejează blocul întreg și tot conținutul acestuia. Nu este nevoie să atribuiți chei copiilor individuali dintr-un bloc care are deja o cheie. Blocurile cu chei pot fi mutate oriunde și imbricate la orice nivel între actualizările șablonului, iar conținutul lor va fi păstrat.
Cheile funcționează la fel și pentru blocurile personalizate Blockstudio. key reprezintă metadatele structurale Page Sync; valorile câmpurilor personalizate rămân atribute Blockstudio obișnuite. Când un editor modifică acele câmpuri, o sincronizare ulterioară a șablonului păstrează valorile editorului și aplică în continuare modificările independente ale șablonului. Paginile create cu versiuni mai vechi, în care cheia se află în datele câmpului personalizat, sunt migrate automat la următoarea sincronizare.
Cum funcționează îmbinarea
Când un fișier șablon se modifică și pagina este sincronizată din nou:
| Bloc | Comportament |
|---|---|
| Bloc cu cheie | Conținutul utilizatorului și valorile câmpurilor Blockstudio sunt păstrate. Atributele și structura gestionate de șablon sunt aplicate. |
| Bloc fără cheie | Este înlocuit în întregime cu versiunea din șablon (la fel ca în lipsa cheilor) |
Exemple
Editările utilizatorilor din blocurile cu chei sunt păstrate:
- Șablonul definește
<p key="intro">Default intro.</p> - Utilizatorul editează paragraful în editor, înlocuindu-l cu „Text introductiv personalizat.”
- Dezvoltatorul actualizează șablonul, adaugă un bloc nou și modifică aspectul
- La sincronizare: paragraful păstrează „Text introductiv personalizat.”, iar noul aspect este aplicat
Atributele din șablon se aplică în continuare:
- Șablonul conține un bloc copertă cu
key="hero"și un atributurl - Dezvoltatorul schimbă atributul
urlal copertei cu o nouă imagine de fundal - La sincronizare: se aplică noua imagine de fundal, dar editările utilizatorului din conținutul copertei sunt păstrate
Situații speciale
| Situație | Comportament |
|---|---|
| Bloc nou cu cheie adăugat la șablon | Apare cu conținutul implicit din șablon |
| Bloc cu cheie eliminat din șablon | Este șters din postare |
| Tipul blocului se schimbă (aceeași cheie) | Șablonul se aplică în întregime, fără îmbinarea conținutului |
| Chei duplicate | A doua apariție este tratată ca un bloc fără cheie |
| Șablonul nu conține chei | Înlocuire completă (același comportament ca în lipsa cheilor) |
| Sincronizare forțată | Înlocuire completă; cheile sunt ignorate |
| Postare blocată | Nu se sincronizează deloc |
Combinarea cu comenzile de editare
Cheile, templateLock și blockEditingMode vă oferă împreună control detaliat asupra acțiunilor permise și interzise clienților. Iată câteva tipare obișnuite de lucru.
Pagină blocată complet
Dezvoltatorul controlează totul. Pagina are un aspect static pe care clienții nu îl pot modifica deloc. Este utilă pentru pagini juridice, condiții de utilizare sau orice pagină care ar trebui să se schimbe doar prin cod.
{
"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>
Nu sunt necesare chei. Șablonul este unica sursă de adevăr. Fiecare sincronizare suprascrie întreaga pagină.
Aspect blocat cu conținut editabil
Cel mai frecvent tipar. Blocați structura paginii, astfel încât clienții să nu poată adăuga, elimina sau rearanja blocuri, dar permiteți-le să editeze textul în anumite locuri. Cheile garantează că editările lor se păstrează la actualizarea șabloanelor.
{
"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>
Clientul poate edita titlul principal, descrierea și introducerea despre funcționalități. Nimic altceva. Textul butonului, URL și imaginea de fundal a copertei sunt controlate de dezvoltator. Când dezvoltatorul actualizează șablonul (e.g., adaugă un al doilea buton), secțiunile cu chei păstrează textul clientului.
Șablon în evoluție cu conținut păstrat
Pentru pagini care cresc în timp. Dezvoltatorul adaugă secțiuni noi în șablon, iar fiecare sincronizare adaugă conținutul nou fără să atingă ceea ce clientul a personalizat deja.
<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>
Secțiunea nouă de mărturii și butonul apar la sincronizare. Modificările clientului la titlu, introducere și servicii rămân neatinse.
Structură inițială creată o singură dată
Creați o pagină cu o structură inițială, apoi predați-o complet. Setați sync la false astfel încât sincronizarea obișnuită să nu creeze sau să actualizeze pagina și creați-o o singură dată cu Blockstudio\Pages::force_sync('blog'). După aceea, clientul deține pagina în întregime.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
wp bs pages sync omite această pagină, așa că force_sync() o creează o singură dată. După aceea, clientul poate adăuga, elimina și rearanja blocuri fără restricții. Modificările șablonului sunt ignorate.
Legături între blocuri
O alternativă la îmbinarea pe bază de chei este folosirea WordPress core Legături între blocuri API pentru a conecta blocurile la meta datele articolului. Aceasta nu este o funcționalitate Blockstudio, ci o capacitate nativă din WordPress API. Blockstudio transmite pur și simplu atributul metadata către marcajul blocului generat. Conținutul este stocat în meta datele articolului, nu în marcajul blocului, astfel încât sincronizările șablonului pot suprascrie liber marcajul, deoarece editorul citește din meta date, nu din innerHTML.
Transmiteți atributul metadata către orice element HTML sau <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"}}}}'
/>
Cheile meta trebuie înregistrate cu show_in_rest activat:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Chei vs. legături
| Aspect | Chei | Legături |
|---|---|---|
| Conținut stocat în | Marcajul blocului (post_content) |
Meta datele articolului (wp_postmeta) |
| Se păstrează la sincronizarea șablonului | Da (îmbinat după cheie) | Da (datele sunt în meta date) |
Poate fi interogat prin WP_Query |
Nu | Da (meta_query) |
| Disponibil în REST API | Nu | Da |
| Necesită înregistrare | Nu | Da (register_post_meta) |
| Utilizatorul poate muta blocurile | Nu (șablonul restabilește structura) | Nu (șablonul restabilește structura) |
Ambele abordări pot fi folosite în același șablon. Folosiți cheile pentru secțiunile în care structura blocurilor contează (e.g., un grup cu mai mulți copii). Folosiți legăturile pentru câmpuri individuale atunci când doriți ca datele să fie accesibile și în afara editorului de blocuri.
Șabloane pentru tipuri de articole
Folosiți templateFor pentru a seta o pagină drept șablon implicit pentru un tip de articol:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
Toate articolele noi de acel tip vor începe cu structura de blocuri definită.
Căi personalizate
În mod implicit, Blockstudio scanează get_template_directory() . '/pages'. Adăugați căi suplimentare cu filtrul:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
Integrările de execuție care combină fișiere din mai multe rădăcini pot înlocui scanarea sistemului de fișiere cu o sursă logică de descoperire. Manifestele paginilor, machetele, încărcătoarele și șabloanele sursă sunt apoi rezolvate după calea logică, chiar dacă fișierele selectate se află în rădăcini diferite.
Filtre și acțiuni
Descoperirea paginilor, sincronizarea și rutarea colecțiilor oferă următoarele puncte de extensie:
| Hook | Tip | Descriere |
|---|---|---|
blockstudio/pages/paths |
Filtru | Adaugă directoare în care Blockstudio caută sursele paginilor. |
blockstudio/pages/collection_post_type_args |
Filtru | Ajustează argumentele register_post_type() pentru un CPT de colecție. |
blockstudio/pages/template_candidates |
Filtru | Ajustează numele fișierelor șablon luate în considerare pentru o sursă de pagină. |
blockstudio/pages/serve_markdown |
Filtru | Activează sau dezactivează răspunsurile brute Markdown. |
blockstudio/pages/orphan_action |
Filtru | Returnează trash, delete sau keep pentru curățarea elementelor orfane. |
blockstudio/pages/docs_allowed_html |
Filtru | Ajustează valorile HTML permise pentru conținutul documentației Markdown generate. |
blockstudio/pages/allow_external_loader_path |
Filtru | Permite ca paths încărcătorului să fie în afara rădăcinii colecției. |
blockstudio/pages/manifest_scan_interval |
Filtru | Setează vechimea maximă a unei memorii cache a manifestului vechi, anterioare 7.6.2, care poate inițializa configurația persistentă de execuție în timpul unei actualizări. |
blockstudio/pages/create_post_data |
Filtru | Modifică datele articolului înainte de crearea unei pagini sincronizate. |
blockstudio/pages/update_post_data |
Filtru | Modifică datele articolului înainte de actualizarea unei pagini sincronizate. |
blockstudio/pages/sync_engine_inputs |
Filtru | Adaugă o versiune de analizator, mapare sau migrare care ar trebui să extindă în mod intenționat reconcilierea o singură dată. |
blockstudio/pages/post_created |
Acțiune | Se execută după crearea unui articol de pagină sincronizat. |
blockstudio/pages/post_updated |
Acțiune | Se execută după actualizarea unui articol de pagină sincronizat. |
blockstudio/pages/synced |
Acțiune | Se execută după încheierea sincronizării registrului de pagini. |
blockstudio/pages/reconciled |
Acțiune | Se execută după o reconciliere explicită, împreună cu raportul care poate fi citit automat. |
blockstudio/pages/renderers |
Acțiune | Înregistrează randerele de pagini cu Blockstudio\Page_Renderers::register(). Se declanșează o dată pentru fiecare solicitare. |
blockstudio/pages/rendered |
Acțiune | Se execută după randarea unei pagini de componentă, împreună cu pagina, HTML acesteia și dependențele sale. |
blockstudio/pages/layout_error |
Acțiune | Se execută atunci când o machetă nu poate fi randată, împreună cu eroarea, calea machetei și 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]);
Consultați Reconcilierea implementării pentru semantica argumentelor, câmpurile raportului și limita verificată a identității sursei.
Funcțiile globale helper sunt disponibile pentru șabloane și machete:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
Tablourile de pagini returnate de Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() și funcțiile globale helper includ identitatea articolului sincronizat, căile sursei și șablonului, metadatele colecției/căii, tipul de conținut, politica de sincronizare, tipul/starea articolului, politica de editare, metadatele personalizate și o cheie permalink. Metadatele colecției sunt încărcate din ultima reconciliere explicită reușită. Cererile obișnuite reconstruiesc aceste date de execuție din configurația persistentă și meta datele articolelor sincronizate, fără a citi arborii sursă ai paginilor. Clasa Pages nu expune o metodă separată pentru legătura permanentă.
Crearea paginilor bazate pe fișiere
Blocarea șabloanelor, modurile de editare a blocurilor, îmbinarea pe bază de chei și controlul asupra elementelor pe care le pot edita clienții.