Pagina’s
Pagina’s zijn bestandssjablonen die als berichten met de WordPress-database worden gesynchroniseerd.
Synchronisatie is expliciet: voer wp bs pages sync uit of roep de Pages API aan
wanneer u bronwijzigingen wilt toepassen. Het laden van de frontend of de WordPress-beheeromgeving
voert nooit volledige paginadetectie uit en wijzigt geen paginaberichten.
Pagina’s kunnen worden gedefinieerd als één map page.json, als zelfstandige Markdown of als een verzameling met een pages.json-manifest. Verzamelingen zijn handig voor documentatie, kennisbanken, bibliotheken met landingspagina’s of elke reeks geneste pagina’s die vanuit bestanden moet worden gegenereerd.
page.json
Voeg voor een pagina die via JSON is gedefinieerd een configuratiebestand page.json toe:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
Eigenschappen
| Eigenschap | Type | Standaard | Beschrijving |
|---|---|---|---|
name |
string |
vereist | Unieke identificatie voor de pagina |
title |
string |
Automatisch op basis van naam | De paginatitel |
slug |
string |
Gelijk aan naam | De URL-slug voor de pagina |
path |
string |
"." |
Logisch pad binnen een collectie |
order |
integer |
0 |
Menuvolgorde voor het gesynchroniseerde bericht |
postType |
string |
"page" |
WordPress-berichttype |
postStatus |
string |
"draft" |
Status voor nieuwe berichten (publish, draft, pending, private) |
postId |
integer |
– | Koppel de pagina aan een specifiek WordPress-bericht-ID |
blockEditingMode |
string |
– | Blokbewerkingsmodus: "default", "contentOnly" of "disabled" |
templateLock |
string|false |
"all" |
Vergrendelingsmodus: "all", "insert", "contentOnly" of false |
templateFor |
string|null |
null |
Instellen als standaardsjabloon voor een berichttype |
sync |
boolean |
true |
Of normale expliciete reconciliatie het bericht mag maken of bijwerken |
render |
string|object|false |
– | De pagina weergeven met een geregistreerde paginarenderer (zie Componentpagina’s) |
In page.json, frontmatter en loadervermeldingen zijn de herkende sleutels onder meer blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock en title. Elke hierboven niet genoemde sleutel wordt opgeslagen in de meta-array van de pagina.
Inhoudsbronnen
Een paginadefinitie bepaalt welk WordPress-bericht moet bestaan. De inhoudsbron bepaalt welke blokopmaak naar dat bericht wordt geschreven.
Als een paginamap een page.json bevat, zoekt Blockstudio in deze volgorde naar een bronbestand in dezelfde map:
| Bestand | Gebruik |
|---|---|
index.php |
HTML-achtige blokopmaak, ongewijzigd gelezen (PHP-code wordt niet uitgevoerd) |
index.blade.php |
Inhoud van Blade-sjabloon |
index.twig |
Inhoud van Twig-sjabloon |
index.md |
Markdown-inhoud |
page.json kan ook inline markdown of html bevatten in plaats van een bestand in dezelfde map:
{
"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>"
}
Verzamelingen bieden nog twee bronmodi:
- Markdown-bestanden die rechtstreeks in de verzamelingsstructuur worden gevonden.
- Loader-items die worden geretourneerd door
loader.php.
Loader-items kunnen markdown, html of content met contentType gebruiken. Ze kunnen ook verwijzen naar een lokale file of template. Het type van bestands- en sjabloonbronnen wordt afgeleid van de extensie, tenzij contentType expliciet is ingesteld.
Ondersteunde waarden voor contentType zijn php, blade, twig, markdown en html. Markdown wordt eerst omgezet naar HTML en vervolgens geparseerd naar native WordPress-blokken. Bronnen van het type PHP, Blade, Twig en HTML worden verwerkt door de normale Blockstudio-paginaparser.
Klassen op core-blokken
Een class op een element HTML dat aan een core-blok is gekoppeld, wordt de className ervan.
Een expliciete core-bloktag kan rechtstreeks className gebruiken. Beide vormen behouden de klassen op de opgeslagen wrapper van het blok, naast de klassen die WordPress genereert:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
Als beide eigenschappen aanwezig zijn, heeft className voorrang. Deze conversie geldt alleen voor core-blokken: bij een aangepaste blokmapping blijft het veld class ongewijzigd. Knopstijlklassen, zoals is-style-outline, horen bij de knopwrapper, niet bij de link.
Voer wp bs pages sync uit om parsercorrecties toe te passen op eerder gesynchroniseerde pagina’s. Parserupgrades worden herkend bij de volgende expliciete synchronisatie, ook zonder wijziging van het bronbestand. Vergrendelde pagina’s en pagina’s met sync: false behouden hun normale beveiligingen; frontendverzoeken voeren deze synchronisatie nooit uit.
Geserialiseerde WordPress-blokken
Pagina- en patroonbronnen kunnen ook geserialiseerde blokken bevatten die uit de code-editor van WordPress zijn gekopieerd:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
Wanneer de bron een <!-- wp:... -->-blokscheidingsteken bevat, gebruikt Blockstudio de native blokparser van WordPress voor de volledige bron. Attributen, geneste blokken, dynamische blokken zoals Query Loop en Blockstudio-blokken behouden hun geserialiseerde structuur. HTML buiten de blokcommentaren blijft native vrije inhoud van HTML; deze wordt niet omgezet in extra blokken. Combineer de HTML-bloktags van Blockstudio niet met dit formaat in de verwachting dat ze worden geconverteerd. Gewone HTML-commentaren activeren de modus voor geserialiseerde blokken niet.
Markdown-pagina’s
Gebruik Markdown wanneer de tekst in bestanden moet staan, maar na synchronisatie toch bewerkbare WordPress-blokinhoud moet worden. De bron Markdown wordt tijdens de synchronisatie omgezet in blokopmaak. Het gesynchroniseerde bericht bevat blokken, niet de ruwe Markdown-tekst.
Markdown kan op drie manieren worden gebruikt:
| Bron | Frontmatter vereist? | Opmerkingen |
|---|---|---|
Zelfstandig pages/example/index.md |
Ja | Frontmatter bevat de pagina-identiteit. |
page.json plus index.md |
Nee | page.json definieert de pagina en Markdown levert de inhoud. |
| Markdown in een verzameling | Nee | De verzameling leidt name en path af uit de bestandslocatie. |
Een zelfstandig index.md-bestand zonder frontmatter wordt overgeslagen, omdat Blockstudio geen pagina-identiteit heeft om te synchroniseren. Voor een Markdown in een verzameling is geen frontmatter nodig, omdat het manifest en bestandspad van de verzameling die identiteit bepalen.
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
U kunt page.json ook combineren met index.md. In dat geval definieert page.json de pagina en levert index.md de inhoud. Frontmatter in index.md overschrijft overeenkomende waarden in 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.
Voor een Markdown in een verzameling wordt het bestandspad het logische paginapad, tenzij frontmatter dit overschrijft:
| Bestand | Standaardpad |
|---|---|
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 |
Onbekende frontmatter-sleutels blijven bewaard in de meta-array van de pagina. Zo kunt u gegevens zoals section of description toevoegen en uitlezen vanuit de PHP API.
Markdown wordt geparseerd als GitHub-Flavored Markdown. Ruwe HTML is toegestaan, onveilige links worden verwijderd en koppen zonder expliciete ID krijgen een stabiele ID. Geneste frontmatter in YAML vereist de meegeleverde parser YAML.
Ruwe Markdown
Bronnen uit Markdown-bestanden kunnen de oorspronkelijke bron-Markdown beschikbaar maken voor externe tools en documentatiegebruikers. Inline Markdown heeft geen bronbestand en wordt daarom wel naar blokken gesynchroniseerd, maar levert geen ruwe .md-respons op.
Vraag de pagina op met een achtervoegsel .md, bijvoorbeeld https://example.com/docs/reference.md. Of stuur een Accept: text/markdown-header naar de normale pagina-URL:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
Frontmatter wordt uit de respons verwijderd. Succesvolle ruwe Markdown-responses sturen Content-Type: text/markdown, X-Robots-Tag: noindex en een canonieke Link-header terug naar de HTML-pagina. Routes voor ontbrekende .md leveren een echte 404 op.
Inhoudsonderhandeling werkt samen met statisch prerenderen: een verzoek waarvan de header Accept text/markdown bevat, krijgt nooit antwoord uit de prerenderopslag of de early-serve-drop-in en bereikt dus WordPress en de Markdown-handler. Vooraf gerenderde HTML-antwoorden, de HTML van een pagina die ook Markdown aanbiedt, en Markdown-antwoorden via Accept sturen Vary: Accept, zodat caches die Vary respecteren de twee gescheiden houden. Een CDN dat alleen de URL als cachesleutel gebruikt, heeft een eigen regel nodig om voor zulke verzoeken de cache te omzeilen. Pages::negotiates_markdown( $post_id ) geeft aan of een pagina Markdown-verzoeken beantwoordt.
De verzameling Markdown behoudt dezelfde URL-structuur voor ruwe Markdown:
| Pagina-URL | Ruwe Markdown URL |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
Schakel ruwe Markdown-responses uit met het filter blockstudio/pages/serve_markdown:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Een .md-URL die niet naar een Markdown-pagina leidt, retourneert alleen een 404 als het pad binnen een paginaverzameling valt. Buiten alle verzamelingen laat Blockstudio de aanvraag over aan WordPress en andere plugins.
Componentpagina’s
Een componentpagina wordt door een paginarenderer weergegeven in plaats van als
blokken te worden opgeslagen. Blockstudio levert geen renderer mee. Een thema of plugin registreert er een
voor de entrybestanden die deze afhandelt, zoals een React-renderer voor page.tsx, en
Blockstudio roept deze aan met de pagina, het WordPress-bericht en de weergegeven slotinhoud.
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 is expliciet. Een map met een index.php en een page.tsx maar zonder
render blijft een gewone pagina, zodat het toevoegen van een renderer een
bestaande pagina nooit tweemaal weergeeft. De vormen zijn:
| Waarde | Betekenis |
|---|---|
"page.tsx" |
Alleen entry, zonder dataloader |
{ "entry": "page.tsx", "data": "data.php" } |
Entry en dataloader |
{ "entry": "page.tsx", "renderer": "react" } |
Entry met een expliciete renderer-ID |
false |
Geen renderer, ook niet als een standaardinstelling van de collectie er een opgeeft |
Paden worden opgelost ten opzichte van de paginamap, of ten opzichte van de hoofdmap van de collectie voor loadervermeldingen. Ze moeten binnen de ontdekkingsbron blijven, tenzij
blockstudio/pages/allow_external_loader_path dit toestaat. Zonder
renderer wordt de renderer gebruikt die aanspraak maakt op de extensie van de entry. Een
render die verwijst naar een ontbrekende entry of databestand, een onbekende renderer of een extensie waarop geen renderer aanspraak maakt, is een ontdekkingsfout. Daardoor mislukt de reconciliatie voordat er iets wordt opgeschoond.
Wat synchronisatie opslaat
Synchronisatie slaat één blok blockstudio/page op. Als de paginamap ook een
index.*-bron bevat, wordt die bron verwerkt zoals elke paginabron en vormt deze de
innerlijke blokken van het blok, oftewel de slot:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
Houd inhoud die eigendom is van WordPress, zoals shortcodes, in de slot. Een bron die uit slechts één shortcode bestaat, zoals [download_checkout],
wordt opgeslagen als een blok core/shortcode, zodat er geen alinea
omheen wordt gezet. Het blijft in
post_content, zodat controles van has_shortcode() de inhoud zien, blokken met slotsleutels worden samengevoegd
met wijzigingen van de editor zoals geneste blokken met sleutels, en do_shortcode de
shortcodes eenmaal uitvoert op de gebruikelijke prioriteit the_content, nadat de renderer ze heeft omkaderd.
De renderdefinitie wordt samen met het bericht opgeslagen als draagbare theme:-paden. De paginavingerafdruk omvat de definitie, niet de bytes van de entry of dataloader: wijzigingen aan page.tsx of data.php laten het bericht ongewijzigd en bereiken bezoekers via rendering en de statische prerender-graaf, waarin de entry, de dataloader en elk bestand dat de renderer rapporteert worden vastgelegd.
Een renderer registreren
Registreer renderers op de actie blockstudio/pages/renderers. Deze wordt eenmaal
per verzoek uitgevoerd, vóór de eerste ontdekking of rendering, zodat wp bs pages sync en
frontendverzoeken hetzelfde register zien.
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',
)
);
}
);
Renderer-ID’s zijn in kleine letters. Een extensie of layoutnaam kan maar bij één
renderer horen, en layout.php blijft de eigen layout van Blockstudio. De aanroepbare
functie ontvangt één verzoek:
| Sleutel | Waarde |
|---|---|
kind |
page, of layout voor een rendererlayout |
renderer |
Renderer-ID |
entry |
Absoluut entrypad |
data |
Absoluut pad naar de dataloader, of null |
page |
Canonieke paginagegevens, inclusief meta |
post_id |
Bericht-ID van WordPress |
slot |
Weergegeven slotinhoud, of de pagina-inhoud voor een layout |
context |
frontend, rest, feed of cli |
Deze retourneert de HTML, de bestanden die tijdens het renderen zijn gelezen en optionele assets:
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 komt uit het requesttype en nooit van de bezoeker, zodat een renderer de bytepariteit tussen ingelogde en anonieme bezoekers niet kan verstoren door deze waarde uit te lezen. Als een renderer een fout geeft, wordt deze doorgegeven: de pagina wordt niet met een lege inhoud weergegeven. In een REST-editorvoorbeeld toont het blok de fout als melding. Na een geslaagde render ontvangt de actie blockstudio/pages/rendered de pagina, de HTML en de afhankelijkheden ervan.
assets vermeldt welke script- en stijlbestanden de pagina nodig heeft. Deze worden verwerkt zoals blokassets (volgens de conventie *.inline.*, als ES-modules, met minificatie en ?ver), en de pagina voegt ze één keer toe via dezelfde buffer als voor blokassets, zodat een vooraf gerenderde pagina ze bevat. Een asset kan version instellen om de waarde van ?ver te vervangen. Code buiten een renderer kan hetzelfde kanaal gebruiken via Blockstudio\Assets::register_owner(), dat de markercommentaar retourneert om af te drukken.
Editor
In de editor toont blockstudio/page een servergerenderd voorbeeld van de pagina, met de slot als inner blocks die de templateLock van de pagina volgen. Het blok kan niet worden ingevoegd, gedupliceerd of genest in een ander blok.
Paginaverzamelingen
Een verzameling is een map met een pages.json-manifest. Deze groepeert meerdere paginabronnen onder één collectieslug, past standaardwaarden toe, ondersteunt geneste paden en kan automatisch een speciaal berichttype registreren.
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"
}
}
| Eigenschap | Type | Beschrijving |
|---|---|---|
collection / slug / name |
string |
Slug van de collectie. collection is de duidelijkste vorm en wordt de openbare basis-URL. |
title |
string |
Voor mensen leesbare titel van de collectie. |
postType |
string |
Berichttype voor gegenereerde pagina’s. Standaard page. Als dit niet bestaat, registreert Blockstudio het. |
postTypeArgs |
object |
Argumenten die aan register_post_type() worden doorgegeven wanneer Blockstudio het berichttype van de collectie registreert. |
defaults |
object |
Standaardeigenschappen voor pagina’s die op elke pagina in de collectie worden toegepast. Een standaard-render wordt alleen toegepast op een pagina als de bijbehorende vermelding in de paginadirectory bestaat. |
scope |
string |
collection (standaard) of site. Zie Sitecollecties. |
meta |
object |
Aangepaste collectiemetadata. Onbekende manifestkeys worden ook opgeslagen in meta. |
Paginapaden binnen verzamelingen zijn logische paden. Een pagina met path: "guide/install" wordt als onderliggende pagina van guide gesynchroniseerd, en guide wordt als onderliggende pagina van de hoofdmap van de verzameling gesynchroniseerd wanneer die bovenliggende pagina’s bestaan.
Als een hiërarchische verzameling een geneste pagina bevat maar er geen bronbestand voor een tussenliggende bovenliggende pagina bestaat, genereert Blockstudio een lege containerpagina voor dat pad, zodat de WordPress-hiërarchie compleet blijft. Voor niet-hiërarchische berichttypen (zonder ondersteuning voor page-attributes als bovenliggende pagina) worden geen lege containers gegenereerd. Ze routeren op basis van het opgeslagen verzamelingspad, zodat geneste paden zoals guide/install en setup/install naast elkaar kunnen bestaan, ook al eindigen ze beide op install.
Berichttypen en URL’s van verzamelingen
Stel postType in het verzamelingsmanifest in om elke pagina in de verzameling naar dat berichttype te synchroniseren. U hoeft dezelfde waarde niet in defaults te herhalen. Afzonderlijke pagina’s kunnen postType nog steeds overschrijven in frontmatter of page.json.
Als het berichttype niet bestaat, registreert Blockstudio het met show_in_rest: true, een pagina-achtige editorconfiguratie en de collectieslug als openbare basis voor URL. postTypeArgs kan de registratieargumenten overschrijven. De rewrite-regels voor berichttypen van verzamelingen worden automatisch ververst wanneer de geregistreerde berichttypen of rewrite-argumenten wijzigen; u hoeft de permalinks van WordPress dus niet opnieuw op te slaan.
URL’s van verzamelingen gebruiken de collectieslug plus het logische path van elke pagina:
| Bronpad | Openbaar URL |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
Dit URL-model werkt voor zowel hiërarchische als niet-hiërarchische verzamelingsberichttypen. Blockstudio leidt dubbele URL’s, zoals /docs/docs/ of /docs/docs/getting-started/, ook om naar de canonieke URL.
Verzamelingspagina’s tonen onbewerkte Markdown op dezelfde URL’s (zie Ruwe Markdown).
Als u een verzameling wijzigt van postType: "page" naar een aangepast berichttype, migreert Blockstudio eerder gesynchroniseerde verzamelingsberichten op hun plek wanneer hun opgeslagen pagina-identiteit overeenkomt. Zo blijven bericht-ID’s, metadata en bestaande inhoud behouden en worden dubbele berichten met het oude type voorkomen. Verouderde verzamelingsberichten worden opgeschoond in alle berichtstatussen volgens het filter blockstudio/pages/orphan_action.
Sitecollecties
Een manifest met "scope": "site" groepeert alle pagina’s eronder zonder ze om te zetten in collectiepagina’s. Gebruik dit in de hoofdmap van de paginaboom van een site om gedeelde standaardwaarden toe te passen en de pagina’s van de site weer te geven met 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" }
}
}
Pagina’s van een sitecollectie behouden precies dezelfde identiteit als zonder het manifest. Als u er een toevoegt aan een bestaande boom, worden er dus geen berichtregels bijgewerkt en wordt er niets aangemaakt of verwijderd:
- Sleutels blijven globaal:
Pages::get_page( 'home' )en opgeslagen paginasleutels blijven overeenkomen. - URL’s blijven WordPress-pagina-URL’s. Er zijn geen herschrijfregels voor collecties, permalinkfilters of redirects met dubbele URL, en er worden geen lege containerpagina’s gegenereerd.
- De logische paden, slugs, bovenliggende pagina’s en bronidentiteiten blijven die van zelfstandige pagina’s; de indelingen worden bepaald door de dichtstbijzijnde voorouder.
- Geneste
pages.json-manifests behouden hun eigen collecties; hun substructuren worden buiten de sitecollectie gehouden. - Standaardwaarden worden per pagina toegepast: een standaard-
rendergeldt alleen voor pagina’s waarvan de directory de bijbehorende vermelding bevat. Pagina’s met shortcodes en Markdown behouden dus hun bronnen.
Verzamelingsladers
Verzamelingen kunnen een vertrouwde lokale loader.php bevatten. Gebruik deze wanneer verzamelingspagina’s uit een andere lokale bron komen, zoals een externe documentatiemap, een pakket of een gegenereerd manifest.
De lader wordt uitgevoerd tijdens expliciete paginadetectie en synchronisatie. Deze hoort deterministisch en lokaal te zijn. Haal geen externe inhoud op via loader.php, omdat de synchronisatie bij implementatie dan afhankelijk zou zijn van die service.
<?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',
),
),
);
Een lader kan een array retourneren met de sleutels pages, meta en paths:
| Sleutel | Beschrijving |
|---|---|
pages |
Een lijst met pagina-arrays. Elke pagina ondersteunt dezelfde herkende sleutels als de frontmatter van page.json en Markdown. |
meta |
Metadata die wordt samengevoegd met de array meta van elke door de loader gegenereerde pagina. |
paths |
Extra lokale mappen die als onderdeel van deze collectie worden doorzocht. Vermeldingen kunnen tekenreeksen of padobjecten zijn. |
render |
Een renderdefinitie voor elke Markdown-pagina die wordt gevonden in paths. |
Als verkorte notatie mag de lader een kale lijst met pagina-arrays retourneren.
Pagina-items van de lader kunnen op de volgende manieren inhoud aanleveren:
| Vorm | Beschrijving |
|---|---|
markdown |
Inline Markdown-inhoud. |
html |
Inline HTML-inhoud. |
content + contentType |
Algemene inline-inhoud. contentType moet worden omgezet naar markdown of html. |
file |
Lokale bestandsbron. Het type wordt afgeleid van de extensie, tenzij contentType is ingesteld. |
template |
Alias voor file. |
Bestandsverwijzingen van de lader kunnen verwijzen naar PHP-, Blade-, Twig-, Markdown- of HTML-bronnen. Relatieve paden worden opgelost vanaf de hoofdmap van de verzameling. Absolute paden en paden buiten de hoofdmap van de verzameling zijn alleen toegestaan als het filter blockstudio/pages/allow_external_loader_path dit toestaat.
Pagina’s van de lader gebruiken standaard generated: true. Wanneer een gegenereerde loaderpagina niet meer in de uitvoer van de lader voorkomt, behandelt Blockstudio het gesynchroniseerde bericht bij de volgende synchronisatie als verweesd. Het wordt opgeschoond volgens het filter blockstudio/pages/orphan_action.
Mappen die in paths staan, worden op dezelfde manier doorzocht als gewone verzamelingsmappen. Ze kunnen Markdown-bestanden of page.json-mappen bevatten. Als die paden buiten de hoofdmap van de verzameling vallen, is hetzelfde filter voor externe paden van toepassing.
Gebruik een string-item wanneer de externe map haar eigen logische paden moet behouden. Gebruik een object-item wanneer de map onder een padprefix van de verzameling moet worden gekoppeld:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
Met deze configuratie wordt cli-docs/index.md path: "cli" en wordt cli-docs/getting-started.md path: "cli/getting-started" in de verzameling. Prefixen voorkomen ook naamconflicten bij gegenereerde pagina’s, zodat meerdere gekoppelde mappen elk index.md of getting-started.md kunnen bevatten. Stel preserveNames in op true voor het padobject als expliciete name-waarden uit frontmatter van page.json of Markdown behouden moeten blijven.
Eigenschappen van padobjecten:
| Eigenschap | Type | Beschrijving |
|---|---|---|
path |
string |
Lokale map om te doorzoeken. Relatieve paden worden opgelost vanaf de hoofdmap van de collectie. |
prefix |
string |
Optioneel logisch padvoorvoegsel binnen de collectie. |
preserveNames |
boolean |
Behoud expliciete paginanamen in plaats van namen te genereren op basis van het pad met voorvoegsel. Standaard false wanneer prefix is ingesteld. |
meta |
object |
Metadata die wordt samengevoegd met elke pagina die via dit pad wordt gevonden. Metadata op paginaniveau heeft voorrang bij dubbele sleutels. |
render |
string|object |
Een renderdefinitie voor de Markdown-pagina’s van dit pad, als vervanging van de render van de loader. |
Markdown renderen via een component
Met render worden de Markdown-pagina’s die een loader vindt via een paginarenderer weergegeven, in plaats van als blokken te worden opgeslagen:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
Het blijven Markdown-pagina’s: het inhoudstype, het inhoudspad, de antwoorden van .md en de frontmatter blijven ongewijzigd. Sync slaat één blockstudio/page-blok op waarvan de inner HTML de geconverteerde Markdown bevat, opgeschoond als de collectie de inhoud opschoont, in plaats van geparseerde blokken, zodat post_content de documenttekst behoudt. De renderer ontvangt die HTML als slot en kan de bron uitlezen via page.content_path. Relatieve paden worden opgelost vanaf de hoofdmap van de collectie; het externe padfilter is van toepassing, net als voor de paden. Een pagina waarvan de frontmatter een eigen render of render: false instelt, wordt buiten beschouwing gelaten.
Indelingen
Een layout.php-bestand verzorgt de frontendweergave van een pagina op basis van een bestand. Het vervangt de gesynchroniseerde post_content niet die is opgeslagen in WordPress, en omhult het editorcanvas niet. De indeling wordt alleen uitgevoerd bij frontendverzoeken voor afzonderlijke pagina’s.
Plaats voor verzamelingen layout.php naast pages.json om elke frontendpagina in die verzameling ermee te omhullen:
<?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() geeft de hoofdtekst van de pagina weer die WordPress normaal via the_content zou weergeven. Als een indeling blockstudio_page_content() niet uitvoert, wordt de pagina-inhoud bewust verborgen.
Indelingen kunnen de hulpfuncties voor pagina’s gebruiken:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
Geneste pagina’s die niet bij een verzameling horen, kunnen ook de dichtstbijzijnde bovenliggende layout.php in de pages-structuur overnemen. Voor verzamelingspagina’s wordt de hoofdindeling van de verzameling op elk gesynchroniseerd bericht opgeslagen en als onderdeel van de paginavingerafdruk gevolgd. Wijzigingen in de indeling worden daardoor bij de volgende synchronisatie opgepikt.
Rendererindelingen
Een indeling kan ook een renderer-entry zijn, zoals layout.tsx voor een renderer die layouts: ["layout.tsx"] registreert. Deze wordt op dezelfde locaties gevonden als layout.php, en een optionele layout.data.php ernaast fungeert als dataloader. Tijdens het renderen ontvangt de renderer kind: "layout" en de gerenderde pagina-inhoud als slot, met dezelfde prioriteit van the_content als layout.php. Een map kan layout.php of één rendererindeling bevatten, maar niet allebei; als beide aanwezig zijn, ontstaat er een ontdekkingsfout. Bij een fout in de indeling wordt blockstudio/pages/layout_error geactiveerd en blijft de pagina-inhoud onverpakt, net als bij layout.php.
Blokbewerkingsmodus
De eigenschap blockEditingMode bepaalt hoe blokken in de editor kunnen worden bewerkt. Stel een standaardwaarde op paginaniveau in page.json in en overschrijf deze per element in de template:
{
"name": "about",
"title": "About Us",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
| Waarde | Beschrijving |
|---|---|
"default" |
Volledig bewerken. Blokken kunnen worden geselecteerd, verplaatst en bewerkt |
"contentOnly" |
Alleen tekst bewerken. Bloktekst kan worden bewerkt, maar instellingen en structuur zijn vergrendeld |
"disabled" |
Niet bewerken. Blokken zijn volledig niet-interactief |
Overschrijvingen per element worden ingesteld als HTML-attributen op elk element (<h1>, <p>, <div> enzovoort) of op <block>-elementen. Bovenliggende containerblokken van overschreven elementen worden automatisch ingesteld op contentOnly, zodat hun onderliggende elementen toegankelijk blijven. Deze cascade loopt vanaf het overschreven element omhoog naar de pagina-hoofdmap; u hoeft dus alleen blockEditingMode in te stellen op de elementen die u bewerkbaar wilt maken.
Templatevergrendeling
De eigenschap templateLock bepaalt hoe gebruikers de pagina in de editor kunnen bewerken:
| Waarde | Toevoegen/verwijderen | Verplaatsen | Inhoud bewerken |
|---|---|---|---|
"all" |
Nee | Nee | Nee |
"insert" |
Nee | Ja | Ja |
"contentOnly" |
Nee | Nee | Ja |
false |
Ja | Ja | Ja |
Wanneer een templateLock is ingesteld, schakelt Blockstudio de mogelijkheid uit om blokken via de editor-UI te ontgrendelen.
Virtuele routes
Sommige documenten hebben geen bericht erachter: een componentreferentie die uit gegevens is gegenereerd, een catalogus of een accountgedeelte. Registreer ze als virtuele routes in plaats van zelf template_redirect te koppelen:
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(),
]
);
} );
Het pad is relatief aan de startpagina van de site. Met prefix bedient de route ook elk pad eronder, en match ontvangt de rest (een lege string voor de route zelf) en retourneert de waarde die de rendercallback ontvangt, of null om de URL over te laten aan WordPress, die vervolgens zoals gebruikelijk antwoordt met 404. De rendercallback echoot het document of retourneert het als string; title is een string of een closure die de matchwaarde ontvangt.
Voor een overeenkomend verzoek voorkomt Blockstudio dat WordPress een 404 markeert en dat redirect_canonical het omleidt, wist de enkelvoudige status die de hoofdquery rapporteert, verstuurt de statuscode (standaard status, 200) en rendert op prioriteit Virtual_Routes::PRIORITY van template_redirect. Dat gebeurt direct nadat de uitvoerbuffer van Blockstudio wordt geopend op Assets::BUFFER_PRIORITY, zodat het voltooide document zijn blokassets, gebundelde UI-assets en gecompileerde Tailwind krijgt, en vóór redirect_canonical op prioriteit 10. Een handler die zelf een volledig document rendert, moet ook na Assets::BUFFER_PRIORITY worden uitgevoerd, anders wordt die verwerking overgeslagen. De paden in urls (standaard het routepad zelf, als het geen prefixroute is) worden toegevoegd aan builds voor statische voorweergave , en Virtual_Routes::urls() retourneert ze als absolute URL’s voor een sitemap.
Virtual_Routes::match( $path ) lost een pad op zoals een verzoek dat zou doen.
Synchronisatiegedrag
Paginaberichten veranderen alleen via een expliciete synchronisatiebewerking:
wp bs pages sync
De opdracht detecteert de volledige broninventaris, maakt gewijzigde berichten aan of werkt ze bij, verwijdert bevestigde verweesde berichten, vernieuwt de verzamelingsroutering en de gecompileerde configuratie van templateFor en rapporteert wat er is veranderd. Voeg --authoritative toe om beheerde inhoud te vervangen in plaats van inhoud van de editor met sleutels te behouden, en --full om de bewerking als een volledige afstemming te rapporteren, ongeacht de opgeslagen bronidentiteit:
wp bs pages sync --authoritative --full
Normale frontend-, beheer-, AJAX-, REST-, cron- en algemene bootstrapverzoeken van WP-CLI voeren geen volledige paginadetectie uit, raadplegen de beheerde afstemmingsinventaris niet en schrijven geen paginaberichten weg. Ze gebruiken reeds gesynchroniseerde berichten van WordPress, plus compacte configuratie voor verzamelingen en berichttype-templates die tijdens de laatste expliciete bewerking is opgeslagen. Bij een koude installatie of upgrade kunnen manifesten van verzamelingen eenmaal worden gescand om routeringsmetadata te herstellen; deze alleen-lezen bootstrap synchroniseert nooit inhoud. Het geverifieerde Canvas-vernieuwingseindpunt waarvoor u zich moet aanmelden, is een expliciete bewerking voor het maken van inhoud API: Canvas roept het eenmaal aan wanneer de werkruimte wordt geopend, zodat nieuw toegevoegde of gewijzigde bronnen in de begininventaris verschijnen. De live modus roept dezelfde grens aan wanneer een wijziging van de paginabron wordt waargenomen.
Blockstudio\Pages::init() registreert nu alleen hooks voor verzoeken. Integraties die eerder een argument force aan die methode doorgaven, moeten in plaats daarvan Blockstudio\Pages::reconcile() aanroepen of wp bs pages sync uitvoeren.
Stel "sync": false in page.json in om te voorkomen dat een pagina na handmatige wijzigingen wordt overschreven.
Draagbare bronlocaties
Gesynchroniseerde themabestanden worden opgeslagen als locaties relatief aan het thema, in plaats van als absolute installatiepaden. Bestanden van child- en parent-thema’s behouden afzonderlijke identiteiten, ook wanneer ze dezelfde relatieve bestandsnaam hebben. Paginahulpfuncties retourneren voor het huidige request nog steeds opgeloste absolute waarden voor template_path, content_path, layout_path en directory.
Zo kunnen CLI synchronisatie en webverzoeken verschillende bestandssysteemroots gebruiken, zoals bij hosting met een afgeschermde omgeving, zonder Markdown-responses, layouts, Tailwind-scans of het bijhouden van prerender-bronnen te verstoren. Bestaande absolute themapaden worden bij het lezen opnieuw gebaseerd als de naam van de themamap ongewijzigd is. Er is geen synchronisatie, databasemigratie of metadataregistratie tijdens verzoeken nodig om ze te lezen; de volgende expliciete synchronisatie slaat de draagbare locaties op.
Een themamap die een symlink is, bijvoorbeeld naar een ontwikkelcheckout, slaat dezelfde theme:-locaties op, ongeacht of een bron via de symlink of via het doel ervan is gelezen, en verwijst deze naar de geconfigureerde themamap.
Bestanden buiten de actieve child- en parentthema’s blijven ondersteund op hun geconfigureerde absolute paden, met inachtneming van de beperkingen van PHP open_basedir. Ze kunnen niet automatisch worden verplaatst: werk na het verplaatsen van een externe bron het geconfigureerde pad bij en voer een expliciete synchronisatie uit.
Eigenaarschap van berichtvelden
postStatus stelt de beginstatus in. Volgende synchronisaties behouden bestaande concept-, wachtende, privé-, gepubliceerde en geplande statussen, ook met --authoritative. Een concept wordt niet opnieuw gepubliceerd alleen omdat het bestand postStatus: "publish" vermeldt. Het bestaande gedrag voor herstel van verweesde berichten blijft ongewijzigd: een expliciete synchronisatie herstelt een naar de prullenbak verplaatst, beheerd bericht wanneer de bron aanwezig is. Vergrendel de pagina of schakel synchronisatie uit om dat herstel te voorkomen.
Het bestand blijft bepalend voor de titel, slug, het berichttype, de bovenliggende pagina en de geconfigureerde menuvolgorde. Als u deze aanpast in WordPress, verandert de brondefinitie niet. De volgende expliciete synchronisatie past de bestandswaarden opnieuw toe en vermeldt de gewijzigde velden in pages.<name>.overwritten, met een waarschuwing in de tabeluitvoer van CLI. De standaardmachtigingen van WordPress blijven gelden, waaronder de lege slug voor wachtende berichten wanneer de synchroniserende gebruiker ze niet kan publiceren.
Gebruik blockstudio/pages/update_post_data voor een integratie die expliciet een ander statusbeleid beheert. Blokken met sleutels behouden de door de editor beheerde blokinhoud; sleutels veranderen het eigenaarschap van de titel of slug van het bericht niet.
Voor verzamelingspagina’s omvatten vingerafdrukken het manifest, de lader, de paginabron, het indelingsbestand, metadata en gerelateerde bronpaden. De volgende expliciete synchronisatie verwerkt wijzigingen in deze invoer.
Wanneer een verzamelingsbron wordt verwijderd, verwijdert Blockstudio de gegenereerde pagina, zodat oude verzamelingspagina’s niet blijven staan nadat het bronbestand is verdwenen. Standaard worden verweesde verzamelingspagina’s naar de prullenbak verplaatst. Gebruik blockstudio/pages/orphan_action om trash, delete of keep te retourneren.
Bij frontendverzoeken vult Blockstudio het paginaregister met reeds gesynchroniseerde gepubliceerde berichten. Concepten en privépagina’s zijn beschikbaar in beheer- en synchronisatiecontexten, maar frontendhulpfuncties vullen het register alleen met gepubliceerde pagina’s.
Afstemming bij implementatie
Blockstudio\Pages::reconcile() is het PHP-ingangspunt voor implementaties. Het detecteert de volledige gewenste inventaris, vergelijkt vingerafdrukken van bronnen en de synchronisatie-engine en retourneert een machineleesbaar 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',
],
],
]);
Het rapport bevat discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, resultaten per pagina, ontdekkingsfouten en een deterministische sourceIdentity.
Vergrendelde pagina’s hebben status: "locked" en worden apart geteld van ongewijzigde pagina’s. removedPages vermeldt voor elke verwijderde pagina de name, key, postId en de werkelijke action (trash of delete); behouden of al naar de prullenbak verplaatste berichten tellen niet mee als nieuw verwijderd. De tabeluitvoer van CLI vermeldt ook aangemaakte, bijgewerkte, vergrendelde, verwijderde en inhoudsbehouden pagina’s met hun bericht-ID’s.
Na het parseren en samenvoegen op basis van sleutels roept een identiek eindbericht wp_update_post() niet aan, wordt post_modified niet gewijzigd, wordt er geen revisie aangemaakt en worden er geen hooks voor berichtupdates geactiveerd. Het resultaat is unchanged. Wanneer de inhoud van de bron afwijkt van de door de editor beheerde inhoud met sleutels, geeft preserved: true die keuze aan en telt de telling preserved op hoofdniveau dit mee. De nieuwe bronvingerafdruk en beheermetadata worden wel opgeslagen, zodat de volgende ongewijzigde synchronisatie niets doet.
preserved is een aanvullende vlag, geen exclusieve status: een pagina kan inhoud met sleutels behouden en tegelijk een door het bestand beheerde titel bijwerken of een ander blok toevoegen.
authoritative: true kan een vergrendeling voor paginasynchronisatie opheffen en vervangt de inhoud door de bestandsdefinitie in plaats van inhoud van de editor met sleutels te behouden. Laat deze op false staan voor een normale expliciete synchronisatie. plan_valid: false, full: true, broad: true, een ontbrekende eerdere bronidentiteit of een gewijzigde vingerafdruk van de synchronisatie-engine markeert de bewerking als een volledige afstemming (fullReconciliation in het rapport). Hoe dan ook wordt bij elke bewerking de volledige inventaris vergeleken. Hernaammeldingen van Git zijn alleen identiteitssuggesties. Ze vervangen nooit de vergelijking van de volledige inventaris.
Bij gelijke vingerafdrukken en ongewijzigde runtimepaden vinden geen wijzigingen aan berichten of postmeta plaats en worden geen updatehooks geactiveerd. Wanneer een ongewijzigde bron naar een nieuwe releasemap wordt verplaatst, vernieuwt de afstemming alleen de opgeslagen template-, inhouds-, indelings- en mappaden; post_content en de wijzigingstijd van het bericht worden niet bijgewerkt. Ontbrekende beheerde pagina’s worden pas verwijderd nadat de volledige afstemming is voltooid zonder detectie- of schrijffouten voor pagina’s.
Een directe afstemming van API markeert een implementatie niet als geslaagd. Nadat u het bijbehorende statische artefact en de routes hebt geactiveerd en gecontroleerd, slaat u de geretourneerde identiteit expliciet op:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync slaat de geretourneerde identiteit op na een geslaagde bewerking. Een gewone bootstrap van WP-CLI registreert alleen de opgeslagen berichttypen van verzamelingen en rewrites. Er worden geen pagina’s gedetecteerd of gesynchroniseerd.
Bericht-ID’s vastzetten
Standaard wijst WordPress automatisch bericht-ID’s toe. Als een pagina wordt verwijderd en opnieuw aangemaakt, verandert de ID. Daardoor werken externe verwijzingen, zoals menu’s of hardgecodeerde links, niet meer.
Gebruik postId om een specifieke ID aan een pagina toe te wijzen:
{
"name": "about",
"title": "About Us",
"postId": 42
}
Bij het aanmaken van de pagina geeft Blockstudio de ID via import_id door aan WordPress. Als de ID beschikbaar is, gebruikt WordPress deze precies. Als de ID al in gebruik is door een niet-gerelateerd bericht, wijst WordPress stilzwijgend automatisch een nieuwe ID toe.
Bij het opzoeken van bestaande pagina’s controleert Blockstudio eerst de vastgezette ID, vóór de metadata of slug. Daardoor krijgt een pagina bij verwijdering en hersynchronisatie dezelfde ID terug.
Blokken samenvoegen op basis van sleutels
Standaard vervangt Blockstudio bij een wijziging van een templatebestand de volledige berichtinhoud door de nieuwe template. Dit betekent dat wijzigingen in de editor van WordPress verloren gaan.
Voeg een key-attribuut toe aan blokken om gebruikerswijzigingen bij templatesynchronisaties te behouden. Als een template blokken met sleutels bevat, voegt Blockstudio templatewijzigingen samen met de bestaande berichtinhoud in plaats van deze te vervangen.
Sleutels toevoegen
Gebruik het attribuut key op elk HTML-element of <block>-element:
<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"
/>
Sleutels moeten uniek zijn in de hele template. Een sleutel beschermt het volledige blok en al zijn inhoud. U hoeft afzonderlijke onderliggende elementen binnen een blok met een sleutel geen eigen sleutel te geven. Blokken met sleutels kunnen tussen template-updates naar elke positie of elk nestingniveau worden verplaatst; hun gebruikersinhoud blijft behouden.
Sleutels werken op dezelfde manier voor aangepaste blokken van Blockstudio. De key is structurele metadata voor paginasynchronisatie; waarden van aangepaste velden blijven gewone Blockstudio-attributen. Wanneer een editor die velden wijzigt, behoudt een latere templatesynchronisatie de editorwaarden en worden onafhankelijke templatewijzigingen toch toegepast. Bij pagina’s die met oudere versies zijn gemaakt, wordt een sleutel die in de gegevens van aangepaste velden staat, automatisch gemigreerd bij de volgende synchronisatie.
Hoe samenvoegen werkt
Wanneer een templatebestand verandert en de pagina opnieuw wordt gesynchroniseerd:
| Blok | Gedrag |
|---|---|
| Blok met sleutel | Gebruikersinhoud en veldwaarden van Blockstudio blijven behouden. Attributen en structuur die bij de template horen, worden toegepast. |
| Blok zonder sleutel | Wordt volledig vervangen door de templateversie (hetzelfde als zonder sleutels) |
Voorbeelden
Gebruikerswijzigingen in blokken met sleutels blijven behouden:
- De template definieert
<p key="intro">Default intro.</p> - De gebruiker wijzigt de alinea in de editor in "Aangepaste introtekst."
- De ontwikkelaar werkt de template bij, voegt een nieuw blok toe en wijzigt de indeling
- Bij synchronisatie blijft "Aangepaste introtekst." in de alinea staan en wordt de nieuwe indeling toegepast
Attributen uit de template blijven van toepassing:
- De template bevat een omslagblok met
key="hero"en een attribuuturl - De ontwikkelaar wijzigt het attribuut
urlvan de omslag in een nieuwe achtergrondafbeelding - Bij synchronisatie wordt de nieuwe achtergrondafbeelding toegepast, maar blijven de inhoudswijzigingen van de gebruiker in de omslag behouden
Randgevallen
| Scenario | Gedrag |
|---|---|
| Nieuw blok met sleutel toegevoegd aan template | Verschijnt met de standaardinhoud van de template |
| Blok met sleutel verwijderd uit template | Verwijderd uit het bericht |
| Bloktype gewijzigd (zelfde sleutel) | Template krijgt volledig voorrang; er wordt niets samengevoegd |
| Dubbele sleutels | De tweede keer wordt het blok behandeld alsof het geen sleutel heeft |
| Geen sleutels in template | Volledige vervanging (hetzelfde gedrag als zonder sleutels) |
| Geforceerde synchronisatie | Volledige vervanging; sleutels worden genegeerd |
| Vergrendeld bericht | Helemaal geen synchronisatie |
Combineren met bewerkingsopties
Sleutels, templateLock en blockEditingMode bieden samen nauwkeurige controle over wat klanten wel en niet kunnen doen. Hier volgen enkele veelgebruikte werkpatronen.
Volledig vergrendelde pagina
De ontwikkelaar beheert alles. De pagina heeft een statische indeling waar klanten niets aan kunnen veranderen. Handig voor juridische pagina’s, servicevoorwaarden en andere pagina’s die alleen via code mogen worden gewijzigd.
{
"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>
Er zijn geen sleutels nodig. De template is de enige bron van waarheid. Elke synchronisatie overschrijft de hele pagina.
Vergrendelde indeling met bewerkbare inhoud
Het meestgebruikte patroon. Vergrendel de paginastructuur zodat klanten geen blokken kunnen toevoegen, verwijderen of verplaatsen, maar laat ze op bepaalde plekken wel tekst bewerken. Dankzij sleutels blijven hun wijzigingen behouden na template-updates.
{
"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>
De klant kan de titel, beschrijving en introductie van de functiesectie aanpassen. Verder niets. De knoptekst, URL en de achtergrondafbeelding van de omslag worden door de ontwikkelaar beheerd. Wanneer de ontwikkelaar de template bijwerkt (e.g., een tweede knop toevoegt), behouden secties met een sleutel de tekst van de klant.
Template uitbreiden met behoud van inhoud
Voor pagina’s die in de loop der tijd groeien. De ontwikkelaar voegt nieuwe secties toe aan de template en bij elke synchronisatie wordt de nieuwe inhoud toegevoegd zonder aan te passen wat de klant al heeft aangepast.
<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>
De nieuwe sectie met testimonials en de knop verschijnen bij synchronisatie. De aanpassingen van de klant aan de titel, introductie en diensten blijven onaangeroerd.
Eenmalige basisstructuur
Maak een pagina met een startstructuur en draag deze vervolgens volledig over. Stel sync in op false, zodat normale synchronisatie de pagina nooit maakt of bijwerkt, en maak deze één keer aan met Blockstudio\Pages::force_sync('blog'). Daarna is de pagina volledig van de klant.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
wp bs pages sync slaat deze pagina over, zodat force_sync() deze één keer aanmaakt. Daarna kan de klant blokken naar eigen inzicht toevoegen, verwijderen en verplaatsen. Templatewijzigingen worden genegeerd.
Blokbindingen
Een alternatief voor samenvoegen op basis van sleutels is de Block Bindings API van de WordPress-core, waarmee je blokken aan berichtmetadata koppelt. Dit is geen Blockstudio-functie, maar een native WordPress API. Blockstudio geeft alleen het attribuut metadata door aan de gegenereerde blokmarkup. De inhoud staat in berichtmetadata in plaats van blokmarkup. Templatesynchronisatie kan de markup daarom vrij overschrijven: de editor leest uit metadata, niet uit innerHTML.
Geef het attribuut metadata mee aan elk element HTML of <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"}}}}'
/>
De metakeys moeten zijn geregistreerd met show_in_rest ingeschakeld:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Sleutels versus bindingen
| Aspect | Sleutels | Bindingen |
|---|---|---|
| Inhoud opgeslagen in | Blokmarkup (post_content) |
Postmeta (wp_postmeta) |
| Blijft behouden bij templatesynchronisatie | Ja (samengevoegd op basis van sleutel) | Ja (gegevens staan in meta) |
Opvraagbaar via WP_Query |
Nee | Ja (meta_query) |
| Beschikbaar in REST API | Nee | Ja |
| Registratie vereist | Nee | Ja (register_post_meta) |
| Kan de gebruiker blokken verplaatsen | Nee (de template legt de structuur opnieuw op) | Nee (de template legt de structuur opnieuw op) |
Beide benaderingen kunnen in dezelfde template worden gebruikt. Gebruik sleutels voor secties waarbij de blokstructuur van belang is (e.g., een groep met meerdere onderliggende blokken). Gebruik bindingen voor afzonderlijke velden waarvan de gegevens ook buiten de blokeditor toegankelijk moeten zijn.
Templates voor berichttypen
Gebruik templateFor om een pagina in te stellen als standaardtemplate voor een berichttype:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
Nieuwe berichten van dat type beginnen met de gedefinieerde blokstructuur.
Aangepaste paden
Standaard scant Blockstudio get_template_directory() . '/pages'. Voeg extra paden toe met het filter:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
Runtime-integraties die bestanden uit meerdere hoofdmappen samenstellen, kunnen de bestandssysteemscan vervangen door een logische ontdekkingsbron. Paginamanifesten, layouts, loaders en bronbestanden van templates worden dan via een logisch pad gevonden, ook wanneer de geselecteerde bestanden in verschillende hoofdmappen staan.
Filters en acties
Paginadetectie, synchronisatie en routering van collecties bieden de volgende uitbreidingspunten:
| Hook | Type | Beschrijving |
|---|---|---|
blockstudio/pages/paths |
Filter | Voegt mappen toe waarin Blockstudio naar paginabronnen zoekt. |
blockstudio/pages/collection_post_type_args |
Filter | Past de argumenten van register_post_type() aan voor een collectie-CPT. |
blockstudio/pages/template_candidates |
Filter | Past de templatebestandsnamen aan die voor een paginabron in aanmerking komen. |
blockstudio/pages/serve_markdown |
Filter | Schakelt ruwe Markdown-responses in of uit. |
blockstudio/pages/orphan_action |
Filter | Geeft trash, delete of keep terug voor het opruimen van verweesde items. |
blockstudio/pages/docs_allowed_html |
Filter | Past de toegestane HTML aan voor gegenereerde docs-inhoud van Markdown. |
blockstudio/pages/allow_external_loader_path |
Filter | Staat loader-paths buiten de collectieroot toe. |
blockstudio/pages/manifest_scan_interval |
Filter | Stelt de maximale leeftijd in van een verouderde manifestcache van vóór 7.6.2 die bij een upgrade de opgeslagen runtimeconfiguratie mag initialiseren. |
blockstudio/pages/create_post_data |
Filter | Wijzigt berichtgegevens voordat een gesynchroniseerde pagina wordt aangemaakt. |
blockstudio/pages/update_post_data |
Filter | Wijzigt berichtgegevens voordat een gesynchroniseerde pagina wordt bijgewerkt. |
blockstudio/pages/sync_engine_inputs |
Filter | Voegt een parser-, mapping- of migratieversie toe die de reconciliatie bewust eenmalig moet uitbreiden. |
blockstudio/pages/post_created |
Action | Wordt uitgevoerd nadat een bericht voor een gesynchroniseerde pagina is aangemaakt. |
blockstudio/pages/post_updated |
Action | Wordt uitgevoerd nadat een bericht voor een gesynchroniseerde pagina is bijgewerkt. |
blockstudio/pages/synced |
Action | Wordt uitgevoerd nadat de paginaregistratie is gesynchroniseerd. |
blockstudio/pages/reconciled |
Action | Wordt uitgevoerd na een expliciete reconciliatie, met het machineleesbare rapport. |
blockstudio/pages/renderers |
Action | Registreert paginarenderers met Blockstudio\Page_Renderers::register(). Wordt eenmaal per verzoek uitgevoerd. |
blockstudio/pages/rendered |
Action | Wordt uitgevoerd nadat een componentpagina is gerenderd, met de pagina, de HTML ervan en de afhankelijkheden. |
blockstudio/pages/layout_error |
Action | Wordt uitgevoerd wanneer een layout niet kan worden gerenderd, met de fout, het layoutpad en de pagina. |
PHP API
// Get all registered pages.
$pages = Blockstudio\Pages::pages();
// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');
// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');
// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');
// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');
// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');
// Get a specific page.
$page = Blockstudio\Pages::get_page('about');
// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');
// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');
// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();
// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
]);
// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);
// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');
// Unlock a page.
Blockstudio\Pages::unlock('about');
// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
'extensions' => ['tsx'],
'layouts' => ['layout.tsx'],
'render' => 'my_theme_render_page',
]);
// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');
// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);
Zie Deploymentreconciliatie voor de semantiek van argumenten, rapportvelden en de grens voor de geverifieerde bronidentiteit.
Globale hulpfuncties zijn beschikbaar voor templates en layouts:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
Pagina-arrays die worden geretourneerd door Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() en de globale hulpfuncties bevatten de identiteit van het gesynchroniseerde bericht, bron- en templatepaden, metadata over de collectie en het pad, het inhoudstype, het synchronisatiebeleid, het berichttype en de berichtstatus, het bewerkingsbeleid, aangepaste metadata en een sleutel permalink. Collectiemetadata wordt geladen uit de laatste geslaagde expliciete reconciliatie. Normale verzoeken reconstrueren deze runtimegegevens uit de opgeslagen configuratie en de metagegevens van gesynchroniseerde berichten, zonder paginabronmappen te lezen. De Pages-klasse heeft geen afzonderlijke permalinkmethode.
Pagina’s op basis van bestanden bouwen
Templates vergrendelen, bewerkingsmodi voor blokken, samenvoegen op basis van sleutels en bepalen wat klanten kunnen aanpassen.