Treci la conținut

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:

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:

JSON
{
  "name": "intro",
  "title": "Intro",
  "markdown": "# Intro\n\nThis page is generated from inline markdown."
}
JSON
{
  "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:

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

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

Markdown
---
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.

JSON
{
  "name": "docs-reference",
  "title": "Reference",
  "path": "reference",
  "sync": true
}
Markdown
---
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:

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

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

Text
pages/legal-notice/
  page.json
  page.tsx
  data.php
JSON
{
  "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:

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

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

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

Cod
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
    loader.php
JSON
{
  "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' ).

JSON
{
  "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.json imbricate îș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ă render se 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
<?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:

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

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

JSON
{
  "name": "about",
  "title": "About Us",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<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:

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

Shell
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ă:

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

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

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

JSON
{
  "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>:

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

  1. Șablonul definește <p key="intro">Default intro.</p>
  2. Utilizatorul editează paragraful în editor, înlocuindu-l cu „Text introductiv personalizat.”
  3. Dezvoltatorul actualizează șablonul, adaugă un bloc nou și modifică aspectul
  4. La sincronizare: paragraful păstrează „Text introductiv personalizat.”, iar noul aspect este aplicat

Atributele din șablon se aplică în continuare:

  1. Șablonul conține un bloc copertă cu key="hero" și un atribut url
  2. Dezvoltatorul schimbă atributul url al copertei cu o nouă imagine de fundal
  3. 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.

JSON
{
  "name": "terms",
  "title": "Terms of Service",
  "templateLock": "all"
}
HTML
<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.

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<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.

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

JSON
{
  "name": "blog",
  "title": "Blog",
  "sync": false
}
HTML
<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>:

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

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

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

JSON
{
  "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:

PHP
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

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

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