Gå til indhold

Sider

Sider er filbaserede skabeloner, der synkroniseres med WordPress-databasen som indlæg. Synkronisering er eksplicit: kør wp bs pages sync, eller kald Pages API, når du vil anvende kildeændringer. Indlæsning af frontend eller WordPress-administrationen udfører aldrig fuld sideidentifikation eller ændrer sideindlæg.

Sider kan defineres som en enkelt page.json-mappe, som selvstændige Markdown-filer eller som en samling med et pages.json-manifest. Samlinger er nyttige til dokumentation, vidensbaser, landingssidebiblioteker eller enhver gruppe indlejrede sider, der skal genereres fra filer.

page.json

For en side defineret med JSON skal du tilføje en page.json-konfigurationsfil:

JSON
{
  "name": "about",
  "title": "About Us",
  "slug": "about-us",
  "postType": "page",
  "postStatus": "publish",
  "templateLock": "all"
}

Egenskaber

Egenskab Type Standard Beskrivelse
name string påkrævet Unik identifikator for siden
title string Automatisk ud fra navn Sidens titel
slug string Samme som navn URL-slug for siden
path string "." Logisk sti i en samling
order integer 0 Menurækkefølge for det synkroniserede indlæg
postType string "page" WordPress-indlægstype
postStatus string "draft" Status for nye indlæg (publish, draft, pending, private)
postId integer – Fastgør siden til et bestemt WordPress-indlægs-id
blockEditingMode string – Blokredigeringstilstand: "default", "contentOnly" eller "disabled"
templateLock string|false "all" Låsetilstand: "all", "insert", "contentOnly" eller false
templateFor string|null null Angiv som standardskabelon for en indlægstype
sync boolean true Om almindelig eksplicit afstemning må oprette eller opdatere indlægget
render string|object|false – Gengiv siden med en registreret sidegengiver (se Komponentsider)

På tværs af page.json, frontmatter og loaderposter omfatter de genkendte nøgler blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock og title. Enhver nøgle, der ikke er angivet ovenfor, gemmes i sidens meta-array.

Indholdskilder

En sidedefinition afgør, hvilket WordPress-indlæg der skal findes. Indholdskilden afgør, hvilken markup for blokke der skrives til indlægget.

Når en sidemappe har en page.json, søger Blockstudio efter en tilhørende kildefil i denne rækkefølge:

Fil Anvendelse
index.php Blokmarkup i stil med HTML, læses som den er (PHP-kode udføres ikke)
index.blade.php Blade-skabelonindhold
index.twig Twig-skabelonindhold
index.md Markdown-indhold

page.json kan også indeholde inline markdown eller html i stedet for en tilhørende fil:

JSON
{
  "name": "intro",
  "title": "Intro",
  "markdown": "# Intro\n\nThis page is generated from inline markdown."
}
JSON
{
  "name": "notice",
  "title": "Notice",
  "html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}

Samlinger tilføjer to andre kildetilstande:

  • Markdown-filer, der findes direkte i samlingens mappetræ.
  • Loader-poster returneret fra loader.php.

Loader-poster kan bruge markdown, html eller content sammen med contentType. De kan også pege på en lokal file eller template. Fil- og skabelonkilder udleder typen fra filtypen, medmindre contentType angives eksplicit.

Understøttede værdier for contentType er php, blade, twig, markdown og html. Markdown konverteres først til HTML og fortolkes derefter til native WordPress-blokke. Kilderne PHP, Blade, Twig og HTML går gennem den almindelige Blockstudio-sideparser.

Klasser på kerneblokke

En class på et element af typen HTML, der er knyttet til en kerneblok, bliver dens className. Et eksplicit kernebloktag kan bruge className direkte. Begge former bevarer klasserne på blokkens gemte wrapper sammen med de klasser, som WordPress genererer:

HTML
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
  <h2 class="title">Feature</h2>
</block>

Hvis begge egenskaber er til stede, har className forrang. Denne konvertering gælder kun for kerneblokke: En tilknytning til en brugerdefineret blok bevarer dens class-felt uændret. Knapstilklasser som is-style-outline hører til knappens wrapper, ikke dens link.

Kør wp bs pages sync for at anvende parserrettelser på tidligere synkroniserede sider. Parseropgraderinger registreres ved den næste eksplicitte synkronisering uden ændringer i kildefilen. Låste sider og sider med sync: false bevarer deres normale beskyttelse; frontend-anmodninger udfører aldrig denne synkronisering.

Serialiserede WordPress-blokke

Side- og mønsterkilder kan også indeholde serialiserede blokke kopieret fra WordPress-kodeeditoren:

HTML
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->

Når kilden indeholder en <!-- wp:... --> blokafgrænser, bruger Blockstudio WordPresss indbyggede blokparser til hele kilden. Attributter, indlejrede blokke, dynamiske blokke som Query Loop og Blockstudio-blokke bevarer deres serialiserede struktur. HTML uden for blokkommentarerne forbliver native fritstående HTML; det mappes ikke til yderligere blokke. Bland ikke Blockstudios HTML-bloktags med dette format, hvis du forventer, at de bliver konverteret. Almindelige HTML-kommentarer aktiverer ikke serialiseret bloktilstand.

Markdown-sider

Brug Markdown, når tekst skal ligge i filer, men stadig blive til redigerbart WordPress-blokindhold efter synkronisering. Markdown-kilden konverteres til blokmarkup under synkronisering. Det synkroniserede indlæg gemmer blokke, ikke den rå Markdown-tekst.

Markdown kan bruges på tre måder:

Kilde Frontmatter påkrævet? Bemærkninger
Selvstændig pages/example/index.md Ja Frontmatter angiver sidens identitet.
page.json plus index.md Nej page.json definerer siden, og Markdown leverer indholdet.
Markdown i en samling Nej Samlingen udleder name og path ud fra filens placering.

En selvstændig index.md uden frontmatter springes over, fordi Blockstudio ikke har nogen sideidentitet at synkronisere. Samlings-Markdown kræver ikke frontmatter, fordi samlingens manifest og filsti angiver identiteten.

Markdown
---
name: about
title: About
slug: about
postStatus: publish
---

# About

This Markdown content is synced as native WordPress blocks.

Du kan også kombinere page.json med index.md. I så fald definerer page.json siden, og index.md leverer indholdet. Frontmatter i index.md tilsidesætter matchende værdier i page.json.

JSON
{
  "name": "docs-reference",
  "title": "Reference",
  "path": "reference",
  "sync": true
}
Markdown
---
title: API Reference
order: 20
---

# Reference

This page uses `page.json` with Markdown content.

For samlings-Markdown bliver filstien sidens logiske sti, medmindre frontmatter tilsidesætter den:

Fil Standardsti
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

Ukendte frontmatter-nøgler bevares i sidens meta-array. Det gør det muligt at tilknytte data som section eller description og læse dem fra PHP API.

Markdown fortolkes som GitHub-flavored Markdown. Rå HTML er tilladt, usikre links fjernes, og overskrifter uden et eksplicit ID får et stabilt ID. Indlejret YAML-frontmatter kræver den medfølgende YAML-parser.

Rå Markdown

Markdown-kildefiler kan stille deres oprindelige kilde-Markdown til rådighed for eksterne værktøjer og dokumentationsforbrugere. Inline Markdown har ingen kildefil, så det synkroniseres til blokke, men giver ikke et råt .md-svar.

Anmod om siden med suffikset .md, f.eks. https://example.com/docs/reference.md. Eller send en Accept: text/markdown-header til sidens normale URL:

Shell
curl -H "Accept: text/markdown" https://example.com/docs/reference/

Frontmatter fjernes fra svaret. Vellykkede rå Markdown-svar sender Content-Type: text/markdown, X-Robots-Tag: noindex og en kanonisk Link-header tilbage til HTML-siden. Manglende .md-ruter returnerer en reel 404.

Forhandlingen fungerer sammen med statisk forhåndsrendering: En anmodning, hvis Accept-header indeholder text/markdown, besvares aldrig fra forhåndsrenderingslageret eller det tidlige serve drop-in, så den når frem til WordPress og Markdown-handleren. Forhåndsrend­erede HTML-svar, HTML for en side, der også forhandler Markdown, og Markdown, der besvares via Accept, sender Vary: Accept, så caches, der respekterer Vary, holder de to adskilt. En CDN, der kun baserer sin cache på URL, skal have sin egen regel for at omgå cachen for sådanne anmodninger. Pages::negotiates_markdown( $post_id ) rapporterer, om en side besvarer Markdown-anmodninger.

Samlings-Markdown bevarer samme URL-format for rå Markdown:

Side-URL Rå Markdown-URL
/docs/ /docs.md
/docs/getting-started/ /docs/getting-started.md
/docs/guide/install/ /docs/guide/install.md

Deaktivér rå Markdown-svar med filteret blockstudio/pages/serve_markdown:

PHP
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );

En .md-URL, der ikke finder en Markdown-baseret side, returnerer kun en 404, hvis stien ligger i en sidekollektion. Uden for alle kollektioner lader Blockstudio anmodningen være, så WordPress og andre plugins kan håndtere den.

Komponentsider

En komponentside gengives af en sidegengiver i stedet for at blive gemt som blokke. Blockstudio leveres ikke med en gengiver. Et tema eller plugin registrerer en for de entryfiler, det håndterer, såsom en React-gengiver for page.tsx, og Blockstudio kalder den med siden, WordPress-indlægget og det gengivne slotindhold.

Text
pages/legal-notice/
  page.json
  page.tsx
  data.php
JSON
{
  "name": "legal-notice",
  "title": "Legal Notice",
  "slug": "legal-notice",
  "postStatus": "publish",
  "render": { "entry": "page.tsx", "data": "data.php" }
}

render er eksplicit. En mappe med en index.php og en page.tsx, men uden render, forbliver en almindelig side, så tilføjelse af en gengiver gengiver aldrig en eksisterende side to gange. Formerne er:

Værdi Betydning
"page.tsx" Kun entry, uden dataloader
{ "entry": "page.tsx", "data": "data.php" } Entry og dataloader
{ "entry": "page.tsx", "renderer": "react" } Entry med et eksplicit gengiver-id
false Ingen gengiver, selv når en samlingsstandard angiver en

Stier løses i forhold til sidens mappe eller i forhold til samlingens rod for loaderposter. De skal forblive inden for discoverykilden, medmindre blockstudio/pages/allow_external_loader_path tillader dem. Uden renderer bruges den gengiver, der gør krav på entryens filtypenavn. En render, der angiver en manglende entry- eller datafil, en ukendt gengiver eller et filtypenavn, som ingen gengiver gør krav på, er en discoveryfejl, der afbryder afstemningen, før noget fjernes.

Hvad synkronisering gemmer

Synkronisering gemmer én blockstudio/page-blok. Når sidemappen også har en index.*-kilde, fortolkes den som enhver anden sidekilde og bliver til blokkens indre blokke, dens slot:

HTML
<!-- wp:blockstudio/page /-->

<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->

Behold indhold ejet af WordPress, såsom shortcodes, i slottet. En kilde, der kun består af én shortcode, såsom [download_checkout], gemmes som en core/shortcode-blok, så dens output ikke får et afsnit omkring sig. Den forbliver i post_content, så has_shortcode()-kontrollerne kan se den, nøglede slotblokke flettes med editorændringer ligesom indlejrede nøglede blokke, og do_shortcode udvider shortcodes én gang med sin sædvanlige prioritet på the_content efter at gengiveren har indrammet dem.

Gengivelsesdefinitionen gemmes sammen med indlægget som portable theme:-stier. Sidens fingeraftryk dækker definitionen, ikke bytes fra entryen eller dataloaderen: redigering af page.tsx eller data.php lader indlægget være uændret og når besøgende gennem gengivelse og statisk forhåndsgengivelsesgraf, som registrerer entryen, dataloaderen og hver fil, gengiveren rapporterer.

Registrering af en gengiver

Registrer gengivere på handlingen blockstudio/pages/renderers. Den udløses én gang pr. anmodning, før den første discovery eller gengivelse, så wp bs pages sync– og frontend-anmodninger ser det samme register.

PHP
add_action(
	'blockstudio/pages/renderers',
	static function (): void {
		Blockstudio\Page_Renderers::register(
			'react',
			array(
				'extensions' => array( 'tsx' ),
				'layouts'    => array( 'layout.tsx' ),
				'render'     => 'my_theme_render_page',
			)
		);
	}
);

Gengiver-id’er skrives med små bogstaver. Et filtypenavn eller layoutnavn kan kun tilhøre én gengiver, og layout.php forbliver Blockstudios eget layout. Den kaldbare funktion modtager én anmodning:

Nøgle Værdi
kind page eller layout for et layout for gengiver
renderer Gengiver-id
entry Absolut entrysti
data Absolut sti til dataloader eller null
page Kanoniske sidedata, inklusive meta
post_id WordPress-indlægs-id
slot Gengivet slotindhold eller sidens indhold for et layout
context frontend, rest, feed eller cli

Den returnerer HTML, de filer gengivelsen læste og valgfrie aktiver:

PHP
function my_theme_render_page( array $request ): array {
	return array(
		'html'         => '<main>...</main>',
		'dependencies' => array( '/abs/path/to/a/file/the/render/read.tsx' ),
		'assets'       => array( array( 'path' => '/abs/path/to/page.js' ) ),
	);
}

context stammer fra anmodningstypen og aldrig fra den besøgende, så en renderer kan ikke bryde bytepariteten mellem indloggede og anonyme brugere ved at læse den. Hvis en renderer fejler, kastes der en fejl: siden gengives ikke med en tom body. I en REST-editorvisning viser blokken i stedet fejlen som en meddelelse. Efter en vellykket gengivelse modtager handlingen blockstudio/pages/rendered siden, HTML og dens afhængigheder.

assets angiver de script- og stilfiler, siden har brug for. De behandles som block-assets (konventionen *.inline.*, ES-moduler, minificering og ?ver), og siden udskriver dem én gang via samme buffer som block-assets, så en præ-renderet side indeholder dem. Et asset kan angive version for at erstatte sin værdi ?ver. Kode uden for en renderer kan bruge samme kanal via Blockstudio\Assets::register_owner(), som returnerer markørkommentaren, der skal udskrives.

Editor

I editoren viser blockstudio/page en server-renderet forhåndsvisning af siden med slotten som indre blokke, der følger sidens templateLock. Blokken kan ikke indsættes, duplikeres eller indlejres i en anden blok.

Sidekollektioner

En kollektion er en mappe med et pages.json-manifest. Den samler mange sidekilder under én kollektionsslug, anvender standardindstillinger, understøtter indlejrede stier og kan automatisk registrere en dedikeret indlægstype.

Kode
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
    loader.php
JSON
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "postTypeArgs": {
    "label": "Docs",
    "rewrite": {
      "slug": "docs"
    },
    "supports": ["title", "editor", "page-attributes"]
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}
Egenskab Type Beskrivelse
collection / slug / name string Samlingsslug. collection er den tydeligste form og bliver basis for den offentlige URL.
title string Menneskeligt læsbar samlingstitel.
postType string Indlægstype for genererede sider. Standard er page. Hvis den ikke findes, registrerer Blockstudio den.
postTypeArgs object Argumenter, der gives til register_post_type(), når Blockstudio registrerer samlingens indlægstype.
defaults object Standardegenskaber for sider, der anvendes på hver side i samlingen. En standard-render anvendes kun på en side, hvis dens post findes i sidemappen.
scope string collection (standard) eller site. Se Webstedssamlinger.
meta object Brugerdefinerede samlingsmetadata. Ukendte manifestnøgler gemmes også i meta.

Sidestier i kollektioner er logiske stier. En side med path: "guide/install" synkroniseres som underside af guide, og guide synkroniseres som underside af kollektionens rod, hvis disse overordnede sider findes.

Hvis en hierarkisk kollektion har en indlejret side, men der ikke findes nogen kilde til en mellemliggende overordnet side, genererer Blockstudio en tom containerside for den sti, så WordPress-hierarkiet forbliver komplet. Indlægstyper, der ikke er hierarkiske (og som ikke understøtter page-attributes-forældre), genererer ikke tomme containere. De dirigerer efter den gemte kollektionssti, så indlejrede stier som guide/install og setup/install kan eksistere side om side, selvom begge slutter med install.

Kollektionens indlægstyper og URL’er

Angiv postType i kollektionens manifest for at synkronisere alle sider i kollektionen til den indlægstype. Du behøver ikke gentage den samme værdi i defaults. Enkeltsider kan stadig tilsidesætte postType i frontmatter eller page.json.

Hvis indlægstypen ikke findes, registrerer Blockstudio den med show_in_rest: true, en editoropsætning, der minder om sider, og kollektionsslugen som offentlig URL-basis. postTypeArgs kan tilsidesætte registreringsargumenterne. Omskrivningsregler for kollektionens indlægstype genindlæses automatisk, når de registrerede kollektionsindlægstyper eller omskrivningsargumenter ændres, så du ikke behøver at gemme permalinks for WordPress igen.

URL’er for kollektioner bruger kollektionsslugen efterfulgt af hver sides logiske path:

Kildesti Offentlig URL
path: "." /docs/
path: "getting-started" /docs/getting-started/
path: "guide/install" /docs/guide/install/

Denne URL-model fungerer for både hierarkiske og ikke-hierarkiske samlingsindlægstyper. Blockstudio omdirigerer også dobbelte URL’er som /docs/docs/ eller /docs/docs/getting-started/ til den kanoniske URL.

Samlingssider viser rå Markdown på de samme URL’er (se Rå Markdown).

Hvis du ændrer en samling fra postType: "page" til en brugerdefineret indlægstype, migrerer Blockstudio allerede synkroniserede samlingsindlæg på stedet, når deres gemte sideidentitet matcher. Det bevarer indlægs-id’er, metadata og eksisterende indhold og undgår samtidig dublerede indlæg med den gamle type. Forældede samlingsindlæg ryddes op på tværs af alle indlægsstatuser i henhold til filteret blockstudio/pages/orphan_action.

Webstedssamlinger

Et manifest med "scope": "site" grupperer alle sider under sig uden at gøre dem til samlingssider. Brug det i roden af et websteds sidetræ for at anvende fælles standardværdier og vise webstedets sider med blockstudio_page_tree( 'my-site' ).

JSON
{
  "collection": "my-site",
  "title": "My Site",
  "scope": "site",
  "defaults": {
    "postStatus": "publish",
    "templateLock": "all",
    "render": { "entry": "page.tsx", "data": "data.php" }
  }
}

Sider i en webstedssamling bevarer præcis den identitet, de har uden manifestet. Når en side føjes til et eksisterende træ, opdateres der derfor ingen indlægsrækker, og intet oprettes eller flyttes til papirkurven:

  • Nøgler forbliver globale: Pages::get_page( 'home' ) og gemte sidekeys bliver ved med at stemme overens.
  • URL’er forbliver WordPress-side-URL’er. Der anvendes ingen omskrivningsregler for samlinger, permalinkfiltre eller omdirigeringer med dobbelt-URL, og der genereres ingen tomme containersider.
  • Logiske stier, slugs, overordnede sider og kildeidentiteter er de samme som for selvstændige sider, og layouts findes via den nærmeste overordnede side.
  • Indlejrede pages.json-manifester bevarer deres egne samlinger, og deres undertræer udelades fra webstedssamlingen.
  • Standardværdier anvendes pr. side: En standard-render anvendes kun på sider, hvis post findes i mappen, så sider med shortcodes og Markdown bevarer deres kilder.

Samlingsindlæsere

Samlinger kan omfatte en betroet lokal loader.php. Brug den, når samlingssider kommer fra en anden lokal kilde, f.eks. en ekstern dokumentationsmappe, en pakke eller et genereret manifest.

Indlæseren køres under eksplicit sideopdagelse og synkronisering. Den bør være deterministisk og lokal. Undgå at hente fjernindhold fra loader.php, da det ville gøre synkronisering ved udrulning afhængig af den tjeneste.

PHP
<?php

return array(
  'meta' => array(
    'source' => 'loader',
  ),
  'paths' => array(
    __DIR__ . '/external-docs',
    array(
      'path' => __DIR__ . '/cli-docs',
      'prefix' => 'cli',
      'meta' => array(
        'doc_set' => 'cli',
      ),
    ),
  ),
  'pages' => array(
    array(
      'name' => 'docs-api',
      'title' => 'API',
      'path' => 'api',
      'content' => "# API\n\nGenerated markdown content.",
      'contentType' => 'markdown',
    ),
    array(
      'name' => 'docs-template',
      'title' => 'Template',
      'path' => 'template',
      'file' => __DIR__ . '/template.md',
    ),
  ),
);

En indlæser kan returnere et array med nøglerne pages, meta og paths:

Nøgle Beskrivelse
pages En liste over sidearrays. Hver side understøtter de samme genkendte nøgler som page.json– og Markdown-frontmatter.
meta Metadata, der flettes ind i meta-arrayet for hver loader-genereret side.
paths Ekstra lokale mapper, der skal søges efter som en del af samlingen. Poster kan være strenge eller stiobjekter.
render En renderingsdefinition for hver Markdown-side, der findes ud fra paths.

Som en genvej kan indlæseren returnere en simpel liste over side-arrays.

Sideelementer fra indlæseren kan angive indhold på følgende måder:

Form Beskrivelse
markdown Indlejret Markdown-indhold.
html Indlejret HTML-indhold.
content + contentType Generisk indlejret indhold. contentType skal løses til markdown eller html.
file Lokal filkilde. Typen udledes af filtypenavnet, medmindre contentType er angivet.
template Alias for file.

Filreferencer fra indlæseren kan pege på kilder af typen PHP, Blade, Twig, Markdown eller HTML. Relative stier løses fra samlingens rodmappe. Absolutte stier og stier uden for samlingens rodmappe er kun tilladt, hvis filteret blockstudio/pages/allow_external_loader_path tillader dem.

Sider fra indlæsere har som standard generated: true. Når en genereret side fra en indlæser forsvinder fra indlæserens output, behandler Blockstudio det synkroniserede indlæg som forældreløst ved næste synkronisering og rydder det op i henhold til filteret blockstudio/pages/orphan_action.

Mapper angivet i paths opdages som almindelige samlingsmapper. De kan indeholde Markdown-filer eller page.json-mapper. Hvis disse stier ligger uden for samlingens rodmappe, gælder det samme filter for eksterne stier.

Brug en streng, hvis den eksterne mappe skal beholde sine egne logiske stier. Brug et objekt, hvis mappen skal monteres under et stipræfiks i samlingen:

PHP
'paths' => array(
  array(
    'path' => __DIR__ . '/cli-docs',
    'prefix' => 'cli',
    'meta' => array(
      'doc_set' => 'cli',
    ),
  ),
),

Med denne konfiguration bliver cli-docs/index.md til path: "cli", og cli-docs/getting-started.md bliver til path: "cli/getting-started" i samlingen. Præfikser forhindrer også navnekollisioner for genererede sider, så flere monterede mapper hver især kan indeholde index.md eller getting-started.md. Sæt preserveNames til true på stiobjektet, hvis eksplicitte name-værdier fra frontmatter i page.json eller Markdown skal bevares i stedet.

Egenskaber for stiobjekter:

Egenskab Type Beskrivelse
path string Lokal mappe, der skal søges efter. Relative stier fortolkes ud fra samlingens rod.
prefix string Valgfrit logisk stipræfiks i samlingen.
preserveNames boolean Bevar eksplicitte sidenavne i stedet for at generere navne fra den præfikserede sti. Standard er false, når prefix er angivet.
meta object Metadata, der flettes ind i hver side, der findes via denne sti. Sidemetadata vinder ved identiske nøgler.
render string|object En renderingsdefinition for denne stis Markdown-sider, som tilsidesætter loaderens render.

Gengivelse af Markdown via en komponent

Med render gengives de Markdown-sider, som en loader finder, via en siderenderer i stedet for at blive gemt som blokke:

PHP
<?php

return array(
  'paths'  => array( __DIR__ . '/external-docs' ),
  'render' => array(
    'entry' => __DIR__ . '/document.tsx',
    'data'  => __DIR__ . '/document.php',
  ),
);

De forbliver Markdown-sider: indholdstypen, indholdsstien, .md-svarene og frontmatter forbliver uændrede. Synkroniseringen gemmer én blockstudio/page-blok, hvis indre HTML er det konverterede Markdown, renset hvis samlingen renser sit indhold, i stedet for fortolkede blokke, så post_content bevarer dokumentteksten. Rendereren modtager dette HTML som slot og kan læse kilden fra page.content_path. Relative stier fortolkes ud fra samlingens rod; det eksterne stipræfiksfilter anvendes som for stierne. En side, hvis frontmatter angiver sin egen render eller render: false, udelades.

Layouts

En layout.php-fil omslutter frontend-renderingen af en filbaseret side. Den erstatter ikke det synkroniserede post_content, der er gemt i WordPress, og den omslutter ikke editorens lærred. Layoutet køres kun ved frontendforespørgsler for enkeltsider.

For samlinger skal du placere layout.php ved siden af pages.json for at omslutte alle frontend-sider i samlingen:

PHP
<?php $current = blockstudio_current_page(); ?>

<main class="docs-layout">
  <aside>
    <?php foreach (blockstudio_page_tree('docs') as $item) : ?>
      <?php $is_current = ($item['post_id'] ?? null) === ($current['post_id'] ?? null); ?>
      <a
        href="<?php echo esc_url($item['permalink'] ?? '#'); ?>"
        <?php echo $is_current ? 'aria-current="page"' : ''; ?>
      >
        <?php echo esc_html($item['title']); ?>
      </a>
    <?php endforeach; ?>
  </aside>

  <article>
    <?php echo blockstudio_page_content(); ?>
  </article>
</main>

blockstudio_page_content() udskriver sidens indhold, som WordPress normalt ville gengive via the_content. Hvis et layout ikke udskriver blockstudio_page_content(), skjules sidens indhold med vilje.

Layouts kan bruge sidens hjælpefunktioner:

PHP
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();

Indlejrede sider, der ikke tilhører en samling, kan også arve det nærmeste overordnede layout.php i træet pages. For samlingssider gemmes samlingens rodlayout på hvert synkroniseret indlæg og overvåges som en del af sidens fingeraftryk, så layoutændringer registreres ved næste synkronisering.

Renderer-layouts

Et layout kan også være en rendererpost, f.eks. layout.tsx for en renderer, der registrerer layouts: ["layout.tsx"]. Den findes de samme steder som layout.php, og en valgfri layout.data.php ved siden af den fungerer som dens dataloader. Ved gengivelsen modtager rendereren kind: "layout" og det gengivne sideindhold som slot med samme the_content-prioritet som layout.php. En mappe kan indeholde layout.php eller ét renderer-layout, men ikke begge dele; hvis den indeholder begge, opstår der en fejl under søgningen. En layoutfejl udløser blockstudio/pages/layout_error og efterlader sideindholdet uden indpakning, ligesom det sker for layout.php.

Redigeringstilstand for blokke

Egenskaben blockEditingMode styrer, hvordan blokke kan redigeres i editoren. Angiv en standardværdi på sideniveau i page.json, og tilsidesæt den for hvert element i skabelonen:

JSON
{
  "name": "about",
  "title": "About Us",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>
Værdi Beskrivelse
"default" Fuld redigering. Blokke kan vælges, flyttes og redigeres
"contentOnly" Kun tekstredigering. Bloktekst kan redigeres, men indstillinger og struktur er låst
"disabled" Ingen redigering. Blokke er helt uden interaktion

Tilsidesættelser pr. element angives som attributter HTML på ethvert element (<h1>, <p>, <div> osv.) eller på <block>-elementer. Overordnede containerblokke for tilsidesatte elementer sættes automatisk til contentOnly, så deres underordnede elementer forbliver tilgængelige. Denne nedarvning går fra det tilsidesatte element op til sidens rod, så du behøver kun at angive blockEditingMode på de elementer, du vil gøre redigerbare.

Skabelonlås

Egenskaben templateLock styrer, hvordan brugere kan redigere siden i editoren:

Værdi Tilføj/fjern Flyt Rediger indhold
"all" Nej Nej Nej
"insert" Nej Ja Ja
"contentOnly" Nej Nej Ja
false Ja Ja Ja

Når en templateLock er angivet, deaktiverer Blockstudio muligheden for at låse blokke op via editorens UI.

Virtuelle ruter

Nogle dokumenter har intet indlæg bag sig: en komponentreference genereret fra data, et katalog eller et kontoområde. Registrer dem som virtuelle ruter i stedet for selv at tilkoble template_redirect:

PHP
add_action( 'init', function () {
    Blockstudio\Virtual_Routes::register(
        'components',
        function ( $component, string $rest ) {
            get_header();
            echo my_component_page( $component );
            get_footer();
        },
        [
            'prefix' => true,
            'match'  => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
            'title'  => fn ( $component ) => my_component_title( $component ),
            'urls'   => fn () => my_component_paths(),
        ]
    );
} );

Stien er relativ til webstedets startside. Med prefix betjener ruten også alle stier nedenunder, og match modtager resten (en tom streng for selve ruten) og returnerer den værdi, som renderingscallbacken modtager, eller null for at lade URL gå videre til WordPress, som derefter svarer med 404 som normalt. Renderingscallbacken udskriver dokumentet eller returnerer det som en streng; title er en streng eller en closure, der modtager matchværdien.

For en anmodning, der matcher, forhindrer Blockstudio WordPress i at markere en 404 og redirect_canonical i at omdirigere den, rydder den entydige tilstand, som hovedforespørgslen rapporterer, sender status (status, 200 som standard) og renderer med template_redirect-prioritet Virtual_Routes::PRIORITY. Det sker lige efter, at Blockstudios outputbuffer åbnes ved Assets::BUFFER_PRIORITY, så det færdige dokument får sine blokaktiver, bundtede UI-aktiver og kompilerede Tailwind som enhver anden side, og før redirect_canonical ved prioritet 10. En handler, der selv renderer et helt dokument, skal også køre efter Assets::BUFFER_PRIORITY, ellers springes denne behandling over. Stierne i urls (som standard selve rutestien, når den ikke er en præfikssrute) føjes til builds med statisk prerendering, og Virtual_Routes::urls() returnerer dem som absolutte URL’er til et sitemap. Virtual_Routes::match( $path ) finder en sti på samme måde som en anmodning ville gøre.

Synkroniseringsadfærd

Sideindlæg ændres kun gennem en eksplicit synkroniseringshandling:

Shell
wp bs pages sync

Kommandoen finder hele kildeinventaret, opretter eller opdaterer ændrede indlæg, fjerner bekræftede forældreløse elementer, opdaterer samlingsrouting og kompileret templateFor-konfiguration og rapporterer ændringerne. Tilføj --authoritative for at erstatte administreret indhold i stedet for at bevare nøglebaseret editorindhold, og --full for at rapportere kørslen som en fuld afstemning uanset den gemte kildeidentitet:

Shell
wp bs pages sync --authoritative --full

Almindelige frontend-, admin-, AJAX-, REST-, cron- og generiske opstartsforespørgsler for WP-CLI finder ikke alle sider, forespørger ikke på inventaret til administreret afstemning og skriver ikke sideindlæg. De bruger allerede synkroniserede indlæg af typen WordPress samt kompakt konfiguration for samlinger og indlægsskabeloner, som er gemt af den seneste eksplicitte handling. En ny installation eller opgradering kan gennemgå samlingsmanifestfiler én gang for at gendanne routingmetadata; denne skrivebeskyttede opstart synkroniserer aldrig indhold. Det godkendte, valgfrie Canvas-opdateringsendepunkt er en eksplicit API til redigering: Canvas kalder det én gang, når arbejdsområdet åbnes, så nye eller ændrede kilder vises i startinventaret. Live-tilstand kalder den samme grænse, når den registrerer en ændring i sidekilden.

Blockstudio\Pages::init() registrerer nu kun hooks ved forespørgselstidspunktet. Integrationer, der tidligere sendte et argument af typen force til denne metode, skal i stedet kalde Blockstudio\Pages::reconcile() eller køre wp bs pages sync.

For at forhindre, at en side overskrives efter manuelle redigeringer, skal du angive "sync": false i page.json.

Flytbare kildeplaceringer

Synkroniserede temafiler gemmes som placeringer relative til temaet i stedet for som absolutte installationsstier. Filer i undertemaet og overordnet tema bevarer separate identiteter, selv når de har samme relative filnavn. Sidehjælpere returnerer stadig opløste absolutte værdier for template_path, content_path, layout_path og directory for den aktuelle anmodning.

Det betyder, at CLI-synkronisering og webanmodninger kan bruge forskellige filsystemrødder, som på hosting med jail, uden at ødelægge Markdown-svar, layouts, scanning af editoren Tailwind eller sporing af prerender-kilder. Eksisterende absolutte temastier tilpasses ved læsning, når temanavnet på mappen er uændret. Det er ikke nødvendigt at synkronisere, migrere databasen eller skrive metadata ved anmodninger for at læse dem; den næste eksplicitte synkronisering gemmer de flytbare placeringer.

En temamappe, der er et symlink, for eksempel til en udviklingscheckout, gemmer de samme theme:-placeringer, uanset om en kilde blev læst via symlinket eller dets mål, og løser dem til den konfigurerede temamappe.

Filer uden for de aktive undertemaer og overordnede temaer understøttes fortsat på deres konfigurerede absolutte stier, underlagt begrænsningerne i PHPs open_basedir. De kan ikke flyttes automatisk: Opdatér den konfigurerede sti, og kør en eksplicit synkronisering, når en ekstern kilde flyttes.

Ejerskab af indlægsfelter

postStatus angiver den indledende status. Efterfølgende synkroniseringer bevarer eksisterende kladde-, afventende, private, publicerede og planlagte statuser, også med --authoritative. En kladde publiceres ikke igen, blot fordi dens fil angiver postStatus: "publish". Den eksisterende adfærd for gendannelse af forældreløse indlæg er uændret: En eksplicit synkronisering gendanner et slettet administreret indlæg, hvis dets kilde stadig findes. Lås siden, eller deaktivér synkronisering for at forhindre gendannelsen.

Filen ejer fortsat titlen, sluggen, indlægstypen, den overordnede side og den konfigurerede menurækkefølge. Redigering af disse i WordPress ændrer ikke kildedefinitionen. Den næste eksplicitte synkronisering anvender filens værdier igen og angiver de berørte felter i pages.<name>.overwritten med en advarsel i CLI-tabeloutputtet. WordPresss oprindelige tilladelser gælder stadig, herunder en tom slug for afventende indlæg, når den synkroniserende bruger ikke kan publicere dem.

Brug blockstudio/pages/update_post_data til en integration, der udtrykkeligt har en anden statuspolitik. Nøglebaserede blokke bevarer indholdet, som editoren ejer; nøgler ændrer ikke ejerskabet af indlæggets titel eller slug.

For samlingssider omfatter fingeraftryk manifestet, indlæseren, sidekilden, layoutfilen, metadataene og relaterede kildestier. Den næste eksplicitte synkronisering anvender ændringer i disse input.

Når en samlingskilde fjernes, fjerner Blockstudio den genererede side, så gamle samlingssider ikke bliver liggende, efter at kildefilen er væk. Forældreløse samlingssider flyttes som standard til papirkurven. Brug blockstudio/pages/orphan_action for at returnere trash, delete eller keep.

Ved frontendforespørgsler indlæser Blockstudio sideregistret fra allerede synkroniserede, publicerede indlæg. Kladder og private sider er tilgængelige i admin- og synkroniseringskontekster, men frontend-hjælpefunktioner indlæser kun publicerede sider.

Afstemning ved udrulning

Blockstudio\Pages::reconcile() er indgangspunktet for udrulning af PHP. Det finder hele det ønskede inventar, sammenligner kilde- og synkroniseringsmotorens fingeraftryk og returnerer en maskinlæsbar rapport:

PHP
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
  'renames' => [
    [
      'from' => 'pages/old/index.php',
      'to' => 'pages/new/index.php',
    ],
  ],
]);

Rapporten indeholder discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, resultater for hver side, opdagelsesfejl og en deterministisk sourceIdentity.

Låste sider har status: "locked" og tælles særskilt fra uændrede sider. removedPages viser hver fjernet sides name, key, postId og faktiske action (trash eller delete); bevarede eller allerede slettede indlæg tælles ikke som nyfjernede. CLI-tabeloutputtet angiver også oprettede, opdaterede, låste, fjernede og indholdsbevarede sider med deres indlægs-id’er.

Efter parsing og nøglebaseret sammenfletning kalder et identisk endeligt indlæg ikke wp_update_post(), ændrer ikke post_modified, opretter ingen revision og udløser ingen hooks til opdatering af indlæg. Resultatet er unchanged. Når kildens indhold afviger fra det nøglebaserede indhold, som editoren ejer, angiver preserved: true denne beslutning, og det øverste preserved-antal inkluderer det. Det nye kildefingeraftryk og administrerede metadata registreres stadig, så den næste uændrede synkronisering ikke foretager sig noget. preserved er et ekstra flag, ikke en eksklusiv status: En side kan bevare nøglebaseret indhold og samtidig opdatere en filejet titel eller tilføje en anden blok.

authoritative: true kan rydde en Page Sync-lås og erstatter indholdet med fild definition i stedet for at bevare nøglebaseret editorindhold. Lad den være false ved en normal, eksplicit synkronisering. plan_valid: false, full: true, broad: true, en manglende tidligere kildeidentitet eller et ændret fingeraftryk for synkroniseringsmotoren markerer kørslen som en fuld afstemning (fullReconciliation i rapporten). Hver kørsel sammenligner hele inventaret uanset hvad. Git-omdøbningsposter er kun identitetshenvisninger. De erstatter aldrig sammenligningen af hele inventaret.

Ens fingeraftryk med uændrede kørselsstier medfører ingen skrivninger til indlæg eller postmeta og udløser ingen opdateringshooks. Når en uændret kilde flyttes til en ny udgivelsesmappe, opdaterer afstemningen kun de gemte stier til skabelon, indhold, layout og mappe; den opdaterer ikke post_content eller tidspunktet for seneste ændring af indlægget. Manglende administrerede sider fjernes først, når hele afstemningen er gennemført uden opdagelses- eller skrivefejl på sider.

Direkte afstemning af API markerer ikke en udrulning som vellykket. Når det matchende statiske artefakt og dets ruter er aktiveret og verificeret, skal du gemme den returnerede identitet eksplicit:

PHP
Blockstudio\Pages::store_successful_source_identity(
  $report['sourceIdentity']
);

wp bs pages sync gemmer den returnerede identitet efter en vellykket kørsel. Almindelig opstart af WP-CLI registrerer kun gemte samlingsindlægstyper og rewrites. Den finder eller synkroniserer ikke sider.

Fastlåsning af indlægs-id’er

Som standard tildeler WordPress automatisk indlægs-id’er. Hvis en side slettes og oprettes igen, ændres id’et, hvilket bryder eksterne referencer som menuer eller hardkodede links.

Brug postId for at fastlåse en side til et bestemt id:

JSON
{
  "name": "about",
  "title": "About Us",
  "postId": 42
}

Når siden oprettes, sender Blockstudio id’et til WordPress via import_id. Hvis id’et er ledigt, bruger WordPress det præcist. Hvis id’et allerede er optaget af et uvedkommende indlæg, tildeler WordPress automatisk og uden besked et nyt id.

Når Blockstudio slår eksisterende sider op, kontrollerer den det fastlåste id først, før den kontrollerer meta eller slug. Det betyder, at hvis en side slettes og synkroniseres igen, får den samme id tilbage.

Sammenfletning af nøglebaserede blokke

Som standard erstatter Blockstudio hele indlæggets indhold med den nye skabelon, når en skabelonfil ændres. Det betyder, at alle redigeringer foretaget i editoren WordPress går tabt.

Tilføj attributten key til blokke for at bevare brugerens redigeringer på tværs af skabelonsynkroniseringer. Når en skabelon har nøglebaserede blokke, sammenfletter Blockstudio skabelonændringer med det eksisterende indlægsindhold i stedet for at erstatte det.

Tilføjelse af nøgler

Brug attributten key på ethvert element af typen HTML eller <block>:

HTML
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>

<div key="features">
  <p>First feature.</p>
  <p>Second feature.</p>
</div>

<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h2>Hero Title</h2>
  <p>Hero description.</p>
</block>

<block
  name="acme/testimonial"
  key="featured-quote"
  quote="Default quote"
/>

Nøgler skal være globalt unikke på tværs af hele skabelonen. En nøgle beskytter hele blokken og alt dens indhold. Du behøver ikke at give de enkelte underordnede elementer inde i en blok med nøgle deres egne nøgler. Blokke med nøgler kan flyttes til enhver position eller indlejringsdybde mellem skabelonopdateringer, og deres brugerindhold bevares.

Nøgler fungerer på samme måde for brugerdefinerede blokke af typen Blockstudio. key er strukturelle Page Sync-metadata; værdier i brugerdefinerede felter forbliver almindelige attributter af typen Blockstudio. Når en redaktør ændrer disse felter, bevarer en senere skabelonsynkronisering redaktørens værdier, mens uafhængige skabelonændringer stadig anvendes. Sider oprettet med ældre versioner, hvor nøglen ligger i dataene for det brugerdefinerede felt, migreres automatisk ved næste synkronisering.

Sådan fungerer sammenfletningen

Når en skabelonfil ændres, og siden synkroniseres igen:

Blok Adfærd
Blok med nøgle Brugerindhold og feltværdier af typen Blockstudio bevares. Skabelonejede attributter og struktur anvendes.
Blok uden nøgle Erstattes helt med skabelonversionen (samme adfærd som uden nøgler)

Eksempler

Brugerens redigeringer bevares i blokke med nøgler:

  1. Skabelonen definerer <p key="intro">Default intro.</p>
  2. Brugeren redigerer afsnittet i editoren til "Brugerdefineret introtekst."
  3. Udvikleren opdaterer skabelonen, tilføjer en ny blok og ændrer layoutet
  4. Ved synkronisering: Afsnittet beholder "Brugerdefineret introtekst.", mens det nye layout anvendes

Attributter fra skabelonen anvendes stadig:

  1. Skabelonen har en forsideblok med key="hero" og en attribut af typen url
  2. Udvikleren ændrer attributten url for forsiden til et nyt baggrundsbillede
  3. Ved synkronisering: Det nye baggrundsbillede anvendes, mens brugerens indholdsredigeringer inde i forsiden bevares

Særlige tilfælde

Scenarie Adfærd
Ny blok med nøgle føjes til skabelonen Vises med skabelonens standardindhold
Blok med nøgle fjernes fra skabelonen Slettes fra indlægget
Bloktypen ændres (samme nøgle) Skabelonen vinder helt; indholdet sammenflettes ikke
Dublerede nøgler Den anden forekomst behandles som en blok uden nøgle
Ingen nøgler i skabelonen Fuld erstatning (samme adfærd som uden nøgler)
Tvungen synkronisering Fuld erstatning; nøgler ignoreres
Låst indlæg Ingen synkronisering

Kombination med redigeringskontroller

Nøgler, templateLock og blockEditingMode giver dig tilsammen detaljeret kontrol over, hvad kunder kan og ikke kan gøre. Her er nogle almindelige arbejdsgange.

Helt låst side

Udvikleren styrer alt. Siden er et statisk layout, som kunderne slet ikke kan ændre. Nyttigt til juridiske sider, servicevilkår eller sider, der kun bør ændres gennem kode.

JSON
{
  "name": "terms",
  "title": "Terms of Service",
  "templateLock": "all"
}
HTML
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>

Der er ikke brug for nøgler. Skabelonen er den eneste sandhedskilde. Hver synkronisering overskriver hele siden.

Låst layout med redigerbart indhold

Det mest almindelige mønster. Lås sidens struktur, så kunderne ikke kan tilføje, fjerne eller omarrangere blokke, men lad dem redigere tekst bestemte steder. Nøgler sikrer, at deres redigeringer bevares ved skabelonopdateringer.

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Title</h1>
  <p blockEditingMode="contentOnly">Edit this description.</p>
</block>

<div key="features">
  <h2>Features</h2>
  <p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">Contact Us</block>
</block>

Klienten kan redigere overskrift, beskrivelse og introduktion til funktionerne i hero-sektionen. Intet andet. Knappens tekst, URL og coverbilledet styres af udvikleren. Når udvikleren opdaterer skabelonen (e.g., tilføjer en ekstra knap), bevarer sektioner med nøgler klientens tekst.

Skabelon i udvikling med bevaret indhold

Til sider, der vokser over tid. Udvikleren tilføjer nye sektioner til skabelonen, og hver synkronisering tilføjer det nye indhold uden at ændre det, klienten allerede har tilpasset.

HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
<div key="testimonials">
  <h2>Testimonials</h2>
  <p>What our clients say.</p>
</div>
<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
</block>

Den nye sektion med kundeudtalelser og knap vises ved synkronisering. Klientens redigeringer af titel, introduktion og tjenester berøres ikke.

Engangsskelet

Opret en side med en grundstruktur, og overdrag den derefter helt. Indstil sync til false, så normal synkronisering aldrig opretter eller opdaterer siden, og opret den én gang med Blockstudio\Pages::force_sync('blog'). Derefter ejer klienten siden fuldt ud.

JSON
{
  "name": "blog",
  "title": "Blog",
  "sync": false
}
HTML
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>

wp bs pages sync springer denne side over, så force_sync() opretter den én gang. Derefter kan klienten frit tilføje, fjerne og omarrangere blokke. Ændringer i skabelonen ignoreres.

Bloktilknytninger

Et alternativ til sammenfletning efter nøgle er at bruge WordPress cores Block Bindings API til at forbinde blokke med post-meta. Det er ikke en Blockstudio-funktion, men en indbygget WordPress API. Blockstudio videresender blot attributten metadata til den genererede blokmarkup. Indholdet ligger i post-meta i stedet for i blokmarkup, så synkronisering af skabeloner frit kan overskrive markuppen, fordi editoren læser fra meta, ikke fra innerHTML.

Angiv attributten metadata på ethvert HTML- eller <block>-element:

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

<p
  metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'
>
  Default description text.
</p>

<img
  metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>

Metanøglerne skal registreres med show_in_rest aktiveret:

PHP
register_post_meta( 'page', 'hero_title', array(
    'show_in_rest'  => true,
    'single'        => true,
    'type'          => 'string',
    'default'       => 'Default Title',
) );

Nøgler kontra tilknytninger

Egenskab Nøgler Tilknytninger
Indhold gemt i Blokmarkup (post_content) Post-meta (wp_postmeta)
Bevares ved skabelonsynkronisering Ja (flettet efter nøgle) Ja (data ligger i meta)
Kan forespørges via WP_Query Nej Ja (meta_query)
Tilgængelig i REST API Nej Ja
Kræver registrering Nej Ja (register_post_meta)
Brugeren kan flytte blokke Nej (skabelonen genindfører strukturen) Nej (skabelonen genindfører strukturen)

Begge metoder kan bruges i samme skabelon. Brug nøgler til sektioner, hvor blokstrukturen er vigtig (e.g., en gruppe med flere underordnede blokke). Brug tilknytninger til individuelle felter, hvor du også ønsker, at dataene skal være tilgængelige uden for blokeditoren.

Skabeloner til indholdstyper

Brug templateFor til at angive en side som standardskabelon for en indholdstype:

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}

Alle nye indlæg af den type starter med den definerede blokstruktur.

Brugerdefinerede stier

Som standard scanner Blockstudio get_template_directory() . '/pages'. Tilføj flere stier med filteret:

PHP
add_filter( 'blockstudio/pages/paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/custom-pages';
    $paths[] = MY_PLUGIN_DIR . '/pages';
    return $paths;
} );

Runtime-integrationer, der sammensætter filer fra flere rødder, kan erstatte filsystemscanningen med en logisk kilde til søgning. Sidemanifester, layouts, loaders og kildeskabeloner findes derefter via logiske stier, selv når de valgte filer ligger i forskellige rødder.

Filtre og handlinger

Sidetilgang, synkronisering og samlingsrouting stiller følgende udvidelsespunkter til rådighed:

Hook Type Beskrivelse
blockstudio/pages/paths Filter Tilføj mapper, som Blockstudio scanner efter sidekilder.
blockstudio/pages/collection_post_type_args Filter Justér register_post_type()-argumenter for en samling-CPT.
blockstudio/pages/template_candidates Filter Justér de skabelonfilnavne, der tages i betragtning som sidekilde.
blockstudio/pages/serve_markdown Filter Aktivér eller deaktivér rå Markdown-svar.
blockstudio/pages/orphan_action Filter Returnér trash, delete eller keep ved oprydning af forældreløse elementer.
blockstudio/pages/docs_allowed_html Filter Justér tilladte HTML for genereret Markdown-dokumentationsindhold.
blockstudio/pages/allow_external_loader_path Filter Tillad loader-paths uden for samlingsroden.
blockstudio/pages/manifest_scan_interval Filter Angiv den maksimale alder for en ældre manifestcache fra før 7.6.2, der må bruges til at starte vedvarende runtime-konfiguration under en opgradering.
blockstudio/pages/create_post_data Filter Redigér indlægsdata, før en synkroniseret side oprettes.
blockstudio/pages/update_post_data Filter Redigér indlægsdata, før en synkroniseret side opdateres.
blockstudio/pages/sync_engine_inputs Filter Tilføj en parser-, mapping- eller migrationsversion, der bevidst skal udvide afstemningen én gang.
blockstudio/pages/post_created Handling Kører, efter et synkroniseret sideindlæg er oprettet.
blockstudio/pages/post_updated Handling Kører, efter et synkroniseret sideindlæg er opdateret.
blockstudio/pages/synced Handling Kører, efter sidesamlingen er færdig med at synkronisere.
blockstudio/pages/reconciled Handling Kører efter en eksplicit afstemning med dens maskinlæsbare rapport.
blockstudio/pages/renderers Handling Registrér sidegengivere med Blockstudio\Page_Renderers::register(). Udløses én gang pr. anmodning.
blockstudio/pages/rendered Handling Kører efter gengivelsen af en komponentbaseret side, med siden, dens HTML og dens afhængigheder.
blockstudio/pages/layout_error Handling Kører, når et layout ikke kan gengives, med fejlen, layoutstien og siden.

PHP API

PHP
// Get all registered pages.
$pages = Blockstudio\Pages::pages();

// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');

// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');

// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');

// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');

// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');

// Get a specific page.
$page = Blockstudio\Pages::get_page('about');

// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');

// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');

// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();

// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
]);

// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);

// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');

// Unlock a page.
Blockstudio\Pages::unlock('about');

// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
  'extensions' => ['tsx'],
  'layouts' => ['layout.tsx'],
  'render' => 'my_theme_render_page',
]);

// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');

// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);

Se Afstemning ved implementering for argumenternes betydning, rapportfelter og den verificerede grænse for kildeidentitet.

Globale hjælpefunktioner er tilgængelige for skabeloner og layouts:

PHP
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();

Sidearrays, der returneres af Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() og de globale hjælpefunktioner, indeholder den synkroniserede indlægsidentitet, kilde- og skabelonstier, metadata om samling og sti, indholdstype, synkroniseringspolitik, indlægstype og -status, redigeringspolitik, brugerdefinerede metadata samt en permalink-nøgle. Samlingsmetadata indlæses fra den seneste vellykkede, eksplicitte afstemning. Almindelige forespørgsler genskaber disse runtime-data fra gemt konfiguration og meta for synkroniserede indlæg uden at læse sidernes kildetræer. Klassen Pages stiller ikke en separat permalink-metode til rådighed.

Opret filbaserede sider

Låsning af skabeloner, blokredigeringstilstande, sammenfletning efter nøgle og styring af, hvad klienter kan redigere.