Přejít k obsahu

Stránky

Stránky jsou šablony založené na souborech, které se synchronizují s databází WordPress jako příspěvky. Synchronizace je explicitní: spusťte wp bs pages sync nebo zavolejte Pages API, když chcete použít změny ve zdrojích. Načtení frontendu nebo administrace WordPress nikdy neprovede úplné vyhledání stránek ani nezmění příspěvky stránek.

Stránky lze definovat jako jedinou složku page.json, jako samostatné Markdown nebo jako kolekci s manifestem pages.json. Kolekce se hodí pro dokumentaci, znalostní báze, knihovny vstupních stránek nebo libovolné skupiny vnořených stránek, které se mají generovat ze souborů.

page.json

U stránky definované pomocí JSON přidejte konfigurační soubor page.json:

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

Vlastnosti

Vlastnost Typ Výchozí hodnota Popis
name string povinné Jedinečný identifikátor stránky
title string Automaticky podle názvu Název stránky
slug string Stejné jako název URL slug stránky
path string "." Logická cesta v rámci kolekce
order integer 0 Pořadí položky v nabídce pro synchronizovaný příspěvek
postType string "page" Typ příspěvku WordPress
postStatus string "draft" Stav nových příspěvků (publish, draft, pending, private)
postId integer – Připnout stránku ke konkrétnímu ID příspěvku WordPress
blockEditingMode string – Režim úprav bloků: "default", "contentOnly" nebo "disabled"
templateLock string|false "all" Režim uzamčení: "all", "insert", "contentOnly" nebo false
templateFor string|null null Nastavit jako výchozí šablonu pro typ příspěvku
sync boolean true Určuje, zda může běžné explicitní sjednocení příspěvek vytvořit nebo aktualizovat
render string|object|false – Vykreslit stránku pomocí registrovaného vykreslovače stránek (viz Stránky komponent)

Mezi page.json, frontmatter a položkami loaderu patří mezi rozpoznávané klíče blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock a title. Každý výše neuvedený klíč se ukládá do pole meta dané stránky.

Zdroje obsahu

Definice stránky určuje, který příspěvek WordPress má existovat. Zdroj obsahu určuje, jaké značky bloků se do příspěvku zapíší.

Pokud složka stránky obsahuje page.json, Blockstudio hledá soubor se zdrojem ve stejné složce v tomto pořadí:

Soubor Použití
index.php Značky bloků ve stylu HTML, čtou se beze změn (kód PHP se nespouští)
index.blade.php Obsah šablony Blade
index.twig Obsah šablony Twig
index.md Obsah Markdown

page.json může také obsahovat vložené markdown nebo html místo souboru ve stejné složce:

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>"
}

Kolekce přidávají dva další režimy zdrojů:

  • Soubory Markdown nalezené přímo ve stromu kolekce.
  • Položky loaderu vrácené z loader.php.

Položky loaderu mohou používat markdown, html nebo content s contentType. Mohou také odkazovat na místní file nebo template. Typ souborových a šablonových zdrojů se odvozuje z přípony, pokud není výslovně nastaveno contentType.

Podporované hodnoty contentType jsou php, blade, twig, markdown a html. Markdown se nejprve převede na HTML a poté se naparsuje do nativních bloků WordPress. Zdroje PHP, Blade, Twig a HTML zpracovává běžný parser stránek Blockstudio.

Třídy na blocích jádra

class na prvku HTML mapovaném na blok jádra se stane jeho className. Výslovná značka bloku jádra může používat přímo className. Obě podoby zachovávají třídy na uloženém obalovém prvku bloku spolu s třídami, které generuje WordPress:

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

Pokud jsou přítomny obě vlastnosti, přednost má className. Tento převod se týká pouze bloků jádra: mapování vlastního bloku ponechá jeho pole class beze změny. Třídy stylu tlačítka, například is-style-outline, patří obalovému prvku tlačítka, nikoli jeho odkazu.

Spuštěním wp bs pages sync použijete opravy parseru na dříve synchronizované stránky. Aktualizace parseru se rozpoznají při další výslovné synchronizaci, i když se zdrojový soubor nezměnil. Uzamčené stránky a stránky s sync: false si zachovávají svou obvyklou ochranu; požadavky frontendu tuto synchronizaci nikdy neprovádějí.

Serializované bloky WordPress

Zdroje stránek a vzorů mohou obsahovat také serializované bloky zkopírované z editoru kódu WordPress:

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

Pokud zdroj obsahuje oddělovač bloku <!-- wp:... -->, Blockstudio použije pro celý zdroj nativní parser bloků WordPress. Atributy, vnořené bloky, dynamické bloky, jako je Query Loop, i bloky Blockstudio zachovají svou serializovanou strukturu. HTML mimo komentáře bloků zůstane nativním volným obsahem HTML; nepřevede se na další bloky. Nemíchejte značky bloků HTML Blockstudio s tímto formátem a neočekávejte, že se převedou. Běžné komentáře HTML režim serializovaných bloků neaktivují.

Stránky Markdown

Použijte Markdown, když má být próza uložena v souborech, ale po synchronizaci se má změnit na upravitelný obsah bloků WordPress. Zdroj Markdown se během synchronizace převede na značky bloků. Synchronizovaný příspěvek ukládá bloky, nikoli původní tělo Markdown.

Markdown lze použít třemi způsoby:

Zdroj Vyžaduje frontmatter? Poznámky
Samostatný pages/example/index.md Ano Frontmatter určuje identitu stránky.
page.json a index.md Ne page.json definuje stránku a Markdown poskytuje obsah.
Markdown v kolekci Ne Kolekce odvodí name a path z umístění souboru.

Samostatný index.md bez frontmatteru se přeskočí, protože Blockstudio nemá identitu stránky, kterou by mohl synchronizovat. Kolekční Markdown frontmatter nepotřebuje, protože identitu určuje manifest kolekce a cesta k souboru.

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

# About

This Markdown content is synced as native WordPress blocks.

page.json můžete také spárovat s index.md. V takovém případě stránku definuje page.json a obsah poskytuje index.md. Frontmatter v index.md přepíše odpovídající hodnoty 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.

U kolekčního Markdown se cesta k souboru stane logickou cestou stránky, pokud ji nepřepíše frontmatter:

Soubor Výchozí cesta
pages/docs/index.md .
pages/docs/getting-started.md getting-started
pages/docs/guide/install/index.md guide/install
pages/docs/guide/install.md guide/install

Neznámé klíče frontmatteru se zachovají v poli meta dané stránky. Můžete tak připojit například data section nebo description a číst je z PHP API.

Markdown se parsuje jako GitHub Flavored Markdown. Je povoleno surové HTML, nebezpečné odkazy se odstraňují a nadpisy bez výslovně zadaného ID dostanou stabilní ID. Vnořený frontmatter YAML vyžaduje přibalený parser YAML.

Surové Markdown

Zdroje souborů Markdown mohou zpřístupnit původní zdroj Markdown externím nástrojům a uživatelům dokumentace. Vložené Markdown nemá zdrojový soubor, takže se synchronizuje do bloků, ale nevytvoří surovou odpověď .md.

Požádejte o stránku s příponou .md, například https://example.com/docs/reference.md. Nebo pošlete hlavičku Accept: text/markdown při běžném požadavku na stránku URL:

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

Frontmatter se z odpovědi odstraní. Úspěšné surové odpovědi Markdown vracejí Content-Type: text/markdown, X-Robots-Tag: noindex a kanonickou hlavičku Link zpět stránce HTML. Pro chybějící trasy .md se vrací skutečný stav 404.

Vyjednávání funguje se statickým předgenerováním: požadavek, jehož hlavička Accept obsahuje text/markdown, nikdy nedostane odpověď z úložiště předgenerovaných stránek ani z doplňku pro předčasné poskytování, takže dorazí k WordPress a obsluze Markdown. Předgenerované odpovědi HTML, HTML stránky, která také vyjednává Markdown, a Markdown obsloužené přes Accept vracejí Vary: Accept, takže mezipaměti, které toto respektují, odliší obě varianty pomocí Vary. CDN, který zakládá klíč mezipaměti pouze na URL, potřebuje vlastní pravidlo, které pro tyto požadavky mezipaměť obejde. Pages::negotiates_markdown( $post_id ) hlásí, zda stránka obsluhuje požadavky Markdown.

Kolekce Markdown zachovává pro surové Markdown stejný tvar URL:

Stránka URL Cesta k surovému Markdown URL
/docs/ /docs.md
/docs/getting-started/ /docs/getting-started.md
/docs/guide/install/ /docs/guide/install.md

Surové odpovědi Markdown vypnete filtrem blockstudio/pages/serve_markdown:

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

Pokud se stránka .md URL nepodaří rozpoznat jako stránku založenou na Markdown, vrátí se 404 pouze tehdy, když cesta spadá do kolekce stránek. Mimo všechny kolekce ponechá Blockstudio požadavek beze změny pro obsluhu pomocí WordPress a dalších pluginů.

Stránky komponent

Stránka komponenty se vykresluje pomocí vykreslovače stránek, místo aby se ukládala jako bloky. Blockstudio nedodává žádný vykreslovač. Motiv nebo plugin zaregistruje vykreslovač pro soubory položek, které zpracovává, například vykreslovač React pro page.tsx, a Blockstudio mu předá stránku, příspěvek WordPress a vykreslený obsah slotu.

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 je výslovné. Adresář obsahující index.php a page.tsx, ale bez render, zůstává běžnou stránkou, takže přidání vykreslovače nevykreslí existující stránku dvakrát. Formáty jsou následující:

Hodnota Význam
"page.tsx" Pouze položka bez datového loaderu
{ "entry": "page.tsx", "data": "data.php" } Položka a datový loader
{ "entry": "page.tsx", "renderer": "react" } Položka s explicitním ID vykreslovače
false Bez vykreslovače, i když ho určuje výchozí nastavení kolekce

Cesty se určují vzhledem k adresáři stránky nebo u položek loaderu vzhledem ke kořenu kolekce. Musí zůstat uvnitř zdroje pro vyhledávání, pokud to blockstudio/pages/allow_external_loader_path nepovoluje. Bez renderer se použije vykreslovač, který zpracovává příponu souboru dané položky. Pokud render odkazuje na chybějící položku nebo datový soubor, neznámý vykreslovač nebo příponu, kterou žádný vykreslovač nezpracovává, jde o chybu vyhledávání, která zastaví sjednocení ještě před odstraněním čehokoli.

Co synchronizace ukládá

Synchronizace ukládá jeden blok blockstudio/page. Pokud zdroj index.* existuje také v adresáři stránky, zpracuje se jako jakýkoli zdroj stránky a stane se vnitřními bloky bloku, tedy jeho slotem:

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

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

Obsah spravovaný pomocí WordPress, například krátké kódy, ponechte ve slotu. Zdroj tvořený jediným krátkým kódem, například [download_checkout], se uloží jako blok core/shortcode, takže se kolem jeho výstupu nepřidá odstavec. Zůstává v post_content, takže ho kontroly has_shortcode() vidí, bloky slotu s klíči se slučují se změnami v editoru stejně jako vnořené bloky s klíči a do_shortcode rozbalí krátké kódy jednou při obvyklé prioritě the_content, až poté, co je vykreslovač obalí.

Definice vykreslení se ukládá spolu s příspěvkem jako přenositelné cesty theme:. Otisk stránky zahrnuje definici, nikoli bajty položky nebo datového loaderu: úprava page.tsx nebo data.php příspěvek nezmění a změny se návštěvníkům projeví při vykreslování a v grafu statického předvykreslení, který zaznamenává položku, datový loader a každý soubor nahlášený vykreslovačem.

Registrace vykreslovače

Vykreslovače registrujte při akci blockstudio/pages/renderers. Spustí se jednou pro každý požadavek před prvním vyhledáváním nebo vykreslením, takže požadavky na wp bs pages sync i frontend používají stejný registr.

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

ID vykreslovačů se zapisují malými písmeny. Přípona souboru nebo název rozvržení může patřit pouze jednomu vykreslovači a layout.php zůstává vlastním rozvržením Blockstudio. Volatelný objekt obdrží jeden požadavek:

Klíč Hodnota
kind page nebo layout pro rozvržení vykreslovače rozvržení vykreslovače
renderer ID vykreslovače
entry Absolutní cesta k položce
data Absolutní cesta k datovému loaderu nebo null
page Kanonická data stránky včetně meta
post_id ID příspěvku WordPress
slot Vykreslený obsah slotu nebo obsah stránky při použití rozvržení
context frontend, rest, feed nebo cli

Vrací HTML, soubory načtené při vykreslení a volitelné prostředky:

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 pochází z typu požadavku, nikdy ne od návštěvníka, takže renderer nemůže narušit shodu bajtů mezi přihlášenými a anonymními uživateli tím, že by jej načetl. Pokud renderer selže, vyvolá výjimku: stránka nevykreslí prázdné tělo. V náhledu editoru REST se chyba místo toho zobrazí jako upozornění. Po úspěšném vykreslení akce blockstudio/pages/rendered obdrží stránku, HTML a její závislosti.

assets uvádí soubory skriptů a stylů, které stránka potřebuje. Procházejí zpracováním prostředků bloku (konvencí *.inline.*, modulů ES, minifikací a ?ver) a stránka je vypíše jednou prostřednictvím stejné vyrovnávací paměti, která vypisuje prostředky bloků, takže je předsestavená stránka obsahuje. Prostředek může nastavit version a nahradit tak jeho hodnotu ?ver. Kód mimo renderer může použít stejný kanál prostřednictvím Blockstudio\Assets::register_owner(), které vrací komentář se značkou k vypsání.

Editor

V editoru blockstudio/page zobrazuje serverově vykreslený náhled stránky, jehož vnitřní bloky tvoří obsah slotu a řídí se rozvržením stránky templateLock. Blok nelze vložit, duplikovat ani vnořit do jiného bloku.

Kolekce stránek

Kolekce je složka s manifestem pages.json. Seskupuje mnoho zdrojů stránek pod jediným slugem kolekce, používá výchozí nastavení, podporuje vnořené cesty a může automaticky zaregistrovat vyhrazený typ příspěvku.

Kód
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"
  }
}
Vlastnost Typ Popis
collection / slug / name string Slug kolekce. collection je nejjednoznačnější forma a stává se základem veřejného URL.
title string Název kolekce určený lidem.
postType string Typ příspěvku pro generované stránky. Výchozí hodnota je page. Pokud neexistuje, Blockstudio jej zaregistruje.
postTypeArgs object Argumenty předávané register_post_type(), když Blockstudio registruje typ příspěvku kolekce.
defaults object Výchozí vlastnosti stránky použité pro každou stránku v kolekci. Výchozí render se použije na stránce pouze tehdy, pokud má v adresáři stránek svou položku.
scope string collection (výchozí) nebo site. Viz Kolekce webu.
meta object Vlastní metadata kolekce. Neznámé klíče manifestu se také ukládají do meta.

Cesty stránek v kolekci jsou logické cesty. Stránka s path: "guide/install" se synchronizuje jako potomek stránky guide a guide jako potomek kořene kolekce, pokud tyto nadřazené stránky existují.

Pokud má hierarchická kolekce vnořenou stránku, ale zdroj prostřední nadřazené stránky neexistuje, Blockstudio vytvoří pro tuto cestu prázdnou kontejnerovou stránku, která zachová úplnou hierarchii WordPress. U nehierarchických typů příspěvků (bez podpory page-attributes rodičovské stránky) se prázdné kontejnery nevytvářejí. Cesty se určují podle uložené cesty kolekce, takže mohou vedle sebe existovat vnořené cesty jako guide/install a setup/install, přestože obě končí na install.

Typy příspěvků kolekce a adresy URL

Nastavte postType v manifestu kolekce, aby se každá stránka kolekce synchronizovala s tímto typem příspěvku. Stejnou hodnotu není nutné opakovat v defaults. Jednotlivé stránky mohou hodnotu postType přesto přepsat ve frontmatteru nebo v page.json.

Pokud typ příspěvku neexistuje, Blockstudio jej zaregistruje s show_in_rest: true, editorem podobným editoru stránek a slugem kolekce jako veřejným základem URL. postTypeArgs může přepsat argumenty registrace. Pravidla přepisu adres URL pro typy příspěvků kolekcí se automaticky obnoví při změně registrovaných typů příspěvků kolekcí nebo argumentů přepisu, takže není třeba znovu ukládat trvalé odkazy WordPress.

Adresy URL kolekce používají slug kolekce a logickou cestu path každé stránky:

Zdrojová cesta Veřejné URL
path: "." /docs/
path: "getting-started" /docs/getting-started/
path: "guide/install" /docs/guide/install/

Tento model URL funguje pro hierarchické i nehierarchické typy příspěvků kolekcí. Blockstudio také přesměrovává zdvojené adresy URL, například /docs/docs/ nebo /docs/docs/getting-started/, na kanonickou URL.

Stránky kolekcí zpřístupňují surové Markdown na stejných adresách URL (viz Surové Markdown).

Pokud změníte kolekci z postType: "page" na vlastní typ příspěvku, Blockstudio převede již synchronizované příspěvky kolekce na místě, pokud jejich uložená identita stránky odpovídá. Zachovají se tak ID příspěvků, metadata i stávající obsah a zároveň se předejde duplicitním příspěvkům se starým typem. Zastaralé příspěvky kolekce se podle filtru blockstudio/pages/orphan_action odstraní ze všech stavů příspěvků.

Kolekce webu

Manifest s "scope": "site" seskupuje všechny stránky pod sebou, aniž by z nich vytvářel stránky kolekce. Použijte jej v kořeni stromu stránek webu, abyste nastavili sdílené výchozí hodnoty a vypsali stránky webu pomocí 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" }
  }
}

Stránky kolekce webu si zachovávají přesně tutéž identitu, jakou měly bez manifestu, takže jeho přidání do existujícího stromu nezmění žádné řádky příspěvků ani nic nevytvoří či neodstraní:

  • Klíče zůstávají globální: Pages::get_page( 'home' ) a uložené klíče stránek se nadále shodují.
  • URL zůstávají URL WordPress stránek. Nepoužijí se žádná pravidla přepisu kolekcí, filtr trvalých odkazů ani přesměrování s dvojitým URL a nevytvářejí se žádné prázdné stránky kontejneru.
  • Logické cesty, slugy, nadřazené stránky a zdrojové identity odpovídají samostatným stránkám a rozvržení se určuje podle nejbližšího předka.
  • Vnořené manifesty pages.json si zachovávají vlastní kolekce a jejich podstromy se do kolekce webu nezahrnují.
  • Výchozí hodnoty se uplatňují pro každou stránku zvlášť: výchozí render se použije pouze u stránek, jejichž adresář obsahuje odpovídající položku, takže stránky se shortcode a Markdown si zachovají své zdroje.

Načítání kolekcí

Kolekce mohou obsahovat důvěryhodný místní loader.php. Použijte jej, pokud stránky kolekce pocházejí z jiného místního zdroje, například z externí složky s dokumentací, balíčku nebo generovaného manifestu.

Načítání probíhá při explicitním vyhledávání stránek a synchronizaci. Mělo by být deterministické a místní. Vyhněte se načítání vzdáleného obsahu z loader.php, protože by synchronizace při nasazení závisela na této službě.

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',
    ),
  ),
);

Načítání může vrátit pole s klíči pages, meta a paths:

Klíč Popis
pages Seznam polí stránek. Každá stránka podporuje stejné rozpoznávané klíče jako frontmatter page.json a Markdown.
meta Metadata sloučená do pole meta každé stránky vytvořené načítacím modulem.
paths Další místní adresáře, které se mají v rámci této kolekce prohledat. Položky mohou být řetězce nebo objekty s cestou.
render Definice vykreslování pro každou stránku Markdown nalezenou v paths.

Pro zkrácený zápis může načítání vrátit přímo seznam polí stránek.

Položky stránek načítání mohou poskytovat obsah následujícími způsoby:

Tvar Popis
markdown Vložený obsah Markdown.
html Vložený obsah HTML.
content + contentType Obecný vložený obsah. contentType se musí vyhodnotit na markdown nebo html.
file Zdroj z místního souboru. Typ se určuje podle přípony, pokud není nastaveno contentType.
template Alias pro file.

Odkazy na soubory při načítání mohou směřovat ke zdrojům PHP, Blade, Twig, Markdown nebo HTML. Relativní cesty se vyhodnocují od kořene kolekce. Absolutní cesty a cesty mimo kořen kolekce jsou povolené pouze tehdy, pokud to umožňuje filtr blockstudio/pages/allow_external_loader_path.

Stránky načtené pomocí loaderu mají ve výchozím nastavení generated: true. Když stránka vytvořená loaderem zmizí z jeho výstupu, Blockstudio při další synchronizaci považuje synchronizovaný příspěvek za osiřelý a odstraní jej podle filtru blockstudio/pages/orphan_action.

Adresáře uvedené v paths se prohledávají stejně jako běžné složky kolekce. Mohou obsahovat soubory Markdown nebo složky page.json. Pokud se tyto cesty nacházejí mimo kořen kolekce, použije se stejný filtr externích cest.

Pokud má externí adresář zachovat vlastní logické cesty, použijte řetězcovou položku. Pokud má být adresář připojen pod předponou cesty kolekce, použijte objektovou položku:

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

S touto konfigurací se cli-docs/index.md v kolekci změní na path: "cli" a cli-docs/getting-started.md na path: "cli/getting-started". Předpony také zabrání kolizím názvů generovaných stránek, takže každý z několika připojených adresářů může obsahovat index.md nebo getting-started.md. Pokud mají být místo toho zachovány explicitní hodnoty name z frontmatter page.json nebo Markdown, nastavte v objektu cesty preserveNames na true.

Vlastnosti objektu cesty:

Vlastnost Typ Popis
path string Místní adresář k prohledání. Relativní cesty se určují od kořene kolekce.
prefix string Volitelná předpona logické cesty uvnitř kolekce.
preserveNames boolean Zachovat výslovně zadané názvy stránek místo generování názvů z cesty s předponou. Pokud je nastaveno prefix, výchozí hodnota je false.
meta object Metadata sloučená do každé stránky nalezené v této cestě. Při duplicitě klíčů mají přednost metadata na úrovni stránky.
render string|object Definice vykreslování stránek Markdown této cesty, která přepisuje hodnotu render načítacího modulu.

Vykreslování Markdown pomocí komponenty

Pomocí render se stránky Markdown nalezené načítacím modulem vykreslují prostřednictvím rendereru stránky namísto ukládání v podobě bloků:

PHP
<?php

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

Zůstávají to stránky Markdown: typ obsahu, cesta k obsahu, odpovědi .md a frontmatter zůstávají beze změny. Synchronizace uloží jeden blok blockstudio/page, jehož vnitřní blok HTML obsahuje převedený obsah Markdown, sanitizovaný, pokud kolekce svůj obsah sanitizuje, místo analyzovaných bloků, takže post_content zachová text dokumentu. Renderer obdrží tento HTML jako slot a může číst zdroj z page.content_path. Relativní cesty se určují od kořene kolekce; filtr externích cest se uplatňuje stejně jako u cest. Stránka, jejíž frontmatter nastavuje vlastní render nebo render: false, se vynechá.

Rozvržení

Soubor layout.php obaluje vykreslení stránky založené na souboru na frontendu. Nenahrazuje synchronizované post_content uložené v WordPress ani neobaluje plátno editoru. Rozvržení se spouští pouze u požadavků frontendu na jednotlivé stránky.

U kolekcí umístěte layout.php vedle pages.json, aby obalovalo všechny stránky kolekce na frontendu:

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() vypíše tělo stránky, které by WordPress běžně vykreslilo prostřednictvím the_content. Pokud rozvržení nevypíše blockstudio_page_content(), obsah stránky je záměrně skrytý.

Rozvržení mohou používat pomocné funkce stránky:

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

Vnořené stránky, které nepatří do kolekce, mohou také převzít nejbližší rozvržení layout.php předka ve stromu pages. U stránek kolekce se kořenové rozvržení kolekce ukládá do každého synchronizovaného příspěvku a sleduje se jako součást otisku stránky, takže změny rozvržení se projeví při další synchronizaci.

Rozvržení rendereru

Rozvržení může být také položkou rendereru, například layout.tsx pro renderer, který registruje layouts: ["layout.tsx"]. Vyhledává se na stejných místech jako layout.php a volitelný soubor layout.data.php vedle něj slouží jako jeho načítací modul dat. Při vykreslování renderer obdrží kind: "layout" a vykreslený obsah stránky jako slot se stejnou prioritou the_content jako layout.php. Adresář může obsahovat layout.php nebo jedno rozvržení rendereru, nikdy obojí; současný výskyt obou je chybou při vyhledávání. Při selhání rozvržení se vyvolá blockstudio/pages/layout_error a obsah stránky zůstane bez obalu, stejně jako v případě layout.php.

Režim úprav bloků

Vlastnost blockEditingMode určuje, jak lze bloky upravovat v editoru. Nastavte výchozí hodnotu pro stránku v page.json a přepište ji u jednotlivých prvků v šabloně:

JSON
{
  "name": "about",
  "title": "About Us",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>
Hodnota Popis
"default" Úplné úpravy. Bloky lze vybírat, přesouvat a upravovat
"contentOnly" Pouze úpravy textu. Text bloku lze upravovat, ale nastavení a struktura jsou uzamčené
"disabled" Bez úprav. Bloky jsou zcela neinteraktivní

Přepsání pro jednotlivé prvky se nastavují jako atributy HTML na libovolném prvku (<h1>, <p>, <div> atd.) nebo na prvcích <block>. Nadřazené bloky kontejnerů přepsaných prvků se automaticky nastaví na contentOnly, aby jejich potomci zůstali přístupní. Toto nastavení se šíří od přepsaného prvku směrem nahoru ke kořeni stránky, takže blockEditingMode stačí nastavit pouze u prvků, které chcete zpřístupnit k úpravám.

Uzamčení šablony

Vlastnost templateLock určuje, jak mohou uživatelé upravovat stránku v editoru:

Hodnota Přidat/odebrat Přesunout Upravit obsah
"all" Ne Ne Ne
"insert" Ne Ano Ano
"contentOnly" Ne Ne Ano
false Ano Ano Ano

Když je nastaveno templateLock, Blockstudio zakáže odemykání bloků prostřednictvím UI editoru.

Virtuální trasy

Některé dokumenty nemají žádný příspěvek: například reference komponenty generovaná z dat, katalog nebo oblast účtu. Zaregistrujte je jako virtuální trasy místo toho, abyste sami napojovali 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(),
        ]
    );
} );

Cesta je relativní k domovské stránce webu. S prefix trasa obsluhuje také všechny cesty pod ní a match obdrží zbytek cesty (prázdný řetězec pro samotnou trasu) a vrátí hodnotu, kterou obdrží funkce zpětného volání pro vykreslení, nebo null, aby se zpracování trasy předalo URL až WordPress, které pak odpoví jako obvykle pomocí 404. Funkce zpětného volání pro vykreslení vypíše dokument nebo jej vrátí jako řetězec; title je řetězec nebo uzávěr, který obdrží hodnotu shody.

U odpovídajícího požadavku Blockstudio zabrání tomu, aby WordPress označilo požadavek jako 404 a aby jej redirect_canonical přesměrovalo, zruší stav jednotlivé stránky hlášený hlavním dotazem, odešle stav (ve výchozím nastavení status, 200) a vykreslí stránku s prioritou template_redirect Virtual_Routes::PRIORITY. To nastane hned poté, co se otevře výstupní buffer Blockstudio na prioritě Assets::BUFFER_PRIORITY, takže výsledný dokument získá své prostředky bloků, sdružené prostředky UI a zkompilované Tailwind stejně jako kterákoli jiná stránka, a před redirect_canonical na prioritě 10. Obslužná rutina, která sama vykreslí celý dokument, se musí spustit také po Assets::BUFFER_PRIORITY, jinak se toto zpracování přeskočí. Cesty v urls (ve výchozím nastavení samotná cesta trasy, pokud nejde o prefixovou trasu) se přidávají do sestavení statického předběžného vykreslení a Virtual_Routes::urls() je vrací jako absolutní adresy URL pro mapu webu. Virtual_Routes::match( $path ) vyhodnocuje cestu stejně jako požadavek.

Chování synchronizace

Příspěvky stránek se mění pouze prostřednictvím explicitní synchronizační operace:

Shell
wp bs pages sync

Příkaz vyhledá úplný seznam zdrojů, vytvoří nebo aktualizuje změněné příspěvky, odstraní potvrzené osiřelé příspěvky, obnoví směrování kolekcí a zkompilovanou konfiguraci templateFor a oznámí provedené změny. Přidejte --authoritative, chcete-li nahradit spravovaný obsah místo zachování obsahu editoru podle klíčů, a --full, chcete-li průchod označit jako úplnou rekonciliaci bez ohledu na uloženou identitu zdroje:

Shell
wp bs pages sync --authoritative --full

Běžné požadavky frontendu, administrace, AJAXu, REST, cron a obecného spuštění WP-CLI neprovádějí úplné vyhledávání stránek, nedotazují se na inventář rekonciliace spravovaného obsahu ani nezapisují příspěvky stránek. Používají již synchronizované příspěvky WordPress a kompaktní konfiguraci kolekcí a šablon typů příspěvků uloženou při poslední explicitní operaci. Při prvním spuštění nebo aktualizaci může proběhnout jednorázové prohledání manifestů kolekcí, aby se obnovila metadata směrování; toto spuštění pouze pro čtení nikdy nesynchronizuje obsah.

Autentizovaný koncový bod pro obnovení plátna s volitelným přihlášením je explicitní API pro tvorbu: plátno jej zavolá jednou při otevření pracovního prostoru, aby se nově přidané nebo změněné zdroje objevily v počátečním inventáři. Živý režim volá stejné rozhraní, jakmile zaznamená změnu zdroje stránky.

Blockstudio\Pages::init() nyní registruje pouze háčky pro zpracování požadavků. Integrace, které dříve předávaly této metodě argument force, musí místo toho zavolat Blockstudio\Pages::reconcile() nebo spustit wp bs pages sync.

Chcete-li zabránit přepsání stránky po ručních úpravách, nastavte "sync": false v page.json.

Přenosná umístění zdrojů

Synchronizované soubory tématu se ukládají jako cesty relativní k tématu, nikoli jako absolutní cesty instalace. Soubory podřízeného a nadřazeného tématu si zachovávají samostatné identity, i když mají stejný relativní název souboru. Pomocné funkce stránky přesto vracejí vyřešené absolutní hodnoty template_path, content_path, layout_path a directory pro aktuální požadavek.

Díky tomu mohou CLI synchronizace a webové požadavky používat různé kořeny souborového systému, například na hostingu s omezeným přístupem, aniž by se narušily Markdown odpovědi, rozvržení, Tailwind skenování nebo sledování zdrojů pro předrenderování. Stávající absolutní cesty k šablonám se při čtení přepočítají podle nového umístění, pokud název adresáře šablony zůstane stejný. K jejich načtení není nutná synchronizace, migrace databáze ani zápis metadat při zpracování požadavku; přenosná umístění uloží až další ručně spuštěná synchronizace.

Adresář šablony, který je symbolickým odkazem, například do vývojové pracovní kopie, ukládá stejná umístění theme: bez ohledu na to, zda byl zdroj načten přes symbolický odkaz, nebo přes jeho cíl, a převádí je na nakonfigurovaný adresář šablony.

Soubory mimo aktivní podřízené a nadřazené šablony zůstávají podporovány na svých nakonfigurovaných absolutních cestách, s omezeními PHP open_basedir. Jejich umístění se automaticky nepřizpůsobí: po přesunutí externího zdroje aktualizujte jeho nakonfigurovanou cestu a spusťte ruční synchronizaci.

Vlastnictví polí příspěvku

postStatus nastavuje počáteční stav. Při dalších synchronizacích se zachovávají stávající stavy konceptu, čekajícího na schválení, soukromého, publikovaného i naplánovaného příspěvku, a to i s --authoritative. Koncept se znovu nepublikuje jen proto, že jeho soubor uvádí postStatus: "publish". Stávající chování při obnově osiřelých příspěvků zůstává beze změny: ruční synchronizace obnoví přesunutý do koše spravovaný příspěvek, pokud je jeho zdroj k dispozici. Chcete-li tomu zabránit, zamkněte stránku nebo zakažte synchronizaci.

Soubor nadále určuje název, slug, typ příspěvku, nadřazený příspěvek i nakonfigurované pořadí v nabídce. Úpravy těchto údajů v WordPress definici zdroje nezmění. Další ruční synchronizace znovu použije hodnoty ze souboru, pojmenuje dotčená pole v pages.<name>.overwritten a ve výstupu tabulky CLI zobrazí varování. Nadále platí nativní oprávnění WordPress, včetně prázdného slugu u příspěvků čekajících na schválení, pokud je synchronizující uživatel nemůže publikovat.

Pro integraci, která výslovně spravuje jinou zásadu stavů, použijte blockstudio/pages/update_post_data. Bloky s klíči zachovávají obsah bloku spravovaný v editoru; klíče nemění, kdo spravuje název ani slug příspěvku.

U stránek kolekcí zahrnují otisky manifest, loader, zdroj stránky, soubor rozvržení, metadata a související cesty ke zdrojům. Změny těchto vstupů se projeví při další explicitní synchronizaci.

Když se zdroj kolekce odstraní, Blockstudio odstraní vytvořenou stránku, aby po smazání zdrojového souboru nezůstávaly staré stránky kolekce. Ve výchozím nastavení se osiřelé stránky kolekce přesunou do koše. Pomocí blockstudio/pages/orphan_action lze místo toho vrátit trash, delete nebo keep.

Při požadavcích frontendu Blockstudio naplní registr stránek z již synchronizovaných publikovaných příspěvků. Koncepty a soukromé stránky jsou dostupné v kontextech administrace a synchronizace, ale pomocné funkce frontendu načítají pouze publikované stránky.

Rekonciliace při nasazení

Blockstudio\Pages::reconcile() je vstupním bodem nasazení PHP. Vyhledá úplný požadovaný inventář, porovná otisky zdrojů a synchronizačního modulu a vrátí strojově čitelný protokol:

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',
    ],
  ],
]);

Zpráva obsahuje discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, výsledky pro jednotlivé stránky, chyby při zjišťování a deterministický sourceIdentity.

Zamčené stránky mají status: "locked" a započítávají se samostatně, mimo nezměněné stránky. removedPages uvádí u každé odebrané stránky její name, key, postId a skutečný action (trash nebo delete); ponechané příspěvky ani příspěvky, které už byly přesunuty do koše, se nezapočítávají mezi nově odebrané. Výstup tabulky CLI také uvádí vytvořené, aktualizované, zamčené a odebrané stránky i stránky se zachovaným obsahem, včetně jejich ID příspěvků.

Pokud je výsledný příspěvek po parsování a sloučení podle klíčů totožný, nevolá se wp_update_post(), nemění se post_modified, nevytváří se revize a nespouštějí se hooky pro aktualizaci příspěvku. Výsledek má stav unchanged. Pokud se obsah zdroje liší od obsahu určeného klíči v editoru, preserved: true označuje toto rozhodnutí a započítává se do něj i celkový počet preserved na nejvyšší úrovni. Nový otisk zdroje a spravovaná metadata se přesto zaznamenají, takže další synchronizace beze změn neprovede žádné operace. preserved je další příznak, nikoli výlučný stav: stránka může zachovat obsah určený klíči a zároveň aktualizovat název spravovaný souborem nebo přidat další blok.

authoritative: true může uvolnit zámek synchronizace stránky a nahrazuje obsah definicí ze souboru místo zachování obsahu editoru podle klíčů. Při běžné explicitní synchronizaci ponechte hodnotu false. plan_valid: false, full: true, broad: true, chybějící identita předchozího zdroje nebo změněný otisk synchronizačního modulu označí průchod jako úplnou rekonciliaci (fullReconciliation v protokolu). Úplný inventář se porovnává při každém průchodu. Záznamy o přejmenování Git slouží pouze jako vodítka k identitě. Nikdy nenahrazují porovnání úplného inventáře.

Při shodných otiscích a nezměněných cestách za běhu se nezapisují příspěvky ani metadata příspěvků a nespouštějí se aktualizační háčky. Když se nezměněný zdroj přesune do nového adresáře vydání, rekonciliace obnoví pouze uložené cesty k šabloně, obsahu, rozvržení a adresáři; neaktualizuje post_content ani čas poslední změny příspěvku. Chybějící spravované stránky se odstraní až po dokončení celé rekonciliace bez chyb při vyhledávání nebo zápisu stránek.

Přímá rekonciliace API neoznačí nasazení za úspěšné. Po aktivaci a ověření odpovídajícího statického artefaktu a tras výslovně uložte vrácenou identitu:

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

wp bs pages sync uloží vrácenou identitu po úspěšném průchodu. Běžné spuštění WP-CLI pouze zaregistruje uložené typy příspěvků kolekcí a přepisovací pravidla. Stránky nevyhledává ani nesynchronizuje.

Pevná ID příspěvků

Ve výchozím nastavení WordPress automaticky přiřazuje ID příspěvků. Pokud stránku smažete a znovu vytvoříte, její ID se změní, čímž se přeruší externí odkazy, například nabídky nebo pevně zadané odkazy.

Pomocí postId můžete stránce pevně přiřadit konkrétní ID:

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

Při vytváření stránky předá Blockstudio ID do WordPress prostřednictvím import_id. Pokud je ID volné, WordPress je použije přesně. Pokud už toto ID patří nesouvisejícímu příspěvku, WordPress tiše automaticky přiřadí nové ID.

Při hledání existujících stránek kontroluje Blockstudio nejprve pevně přiřazené ID a teprve potom metadata nebo slug. Pokud tedy stránku smažete a znovu synchronizujete, získá stejné ID.

Sloučení bloků podle klíčů

Ve výchozím nastavení Blockstudio při změně souboru šablony nahradí celý obsah příspěvku novou šablonou. Veškeré úpravy provedené v editoru WordPress se tak ztratí.

Přidejte blokům atribut key, aby se uživatelské úpravy zachovaly i při synchronizaci šablon. Pokud šablona obsahuje bloky s klíči, Blockstudio sloučí změny šablony se stávajícím obsahem příspěvku místo jeho nahrazení.

Přidávání klíčů

Atribut key použijte na libovolném prvku HTML nebo <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"
/>

Klíče musí být jedinečné v celé šabloně. Klíč chrání celý blok i veškerý jeho obsah. Potomky uvnitř bloku s klíčem nemusíte opatřovat vlastními klíči. Mezi aktualizacemi šablony lze bloky s klíči přesouvat na libovolnou pozici nebo úroveň vnoření a jejich uživatelský obsah zůstane zachován.

Klíče fungují stejně i pro vlastní bloky Blockstudio. key jsou strukturální metadata synchronizace stránky; hodnoty vlastních polí zůstávají běžnými atributy Blockstudio. Když editor tato pole změní, pozdější synchronizace šablony zachová hodnoty z editoru a zároveň použije nezávislé změny šablony. Stránky vytvořené staršími verzemi, které mají klíč uvnitř dat vlastního pole, se při další synchronizaci automaticky převedou.

Jak funguje slučování

Když se soubor šablony změní a stránka se znovu synchronizuje:

Blok Chování
Blok s klíčem Uživatelský obsah a hodnoty polí Blockstudio se zachovají. Použijí se atributy a struktura spravované šablonou.
Blok bez klíče Zcela se nahradí verzí ze šablony (stejně jako bez klíčů)

Příklady

Uživatelské úpravy v blocích s klíčem zůstávají zachovány:

  1. Šablona definuje <p key="intro">Default intro.</p>
  2. Uživatel upraví odstavec v editoru na „Vlastní úvodní text.“
  3. Vývojář aktualizuje šablonu, přidá nový blok a změní rozvržení
  4. Při synchronizaci se v odstavci zachová „Vlastní úvodní text.“ a použije se nové rozvržení

Atributy ze šablony se stále použijí:

  1. Šablona obsahuje blok obálky s key="hero" a atributem url
  2. Vývojář změní atribut url obálky na nový obrázek pozadí
  3. Při synchronizaci se použije nový obrázek pozadí, ale uživatelské úpravy obsahu uvnitř obálky zůstanou zachovány

Okrajové případy

Situace Chování
Do šablony přidán nový blok s klíčem Zobrazí se s výchozím obsahem šablony
Blok s klíčem odebrán ze šablony Odstraní se z příspěvku
Změní se typ bloku (stejný klíč) Zcela se použije šablona, obsah se neslučuje
Duplicitní klíče Druhý výskyt se považuje za blok bez klíče
Šablona neobsahuje žádné klíče Úplné nahrazení (stejně jako bez klíčů)
Vynucená synchronizace Úplné nahrazení, klíče se ignorují
Uzamčený příspěvek Synchronizace se vůbec neprovede

Kombinace s ovládacími prvky úprav

Klíče, templateLock a blockEditingMode umožňují přesně řídit, co klienti mohou a nemohou dělat. Zde jsou běžné vzory pracovních postupů.

Zcela uzamčená stránka

Vývojář má vše pod kontrolou. Stránka má statické rozvržení, do kterého klienti nemohou vůbec zasahovat. Hodí se pro právní stránky, podmínky služby nebo jakoukoli stránku, kterou lze měnit pouze prostřednictvím kódu.

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>

Nejsou potřeba žádné klíče. Šablona je jediným zdrojem pravdy. Každá synchronizace přepíše celou stránku.

Uzamčené rozvržení s upravitelným obsahem

Nejběžnější vzor. Uzamkněte strukturu stránky, aby klienti nemohli přidávat, odebírat ani přesouvat bloky, ale umožněte jim upravovat text na konkrétních místech. Klíče zajistí, že se jejich úpravy zachovají i při aktualizacích šablony.

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>

Klient může upravovat nadpis hlavní sekce, popis a úvod k funkcím. Nic jiného. Text tlačítka, URL a obrázek na pozadí titulní plochy jsou pod kontrolou vývojáře. Když vývojář aktualizuje šablonu (e.g., přidá druhé tlačítko), pojmenované sekce zachovají klientův text.

Vyvíjející se šablona se zachovaným obsahem

Pro stránky, které se postupně rozrůstají. Vývojář přidává do šablony nové sekce a každá synchronizace doplní nový obsah, aniž by zasáhla do toho, co si klient už upravil.

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>

Nová sekce s referencemi a tlačítko se objeví po synchronizaci. Klientovy úpravy nadpisu, úvodu a služeb zůstanou nedotčené.

Jednorázová základní struktura

Vytvořte stránku se základní strukturou a pak ji celou předejte klientovi. Nastavte sync na false, aby běžná synchronizace stránku nikdy nevytvořila ani neaktualizovala, a jednou ji vytvořte pomocí Blockstudio\Pages::force_sync('blog'). Poté stránku plně vlastní klient.

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

wp bs pages sync tuto stránku přeskočí, takže ji force_sync() vytvoří jednou. Poté může klient bloky libovolně přidávat, odebírat a přesouvat. Změny šablony se ignorují.

Vazby bloků

Alternativou ke slučování podle klíčů je použití WordPress core pro Vazby blokůAPI, které propojí bloky s metadaty příspěvku. Nejde o funkci Blockstudio, ale o nativní WordPress API. Blockstudio pouze předá atribut metadata do vygenerovaného značkování bloku. Obsah je uložen v metadatech příspěvku místo ve značkování bloku, takže synchronizace šablony může značkování libovolně přepsat, protože editor čte metadata, nikoli innerHTML.

Předejte atribut metadata libovolnému prvku HTML nebo <block>:

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

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

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

Meta klíče musí být zaregistrovány s povolenou volbou show_in_rest:

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

Klíče a vazby

Vlastnost Klíče Vazby
Uložení obsahu Označení bloku (post_content) Metadata příspěvku (wp_postmeta)
Zachování při synchronizaci šablony Ano (sloučeno podle klíče) Ano (data jsou v metadatech)
Lze vyhledávat přes WP_Query Ne Ano (meta_query)
Dostupné v REST API Ne Ano
Vyžaduje registraci Ne Ano (register_post_meta)
Uživatel může přesouvat bloky Ne (šablona znovu vynutí strukturu) Ne (šablona znovu vynutí strukturu)

Oba přístupy lze použít v jedné šabloně. Klíče použijte pro sekce, kde záleží na struktuře bloků (e.g., skupina s více potomky). Vazby použijte pro jednotlivá pole, jejichž data chcete zpřístupnit i mimo editor bloků.

Šablony typů příspěvků

Pomocí templateFor nastavte stránku jako výchozí šablonu pro typ příspěvku:

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

Každý nový příspěvek tohoto typu začne s definovanou strukturou bloků.

Vlastní cesty

Ve výchozím nastavení Blockstudio prohledává get_template_directory() . '/pages'. Další cesty přidáte pomocí filtru:

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

Runtime integrace, které skládají soubory z několika kořenových adresářů, mohou nahradit prohledávání souborového systému logickým zdrojem pro vyhledávání. Manifesty stránek, rozvržení, loadery a zdrojové šablony se pak vyhledávají podle logické cesty, i když se vybrané soubory nacházejí v různých kořenových adresářích.

Filtry a akce

Vyhledávání stránek, synchronizace a směrování kolekcí zpřístupňují tyto body rozšíření:

Hook Typ Popis
blockstudio/pages/paths Filtr Přidá adresáře, ve kterých Blockstudio hledá zdroje stránek.
blockstudio/pages/collection_post_type_args Filtr Upraví argumenty register_post_type() pro vlastní typ příspěvku kolekce.
blockstudio/pages/template_candidates Filtr Upraví názvy souborů šablon, které se zvažují jako zdroj stránky.
blockstudio/pages/serve_markdown Filtr Povolí nebo zakáže nezpracované odpovědi Markdown.
blockstudio/pages/orphan_action Filtr Vrátí trash, delete nebo keep pro úklid osiřelých položek.
blockstudio/pages/docs_allowed_html Filtr Upraví povolené HTML pro obsah generovaný do dokumentace Markdown.
blockstudio/pages/allow_external_loader_path Filtr Povolí cestu paths zavaděče mimo kořen adresáře kolekce.
blockstudio/pages/manifest_scan_interval Filtr Nastaví maximální stáří mezipaměti manifestu z období před 7.6.2, která může při aktualizaci posloužit jako základ pro uloženou konfiguraci za běhu.
blockstudio/pages/create_post_data Filtr Upraví data příspěvku před vytvořením synchronizované stránky.
blockstudio/pages/update_post_data Filtr Upraví data příspěvku před aktualizací synchronizované stránky.
blockstudio/pages/sync_engine_inputs Filtr Přidá verzi parseru, mapování nebo migrace, která má záměrně jednorázově rozšířit rozsah sladění.
blockstudio/pages/post_created Akce Spustí se po vytvoření synchronizovaného příspěvku stránky.
blockstudio/pages/post_updated Akce Spustí se po aktualizaci synchronizovaného příspěvku stránky.
blockstudio/pages/synced Akce Spustí se po dokončení synchronizace registru stránek.
blockstudio/pages/reconciled Akce Spustí se po ručním sladění a obdrží jeho strojově čitelnou zprávu.
blockstudio/pages/renderers Akce Zaregistruje vykreslovače stránek pomocí Blockstudio\Page_Renderers::register(). Spustí se jednou pro každý požadavek.
blockstudio/pages/rendered Akce Spustí se po vykreslení stránky komponenty a obdrží stránku, její HTML i závislosti.
blockstudio/pages/layout_error Akce Spustí se, když nelze vykreslit rozvržení; obdrží chybu, cestu k rozvržení a stránku.

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]);

Viz Reconciliace nasazení, kde najdete sémantiku argumentů, pole protokolu a ověřenou hranici identity zdroje.

Globální pomocné funkce jsou dostupné pro šablony a rozvržení:

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

Pole stránek vrácená funkcemi Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() a globálními pomocnými funkcemi zahrnují identitu synchronizovaného příspěvku, cesty ke zdroji a šabloně, metadata kolekce a cesty, typ obsahu, zásady synchronizace, typ a stav příspěvku, zásady úprav, vlastní metadata a klíč permalink. Metadata kolekce se načítají z poslední úspěšné explicitní reconciliace. Běžné požadavky rekonstruují tato runtime data z uložené konfigurace a metadat synchronizovaných příspěvků, aniž by četly stromy zdrojových stránek. Třída Pages neposkytuje samostatnou metodu permalinku.

Vytváření stránek ze souborů

Uzamčení šablony, režimy úprav bloků, slučování podle klíčů a řízení toho, co mohou klienti upravovat.