Stránky
Stránky sú šablóny zo súborov, ktoré sa synchronizujú s databázou WordPress ako príspevky.
Synchronizácia je explicitná: spustite wp bs pages sync alebo zavolajte Pages API, keď chcete použiť zmeny v zdroji. Načítanie frontendu alebo administrácie WordPress nikdy nespustí úplné vyhľadanie stránok ani nezmení príspevky stránok.
Stránky možno definovať ako jeden priečinok page.json, ako samostatné súbory Markdown alebo ako kolekciu s manifestom pages.json. Kolekcie sú užitočné pre dokumentáciu, vedomostné databázy, knižnice vstupných stránok alebo ľubovoľné skupiny vnorených stránok, ktoré sa majú vytvárať zo súborov.
page.json
Pre stránku definovanú pomocou JSON pridajte konfiguračný súbor page.json:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
Vlastnosti
| Vlastnosť | Typ | Predvolená hodnota | Opis |
|---|---|---|---|
name |
string |
povinné | Jedinečný identifikátor stránky |
title |
string |
Automaticky podľa názvu | Názov stránky |
slug |
string |
Rovnaké ako názov | URL slug stránky |
path |
string |
"." |
Logická cesta v kolekcii |
order |
integer |
0 |
Poradie v ponuke synchronizovaného príspevku |
postType |
string |
"page" |
Typ príspevku WordPress |
postStatus |
string |
"draft" |
Stav nových príspevkov (publish, draft, pending, private) |
postId |
integer |
– | Pripne stránku ku konkrétnemu ID príspevku WordPress |
blockEditingMode |
string |
– | Režim úprav bloku: "default", "contentOnly" alebo "disabled" |
templateLock |
string|false |
"all" |
Režim uzamknutia: "all", "insert", "contentOnly" alebo false |
templateFor |
string|null |
null |
Nastaví sa ako predvolená šablóna pre typ príspevku |
sync |
boolean |
true |
Určuje, či môže bežné výslovné zosúladenie vytvoriť alebo aktualizovať príspevok |
render |
string|object|false |
– | Vykreslí stránku pomocou registrovaného vykresľovača stránok (pozrite si Stránky komponentov) |
Medzi page.json, frontmatter a položky loadera patria medzi rozpoznávané kľúče blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock a title. Každý kľúč, ktorý nie je uvedený vyššie, sa uloží do poľa meta stránky.
Zdroje obsahu
Definícia stránky určuje, ktorý príspevok WordPress má existovať. Zdroj obsahu určuje, aké značky blokov sa doň zapíšu.
Ak priečinok stránky obsahuje súbor page.json, Blockstudio hľadá súbor zdroja vedľa neho v tomto poradí:
| Súbor | Použitie |
|---|---|
index.php |
Značky blokov podobné HTML, čítajú sa bez úprav (kód PHP sa nespúšťa) |
index.blade.php |
Obsah šablóny Blade |
index.twig |
Obsah šablóny Twig |
index.md |
Obsah Markdown |
page.json môže namiesto súboru vedľa neho obsahovať aj vložené markdown alebo html:
{
"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>"
}
Kolekcie pridávajú dva ďalšie režimy zdrojov:
- Súbory Markdown nájdené priamo v strome kolekcie.
- Položky načítavača vrátené z
loader.php.
Položky načítavača môžu používať markdown, html alebo content spolu s contentType. Môžu tiež odkazovať na lokálny file alebo template. Typ súborových a šablónových zdrojov sa určuje podľa prípony, pokiaľ nie je výslovne nastavené contentType.
Podporované hodnoty contentType sú php, blade, twig, markdown a html. Markdown sa najprv prevedie na HTML a potom sa analyzuje na natívne bloky WordPress. Zdroje PHP, Blade, Twig a HTML prechádzajú bežným parserom stránok Blockstudio.
Triedy v blokoch jadra
Trieda class na prvku HTML namapovanom na blok jadra sa stane jeho className.
Explicitná značka bloku jadra môže priamo použiť className. Obe formy zachovajú
triedy v uloženej obalovej značke bloku spolu s triedami, ktoré generuje WordPress:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
Ak sú prítomné obe vlastnosti, prednosť má className. Táto konverzia sa
vzťahuje iba na bloky jadra: mapovanie vlastného bloku ponechá jeho pole class
nezmenené. Triedy štýlu tlačidla, ako napríklad is-style-outline, patria obalovému prvku
tlačidla, nie jeho odkazu.
Spustením wp bs pages sync použijete opravy parsera na predtým synchronizované
stránky. Aktualizácie parsera sa rozpoznajú pri nasledujúcej explicitnej synchronizácii bez úpravy
zdrojového súboru. Uzamknuté stránky a stránky s sync: false si zachovávajú svoju
bežnú ochranu; požiadavky frontendu túto synchronizáciu nikdy nevykonávajú.
Bloky WordPress v serializovanej podobe
Zdroje stránok a vzorov môžu obsahovať aj serializované bloky skopírované z editora kódu WordPress:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
Ak zdroj obsahuje oddeľovač bloku <!-- wp:... -->, Blockstudio
použije na celý zdroj natívny parser blokov WordPress. Atribúty,
vnorené bloky, dynamické bloky, ako napríklad Query Loop, a bloky Blockstudio
si zachovajú svoju serializovanú štruktúru. Obsah HTML mimo komentárov blokov zostáva
natívnym voľným obsahom HTML; nemapuje sa na ďalšie bloky. Nemiešajte značky blokov HTML Blockstudio s týmto formátom a neočakávajte, že sa prevedú. Bežné komentáre HTML neaktivujú režim serializovaných blokov.
Stránky Markdown
Použite Markdown, ak má byť text uložený v súboroch, ale po synchronizácii sa má zmeniť na upraviteľný obsah blokov WordPress. Zdroj Markdown sa počas synchronizácie prevedie na značky blokov. Synchronizovaný príspevok ukladá bloky, nie pôvodný text Markdown.
Markdown možno použiť tromi spôsobmi:
| Zdroj | Vyžaduje frontmatter? | Poznámky |
|---|---|---|
Samostatný súbor pages/example/index.md |
Áno | Frontmatter poskytuje identitu stránky. |
page.json a index.md |
Nie | page.json definuje stránku a Markdown poskytuje obsah. |
| Markdown v kolekcii | Nie | Kolekcia odvodí name a path z umiestnenia súboru. |
Samostatný súbor index.md bez frontmatter sa preskočí, pretože Blockstudio nemá identitu stránky, ktorú by mohol synchronizovať. Kolekcia Markdown frontmatter nepotrebuje, pretože túto identitu poskytuje manifest kolekcie a cesta k súboru.
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
page.json môžete skombinovať aj s index.md. V takom prípade page.json definuje stránku a index.md poskytuje obsah. Frontmatter v index.md má prednosť pred zodpovedajúcimi hodnotami page.json.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
title: API Reference
order: 20
---
# Reference
This page uses `page.json` with Markdown content.
Pri kolekcii Markdown sa cesta k súboru stáva logickou cestou stránky, pokiaľ ju neprepíše frontmatter:
| Súbor | Predvolená cesta |
|---|---|
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 |
Neznáme kľúče frontmatter sa zachovajú v poli meta stránky. Môžete tak pripojiť údaje, napríklad section alebo description, a čítať ich z PHP API.
Markdown sa analyzuje ako GitHub s rozšírením Markdown. Pôvodný HTML je povolený, nebezpečné odkazy sa odstránia a nadpisy bez výslovného ID dostanú stabilné ID. Vnorený frontmatter YAML vyžaduje pribalený parser YAML.
Pôvodný Markdown
Zdroje súborov Markdown môžu sprístupniť pôvodný zdroj Markdown pre externé nástroje a používateľov dokumentácie. Vložený Markdown nemá zdrojový súbor, preto sa synchronizuje do blokov, ale nevytvára pôvodnú odpoveď .md.
Požiadajte o stránku s príponou .md, napríklad https://example.com/docs/reference.md. Alebo odošlite hlavičku Accept: text/markdown na bežnú cestu stránky URL:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
Frontmatter sa z odpovede odstráni. Úspešné pôvodné odpovede Markdown odošlú hlavičky Content-Type: text/markdown, X-Robots-Tag: noindex a kanonickú hlavičku Link späť na stránku HTML. Chýbajúce cesty .md vrátia skutočný stav 404.
Vyjednávanie funguje so statickým predgenerovaním: požiadavka, ktorej hlavička Accept obsahuje text/markdown, nikdy nedostane odpoveď z úložiska predgenerovaných stránok ani z doplnku na skoré poskytovanie, takže sa dostane k WordPress a obslužnej rutine Markdown. Predgenerované odpovede HTML, HTML stránky, ktorá tiež vyjednáva Markdown, aj Markdown obslúžená cez Accept odosielajú Vary: Accept, takže vyrovnávacie pamäte, ktoré rešpektujú Vary, ich udržia oddelené. CDN, ktorý zakladá kľúč vyrovnávacej pamäte iba na URL, potrebuje vlastné pravidlo na obídenie vyrovnávacej pamäte pre takéto požiadavky. Pages::negotiates_markdown( $post_id ) uvádza, či stránka odpovedá na požiadavky Markdown.
Kolekcia Markdown zachováva rovnaký tvar URL pre pôvodný obsah Markdown:
| Cesta stránky URL | Cesta pôvodného Markdown URL |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
Vypnite odpovede s pôvodným obsahom Markdown pomocou filtra blockstudio/pages/serve_markdown:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Požiadavka .md URL, ktorá nesmeruje na stránku založenú na Markdown, vráti 404 iba vtedy, ak cesta patrí do kolekcie stránok. Mimo všetkých kolekcií Blockstudio ponechá požiadavku na obsluhu pre WordPress a ďalšie doplnky.
Stránky komponentov
Stránku komponentu vykresľuje vykresľovač stránok namiesto toho, aby sa uložila ako
bloky. Blockstudio nedodáva vykresľovač. Téma alebo plugin zaregistruje jeden
pre súbory položiek, ktoré spracúva, napríklad vykresľovač React pre page.tsx, a
Blockstudio ho zavolá s údajmi stránky, príspevkom WordPress a vykresleným obsahom slotu.
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 je výslovné. Adresár s index.php a page.tsx, ale bez render, zostáva bežnou stránkou, takže pridaním vykresľovača sa existujúca stránka nevykreslí dvakrát. Formy sú:
| Hodnota | Význam |
|---|---|
"page.tsx" |
Iba položka bez dátového loadera |
{ "entry": "page.tsx", "data": "data.php" } |
Položka a dátový loader |
{ "entry": "page.tsx", "renderer": "react" } |
Položka s výslovným ID vykresľovača |
false |
Bez vykresľovača, aj keď ho predvolené nastavenie kolekcie určuje |
Cesty sa určujú vzhľadom na adresár stránky alebo pri položkách loadera vzhľadom na koreň kolekcie. Musia zostať v rámci zdroja vyhľadávania, pokiaľ to nepovoľuje blockstudio/pages/allow_external_loader_path. Bez renderer sa použije vykresľovač, ktorý spracúva príponu položky. Chýbajúca položka alebo dátový súbor uvedený v render, neznámy vykresľovač alebo prípona, ktorú nespracúva žiadny vykresľovač, predstavujú chybu vyhľadávania, ktorá zastaví zosúladenie skôr, ako sa čokoľvek odstráni.
Čo synchronizácia ukladá
Synchronizácia ukladá jeden blok blockstudio/page. Keď má adresár stránky aj zdroj index.*, tento zdroj sa spracuje ako ľubovoľný zdroj stránky a stane sa vnútornými blokmi bloku, teda jeho slotom:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
Obsah spravovaný pomocou WordPress, napríklad skrátené kódy, ponechajte v slote. Zdroj, ktorý obsahuje iba jeden skrátený kód, napríklad [download_checkout], sa uloží ako blok core/shortcode, takže sa okolo jeho výstupu nepridá odsek. Zostáva v post_content, takže kontroly has_shortcode() ho zachytia, bloky slotu s kľúčmi sa zlúčia so zmenami v editore rovnako ako vnorené bloky s kľúčmi a do_shortcode rozbalí skrátené kódy raz pri obvyklej priorite the_content, keď ich vykresľovač obalí.
Definícia vykreslenia sa ukladá spolu s príspevkom ako prenositeľné cesty theme:. Odtlačok stránky zahŕňa definíciu, nie bajty položky ani dátového loadera: úprava page.tsx alebo data.php ponechá príspevok nezmenený a zmeny sa návštevníkom prejavia pri vykreslení a prostredníctvom predvyrenderovaného statického grafu, ktorý zaznamenáva položku, dátový loader a každý súbor nahlásený vykresľovačom.
Registrácia vykresľovača
Vykresľovače registrujte v rámci akcie blockstudio/pages/renderers. Spustí sa raz
pri každej požiadavke, pred prvým vyhľadaním alebo vykreslením, takže wp bs pages sync aj
požiadavky frontendovej časti majú rovnaký register.
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 vykresľovačov sú malé písmená. Prípona alebo názov rozloženia môžu patriť iba jednému vykresľovaču a layout.php zostáva vlastným rozložením Blockstudio. Volateľný objekt dostane jednu požiadavku:
| Kľúč | Hodnota |
|---|---|
kind |
page alebo layout pre rozloženie vykresľovača rozloženie |
renderer |
ID vykresľovača |
entry |
Absolútna cesta k položke |
data |
Absolútna cesta k dátovému loaderu alebo null |
page |
Kanonické údaje stránky vrátane meta |
post_id |
ID príspevku WordPress |
slot |
Vykreslený obsah slotu alebo obsah stránky pre rozloženie |
context |
frontend, rest, feed alebo cli |
Vráti HTML, súbory, ktoré vykreslenie načítalo, a voliteľné zdroje:
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 pochádza z typu požiadavky, nikdy nie od návštevníka, takže renderer nemôže narušiť zhodu bajtov medzi prihlásenými a anonymnými používateľmi tým, že ho načíta. Ak renderer zlyhá, vyvolá chybu: stránka sa nevyrenderuje s prázdnym telom. V náhľade editora REST sa chyba bloku namiesto toho zobrazí ako upozornenie. Po úspešnom vykreslení dostane akcia blockstudio/pages/rendered stránku, objekt HTML a jeho závislosti.
assets uvádza súbory skriptov a štýlov, ktoré stránka potrebuje. Spracujú sa ako prostriedky bloku (konvencia *.inline.*, moduly ES, minifikácia a ?ver) a stránka ich vypíše raz prostredníctvom rovnakej vyrovnávacej pamäte ako prostriedky bloku, takže ich obsahuje aj vopred vykreslená stránka. Prostriedok môže nastaviť version, aby nahradil svoju hodnotu ?ver. Kód mimo renderera môže použiť rovnaký kanál prostredníctvom Blockstudio\Assets::register_owner(), ktorý vráti komentár so značkou na vypísanie.
Editor
V editore blockstudio/page zobrazuje serverom vykreslený náhľad stránky, pričom slot tvorí vnútorné bloky, ktoré sa riadia templateLock stránky. Blok nemožno vložiť, duplikovať ani vnoriť do iného bloku.
Kolekcie stránok
Kolekcia je priečinok s manifestom pages.json. Zoskupuje viaceré zdroje stránok pod jeden slug kolekcie, uplatňuje predvolené hodnoty, podporuje vnorené cesty a môže automaticky zaregistrovať vyhradený typ príspevku.
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"
}
}
| Vlastnosť | Typ | Opis |
|---|---|---|
collection / slug / name |
string |
Slug kolekcie. collection je najzrozumiteľnejšia forma a tvorí základ verejného URL. |
title |
string |
Názov kolekcie určený ľuďom. |
postType |
string |
Typ príspevku pre generované stránky. Predvolená hodnota je page. Ak neexistuje, Blockstudio ho zaregistruje. |
postTypeArgs |
object |
Argumenty odovzdávané register_post_type(), keď Blockstudio zaregistruje typ príspevku kolekcie. |
defaults |
object |
Predvolené vlastnosti stránky použité pre každú stránku v kolekcii. Predvolená hodnota render sa použije iba na stránku, ak jej položka existuje v adresári stránok. |
scope |
string |
collection (predvolené) alebo site. Pozrite si Kolekcie stránok. |
meta |
object |
Vlastné metadáta kolekcie. Neznáme kľúče manifestu sa tiež ukladajú do meta. |
Cesty stránok v kolekcii sú logické. Stránka s hodnotou path: "guide/install" sa synchronizuje ako podradená stránka guide a guide sa synchronizuje ako podradená stránka koreňovej stránky kolekcie, ak tieto nadradené stránky existujú.
Ak hierarchická kolekcia obsahuje vnorenú stránku, ale chýba zdrojová stránka niektorého medzistupňa, Blockstudio vytvorí pre túto cestu prázdnu kontajnerovú stránku, čím sa zachová úplná hierarchia WordPress. Pri nehierarchických typoch príspevkov (bez podpory nadradeného prvku page-attributes) sa prázdne kontajnery nevytvárajú. Smerovanie sa riadi uloženou cestou kolekcie, takže vnorené cesty ako guide/install a setup/install môžu existovať súčasne, hoci obe končia na install.
Typy príspevkov a adresy URL kolekcie
Nastavte postType v manifeste kolekcie, aby sa každá stránka v kolekcii synchronizovala s daným typom príspevku. Tú istú hodnotu nemusíte opakovať v defaults. Jednotlivé stránky môžu stále prepísať postType vo frontmatter alebo v page.json.
Ak typ príspevku neexistuje, Blockstudio ho zaregistruje pomocou show_in_rest: true, teda editora nastaveného podobne ako pri stránkach, a použije slug kolekcie ako verejný základ URL. postTypeArgs môže prepísať argumenty registrácie. Pravidlá prepisovania typu príspevku kolekcie sa automaticky obnovia pri zmene zaregistrovaných typov príspevkov kolekcie alebo argumentov prepisovania, takže nemusíte znova ukladať trvalé odkazy v WordPress.
Adresy URL kolekcie používajú slug kolekcie a logickú cestu každej stránky path:
| Zdrojová cesta | Verejná URL |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
Tento model URL funguje pre hierarchické aj nehiearchické typy príspevkov kolekcie. Blockstudio tiež presmeruje zdvojené adresy URL, napríklad /docs/docs/ alebo /docs/docs/getting-started/, na kanonickú adresu URL.
Stránky kolekcie sprístupňujú surový Markdown na rovnakých adresách URL (pozrite si Surový Markdown).
Ak zmeníte kolekciu z postType: "page" na vlastný typ príspevku, Blockstudio priebežne migruje už synchronizované príspevky kolekcie, ak sa ich uložená identita stránky zhoduje. Zachovajú sa tak ID príspevkov, metadáta a existujúci obsah bez vytvárania duplicitných príspevkov so starým typom. Zastarané príspevky kolekcie sa vyčistia vo všetkých stavoch príspevkov podľa filtra blockstudio/pages/orphan_action.
Kolekcie stránok
Manifest s "scope": "site" zoskupuje všetky stránky pod sebou bez toho, aby z nich vytvoril stránky kolekcie. Použite ho v koreňovom adresári stromu stránok webu na nastavenie spoločných predvolených hodnôt a vypísanie stránok webu pomocou 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" }
}
}
Stránky kolekcie webu si zachovávajú presne tú istú identitu, akú mali bez manifestu. Pridaním manifestu do existujúceho stromu sa preto neaktualizujú žiadne riadky príspevkov ani nič nevytvorí či neodstráni z koša:
- Kľúče zostávajú globálne:
Pages::get_page( 'home' )a uložené kľúče stránok sa naďalej zhodujú. - Adresy URL zostávajú adresami stránok typu WordPress. Neuplatňujú sa žiadne pravidlá prepisovania kolekcie, filter trvalých odkazov ani presmerovanie s dvojitým URL a negenerujú sa žiadne prázdne stránky kontajnera.
- Logické cesty, slugy, nadradené stránky a identity zdrojov zostávajú rovnaké ako pri samostatných stránkach; rozloženia sa vyberajú podľa najbližšieho predka.
- Vnorené manifesty
pages.jsonsi zachovávajú vlastné kolekcie a ich podstromy sa z kolekcie webu vynechajú. - Predvolené hodnoty sa uplatňujú pre každú stránku osobitne: predvolená hodnota
rendersa použije iba na stránkach, ktorých adresár obsahuje jej položku, takže stránky so skratkovým kódom a Markdown si zachovajú svoje zdroje.
Načítavače kolekcií
Kolekcie môžu obsahovať dôveryhodný lokálny loader.php. Použite ho, ak stránky kolekcie pochádzajú z iného lokálneho zdroja, napríklad z externého priečinka s dokumentáciou, balíka alebo vygenerovaného manifestu.
Načítavač sa spúšťa pri explicitnom vyhľadávaní stránok a synchronizácii. Mal by
byť deterministický a lokálny. Vyhnite sa načítavaniu vzdialeného obsahu z loader.php,
pretože by synchronizácia nasadenia závisela od tejto služby.
<?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',
),
),
);
Načítavač môže vrátiť pole s kľúčmi pages, meta a paths:
| Kľúč | Opis |
|---|---|
pages |
Zoznam polí stránok. Každá stránka podporuje rovnaké rozpoznávané kľúče ako frontmatter page.json a Markdown. |
meta |
Metadáta zlúčené do poľa meta každej stránky vygenerovanej načítavačom. |
paths |
Ďalšie lokálne adresáre, ktoré sa majú prehľadať ako súčasť tejto kolekcie. Položky môžu byť reťazce alebo objekty ciest. |
render |
Definícia vykreslenia pre každú stránku Markdown nájdenú v paths. |
Ako skrátený zápis môže načítavač vrátiť priamo zoznam polí stránok.
Položky stránok načítavača môžu obsahovať obsah týmito spôsobmi:
| Tvar | Opis |
|---|---|
markdown |
Vložený obsah Markdown. |
html |
Vložený obsah HTML. |
content + contentType |
Všeobecný vložený obsah. contentType sa musí vyhodnotiť na markdown alebo html. |
file |
Zdroj z lokálneho súboru. Typ sa určí podľa prípony, ak nie je nastavené contentType. |
template |
Alias pre file. |
Odkazy na súbory v načítavači môžu smerovať na zdroje PHP, Blade, Twig, Markdown alebo HTML. Relatívne cesty sa vyhodnocujú vzhľadom na koreň kolekcie. Absolútne cesty a cesty mimo koreňa kolekcie sú povolené iba vtedy, ak to povoľuje filter blockstudio/pages/allow_external_loader_path.
Stránky načítavača majú predvolene generated: true. Keď vygenerovaná stránka načítavača zmizne z jeho výstupu, Blockstudio pri ďalšej synchronizácii považuje synchronizovaný príspevok za osirelý a vyčistí ho podľa filtra blockstudio/pages/orphan_action.
Priečinky uvedené v paths sa vyhľadávajú rovnako ako bežné priečinky kolekcie. Môžu obsahovať súbory Markdown alebo priečinky page.json. Ak sa tieto cesty nachádzajú mimo koreňa kolekcie, uplatňuje sa rovnaký filter externých ciest.
Použite reťazcovú položku, ak si má externý priečinok zachovať vlastné logické cesty. Objektovú položku použite, ak sa má priečinok pripojiť pod predponu cesty kolekcie:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
Pri tejto konfigurácii sa cli-docs/index.md v kolekcii zmení na path: "cli" a cli-docs/getting-started.md na path: "cli/getting-started". Predpony tiež zabraňujú kolíziám názvov vygenerovaných stránok, takže každý z viacerých pripojených priečinkov môže obsahovať index.md alebo getting-started.md. Ak sa majú namiesto toho zachovať explicitné hodnoty name z frontmatter v page.json alebo Markdown, nastavte na objekte cesty preserveNames na true.
Vlastnosti objektu cesty:
| Vlastnosť | Typ | Opis |
|---|---|---|
path |
string |
Lokálny adresár, ktorý sa má prehľadať. Relatívne cesty sa vyhodnocujú od koreňa kolekcie. |
prefix |
string |
Voliteľný prefix logickej cesty v rámci kolekcie. |
preserveNames |
boolean |
Ponechanie explicitných názvov stránok namiesto generovania názvov z cesty s prefixom. Predvolená hodnota je false, keď je nastavené prefix. |
meta |
object |
Metadáta zlúčené do každej stránky nájdenej v tejto ceste. Pri duplicitných kľúčoch majú metadáta na úrovni stránky prednosť. |
render |
string|object |
Definícia vykreslenia stránok Markdown tejto cesty, ktorá nahrádza hodnotu render načítavača. |
Vykreslenie Markdown pomocou komponentu
Pomocou render sa stránky Markdown nájdené načítavačom vykresľujú prostredníctvom renderera stránok namiesto uloženia vo forme blokov:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
Zostávajú stránkami Markdown: typ obsahu, cesta k obsahu, odpovede .md a frontmatter sa nemenia. Synchronizácia uloží jeden blok blockstudio/page, ktorého vnútorný HTML obsahuje skonvertovaný Markdown, sanitizovaný, ak kolekcia sanitizuje svoj obsah, namiesto rozparsovaných blokov, takže post_content zachová text dokumentu. Renderer dostane toto HTML ako slot a zdroj môže načítať z page.content_path. Relatívne cesty sa vyhodnocujú od koreňa kolekcie; na cesty sa uplatňuje externý filter ciest. Stránka, ktorej frontmatter nastavuje vlastné render alebo render: false, sa vynechá.
Rozloženia
Súbor layout.php obaľuje vykreslenie stránky založenej na súbore na frontende. Nenahrádza synchronizovaný post_content uložený v WordPress a neobaľuje plátno editora. Rozloženie sa spúšťa iba pri požiadavkách na jednotlivé stránky frontendu.
Pri kolekciách umiestnite layout.php vedľa pages.json, aby obaľovalo každú stránku tejto kolekcie na frontende:
<?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() vypíše telo stránky, ktoré by WordPress za bežných okolností vykreslilo cez the_content. Ak rozloženie nevypíše blockstudio_page_content(), obsah stránky zostane zámerne skrytý.
Rozloženia môžu používať pomocné funkcie stránky:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
Vnorené stránky mimo kolekcií môžu tiež zdediť najbližšie nadradené layout.php v strome pages. Pri stránkach kolekcie sa koreňové rozloženie kolekcie uloží do každého synchronizovaného príspevku a sleduje sa ako súčasť odtlačku stránky, takže zmeny rozloženia sa prejavia pri ďalšej synchronizácii.
Rozloženia rendererov
Rozloženie môže byť aj položkou renderera, napríklad layout.tsx pre renderer, ktorý registruje layouts: ["layout.tsx"]. Vyhľadáva sa na rovnakých miestach ako layout.php a voliteľný súbor layout.data.php vedľa neho slúži ako jeho načítavač dát. Pri vykresľovaní renderer dostane kind: "layout" a vykreslený obsah stránky ako slot s rovnakou prioritou the_content ako layout.php. Adresár môže obsahovať buď layout.php, alebo jedno rozloženie renderera, nie oboje; ak obsahuje oboje, pri objavovaní dôjde k chybe. Pri zlyhaní rozloženia sa vyvolá blockstudio/pages/layout_error a obsah stránky zostane bez obalu, rovnako ako pri layout.php.
Režim úprav blokov
Vlastnosť blockEditingMode určuje, ako možno upravovať bloky v editore. Nastavte predvolenú hodnotu na úrovni stránky v page.json a v šablóne ju prepíšte pre jednotlivé prvky:
{
"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>
| Hodnota | Opis |
|---|---|
"default" |
Úplné úpravy. Bloky možno vyberať, presúvať a upravovať |
"contentOnly" |
Iba úpravy textu. Text blokov možno upravovať, no nastavenia a štruktúra sú uzamknuté |
"disabled" |
Bez úprav. Bloky sú úplne neinteraktívne |
Prepísania pre jednotlivé prvky sa nastavujú ako atribúty HTML na ľubovoľnom prvku (<h1>, <p>, <div> atď.) alebo na prvkoch <block>. Nadriadené kontajnerové bloky prepísaných prvkov sa automaticky nastavia na contentOnly, aby ich podriadené prvky zostali prístupné. Toto postupné uplatnenie nastavení smeruje od prepísaného prvku ku koreňu stránky, takže blockEditingMode stačí nastaviť iba na prvkoch, ktoré chcete upravovať.
Uzamknutie šablóny
Vlastnosť templateLock určuje, ako môžu používatelia upravovať stránku v editore:
| Hodnota | Pridať/odstrániť | Presunúť | Upraviť obsah |
|---|---|---|---|
"all" |
Nie | Nie | Nie |
"insert" |
Nie | Áno | Áno |
"contentOnly" |
Nie | Nie | Áno |
false |
Áno | Áno | Áno |
Keď je nastavené templateLock, Blockstudio zakáže odomykanie blokov cez UI editora.
Virtuálne trasy
Niektoré dokumenty nemajú za sebou príspevok: napríklad referencia komponentu vygenerovaná z údajov, katalóg alebo používateľská sekcia. Zaregistrujte ich ako virtuálne trasy namiesto toho, aby ste sami pripojili 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(),
]
);
} );
Cesta je relatívna k domovskej stránke webu. Pomocou prefix trasa obsluhuje aj všetky cesty pod ňou a match dostane zvyšnú časť (prázdny reťazec pre samotnú trasu) a vráti hodnotu, ktorú dostane funkcia spätného volania vykreslenia, alebo null, čím ponechá URL na obsluhu pre WordPress, ktoré potom odpovie na 404 ako obvykle. Funkcia spätného volania vykreslenia vypíše dokument alebo ho vráti ako reťazec; title je reťazec alebo uzáver, ktorý dostane hodnotu zhody.
Pri zhodnej požiadavke Blockstudio zabráni tomu, aby WordPress označil požiadavku ako 404, a aby ju redirect_canonical presmeroval, zruší stav jednej stránky hlásený hlavným dopytom, odošle stav (predvolene status, 200) a vykreslí obsah s prioritou template_redirect Virtual_Routes::PRIORITY. To je hneď po otvorení výstupnej vyrovnávacej pamäte Blockstudio na priorite Assets::BUFFER_PRIORITY, takže hotový dokument získa svoje zdroje blokov, pribalené zdroje UI a skompilované Tailwind ako každá stránka, a to pred redirect_canonical na priorite 10. Obslužný program, ktorý vykresľuje celý dokument samostatne, sa musí spustiť aj po Assets::BUFFER_PRIORITY, inak sa toto spracovanie preskočí. Cesty v urls (predvolene samotná cesta trasy, ak nejde o trasu s predponou) sa pridajú do zostavení statického predgenerovania a Virtual_Routes::urls() ich vráti ako absolútne adresy URL pre mapu stránok.
Virtual_Routes::match( $path ) vyhodnotí cestu tak, ako by to urobila požiadavka.
Správanie synchronizácie
Príspevky stránok sa menia iba prostredníctvom explicitnej operácie synchronizácie:
wp bs pages sync
Príkaz vyhľadá úplný inventár zdrojov, vytvorí alebo aktualizuje zmenené
príspevky, odstráni potvrdené osirelé položky, obnoví smerovanie kolekcií a kompilovanú
konfiguráciu templateFor a oznámi vykonané zmeny. Pridajte --authoritative,
ak chcete nahradiť spravovaný obsah namiesto zachovania obsahu editora priradeného ku kľúčom, a
--full, ak má byť priebeh označený ako úplná rekonciliácia bez ohľadu na uloženú
identitu zdroja:
wp bs pages sync --authoritative --full
Bežné požiadavky na zavedenie frontendu, administrácie, AJAX, REST, cron a všeobecné požiadavky WP-CLI nespúšťajú úplné vyhľadávanie stránok, nevyhľadávajú inventár spravovanej rekonciliácie ani nezapisujú príspevky stránok. Používajú už synchronizované príspevky WordPress spolu s kompaktnou konfiguráciou kolekcií a šablón typov príspevkov uloženou poslednou explicitnou operáciou. Nová inštalácia alebo aktualizácia môže raz prehľadať manifesty kolekcií, aby obnovila metadáta smerovania; toto zavedenie iba na čítanie nikdy nesynchronizuje obsah. Overený obnovovací koncový bod Canvasu, ktorý sa používa výslovne, je explicitná operácia API na úpravu: Canvas ho zavolá raz pri otvorení pracovného priestoru, aby sa nové alebo zmenené zdroje objavili v počiatočnom inventári. Živý režim zavolá rovnaký koncový bod, keď zaznamená zmenu zdroja stránky.
Blockstudio\Pages::init() teraz registruje iba hooky pri požiadavke. Integrácie,
ktoré predtým tejto metóde odovzdávali argument force, musia namiesto toho zavolať
Blockstudio\Pages::reconcile() alebo spustiť wp bs pages sync.
Ak chcete zabrániť prepísaniu stránky po manuálnych úpravách, nastavte "sync": false v page.json.
Prenositeľné umiestnenia zdrojov
Synchronizované súbory témy sa ukladajú ako umiestnenia relatívne k téme, nie ako absolútne cesty k inštalácii. Súbory podradenej a nadradenej témy si zachovávajú samostatné identity, aj keď majú rovnaký relatívny názov súboru. Pomocné funkcie stránok naďalej vracajú vyriešené absolútne hodnoty template_path, content_path, layout_path a directory pre aktuálnu požiadavku.
Vďaka tomu môžu CLI synchronizácia a webové požiadavky používať rôzne korene súborového systému, napríklad na hostingu s obmedzeným prostredím, bez narušenia Markdown odpovedí, rozložení, skenovania editora Tailwind ani sledovania zdrojov predgenerovaných stránok. Existujúce absolútne cesty k témam sa pri čítaní upravia podľa nového umiestnenia, ak sa názov adresára témy nezmenil. Na ich čítanie nie je potrebná synchronizácia, migrácia databázy ani zápis metadát počas požiadavky; pri najbližšej explicitnej synchronizácii sa uložia prenosné umiestnenia.
Ak je adresár témy symbolickým odkazom, napríklad do vývojového checkoutu, ukladajú sa rovnaké umiestnenia theme: bez ohľadu na to, či bol zdroj načítaný cez symbolický odkaz alebo cez jeho cieľ, a rozlíšia sa vzhľadom na nakonfigurovaný adresár témy.
Súbory mimo aktívnych podriadených a nadradených tém zostávajú podporované na svojich nakonfigurovaných absolútnych cestách, s obmedzeniami PHP open_basedir. Nemožno ich automaticky premiestniť: po presunutí externého zdroja aktualizujte jeho nakonfigurovanú cestu a spustite explicitnú synchronizáciu.
Vlastníctvo polí príspevku
postStatus nastavuje počiatočný stav. Následné synchronizácie zachovávajú existujúce stavy konceptu, čakajúceho, súkromného, zverejneného a naplánovaného príspevku, a to aj pri použití --authoritative. Koncept sa znova nezverejní len preto, že jeho súbor uvádza postStatus: "publish". Existujúce správanie pri obnove osirelých príspevkov zostáva nezmenené: explicitná synchronizácia obnoví presunutý do koša spravovaný príspevok, ak je prítomný jeho zdroj. Obnoveniu zabránite uzamknutím stránky alebo vypnutím synchronizácie.
Súbor naďalej určuje názov, slug, typ príspevku, nadradený príspevok a nakonfigurované poradie v ponuke. Úpravy týchto údajov v WordPress nemenia definíciu zdroja. Pri najbližšej explicitnej synchronizácii sa znova použijú hodnoty zo súboru a dotknuté polia sa uvedú v pages.<name>.overwritten spolu s upozornením vo výstupe tabuľky CLI. Stále platia natívne oprávnenia WordPress vrátane prázdneho slugu pri čakajúcich príspevkoch, ak synchronizujúci používateľ nemá oprávnenie zverejňovať.
Pre integráciu, ktorá výslovne spravuje inú politiku stavov, použite blockstudio/pages/update_post_data. Bloky s kľúčmi zachovávajú obsah bloku spravovaný editorom; kľúče nemenia vlastníctvo názvu ani slugu príspevku.
Pri stránkach kolekcie odtlačky zahŕňajú manifest, načítavač, zdroj stránky, súbor rozloženia, metadáta a súvisiace zdrojové cesty. Ďalšia explicitná synchronizácia uplatní zmeny týchto vstupov.
Keď sa odstráni zdroj kolekcie, Blockstudio odstráni vygenerovanú stránku, aby staré stránky kolekcie nezostali po odstránení zdrojového súboru. Predvolene sa osirelé stránky kolekcie presunú do koša. Pomocou blockstudio/pages/orphan_action môžete vrátiť trash, delete alebo keep.
Pri požiadavkách frontendu Blockstudio naplní register stránok z už synchronizovaných publikovaných príspevkov. Koncepty a súkromné stránky sú dostupné v kontextoch administrácie a synchronizácie, no pomocné funkcie frontendu načítajú iba publikované stránky.
Rekoncilácia nasadenia
Blockstudio\Pages::reconcile() je vstupný bod nasadenia PHP. Vyhľadá
úplný požadovaný inventár, porovná odtlačky zdroja a synchronizačného nástroja
a vráti strojovo čitateľnú správu:
$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',
],
],
]);
Správa obsahuje discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, výsledky za jednotlivé stránky, chyby pri vyhľadávaní a deterministické sourceIdentity.
Uzamknuté stránky majú status: "locked" a počítajú sa osobitne od nezmenených stránok. removedPages uvádza pri každej odstránenej stránke jej name, key, postId a skutočné action (trash alebo delete); ponechané ani už odstránené príspevky sa nepočítajú ako novo odstránené. Výstup tabuľky CLI tiež uvádza vytvorené, aktualizované, uzamknuté, odstránené a obsahovo zachované stránky spolu s ID ich príspevkov.
Po spracovaní a zlúčení blokov podľa kľúčov sa pri identickom výslednom príspevku nevolá wp_update_post(), nemení sa post_modified, nevytvára sa revízia ani sa nespúšťajú hooky aktualizácie príspevku. Výsledkom je unchanged. Ak sa obsah zdroja líši od obsahu blokov spravovaného editorom, preserved: true označí toto rozhodnutie a započíta sa do celkového počtu preserved. Nový odtlačok zdroja a spravované metadáta sa aj tak zaznamenajú, takže nasledujúca synchronizácia bez zmien nevykoná žiadnu zmenu. preserved je dodatočný príznak, nie výlučný stav: stránka môže zachovať obsah blokov s kľúčmi a zároveň aktualizovať názov určený súborom alebo pridať ďalší blok.
authoritative: true môže zrušiť zámok synchronizácie stránky a nahradí obsah definíciou zo
súboru namiesto zachovania obsahu editora priradeného ku kľúčom. Pri bežnej explicitnej synchronizácii ho ponechajte false.
plan_valid: false, full: true, broad: true, chýbajúca identita predchádzajúceho zdroja alebo zmenený odtlačok synchronizačného nástroja označia priebeh ako úplnú rekonciliáciu (fullReconciliation v správe). Každý priebeh v každom prípade porovná celý inventár. Záznamy o premenovaní Git slúžia iba ako pomôcky pri určovaní identity. Nikdy nenahrádzajú porovnanie celého inventára.
Pri rovnakých odtlačkoch a nezmenených cestách prostredia sa nevykonajú zápisy príspevkov ani metadát príspevkov a nespustia sa hooky aktualizácie. Keď sa nezmenený zdroj presunie do nového adresára vydania, rekonciliácia obnoví iba jeho uložené cesty k šablóne, obsahu, rozloženiu a adresáru; neaktualizuje post_content ani čas poslednej úpravy príspevku. Chýbajúce spravované stránky sa odstránia až po dokončení celej rekonciliácie bez chýb pri vyhľadávaní alebo zápise stránok.
Priama rekonciliácia API neoznačuje nasadenie za úspešné. Po aktivácii a overení zodpovedajúceho statického artefaktu a trás explicitne uložte vrátenú identitu:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync uloží vrátenú identitu po úspešnom priebehu.
Bežné zavedenie WP-CLI registruje iba uložené typy príspevkov kolekcie
a pravidlá prepisovania. Nevyhľadáva ani nesynchronizuje stránky.
Priradenie ID príspevku
Predvolene WordPress automaticky prideľuje ID príspevkov. Ak sa stránka odstráni a znova vytvorí, ID sa zmení, čím sa porušia externé odkazy, napríklad položky ponúk alebo natvrdo zadané odkazy.
Použite postId na priradenie konkrétneho ID stránke:
{
"name": "about",
"title": "About Us",
"postId": 42
}
Pri vytváraní stránky Blockstudio odovzdá ID do WordPress cez import_id. Ak je ID voľné, WordPress ho použije presne. Ak ID už patrí nesúvisiacemu príspevku, WordPress mu potichu pridelí nové ID.
Pri vyhľadávaní existujúcich stránok Blockstudio najprv skontroluje priradené ID a až potom metadáta alebo slug. Ak sa teda stránka odstráni a znova synchronizuje, získa späť rovnaké ID.
Zlučovanie blokov podľa kľúča
Predvolene Blockstudio pri zmene súboru šablóny nahradí celý obsah príspevku novou šablónou. To znamená, že sa stratia všetky úpravy vykonané v editore WordPress.
Pridajte blokom atribút key, aby sa používateľské úpravy zachovali aj pri synchronizácii šablón. Ak šablóna obsahuje bloky s kľúčmi, Blockstudio zlúči zmeny šablóny s existujúcim obsahom príspevku namiesto toho, aby ho nahradil.
Pridávanie kľúčov
Použite atribút key na ľubovoľnom prvku HTML alebo <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"
/>
Kľúče musia byť jedinečné v rámci celej šablóny. Kľúč chráni celý blok a všetok jeho obsah. Jednotlivým podriadeným prvkom v bloku s kľúčom nemusíte priraďovať kľúče. Bloky s kľúčmi možno medzi aktualizáciami šablóny presúvať na ľubovoľnú pozíciu alebo úroveň vnorenia a ich používateľský obsah sa zachová.
Kľúče fungujú rovnako aj pri vlastných blokoch Blockstudio. key predstavuje štrukturálne metadáta synchronizácie stránky; hodnoty vlastných polí zostávajú bežnými atribútmi Blockstudio.
Keď editor zmení tieto polia, neskoršia synchronizácia šablóny zachová hodnoty editora a zároveň uplatní nezávislé zmeny šablóny. Stránky vytvorené staršími verziami, ktoré majú kľúč v údajoch vlastného poľa, sa automaticky upravia pri ďalšej synchronizácii.
Ako funguje zlučovanie
Keď sa zmení súbor šablóny a stránka sa znova synchronizuje:
| Blok | Správanie |
|---|---|
| Blok s kľúčom | Používateľský obsah a hodnoty poľa Blockstudio sa zachovajú. Uplatnia sa atribúty a štruktúra spravované šablónou. |
| Blok bez kľúča | Úplne sa nahradí verziou zo šablóny (rovnako ako bez kľúčov) |
Príklady
Používateľské úpravy sa v blokoch s kľúčom zachovajú:
- Šablóna definuje
<p key="intro">Default intro.</p> - Používateľ upraví odsek v editore na „Vlastný úvodný text.“
- Vývojár aktualizuje šablónu, pridá nový blok a zmení rozloženie
- Pri synchronizácii si odsek zachová text „Vlastný úvodný text.“, zatiaľ čo sa použije nové rozloženie
Atribúty zo šablóny sa naďalej uplatňujú:
- Šablóna obsahuje krycí blok s
key="hero"a atribútomurl - Vývojár zmení atribút
urlkrycieho bloku na nový obrázok pozadia - Pri synchronizácii sa použije nový obrázok pozadia, no používateľské úpravy obsahu vo vnútri krycieho bloku sa zachovajú
Hraničné prípady
| Scenár | Správanie |
|---|---|
| Do šablóny sa pridá nový blok s kľúčom | Zobrazí sa s predvoleným obsahom šablóny |
| Blok s kľúčom sa odstráni zo šablóny | Odstráni sa z príspevku |
| Zmení sa typ bloku (rovnaký kľúč) | Úplne sa použije šablóna, obsah sa nezlúči |
| Duplicitné kľúče | Druhý výskyt sa považuje za blok bez kľúča |
| Šablóna neobsahuje kľúče | Úplné nahradenie (rovnako ako bez kľúčov) |
| Vynútená synchronizácia | Úplné nahradenie, kľúče sa ignorujú |
| Uzamknutý príspevok | Synchronizácia sa vôbec nevykoná |
Kombinovanie s ovládacími prvkami úprav
Kľúče, templateLock a blockEditingMode vám umožňujú presne určiť, čo klienti môžu a nemôžu robiť. Tu je niekoľko bežných pracovných postupov.
Úplne uzamknutá stránka
Vývojár má všetko pod kontrolou. Stránka má statické rozloženie, do ktorého klienti nemôžu vôbec zasahovať. Hodí sa na právne stránky, podmienky používania alebo akúkoľvek stránku, ktorú možno meniť iba prostredníctvom kódu.
{
"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>
Nie sú potrebné žiadne kľúče. Šablóna je jediným zdrojom pravdy. Každá synchronizácia stránku úplne prepíše.
Uzamknuté rozloženie s upraviteľným obsahom
Najbežnejší vzor. Uzamknite štruktúru stránky, aby klienti nemohli pridávať, odstraňovať ani presúvať bloky, ale umožnite im upravovať text na konkrétnych miestach. Kľúče zabezpečia, že sa ich úpravy zachovajú aj po aktualizáciách šablóny.
{
"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>
Klient môže upravovať hlavný nadpis, popis a úvod k funkciám. Nič iné. Text tlačidla, URL a obrázok na pozadí titulnej časti ovláda vývojár. Keď vývojár aktualizuje šablónu (e.g, pridá druhé tlačidlo), sekcie s kľúčmi zachovajú text klienta.
Rozvíjajúca sa šablóna so zachovaným obsahom
Pre stránky, ktoré sa časom rozrastajú. Vývojár pridáva do šablóny nové sekcie a každá synchronizácia pridá nový obsah bez zásahu do toho, čo si klient už prispôsobil.
<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>
Nová sekcia s referenciami a tlačidlo sa zobrazia po synchronizácii. Úpravy klienta v nadpise, úvode a službách zostanú nedotknuté.
Jednorazová kostra
Vytvorte stránku so základnou štruktúrou a potom ju úplne odovzdajte. Nastavte sync na false, aby bežná synchronizácia stránku nikdy nevytvorila ani neaktualizovala, a vytvorte ju raz pomocou Blockstudio\Pages::force_sync('blog'). Potom bude stránka úplne patriť klientovi.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
wp bs pages sync túto stránku preskočí, takže force_sync() ju vytvorí iba raz. Potom môže klient ľubovoľne pridávať, odstraňovať a presúvať bloky. Zmeny šablóny sa ignorujú.
Väzby blokov
Alternatívou k zlučovaniu podľa kľúčov je použitie WordPress core Väzieb blokov API na prepojenie blokov s metadátami príspevku. Nejde o funkciu Blockstudio, ale o natívnu funkciu WordPress API. Blockstudio jednoducho odovzdá atribút metadata do vygenerovaného označenia bloku. Obsah sa ukladá do metadát príspevku namiesto označenia bloku, takže synchronizácia šablóny môže označenie ľubovoľne prepísať, pretože editor číta z metadát, nie z innerHTML.
Odovzdajte atribút metadata ľubovoľnému prvku HTML alebo <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"}}}}'
/>
Kľúče metadát musia byť zaregistrované so zapnutou možnosťou show_in_rest:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Kľúče a väzby
| Aspekt | Kľúče | Väzby |
|---|---|---|
| Kde sa ukladá obsah | Označenie bloku (post_content) |
Metadáta príspevku (wp_postmeta) |
| Zachová sa pri synchronizácii šablóny | Áno (zlúčené podľa kľúča) | Áno (údaje sú v metadátach) |
Možnosť vyhľadávania cez WP_Query |
Nie | Áno (meta_query) |
| Dostupné v REST API | Nie | Áno |
| Vyžaduje registráciu | Nie | Áno (register_post_meta) |
| Používateľ môže presúvať bloky | Nie (šablóna znovu vynúti štruktúru) | Nie (šablóna znovu vynúti štruktúru) |
Oba prístupy možno použiť v tej istej šablóne. Kľúče použite pre sekcie, v ktorých záleží na štruktúre blokov (e.g, napríklad skupina s viacerými potomkami). Väzby použite pre jednotlivé polia, ktorých údaje chcete sprístupniť aj mimo editora blokov.
Šablóny typov príspevkov
Pomocou templateFor nastavte stránku ako predvolenú šablónu pre typ príspevku:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
Všetky nové príspevky tohto typu sa začnú s definovanou štruktúrou blokov.
Vlastné cesty
Štandardne Blockstudio prehľadáva get_template_directory() . '/pages'. Ďalšie cesty pridajte pomocou filtra:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
Integrácie za behu, ktoré skladajú súbory z viacerých koreňových priečinkov, môžu nahradiť prehľadávanie súborového systému logickým zdrojom vyhľadávania. Manifesty stránok, rozloženia, načítavače a zdrojové šablóny sa potom vyhľadávajú podľa logickej cesty, aj keď sa vybrané súbory nachádzajú v rôznych koreňových priečinkoch.
Filtre a akcie
Vyhľadávanie stránok, synchronizácia a smerovanie kolekcií sprístupňujú tieto rozšírenia:
| Hook | Typ | Opis |
|---|---|---|
blockstudio/pages/paths |
Filter | Pridáva adresáre, v ktorých Blockstudio hľadá zdroje stránok. |
blockstudio/pages/collection_post_type_args |
Filter | Upravuje argumenty register_post_type() pre CPT kolekcie. |
blockstudio/pages/template_candidates |
Filter | Upravuje názvy súborov šablón, ktoré sa zvažujú pre zdroj stránky. |
blockstudio/pages/serve_markdown |
Filter | Zapína alebo vypína surové odpovede Markdown. |
blockstudio/pages/orphan_action |
Filter | Vracajú sa hodnoty trash, delete alebo keep na čistenie osirelých položiek. |
blockstudio/pages/docs_allowed_html |
Filter | Upravuje povolené HTML pre obsah dokumentácie Markdown. |
blockstudio/pages/allow_external_loader_path |
Filter | Povoľuje paths zavádzača mimo koreňa kolekcie. |
blockstudio/pages/manifest_scan_interval |
Filter | Nastavuje maximálny vek zastaranej vyrovnávacej pamäte manifestu spred 7.6.2, ktorá môže pri aktualizácii slúžiť ako zdroj pre trvalú konfiguráciu prostredia. |
blockstudio/pages/create_post_data |
Filter | Upravuje údaje príspevku pred vytvorením synchronizovanej stránky. |
blockstudio/pages/update_post_data |
Filter | Upravuje údaje príspevku pred aktualizáciou synchronizovanej stránky. |
blockstudio/pages/sync_engine_inputs |
Filter | Pridáva verziu parsera, mapovania alebo migrácie, ktorá má zámerne jednorazovo rozšíriť zosúladenie. |
blockstudio/pages/post_created |
Akcia | Spúšťa sa po vytvorení príspevku synchronizovanej stránky. |
blockstudio/pages/post_updated |
Akcia | Spúšťa sa po aktualizácii príspevku synchronizovanej stránky. |
blockstudio/pages/synced |
Akcia | Spúšťa sa po dokončení synchronizácie registra stránok. |
blockstudio/pages/reconciled |
Akcia | Spúšťa sa po explicitnom zosúladení a odovzdá mu strojovo čitateľnú správu. |
blockstudio/pages/renderers |
Akcia | Registruje vykresľovače stránok pomocou Blockstudio\Page_Renderers::register(). Spúšťa sa raz pri každej požiadavke. |
blockstudio/pages/rendered |
Akcia | Spúšťa sa po vykreslení stránky komponentu a poskytuje stránku, jej HTML a závislosti. |
blockstudio/pages/layout_error |
Akcia | Spúšťa sa, keď nemožno vykresliť rozloženie, a poskytuje chybu, cestu k rozloženiu a stránku. |
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]);
Pozrite si Zosúladenie nasadenia, kde nájdete význam argumentov, polia správy a overenú hranicu identity zdroja.
Pre šablóny a rozloženia sú dostupné globálne pomocné funkcie:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
Polia stránok vrátené funkciami Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() a globálnymi pomocnými funkciami obsahujú identitu synchronizovaného príspevku, cesty k zdroju a šablóne, metadáta kolekcie a cesty, typ obsahu, pravidlá synchronizácie, typ a stav príspevku, pravidlá úprav, vlastné metadáta a kľúč permalink. Metadáta kolekcie sa načítavajú z posledného úspešného výslovného zosúladenia. Bežné požiadavky obnovujú tieto údaje za behu z uloženej konfigurácie a metadát synchronizovaných príspevkov bez čítania stromov zdrojových stránok. Trieda Pages nesprístupňuje samostatnú metódu permalinku.
Uzamykanie šablón, režimy úprav blokov, zlučovanie podľa kľúčov a riadenie toho, čo môžu klienti upravovať.