Sidor
Sidor är filbaserade mallar som synkroniseras till WordPress-databasen som inlägg. Synkroniseringen är uttrycklig: kör wp bs pages sync eller anropa Pages API när du vill tillämpa källändringar. Inläsning av frontend eller WordPress-administrationen utför aldrig en fullständig sidsökning eller ändrar sidinlägg.
Sidor kan definieras som en enda mapp page.json, som fristående Markdown eller som en samling med ett pages.json-manifest. Samlingar passar för dokumentation, kunskapsbaser, bibliotek med landningssidor eller andra uppsättningar av nästlade sidor som ska genereras från filer.
page.json
För en sida definierad med JSON lägger du till en konfigurationsfil page.json:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
Egenskaper
| Egenskap | Typ | Standard | Beskrivning |
|---|---|---|---|
name |
string |
obligatorisk | Unik identifierare för sidan |
title |
string |
Hämtas automatiskt från namnet | Sidans titel |
slug |
string |
Samma som namnet | URL-slug för sidan |
path |
string |
"." |
Logisk sökväg i en samling |
order |
integer |
0 |
Menyordning för det synkroniserade inlägget |
postType |
string |
"page" |
WordPress inläggstyp |
postStatus |
string |
"draft" |
Status för nya inlägg (publish, draft, pending, private) |
postId |
integer |
– | Fäst sidan vid ett specifikt WordPress-inläggs-ID |
blockEditingMode |
string |
– | Redigeringsläge för block: "default", "contentOnly" eller "disabled" |
templateLock |
string|false |
"all" |
Låsläge: "all", "insert", "contentOnly" eller false |
templateFor |
string|null |
null |
Ange som standardmall för en inläggstyp |
sync |
boolean |
true |
Om vanlig uttrycklig avstämning får skapa eller uppdatera inlägget |
render |
string|object|false |
– | Återge sidan med en registrerad sidrenderare (se Komponentsidor) |
Bland page.json, frontmatter och laddarposter finns bland de igenkända nycklarna blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock och title. Alla nycklar som inte listas ovan lagras i sidans meta-array.
Innehållskällor
En siddefinition avgör vilket WordPress-inlägg som ska finnas. Innehållskällan avgör vilken blockmarkup som skrivs till inlägget.
När en sidmapp innehåller en page.json letar Blockstudio efter en intilliggande källfil i följande ordning:
| Fil | Användning |
|---|---|
index.php |
Blockmarkup som liknar HTML, läses som den är (PHP-kod körs inte) |
index.blade.php |
Mallinnehåll för Blade |
index.twig |
Mallinnehåll för Twig |
index.md |
Innehåll för Markdown |
page.json kan också tillhandahålla infogad markdown eller html i stället för en intilliggande fil:
{
"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>"
}
Samlingar har ytterligare två källägen:
- Markdown-filer som hittas direkt i samlingens träd.
- Loader-poster som returneras från
loader.php.
Loader-poster kan använda markdown, html eller content tillsammans med contentType. De kan också peka på en lokal file eller template. Fil- och mallkällor härleder sin typ från filändelsen om inte contentType anges uttryckligen.
Värden som stöds för contentType är php, blade, twig, markdown och html. Markdown konverteras först till HTML och tolkas sedan till inbyggda WordPress-block. Källorna PHP, Blade, Twig och HTML går via den vanliga sidparsern Blockstudio.
Klasser på kärnblock
En class på ett element av typen HTML som mappas till ett kärnblock blir dess className.
En uttrycklig kärnblockstagg kan använda className direkt. Båda formerna bevarar
klasserna på blockets sparade omslag, tillsammans med de klasser som WordPress
genererar:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
Om båda egenskaperna finns har className företräde. Den här konverteringen
gäller bara kärnblock: en anpassad blockmappning behåller sitt class-fält
oförändrat. Knappens stilklasser, till exempel is-style-outline, hör till
knappens omslag, inte dess länk.
Kör wp bs pages sync för att tillämpa parserkorrigeringar på tidigare synkroniserade
sidor. Parseruppgraderingar identifieras vid nästa uttryckliga synkronisering utan
att någon källfil behöver redigeras. Låsta sidor och sidor med sync: false behåller sina
vanliga skydd; frontend-förfrågningar utför aldrig den här synkroniseringen.
Serialiserade WordPress-block
Sid- och mönsterkällor kan också innehålla serialiserade block som kopierats från kodredigeraren WordPress:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
När källan innehåller en <!-- wp:... -->-blockavgränsare använder Blockstudio WordPress inbyggda blocktolkare för hela källan. Attribut, nästlade block, dynamiska block som Query Loop och Blockstudio-block behåller sin serialiserade struktur. HTML utanför blockkommentarerna förblir inbyggd friforms-HTML; den mappas inte till ytterligare block. Blanda inte Blockstudios HTML-blocktaggar med det här formatet och förvänta dig att de konverteras. Vanliga HTML-kommentarer väljer inte serialiserat blockläge.
Markdown-sidor
Använd Markdown när text ska ligga i filer men ändå bli redigerbart WordPress-blockinnehåll efter synkronisering. Källan Markdown konverteras till blockmarkup under synkroniseringen. Det synkroniserade inlägget lagrar block, inte den råa Markdown-texten.
Markdown kan användas på tre sätt:
| Källa | Frontmatter krävs? | Anmärkningar |
|---|---|---|
Fristående pages/example/index.md |
Ja | Frontmatter anger sidans identitet. |
page.json plus index.md |
Nej | page.json definierar sidan och Markdown tillhandahåller innehållet. |
| Markdown i en samling | Nej | Samlingen härleder name och path från filens plats. |
En fristående index.md utan frontmatter hoppas över eftersom Blockstudio saknar sididentitet att synkronisera. Samlingens Markdown behöver inte frontmatter eftersom samlingens manifest och filsökvägen anger identiteten.
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
Du kan också kombinera page.json med index.md. I så fall definierar page.json sidan och index.md tillhandahåller innehållet. Frontmatter i index.md åsidosätter motsvarande värden i 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.
För samlings-Markdown blir filsökvägen den logiska sökvägen för sidan, om inte frontmatter åsidosätter den:
| Fil | Standardsökväg |
|---|---|
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 |
Okända frontmatter-nycklar bevaras i sidans array meta. Då kan du lägga till data som section eller description och läsa den från PHP API.
Markdown tolkas som GitHub Flavored Markdown. Rå HTML tillåts, osäkra länkar tas bort och rubriker utan uttryckligt ID får ett stabilt ID. Nästlad frontmatter i YAML kräver den medföljande YAML-parsern.
Rå Markdown
Källor från Markdown-filer kan exponera sin ursprungliga källtext Markdown för externa verktyg och dokumentationskonsumenter. Infogad Markdown har ingen källfil. Därför synkroniseras den till block men ger inget rått .md-svar.
Begär sidan med suffixet .md, till exempel https://example.com/docs/reference.md. Du kan också skicka ett Accept: text/markdown-huvud till sidans vanliga URL:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
Frontmatter tas bort från svaret. Vid lyckade råa Markdown-svar skickas Content-Type: text/markdown, X-Robots-Tag: noindex och ett kanoniskt Link-huvud tillbaka till HTML-sidan. Om rutten för .md saknas returneras en riktig 404.
Innehållsförhandling fungerar med statisk förgenerering: en begäran vars Accept-huvud innehåller text/markdown besvaras aldrig från den förgenererade lagringen eller det tidiga serverings-tillägget, utan når WordPress och hanteraren Markdown. Förgenererade HTML-svar, HTML för en sida som också förhandlar om Markdown och Markdown som besvaras via Accept skickar Vary: Accept, så att cacheminnen som respekterar Vary håller dem åtskilda. En CDN som nycklar sin cache enbart efter URL behöver en egen regel för att kringgå cachen för sådana begäranden. Pages::negotiates_markdown( $post_id ) rapporterar om en sida besvarar begäranden med Markdown.
Samlingens Markdown behåller samma URL-struktur för råa Markdown:
| Sidans URL | Rå Markdown-URL |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
Inaktivera råa Markdown-svar med filtret blockstudio/pages/serve_markdown:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
En begäran med .md URL som inte matchar en sida baserad på Markdown returnerar 404 endast om sökvägen ligger inom en sidsamling. Utanför alla samlingar lämnar Blockstudio begäran orörd så att WordPress och andra tillägg kan hantera den.
Komponentsidor
En komponentsida återges av en sidrenderare i stället för att lagras som
block. Blockstudio levereras inte med en renderare. Ett tema eller tillägg registrerar en
för de entry-filer det hanterar, till exempel en React-renderare för page.tsx, och
Blockstudio anropar den med sidan, inlägget WordPress och det återgivna platshållarinnehållet.
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 är uttrycklig. En katalog med en index.php och en page.tsx men utan
render förblir en vanlig sida, så att en tillagd renderare aldrig återger en
befintlig sida två gånger. Formerna är:
| Värde | Betydelse |
|---|---|
"page.tsx" |
Endast entry, utan dataladdare |
{ "entry": "page.tsx", "data": "data.php" } |
Entry och dataladdare |
{ "entry": "page.tsx", "renderer": "react" } |
Entry med ett uttryckligt renderar-ID |
false |
Ingen renderare, även när en standard för samlingen anger en |
Sökvägar löses i förhållande till sidkatalogen eller till samlingens rot för
laddarposter. De måste ligga kvar i upptäcktskällan, såvida inte
blockstudio/pages/allow_external_loader_path tillåter dem. Utan
renderer används den renderare som gör anspråk på postens filändelse. En
render som anger en saknad entry- eller datafil, en okänd renderare eller en
filändelse som ingen renderare gör anspråk på är ett upptäcktsfel, vilket avbryter
avstämningen innan något rensas bort.
Vad synkroniseringen lagrar
Synkroniseringen lagrar ett blockstudio/page-block. När sidkatalogen också har en
index.*-källa tolkas den som vilken sidkälla som helst och blir blockets inre block, dess platshållare:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
Behåll innehåll som ägs av WordPress, till exempel kortkoder, i platshållaren. En källa som bara består av en kortkod, till exempel [download_checkout],
lagras som ett core/shortcode-block, så att dess utdata inte får något stycke
runt sig. Den ligger kvar i
post_content, så att kontrollerna has_shortcode() kan se den, nycklade platshållarblock slås samman
med redigeringsändringar på samma sätt som nästlade nycklade block gör, och do_shortcode expanderar
kortkoderna en gång med sin vanliga prioritet the_content, efter att renderaren har ramat in dem.
Renderingsdefinitionen lagras tillsammans med inlägget som portabla theme:-sökvägar. Sidfingeravtrycket omfattar definitionen, inte byten i entry- eller dataladdaren: redigering av page.tsx eller data.php lämnar inlägget oförändrat och når besökarna via återgivning och den statiska förgenereringsgrafen, som registrerar entryn, dataladdaren och varje fil som renderaren rapporterar.
Registrera en renderare
Registrera renderare på åtgärden blockstudio/pages/renderers. Den körs en gång
per förfrågan, före den första upptäckten eller återgivningen, så att wp bs pages sync– och
frontendförfrågningar ser samma 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',
)
);
}
);
Renderar-ID:n skrivs med små bokstäver. En filändelse eller layout får bara tillhöra en
renderare, och layout.php förblir Blockstudios egen layout. Den anropbara funktionen
tar emot en förfrågan:
| Nyckel | Värde |
|---|---|
kind |
page eller layout för en renderarlayout |
renderer |
Renderar-ID |
entry |
Absolut entry-sökväg |
data |
Absolut sökväg till dataladdaren eller null |
page |
Kanoniska siddata, inklusive meta |
post_id |
Inläggs-ID för WordPress |
slot |
Återgivet platshållarinnehåll eller sidinnehållet för en layout |
context |
frontend, rest, feed eller cli |
Den returnerar HTML, filerna som återgivningen läste och valfria tillgångar:
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 kommer från begärandetypen och aldrig från besökaren, så en renderare kan inte bryta bytepariteten mellan inloggade och anonyma genom att läsa den. Om en renderare misslyckas kastas ett fel: sidan renderas inte med en tom body. I en REST-redigerarförhandsvisning visas felet i blocket som en avisering i stället. Efter en lyckad rendering får åtgärden blockstudio/pages/rendered sidan, HTML och dess beroenden.
assets listar skript- och stilfiler som sidan behöver. De bearbetas som blockresurser (enligt konventionen *.inline.*, som ES-moduler, minifiering och ?ver), och sidan skriver ut dem en gång via samma buffer som skriver ut blockresurser, så att en förhandsrenderad sida innehåller dem. En resurs kan ange version för att ersätta värdet för ?ver. Kod utanför en renderare kan använda samma kanal via Blockstudio\Assets::register_owner(), som returnerar markörkommentaren som ska skrivas ut.
Redigerare
I redigeraren visar blockstudio/page en serverrenderad förhandsvisning av sidan, där slotten utgörs av inre block som följer sidans templateLock. Blocket kan inte infogas, dupliceras eller kapslas in i ett annat block.
Sidsamlingar
En samling är en mapp med ett pages.json-manifest. Den grupperar många sidkällor under en samlingsslug, tillämpar standardvärden, stöder nästlade sökvägar och kan automatiskt registrera en särskild inläggstyp.
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"
}
}
| Egenskap | Typ | Beskrivning |
|---|---|---|
collection / slug / name |
string |
Samlingsslug. collection är den tydligaste formen och blir den offentliga basen för URL. |
title |
string |
Samlingens läsbara titel. |
postType |
string |
Inläggstyp för genererade sidor. Standardvärdet är page. Om den inte finns registrerar Blockstudio den. |
postTypeArgs |
object |
Argument som skickas till register_post_type() när Blockstudio registrerar samlingens inläggstyp. |
defaults |
object |
Standardsidegenskaper som tillämpas på varje sida i samlingen. Ett standardvärde för render tillämpas på en sida endast när dess post finns i sidkatalogen. |
scope |
string |
collection (standard) eller site. Se Webbplatssamlingar. |
meta |
object |
Anpassade samlingsmetadata. Okända manifestnycklar lagras också i meta. |
Sidsökvägar i en samling är logiska sökvägar. En sida med path: "guide/install" synkroniseras som underordnad till guide, och guide synkroniseras som underordnad till samlingens rot när de överordnade sidorna finns.
Om en hierarkisk samling har en nästlad sida men en mellanliggande överordnad källa saknas skapar Blockstudio en tom containersida för sökvägen, vilket håller WordPress-hierarkin komplett. Icke-hierarkiska inläggstyper (de utan stöd för överordnade page-attributes) skapar inga tomma containrar. De dirigeras efter den lagrade samlingssökvägen, så nästlade sökvägar som guide/install och setup/install kan samexistera trots att båda slutar med install.
Samlingens inläggstyper och URL:er
Ange postType i samlingens manifest för att synkronisera varje sida i samlingen till den inläggstypen. Du behöver inte upprepa samma värde i defaults. Enskilda sidor kan fortfarande åsidosätta postType i frontmatter eller page.json.
Om inläggstypen inte finns registrerar Blockstudio den med show_in_rest: true, en redigeraruppsättning som liknar sidor och samlingssluggen som offentlig URL-bas. postTypeArgs kan åsidosätta registreringsargumenten. Omskrivningsregler för samlingens inläggstyp uppdateras automatiskt när registrerade samlingsinläggstyper eller omskrivningsargument ändras, så du behöver inte spara om WordPress-permalänkar.
URL:er för samlingar använder samlingssluggen följd av varje sidas logiska path:
| Källsökväg | Offentlig URL |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
Den här URL modellen fungerar för både hierarkiska och icke-hierarkiska samlingsinläggstyper. Blockstudio omdirigerar också dubblerade URL:er som /docs/docs/ eller /docs/docs/getting-started/ till den kanoniska URL.
Samlingssidor visar rå Markdown på samma URL:er (se Rå Markdown).
Om du ändrar en samling från postType: "page" till en anpassad inläggstyp migrerar Blockstudio redan synkroniserade samlingsinlägg på plats när deras lagrade sididentitet matchar. Det bevarar inläggs-ID:n, metadata och befintligt innehåll samtidigt som dubblerade inlägg med den gamla typen undviks. Föråldrade samlingsinlägg rensas bort i alla inläggsstatusar enligt filtret blockstudio/pages/orphan_action.
Webbplatssamlingar
Ett manifest med "scope": "site" grupperar varje sida under sig utan att göra dem till samlingssidor. Använd det i roten av en webbplats sidträd för att tillämpa gemensamma standardvärden och lista webbplatsens sidor med 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" }
}
}
Sidor i en webbplatssamling behåller exakt samma identitet som de hade utan manifestet, så att lägga till ett manifest i ett befintligt träd uppdaterar inga inläggsrader och skapar eller tar bort ingenting:
- Nycklarna förblir globala:
Pages::get_page( 'home' )och lagrade sidnycklar fortsätter att matcha. - URL:er förblir WordPress sid-URL:er. Inga omskrivningsregler för samlingar, permalinkfilter eller omdirigeringar med dubbla URL tillämpas, och inga tomma behållarsidor genereras.
- Logiska sökvägar, sluggar, föräldrar och källidentiteter är desamma som för fristående sidor, och layouter löses utifrån närmaste överordnade.
- Kapslade
pages.json-manifest behåller sina egna samlingar, och deras underträd utelämnas från webbplatssamlingen. - Standardvärden tillämpas per sida: ett standardvärde för
rendertillämpas endast på sidor vars katalog innehåller motsvarande post, så sidor med kortkoder och Markdown behåller sina källor.
Samlingsladdare
Samlingar kan innehålla en betrodd lokal loader.php. Använd den när samlingssidor kommer från en annan lokal källa, till exempel en extern dokumentationsmapp, ett paket eller ett genererat manifest.
Laddaren körs vid uttrycklig sidupptäckt och synkronisering. Den bör
vara deterministisk och lokal. Undvik att hämta fjärrinnehåll från loader.php,
e eftersom det skulle göra synkroniseringen vid driftsättning beroende av den tjänsten.
<?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',
),
),
);
En laddare kan returnera en array med nycklarna pages, meta och paths:
| Nyckel | Beskrivning |
|---|---|
pages |
En lista med sidarrayer. Varje sida stöder samma igenkända nycklar som page.json– och Markdown-frontmatter. |
meta |
Metadata som slås samman med arrayen meta för varje sida som genereras av laddaren. |
paths |
Ytterligare lokala kataloger att hitta som en del av samlingen. Poster kan vara strängar eller sökvägsobjekt. |
render |
En renderingsdefinition för varje Markdown-sida som hittas från paths. |
Som en kortare variant kan laddaren returnera en enkel lista med sidarrayer.
Laddarsidornas poster kan ange innehåll på följande sätt:
| Form | Beskrivning |
|---|---|
markdown |
Inline-innehåll i Markdown. |
html |
Inline-innehåll i HTML. |
content + contentType |
Generiskt inline-innehåll. contentType måste lösas till markdown eller html. |
file |
Lokal filkälla. Typen härleds från filändelsen om inte contentType har angetts. |
template |
Alias för file. |
Fillänkar från laddaren kan peka på källor av typen PHP, Blade, Twig, Markdown eller HTML. Relativa sökvägar löses från samlingens rot. Absoluta sökvägar och sökvägar utanför samlingens rot tillåts bara om filtret blockstudio/pages/allow_external_loader_path godkänner dem.
Laddarsidor får som standard generated: true. När en genererad laddarsida försvinner från laddarens utdata behandlar Blockstudio det synkroniserade inlägget som en föräldralös sida vid nästa synkronisering, och rensar bort det enligt filtret blockstudio/pages/orphan_action.
Kataloger som anges i paths upptäcks på samma sätt som vanliga samlingsmappar. De kan innehålla Markdown-filer eller page.json-mappar. Om sökvägarna ligger utanför samlingens rot gäller samma filter för externa sökvägar.
Använd en strängpost när den externa katalogen ska behålla sina egna logiska sökvägar. Använd en objektpost när katalogen ska monteras under ett sökvägsprefix i samlingen:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
Med den konfigurationen blir cli-docs/index.md path: "cli" och cli-docs/getting-started.md blir path: "cli/getting-started" i samlingen. Prefix gör också genererade sidnamn unika, så att flera monterade kataloger kan innehålla var sin index.md eller getting-started.md. Ange preserveNames som true på sökvägsobjektet om uttryckliga värden för name från frontmatter i page.json eller Markdown ska behållas i stället.
Egenskaper för sökvägsobjekt:
| Egenskap | Typ | Beskrivning |
|---|---|---|
path |
string |
Lokal katalog att söka igenom. Relativa sökvägar utgår från samlingens rot. |
prefix |
string |
Valfritt logiskt sökvägsprefix inom samlingen. |
preserveNames |
boolean |
Behåll uttryckliga sidnamn i stället för att generera namn från den prefixförsedda sökvägen. Standardvärdet är false när prefix har angetts. |
meta |
object |
Metadata som slås samman med varje sida som hittas från den här sökvägen. Metadata på sidnivå har företräde vid duplicerade nycklar. |
render |
string|object |
En renderingsdefinition för Markdown-sidorna i den här sökvägen, som åsidosätter laddarens render. |
Rendera Markdown via en komponent
Med render renderas sidorna Markdown som en laddare hittar via en sidas renderare i stället för att lagras som block:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
De förblir Markdown-sidor: innehållstypen, innehållssökvägen, svaren .md och frontmatter förblir oförändrade. Synkroniseringen lagrar ett blockstudio/page-block vars inre HTML är den konverterade Markdown, rensad när samlingen rensar sitt innehåll, i stället för tolkade block, så att post_content bevarar dokumenttexten. Renderaren får detta HTML som slot och kan läsa källan från page.content_path. Relativa sökvägar utgår från samlingens rot; det externa sökvägsfiltret gäller på samma sätt som för sökvägarna. En sida vars frontmatter anger ett eget render eller render: false utelämnas.
Layouter
En layout.php-fil omsluter frontend-renderingen av en filbaserad sida. Den ersätter inte den synkroniserade post_content som lagras i WordPress, och den omsluter inte heller redigeringsytan. Layouten körs endast för enskilda frontend-förfrågningar.
För samlingar placerar du layout.php bredvid pages.json för att omsluta varje frontend-sida i samlingen:
<?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() skriver ut sidans innehåll som WordPress vanligtvis skulle rendera via the_content. Om en layout inte matar ut blockstudio_page_content() döljs sidinnehållet med avsikt.
Layouter kan använda sidans hjälpfunktioner:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
Även nästlade sidor som inte tillhör en samling kan ärva närmaste överordnade layout.php i trädet pages. För samlingssidor lagras samlingens rotlayout på varje synkroniserat inlägg och bevakas som en del av sidans fingeravtryck, så layoutändringar hämtas vid nästa synkronisering.
Renderarlayouter
En layout kan också vara en renderarpost, till exempel layout.tsx för en renderare som registrerar layouts: ["layout.tsx"]. Den hittas på samma platser som layout.php, och en valfri layout.data.php bredvid den fungerar som dess dataladdare. Vid rendering får renderaren kind: "layout" och det renderade sidinnehållet som slot, med samma prioritet för the_content som layout.php. En katalog kan innehålla layout.php eller en renderarlayout, men inte båda; om den innehåller båda uppstår ett identifieringsfel. Om en layout misslyckas utlöses blockstudio/pages/layout_error och sidinnehållet lämnas utan omslag, på samma sätt som för layout.php.
Blockredigeringsläge
Egenskapen blockEditingMode styr hur block kan redigeras i redigeraren. Ange ett standardvärde på sidnivå i page.json och åsidosätt det per element i mallen:
{
"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>
| Värde | Beskrivning |
|---|---|
"default" |
Fullständig redigering. Block kan väljas, flyttas och redigeras |
"contentOnly" |
Endast textredigering. Blocktext kan redigeras, men inställningar och struktur är låsta |
"disabled" |
Ingen redigering. Block är helt icke-interaktiva |
Åsidosättningar per element anges som attribut av typen HTML på valfritt element (<h1>, <p>, <div> osv.) eller på <block>-element. Överordnade containerblock för åsidosatta element ställs automatiskt in på contentOnly så att deras underordnade element förblir tillgängliga. Den här kaskaden går från det åsidosatta elementet upp till sidans rot, så du behöver bara ange blockEditingMode på de element du vill göra redigerbara.
Mallås
Egenskapen templateLock styr hur användare kan redigera sidan i redigeraren:
| Värde | Lägga till/ta bort | Flytta | Redigera innehåll |
|---|---|---|---|
"all" |
Nej | Nej | Nej |
"insert" |
Nej | Ja | Ja |
"contentOnly" |
Nej | Nej | Ja |
false |
Ja | Ja | Ja |
När en templateLock har angetts inaktiverar Blockstudio möjligheten att låsa upp block via redigerarens UI.
Virtuella rutter
Vissa dokument har inget inlägg bakom sig: en komponentreferens som genererats
från data, en katalog eller ett kontoområde. Registrera dem som virtuella rutter
i stället för att själv koppla in 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(),
]
);
} );
Sökvägen är relativ till webbplatsens startsida. Med prefix betjänar rutten också alla sökvägar under den, och match tar emot den återstående delen (en tom sträng för själva rutten) och returnerar värdet som renderingsåteranropet får, eller null för att låta URL hantera WordPress, som sedan svarar på 404 som vanligt. Renderingsåteranropet ekar ut dokumentet eller returnerar det som en sträng; title är en sträng eller en closure som tar emot matchningsvärdet.
För en matchad begäran hindrar Blockstudio WordPress från att flagga en 404 och redirect_canonical från att omdirigera den, rensar det enskilda tillståndet som huvudfrågan rapporterar, skickar statusen (status, 200 som standard) och renderar med prioritet Virtual_Routes::PRIORITY för template_redirect. Det sker direkt efter att Blockstudios utbuffert öppnas vid Assets::BUFFER_PRIORITY, så det färdiga dokumentet får sina blockresurser, paketerade UI-resurser och kompilerade Tailwind som vilken sida som helst, och före redirect_canonical vid prioritet 10. En hanterare som renderar ett helt dokument på egen hand måste också köras efter Assets::BUFFER_PRIORITY, annars hoppas den bearbetningen över. Sökvägarna i urls (som standard själva ruttens sökväg när det inte är en prefixrutt) läggs till i byggen med statisk förgenerering, och Virtual_Routes::urls() returnerar dem som absoluta URL:er för en webbplatskarta.
Virtual_Routes::match( $path ) löser en sökväg på samma sätt som en begäran skulle göra.
Synkroniseringsbeteende
Sidinlägg ändras endast genom en uttrycklig synkroniseringsåtgärd:
wp bs pages sync
Kommandot hittar alla källor, skapar eller uppdaterar ändrade
inlägg, rensar bort bekräftade föräldralösa poster, uppdaterar samlingarnas routning och den kompilerade
konfigurationen templateFor och rapporterar ändringarna. Lägg till --authoritative för att
ersätta hanterat innehåll i stället för att bevara nycklat redigerarinnehåll, och
--full för att rapportera körningen som en fullständig avstämning oavsett den lagrade
källidentiteten:
wp bs pages sync --authoritative --full
Vanliga frontend-, admin-, AJAX-, REST-, cron- och generiska bootstrap-begäranden av typen WP-CLI utför inte fullständig sidupptäckt, frågar inte efter avstämningsinventeringen för hanterade objekt och skriver inte sidinlägg. De använder redan synkroniserade WordPress-inlägg samt kompakt konfiguration för samlingar och inläggsmallar som sparats vid den senaste uttryckliga åtgärden. En ny installation eller uppgradering kan skanna samlingsmanifest en gång för att återställa metadata för routning; den skrivskyddade bootstrapen synkroniserar aldrig innehåll. Den autentiserade Canvas-slutpunkten för uppdatering, som används efter uttryckligt val, är en uttrycklig redigeringsåtgärd API: Canvas anropar den en gång när arbetsytan öppnas så att nyligen tillagda eller ändrade källor finns med i den första inventeringen. Live-läge anropar samma gräns när en ändring i en sidkälla upptäcks.
Blockstudio\Pages::init() registrerar nu endast hooks vid begärandetillfället. Integrationer
som tidigare skickade ett argument av typen force till den metoden måste anropa
Blockstudio\Pages::reconcile() eller köra wp bs pages sync i stället.
Om du vill förhindra att en sida skrivs över efter manuella ändringar anger du "sync": false i page.json.
Portabla källplatser
Synkroniserade temafiler lagras som temarelativa platser i stället för absoluta installationssökvägar. Filer i barnteman och föräldrateman behåller separata identiteter även när de har samma relativa filnamn. Sidhjälpare returnerar fortfarande lösta absoluta värden för template_path, content_path, layout_path och directory för den aktuella begäran.
Detta gör att CLI-synkronisering och webbförfrågningar kan använda olika filsystemsrotkataloger, som på låst webbhotell, utan att Markdown-svar, layouter, redigerarens Tailwind-genomsökning eller spårning av förkällor för förhandsrendering påverkas. Befintliga absoluta temapaths anpassas vid läsning om temakatalogens namn är oförändrat. Ingen synkronisering, databasmigrering eller skrivning av metadata vid förfrågningar krävs för att läsa dem; nästa uttryckliga synkronisering sparar de portabla sökvägarna.
En temakatalog som är en symbolisk länk, till exempel till en utvecklingskassa, sparar samma theme:-sökvägar oavsett om en källa läses via den symboliska länken eller dess mål, och löser dem till den konfigurerade temakatalogen.
Filer utanför de aktiva barn- och föräldrateman stöds fortfarande på sina konfigurerade absoluta sökvägar, med förbehåll för PHPs begränsningar för open_basedir. De kan inte flyttas automatiskt: efter att en extern källa har flyttats uppdaterar du dess konfigurerade sökväg och kör en uttrycklig synkronisering.
Ägarskap av inläggsfält
postStatus anger den ursprungliga statusen. Efterföljande synkroniseringar bevarar befintliga statusar som utkast, väntande, privat, publicerat och schemalagt, även med --authoritative. Ett utkast publiceras inte på nytt bara för att filen anger postStatus: "publish". Det befintliga beteendet för återställning av föräldralösa objekt är oförändrat: en uttrycklig synkronisering återställer ett borttaget hanterat inlägg om dess källa finns. Lås sidan eller inaktivera synkronisering för att förhindra återställningen.
Filen fortsätter att styra titeln, sluggen, inläggstypen, föräldern och den konfigurerade menyordningen. Om du ändrar dessa i WordPress ändras inte källdefinitionen. Nästa uttryckliga synkronisering återställer filvärdena och anger de berörda fälten i pages.<name>.overwritten, med en varning i CLI-tabellutdata. WordPresss inbyggda behörigheter gäller fortfarande, inklusive tom slug för väntande inlägg när synkroniseringsanvändaren inte kan publicera dem.
Använd blockstudio/pages/update_post_data för en integration som uttryckligen ansvarar för en annan statuspolicy. Nyckelmärkta block bevarar innehåll som ägs av redigeraren; nycklar ändrar inte vem som ansvarar för inläggets titel eller slug.
För samlingssidor omfattar fingeravtrycken manifestet, laddaren, sidkällan, layoutfilen, metadata och relaterade källsökvägar. Nästa uttryckliga synkronisering tillämpar ändringar i dessa indata.
När en samlingskälla tas bort tar Blockstudio bort den genererade sidan, så att gamla samlingssidor inte blir kvar när källfilen har försvunnit. Som standard flyttas föräldralösa samlingssidor till papperskorgen. Använd blockstudio/pages/orphan_action för att returnera trash, delete eller keep.
Vid frontend-begäranden återställer Blockstudio sidregistret från redan synkroniserade och publicerade inlägg. Utkast och privata sidor är tillgängliga i admin- och synkroniseringssammanhang, men frontend-hjälpfunktioner läser endast in publicerade sidor.
Avstämning vid driftsättning
Blockstudio\Pages::reconcile() är ingångspunkten PHP för driftsättning. Den hittar hela den önskade inventeringen, jämför källans och synkroniseringsmotorns fingeravtryck och returnerar en maskinläsbar rapport:
$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',
],
],
]);
Rapporten innehåller discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, resultat per sida, upptäcktsfel och en deterministisk sourceIdentity.
Låsta sidor har status: "locked" och räknas separat från oförändrade sidor. removedPages listar varje borttagen sidas name, key, postId och faktiska action (trash eller delete); behållna eller redan borttagna inlägg räknas inte som nyligen borttagna. CLI-tabellutdata anger också skapade, uppdaterade, låsta och borttagna sidor samt sidor med bevarat innehåll, tillsammans med deras inläggs-ID:n.
Efter parsning och sammanslagning av nyckelmärkta block anropar ett identiskt slutligt inlägg inte wp_update_post(), ändrar inte post_modified, skapar ingen revision och utlöser inga krokar för uppdatering av inlägg. Resultatet är unchanged. När källans innehåll skiljer sig från innehållet i nyckelmärkta block som ägs av redigeraren identifierar preserved: true det beslutet, och det övergripande antalet preserved inkluderar det. Det nya källfingeravtrycket och de hanterade metadatauppgifterna sparas ändå, så nästa oförändrade synkronisering inte gör något. preserved är en extra flagga, inte en exklusiv status: en sida kan bevara nyckelmärkt innehåll samtidigt som en filtitel uppdateras eller ett annat block läggs till.
authoritative: true kan ta bort ett Page Sync-lås och ersätter innehållet med
fildefinitionen i stället för att bevara nycklat redigerarinnehåll. Låt det vara false
vid en vanlig uttrycklig synkronisering. plan_valid: false, full: true,
broad: true, en saknad tidigare källidentitet eller ett ändrat fingeravtryck för
synkroniseringsmotorn markerar körningen som en fullständig avstämning (fullReconciliation i
rapporten). Varje körning jämför hela inventeringen oavsett. Git-poster för namnändringar
är endast identitetstips. De ersätter aldrig jämförelsen av hela inventeringen.
Lika fingeravtryck med oförändrade körningssökvägar innebär inga ändringar av inlägg eller postmeta och utlöser inga uppdateringshooks. När en oförändrad källa flyttas till en ny versionskatalog uppdaterar avstämningen endast de sparade sökvägarna för mall, innehåll, layout och katalog; den uppdaterar inte post_content eller tidsstämpeln för när inlägget senast ändrades. Saknade hanterade sidor rensas bort först när hela avstämningen har slutförts utan upptäckts- eller sidskrivningsfel.
En direkt avstämning med API markerar inte en driftsättning som lyckad. När du har aktiverat och verifierat den matchande statiska artefakten och dess rutter sparar du den returnerade identiteten uttryckligen:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync sparar den returnerade identiteten efter en lyckad körning.
Vanlig bootstrap med WP-CLI registrerar endast sparade samlingsinläggstyper och
omskrivningsregler. Den upptäcker eller synkroniserar inte sidor.
Låsning av inläggs-ID
Som standard tilldelar WordPress inläggs-ID:n automatiskt. Om en sida tas bort och skapas på nytt ändras ID:t, vilket bryter externa referenser som menyer eller hårdkodade länkar.
Använd postId för att låsa en sida till ett specifikt ID:
{
"name": "about",
"title": "About Us",
"postId": 42
}
När sidan skapas skickar Blockstudio ID:t till WordPress via import_id. Om ID:t är ledigt använder WordPress det precis som angivet. Om ID:t redan används av ett orelaterat inlägg tilldelar WordPress automatiskt ett nytt ID utan att meddela det.
När befintliga sidor söks igenom kontrollerar Blockstudio det låsta ID:t först, innan metadata eller slug kontrolleras. Det innebär att om en sida tas bort och synkroniseras på nytt får den tillbaka samma ID.
Sammanfogning av nycklade block
Som standard ersätter Blockstudio allt innehåll i inlägget med den nya mallen när en mallfil ändras. Det innebär att alla ändringar som gjorts i redigeraren WordPress går förlorade.
Lägg till attributet key i block för att bevara användarändringar mellan mallsynkroniseringar. När en mall innehåller nycklade block sammanfogar Blockstudio malländringarna med det befintliga inläggsinnehållet i stället för att ersätta det.
Lägga till nycklar
Använd attributet key på valfritt element av typen HTML eller <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"
/>
Nycklar måste vara globalt unika i hela mallen. En nyckel skyddar hela blocket och allt dess innehåll. Du behöver inte nyckla enskilda underordnade element inuti ett nycklat överordnat block. Nycklade block kan flyttas till valfri position eller nästlingsnivå mellan malluppdateringar, och deras användarinnehåll bevaras.
Nycklar fungerar på samma sätt för anpassade block i Blockstudio. key är strukturella Page Sync-metadata; anpassade fältvärden förblir vanliga attribut av typen Blockstudio.
När en redigerare ändrar dessa fält bevarar en senare mallsynkronisering redigerarens värden samtidigt som oberoende malländringar tillämpas. Sidor som skapats med äldre versioner, där nyckeln ligger inuti det anpassade fältets data, migreras automatiskt vid nästa synkronisering.
Så fungerar sammanfogningen
När en mallfil ändras och sidan synkroniseras på nytt:
| Block | Beteende |
|---|---|
| Nycklat block | Användarinnehåll och fältvärden av typen Blockstudio bevaras. Mallägda attribut och struktur tillämpas. |
| Onyklat block | Ersätts helt med mallversionen (samma som utan nycklar) |
Exempel
Användarändringar bevaras i nycklade block:
- Mallen definierar
<p key="intro">Default intro.</p> - Användaren ändrar stycket i redigeraren till "Anpassad introduktionstext."
- Utvecklaren uppdaterar mallen, lägger till ett nytt block och ändrar layouten
- Vid synkronisering: stycket behåller "Anpassad introduktionstext." medan den nya layouten tillämpas
Attribut från mallen tillämpas fortfarande:
- Mallen har ett omslagsblock med
key="hero"och ett attribut av typenurl - Utvecklaren ändrar omslagsblockets attribut
urltill en ny bakgrundsbild - Vid synkronisering: den nya bakgrundsbilden tillämpas, men användarens innehållsändringar inuti omslagsblocket bevaras
Specialfall
| Scenario | Beteende |
|---|---|
| Ett nytt nycklat block läggs till i mallen | Visas med mallens standardinnehåll |
| Ett nycklat block tas bort från mallen | Tas bort från inlägget |
| Blocktypen ändras (samma nyckel) | Mallen gäller helt, ingen innehållssammanfogning |
| Dubblerade nycklar | Den andra förekomsten behandlas som onyklad |
| Inga nycklar i mallen | Fullständig ersättning (samma beteende som utan nycklar) |
| Tvingad synkronisering | Fullständig ersättning, nycklar ignoreras |
| Låst inlägg | Ingen synkronisering alls |
Kombinera med redigeringskontroller
Nycklar, templateLock och blockEditingMode ger tillsammans detaljerad kontroll över vad kunder kan och inte kan göra. Här är några vanliga arbetsflödesmönster.
Helt låst sida
Utvecklaren styr allt. Sidan är en statisk layout som kunder inte kan ändra alls. Användbart för juridiska sidor, användarvillkor eller sidor som endast ska ändras genom kod.
{
"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>
Inga nycklar behövs. Mallen är den enda sanningskällan. Varje synkronisering skriver över hela sidan.
Låst layout med redigerbart innehåll
Det vanligaste mönstret. Lås sidstrukturen så att kunder inte kan lägga till, ta bort eller ordna om block, men låt dem redigera text på särskilda platser. Nycklar ser till att deras ändringar överlever malluppdateringar.
{
"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>
Klienten kan redigera herotiteln, beskrivningen och introduktionen till funktionerna. Inget annat. Knapptexten, URL och omslagsbildens bakgrund styrs av utvecklaren. När utvecklaren uppdaterar mallen (e.g., lägger till en andra knapp) behåller de nyckelbaserade sektionerna klientens text.
Mall som utvecklas med bevarat innehåll
För sidor som växer med tiden. Utvecklaren lägger till nya sektioner i mallen, och varje synkronisering lägger till det nya innehållet utan att röra det som klienten redan har anpassat.
<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>
Den nya sektionen med kundomdömen och knappen visas vid synkronisering. Klientens ändringar av titeln, introduktionen och tjänsterna lämnas orörda.
Engångsskelett
Skapa en sida med en grundstruktur och lämna sedan över den helt. Ställ in sync på false så att vanlig synkronisering aldrig skapar eller uppdaterar sidan, och skapa den en gång med Blockstudio\Pages::force_sync('blog'). Därefter äger klienten sidan helt.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
wp bs pages sync hoppar över den här sidan, så force_sync() skapar den en gång. Därefter kan klienten lägga till, ta bort och ordna om block fritt. Malländringar ignoreras.
Blockbindningar
Ett alternativ till nyckelbaserad sammanslagning är att använda WordPress cores Blockbindningar API för att koppla block till inläggsmetadata. Detta är ingen Blockstudio-funktion, utan en inbyggd WordPress API. Blockstudio skickar helt enkelt attributet metadata vidare till den genererade blockuppmärkningen. Innehållet lagras i inläggsmetadata i stället för i blockuppmärkningen, så mallsynkroniseringar kan skriva över uppmärkningen fritt eftersom redigeraren läser från metadata, inte från innerHTML.
Ange attributet metadata på valfritt HTML-element eller <block>-element:
<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"}}}}'
/>
Metanycklarna måste registreras med show_in_rest aktiverat:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Nycklar jämfört med bindningar
| Aspekt | Nycklar | Bindningar |
|---|---|---|
| Innehåll lagras i | Blockuppmärkning (post_content) |
Inläggsmetadata (wp_postmeta) |
| Bevaras vid mallsynkronisering | Ja (slås samman efter nyckel) | Ja (data lagras i metadata) |
Kan hämtas via WP_Query |
Nej | Ja (meta_query) |
| Tillgängligt i REST API | Nej | Ja |
| Kräver registrering | Nej | Ja (register_post_meta) |
| Användaren kan flytta block | Nej (mallen återställer strukturen) | Nej (mallen återställer strukturen) |
Båda metoderna kan användas i samma mall. Använd nycklar för sektioner där blockstrukturen är viktig (e.g., en grupp med flera underordnade block). Använd bindningar för enskilda fält när du också vill att data ska vara tillgängliga utanför blockredigeraren.
Inläggstypsmallar
Använd templateFor för att ange en sida som standardmall för en inläggstyp:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
Alla nya inlägg av den typen börjar med den definierade blockstrukturen.
Anpassade sökvägar
Som standard söker Blockstudio igenom get_template_directory() . '/pages'. Lägg till fler sökvägar med filtret:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
Körningsintegreringar som sammanfogar filer från flera rötter kan ersätta filsystemsökningen med en logisk upptäcktskälla. Sidmanifest, layouter, laddare och källmallar löses då via logiska sökvägar, även när de valda filerna finns i olika rötter.
Filter och åtgärder
Sididentifiering, synkronisering och samlingsroutning tillhandahåller följande utökningspunkter:
| Krok | Typ | Beskrivning |
|---|---|---|
blockstudio/pages/paths |
Filter | Lägg till kataloger där Blockstudio söker efter sidkällor. |
blockstudio/pages/collection_post_type_args |
Filter | Justera argumenten för register_post_type() för en samlings-CPT. |
blockstudio/pages/template_candidates |
Filter | Justera mallfilnamn som beaktas för en sidkälla. |
blockstudio/pages/serve_markdown |
Filter | Aktivera eller inaktivera råa Markdown-svar. |
blockstudio/pages/orphan_action |
Filter | Returnera trash, delete eller keep vid rensning av föräldralösa objekt. |
blockstudio/pages/docs_allowed_html |
Filter | Justera tillåtna HTML för genererat Markdown-dokumentationsinnehåll. |
blockstudio/pages/allow_external_loader_path |
Filter | Tillåt laddarens paths utanför samlingens rotkatalog. |
blockstudio/pages/manifest_scan_interval |
Filter | Ange den maximala åldern för en äldre manifestcache från före 7.6.2 som får användas för att initiera sparad körningskonfiguration under en uppgradering. |
blockstudio/pages/create_post_data |
Filter | Ändra inläggsdata innan en synkroniserad sida skapas. |
blockstudio/pages/update_post_data |
Filter | Ändra inläggsdata innan en synkroniserad sida uppdateras. |
blockstudio/pages/sync_engine_inputs |
Filter | Lägg till en parser-, mappnings- eller migreringsversion som avsiktligt ska utöka avstämningen en gång. |
blockstudio/pages/post_created |
Åtgärd | Körs efter att ett synkroniserat sidinlägg har skapats. |
blockstudio/pages/post_updated |
Åtgärd | Körs efter att ett synkroniserat sidinlägg har uppdaterats. |
blockstudio/pages/synced |
Åtgärd | Körs när sidregistret har synkroniserats klart. |
blockstudio/pages/reconciled |
Åtgärd | Körs efter en uttrycklig avstämning med dess maskinläsbara rapport. |
blockstudio/pages/renderers |
Åtgärd | Registrera sidsrenderare med Blockstudio\Page_Renderers::register(). Körs en gång per förfrågan. |
blockstudio/pages/rendered |
Åtgärd | Körs efter att en komponentsida har renderats, med sidan, dess HTML och dess beroenden. |
blockstudio/pages/layout_error |
Åtgärd | Körs när en layout inte kan renderas, med felet, layoutsökvägen och sidan. |
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]);
Se Avstämning vid driftsättning för information om argumentens betydelse, rapportfält och gränsen för verifierad källidentitet.
Globala hjälpfunktioner är tillgängliga för mallar och layouter:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
Sidarrayer som returneras av Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() och de globala hjälpfunktionerna innehåller den synkroniserade inläggsidentiteten, sökvägar till källa och mall, metadata om samling och sökväg, innehållstyp, synkroniseringspolicy, inläggstyp och status, redigeringspolicy, anpassade metadata och en permalink-nyckel. Samlingsmetadata läses in från den senaste lyckade uttryckliga avstämningen. Vanliga förfrågningar återskapar dessa körningsdata från beständig konfiguration och synkroniserade inläggsmetadata utan att läsa källträd för sidor. Klassen Pages har ingen separat metod för permalänkar.
Mallåsning, redigeringslägen för block, nyckelbaserad sammanslagning och styrning av vad klienter kan redigera.