Strony
Strony to szablony oparte na plikach, synchronizowane z bazą danych WordPress jako wpisy. Synchronizacja jest jawna: uruchom wp bs pages sync lub wywołaj API stron, gdy chcesz zastosować zmiany w źródłach. Wczytanie frontendu lub panelu administracyjnego WordPress nigdy nie wyszukuje wszystkich stron ani nie modyfikuje wpisów stron.
Strony można definiować w pojedynczym folderze page.json, jako samodzielne pliki Markdown lub jako zbiór z manifestem pages.json. Zbiory przydają się do dokumentacji, baz wiedzy, bibliotek stron docelowych oraz innych zestawów zagnieżdżonych stron, które mają być generowane z plików.
page.json
Aby zdefiniować stronę za pomocą JSON, dodaj plik konfiguracyjny page.json:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
Właściwości
| Właściwość | Typ | Domyślnie | Opis |
|---|---|---|---|
name |
string |
wymagane | Unikalny identyfikator strony |
title |
string |
Automatycznie z nazwy | Tytuł strony |
slug |
string |
Taki sam jak nazwa | Slug URL strony |
path |
string |
"." |
Ścieżka logiczna w kolekcji |
order |
integer |
0 |
Kolejność w menu synchronizowanego wpisu |
postType |
string |
"page" |
Typ wpisu WordPress |
postStatus |
string |
"draft" |
Status nowych wpisów (publish, draft, pending, private) |
postId |
integer |
– | Przypnij stronę do określonego identyfikatora wpisu WordPress |
blockEditingMode |
string |
– | Tryb edycji bloków: "default", "contentOnly" lub "disabled" |
templateLock |
string|false |
"all" |
Tryb blokady: "all", "insert", "contentOnly" lub false |
templateFor |
string|null |
null |
Ustaw jako domyślny szablon dla typu wpisu |
sync |
boolean |
true |
Określa, czy zwykłe jawne uzgadnianie może utworzyć lub zaktualizować wpis |
render |
string|object|false |
– | Renderuj stronę za pomocą zarejestrowanego renderera stron (zob. strony komponentów) |
Wśród page.json, danych frontmatter i wpisów loadera rozpoznawane klucze to: blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock i title. Każdy niewymieniony wyżej klucz jest przechowywany w tablicy meta strony.
Źródła treści
Definicja strony określa, który wpis WordPress ma istnieć. Źródło treści określa, jaki znacznik bloku zostanie zapisany w tym wpisie.
Gdy folder strony zawiera plik page.json, Blockstudio szuka sąsiedniego pliku źródłowego w następującej kolejności:
| Plik | Zastosowanie |
|---|---|
index.php |
Znaczniki bloków podobne do HTML, odczytywane bez zmian (kod PHP nie jest wykonywany) |
index.blade.php |
Treść szablonu Blade |
index.twig |
Treść szablonu Twig |
index.md |
Treść Markdown |
page.json może też zawierać bezpośrednio kod markdown lub html zamiast korzystać z sąsiedniego pliku:
{
"name": "intro",
"title": "Intro",
"markdown": "# Intro\n\nThis page is generated from inline markdown."
}
{
"name": "notice",
"title": "Notice",
"html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}
Zbiory udostępniają dwa dodatkowe tryby źródeł:
- Pliki Markdown wykrywane bezpośrednio w strukturze folderów zbioru.
- Wpisy loadera zwracane przez
loader.php.
Wpisy loadera mogą używać markdown, html lub content z contentType. Mogą też wskazywać lokalny plik file lub template. Typ źródeł plikowych i szablonów jest określany na podstawie rozszerzenia, chyba że jawnie ustawiono contentType.
Obsługiwane wartości contentType to php, blade, twig, markdown i html. Markdown najpierw jest konwertowane do HTML, a następnie parsowane do natywnych bloków WordPress. Źródła PHP, Blade, Twig i HTML są przetwarzane przez standardowy parser stron Blockstudio.
Klasy w blokach rdzenia
class w elemencie HTML przypisanym do bloku rdzenia staje się jego className.
Jawny znacznik bloku rdzenia może bezpośrednio używać className. Obie formy zachowują
klasy zapisanej otoczki bloku, obok klas generowanych przez WordPress:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
Jeśli obecne są obie właściwości, pierwszeństwo ma className. Ta konwersja
dotyczy wyłącznie bloków rdzenia: mapowanie bloku niestandardowego pozostawia jego pole class
bez zmian. Klasy stylu przycisku, takie jak is-style-outline, należą do
otoczki przycisku, a nie jego odnośnika.
Uruchom wp bs pages sync, aby zastosować poprawki parsera do wcześniej zsynchronizowanych
stron. Aktualizacje parsera zostaną rozpoznane podczas następnej jawnej synchronizacji, nawet bez edycji
pliku źródłowego. Zablokowane strony i strony z sync: false zachowują
standardowe zabezpieczenia; żądania frontendu nigdy nie wykonują tej synchronizacji.
Zserializowane bloki WordPress
Źródła stron i wzorców mogą też zawierać zserializowane bloki skopiowane z edytora kodu WordPress:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
Gdy źródło zawiera separator bloku <!-- wp:... -->, Blockstudio używa natywnego parsera bloków WordPress dla całego źródła. Atrybuty, zagnieżdżone bloki, bloki dynamiczne, takie jak Query Loop, oraz bloki Blockstudio zachowują swoją serializowaną strukturę. HTML poza komentarzami bloków pozostaje natywną zawartością swobodną HTML; nie jest mapowana na dodatkowe bloki. Nie mieszaj znaczników bloków HTML Blockstudio z tym formatem i nie oczekuj, że zostaną przekonwertowane. Zwykłe komentarze HTML nie włączają trybu bloków serializowanych.
Strony Markdown
Używaj Markdown, gdy treść ma znajdować się w plikach, ale po synchronizacji nadal być edytowalną zawartością bloków WordPress. Źródło Markdown jest konwertowane podczas synchronizacji na znaczniki bloków. Synchronizowany wpis przechowuje bloki, a nie surową treść Markdown.
Z Markdown można korzystać na trzy sposoby:
| Źródło | Wymagane frontmatter? | Uwagi |
|---|---|---|
Samodzielny plik pages/example/index.md |
Tak | Frontmatter określa tożsamość strony. |
page.json i index.md |
Nie | page.json definiuje stronę, a Markdown zawiera treść. |
| Markdown w zbiorze | Nie | Zbiór określa name i path na podstawie lokalizacji pliku. |
Samodzielny plik index.md bez frontmatter jest pomijany, ponieważ Blockstudio nie ma tożsamości strony do synchronizacji. Wpis Markdown w zbiorze nie wymaga frontmatter, ponieważ manifest zbioru i ścieżka pliku określają tę tożsamość.
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
Możesz też połączyć page.json z index.md. W takim przypadku page.json definiuje stronę, a index.md zawiera treść. Frontmatter w index.md zastępuje pasujące wartości page.json.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
title: API Reference
order: 20
---
# Reference
This page uses `page.json` with Markdown content.
W zbiorze Markdown ścieżka pliku staje się logiczną ścieżką strony, chyba że zmieni ją frontmatter:
| Plik | Domyślna ścieżka |
|---|---|
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 |
Nierozpoznane klucze frontmatter są zachowywane w tablicy meta strony. Pozwala to dołączać dane, takie jak section lub description, i odczytywać je z PHP API.
Markdown jest parsowane jako GitHub Flavored Markdown. Dozwolony jest surowy kod HTML, niebezpieczne odnośniki są usuwane, a nagłówki bez jawnego ID otrzymują stabilny identyfikator. Zagnieżdżone frontmatter YAML wymaga dołączonego parsera YAML.
Surowy kod Markdown
Źródła plikowe Markdown mogą udostępniać oryginalny kod źródłowy Markdown zewnętrznym narzędziom i odbiorcom dokumentacji. Kod Markdown podany bezpośrednio nie ma pliku źródłowego, więc jest synchronizowany do bloków, ale nie generuje surowej odpowiedzi .md.
Zażądaj strony z sufiksem .md, na przykład https://example.com/docs/reference.md. Możesz też wysłać nagłówek Accept: text/markdown do zwykłego URL strony:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
Frontmatter jest usuwane z odpowiedzi. Udane odpowiedzi z surową treścią Markdown zwracają Content-Type: text/markdown, X-Robots-Tag: noindex i kanoniczny nagłówek Link z powrotem do strony HTML. Brakujące trasy .md zwracają prawdziwy kod 404.
Negocjacja działa ze statycznym prerenderowaniem: żądanie, którego nagłówek Accept zawiera text/markdown, nigdy nie otrzymuje odpowiedzi z magazynu prerenderowania ani z mechanizmu wczesnego serwowania, więc trafia do WordPress i obsługi Markdown. Odpowiedzi HTML z prerenderowania, HTML strony obsługującej również negocjację Markdown oraz Markdown obsługiwane przez Accept zawierają Vary: Accept, dzięki czemu pamięci podręczne respektujące Vary rozróżniają te odpowiedzi. CDN, który indeksuje pamięć podręczną wyłącznie według URL, wymaga własnej reguły pomijania pamięci podręcznej dla takich żądań. Pages::negotiates_markdown( $post_id ) informuje, czy strona odpowiada na żądania Markdown.
Zbiór Markdown zachowuje ten sam kształt URL dla surowego Markdown:
| Strona URL | Surowe Markdown URL |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
Wyłączanie odpowiedzi z surową treścią Markdown za pomocą filtra blockstudio/pages/serve_markdown:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Żądanie .md URL, które nie wskazuje strony opartej na Markdown, zwraca 404 tylko wtedy, gdy ścieżka należy do zbioru stron. Poza wszystkimi zbiorami Blockstudio pozostawia żądanie do obsługi przez WordPress i inne wtyczki.
Strony komponentów
Strona komponentu jest renderowana przez renderer stron, zamiast być
przechowywana jako bloki. Blockstudio nie zawiera renderera. Motyw lub wtyczka rejestruje go
dla obsługiwanych plików wejściowych, na przykład renderer React dla page.tsx, a
Blockstudio wywołuje go z użyciem strony, wpisu WordPress i wyrenderowanej zawartości slotu.
pages/legal-notice/
page.json
page.tsx
data.php
{
"name": "legal-notice",
"title": "Legal Notice",
"slug": "legal-notice",
"postStatus": "publish",
"render": { "entry": "page.tsx", "data": "data.php" }
}
render jest jawne. Katalog zawierający index.php i page.tsx, ale bez
render, pozostaje zwykłą stroną, więc dodanie renderera nigdy nie spowoduje
ponownego wyrenderowania istniejącej strony. Dostępne formy:
| Wartość | Znaczenie |
|---|---|
"page.tsx" |
Tylko plik wejściowy, bez loadera danych |
{ "entry": "page.tsx", "data": "data.php" } |
Plik wejściowy i loader danych |
{ "entry": "page.tsx", "renderer": "react" } |
Plik wejściowy z jawnym identyfikatorem renderera |
false |
Brak renderera, nawet gdy domyślna konfiguracja kolekcji go wskazuje |
Ścieżki są rozwiązywane względem katalogu strony lub, w przypadku wpisów loadera, względem katalogu głównego kolekcji. Muszą pozostać w obrębie źródła wykrywania, chyba że zezwala na to blockstudio/pages/allow_external_loader_path. Bez renderer używany jest renderer obsługujący rozszerzenie pliku wejściowego. render wskazujące nieistniejący plik wejściowy lub plik danych, nieznany renderer albo rozszerzenie, którego nie obsługuje żaden renderer, powoduje błąd wykrywania, który przerywa uzgadnianie, zanim cokolwiek zostanie usunięte.
Co przechowuje synchronizacja
Synchronizacja zapisuje jeden blok blockstudio/page. Jeśli katalog strony zawiera również źródło index.*, jest ono analizowane jak każde źródło strony i staje się blokami wewnętrznymi tego bloku, czyli jego slotem:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
Treści należące do WordPress, takie jak shortcode’y, umieszczaj w slocie. Źródło zawierające tylko jeden shortcode, na przykład [download_checkout],
jest zapisywane jako blok core/shortcode, więc wokół jego wyniku nie jest dodawany akapit. Pozostaje ono w
post_content, dzięki czemu uwzględniają je kontrole has_shortcode(), bloki slotu z kluczami łączą się ze zmianami w edytorze tak jak zagnieżdżone bloki z kluczami, a do_shortcode rozwija
shortcode’y raz, z użyciem zwykłego priorytetu the_content, po ich opakowaniu przez renderer.
Definicja renderowania jest zapisywana wraz z wpisem jako przenośne ścieżki theme:. Odcisk strony obejmuje definicję, a nie bajty pliku wejściowego ani loadera danych: edycja page.tsx lub data.php nie zmienia wpisu, a jej efekty są widoczne dla odwiedzających podczas renderowania i przez wstępne renderowanie grafu statycznego, które rejestruje plik wejściowy, loader danych i każdy plik zgłoszony przez renderer.
Rejestrowanie renderera
Rejestruj renderery w ramach akcji blockstudio/pages/renderers. Jest ona uruchamiana raz
na żądanie, przed pierwszym wykrywaniem lub renderowaniem, dzięki czemu wp bs pages sync i
żądania z frontendu widzą ten sam rejestr.
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',
)
);
}
);
Identyfikatory rendererów są zapisywane małymi literami. Rozszerzenie lub nazwa układu może należeć tylko do jednego renderera, a layout.php pozostaje własnym układem należącym do Blockstudio. Funkcja wywoływalna otrzymuje jedno żądanie:
| Klucz | Wartość |
|---|---|
kind |
page lub layout dla układu renderera układu |
renderer |
Identyfikator renderera |
entry |
Bezwzględna ścieżka do pliku wejściowego |
data |
Bezwzględna ścieżka do loadera danych lub null |
page |
Kanoniczne dane strony, w tym meta |
post_id |
Identyfikator wpisu WordPress |
slot |
Wyrenderowana zawartość slotu lub treść strony w przypadku układu |
context |
frontend, rest, feed lub cli |
Zwraca HTML, pliki odczytane podczas renderowania oraz opcjonalne zasoby:
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 pochodzi z typu żądania, a nigdy od odwiedzającego, więc renderer nie może naruszyć zgodności bajtowej między zalogowanymi i anonimowymi użytkownikami przez odczytanie tej wartości. Błąd renderera powoduje wyjątek: strona nie wyświetla pustej treści. W REST podglądzie edytora blok pokazuje błąd jako powiadomienie. Po pomyślnym renderowaniu działanie blockstudio/pages/rendered otrzymuje stronę, wartość HTML i jej zależności.
assets wymienia pliki skryptów i stylów potrzebne stronie. Są one przetwarzane jak zasoby bloków (konwencja *.inline.*, moduły ES, minifikacja i ?ver), a strona wypisuje je raz, przez ten sam bufor co zasoby bloków, dzięki czemu strona renderowana z wyprzedzeniem je zawiera. Zasób może ustawić version, aby zastąpić jego wartość ?ver. Kod poza rendererem może korzystać z tego samego kanału przez Blockstudio\Assets::register_owner(), które zwraca komentarz-znacznik do wypisania.
Edytor
W edytorze blockstudio/page wyświetla renderowany po stronie serwera podgląd strony, w którym slot jest blokami wewnętrznymi podlegającymi hierarchii templateLock strony. Tego bloku nie można wstawić, zduplikować ani zagnieździć w innym bloku.
Zbiory stron
Zbiór to folder z manifestem pages.json. Grupuje wiele źródeł stron pod jednym slugiem zbioru, stosuje ustawienia domyślne, obsługuje zagnieżdżone ścieżki i może automatycznie zarejestrować dedykowany typ wpisu.
pages/
docs/
pages.json
layout.php
index.md
guide/
install/
index.md
reference/
page.json
index.md
loader.php
{
"collection": "docs",
"title": "Documentation",
"postType": "bs_docs",
"postTypeArgs": {
"label": "Docs",
"rewrite": {
"slug": "docs"
},
"supports": ["title", "editor", "page-attributes"]
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
| Właściwość | Typ | Opis |
|---|---|---|
collection / slug / name |
string |
Identyfikator kolekcji. collection to najczytelniejsza forma, która staje się publiczną podstawą URL. |
title |
string |
Czytelny dla człowieka tytuł kolekcji. |
postType |
string |
Typ wpisu dla generowanych stron. Domyślnie page. Jeśli nie istnieje, Blockstudio go rejestruje. |
postTypeArgs |
object |
Argumenty przekazywane do register_post_type(), gdy Blockstudio rejestruje typ wpisu kolekcji. |
defaults |
object |
Domyślne właściwości strony stosowane do każdej strony w kolekcji. Domyślna wartość render dotyczy strony tylko wtedy, gdy jej wpis znajduje się w katalogu stron. |
scope |
string |
collection (domyślnie) lub site. Zobacz Kolekcje witryn. |
meta |
object |
Niestandardowe metadane kolekcji. Nieznane klucze manifestu są również przechowywane w meta. |
Ścieżki stron w zbiorze są ścieżkami logicznymi. Strona z path: "guide/install" jest synchronizowana jako strona podrzędna względem guide, a guide jest synchronizowana jako strona podrzędna katalogu głównego zbioru, jeśli istnieją odpowiednie strony nadrzędne.
Jeśli w hierarchicznym zbiorze znajduje się strona zagnieżdżona, ale nie istnieje źródło strony nadrzędnej na pośrednim poziomie, Blockstudio generuje pustą stronę-kontener dla tej ścieżki, aby zachować pełną hierarchię WordPress. Niehierarchiczne typy wpisów (bez obsługi stron nadrzędnych page-attributes) nie generują pustych kontenerów. Korzystają ze ścieżki zbioru zapisanej we wpisie, więc zagnieżdżone ścieżki, takie jak guide/install i setup/install, mogą współistnieć, mimo że obie kończą się na install.
Typy wpisów zbioru i adresy URL
Ustaw postType w manifeście zbioru, aby synchronizować wszystkie strony w zbiorze z tym typem wpisu. Nie musisz powtarzać tej samej wartości w defaults. Poszczególne strony nadal mogą zmieniać postType w frontmatter lub page.json.
Jeśli typ wpisu nie istnieje, Blockstudio rejestruje go z show_in_rest: true, konfiguracją edytora podobną do stron i slugiem zbioru jako publiczną podstawą URL. postTypeArgs może zastąpić argumenty rejestracji. Reguły przepisywania adresów URL typu wpisu zbioru są odświeżane automatycznie po zmianie zarejestrowanych typów wpisów zbioru lub argumentów przepisywania, więc nie trzeba ponownie zapisywać bezpośrednich odnośników WordPress.
Adresy URL zbioru składają się ze slugu zbioru i logicznej ścieżki każdej strony path:
| Ścieżka źródłowa | Publiczny URL |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
Ten model URL działa zarówno z hierarchicznymi, jak i niehierarchicznymi typami wpisów kolekcji. Blockstudio przekierowuje również zdublowane adresy URL, takie jak /docs/docs/ lub /docs/docs/getting-started/, do kanonicznego URL.
Strony kolekcji udostępniają surowe Markdown pod tymi samymi adresami URL (zobacz Surowe Markdown).
Jeśli zmienisz kolekcję z postType: "page" na własny typ wpisu, Blockstudio przeniesie już zsynchronizowane wpisy kolekcji w miejsce, jeśli ich zapisana tożsamość strony będzie zgodna. Dzięki temu zachowane zostaną identyfikatory wpisów, metadane i istniejąca treść, a jednocześnie unikniesz duplikowania wpisów ze starym typem. Nieaktualne wpisy kolekcji są usuwane ze wszystkich statusów wpisów zgodnie z filtrem blockstudio/pages/orphan_action.
Kolekcje witryn
Manifest z "scope": "site" grupuje wszystkie znajdujące się pod nim strony, nie zmieniając ich w strony kolekcji. Użyj go w katalogu głównym drzewa stron witryny, aby zastosować wspólne ustawienia domyślne i wyświetlić strony witryny za pomocą blockstudio_page_tree( 'my-site' ).
{
"collection": "my-site",
"title": "My Site",
"scope": "site",
"defaults": {
"postStatus": "publish",
"templateLock": "all",
"render": { "entry": "page.tsx", "data": "data.php" }
}
}
Strony kolekcji witryny zachowują dokładnie tę samą tożsamość, którą miały bez manifestu, więc dodanie go do istniejącego drzewa nie aktualizuje żadnych rekordów wpisów ani niczego nie tworzy czy nie przenosi do kosza:
- Klucze pozostają globalne:
Pages::get_page( 'home' )i zapisane klucze stron nadal do siebie pasują. - Adresy URL stron pozostają WordPress. Nie mają zastosowania reguły przepisywania dla kolekcji, filtr łączy bezpośrednich ani przekierowania z podwójnym URL; nie są też generowane puste strony kontenerów.
- Ścieżki logiczne, identyfikatory, strony nadrzędne i tożsamości źródłowe są takie jak w przypadku samodzielnych stron, a układy są określane na podstawie najbliższego przodka.
- Zagnieżdżone manifesty
pages.jsonzachowują własne kolekcje, a ich poddrzewa są wyłączone z kolekcji witryny. - Ustawienia domyślne są stosowane dla każdej strony osobno: domyślna wartość
renderdotyczy tylko stron, których katalog zawiera odpowiedni wpis, więc strony z shortcode’ami i Markdown zachowują swoje źródła.
Moduły ładujące kolekcje
Kolekcje mogą zawierać zaufany lokalny element loader.php. Użyj go, gdy strony kolekcji pochodzą z innego lokalnego źródła, na przykład z zewnętrznego folderu dokumentacji, pakietu lub wygenerowanego manifestu.
Moduł ładujący jest uruchamiany podczas jawnego wykrywania i synchronizacji stron. Powinien działać deterministycznie i lokalnie. Unikaj pobierania zdalnej zawartości z loader.php, ponieważ uzależniłoby to synchronizację wdrożenia od tej usługi.
<?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',
),
),
);
Moduł ładujący może zwrócić tablicę z kluczami pages, meta i paths:
| Klucz | Opis |
|---|---|
pages |
Lista tablic stron. Każda strona obsługuje te same rozpoznawane klucze co page.json i frontmatter Markdown. |
meta |
Metadane scalane z tablicą meta każdej strony wygenerowanej przez loader. |
paths |
Dodatkowe lokalne katalogi wykrywane jako część tej kolekcji. Wpisy mogą być ciągami znaków lub obiektami ścieżek. |
render |
Definicja renderowania dla każdej strony Markdown wykrytej w paths. |
W skróconej formie moduł ładujący może zwrócić zwykłą listę tablic stron.
Wpisy stron modułu ładującego mogą udostępniać zawartość na następujące sposoby:
| Postać | Opis |
|---|---|
markdown |
Zawartość Markdown umieszczona bezpośrednio. |
html |
Zawartość HTML umieszczona bezpośrednio. |
content + contentType |
Ogólna zawartość umieszczona bezpośrednio. contentType musi wskazywać na markdown lub html. |
file |
Lokalne źródło plikowe. Typ jest określany na podstawie rozszerzenia, chyba że ustawiono contentType. |
template |
Alias dla file. |
Odwołania do plików w module ładującym mogą wskazywać źródła PHP, Blade, Twig, Markdown lub HTML. Ścieżki względne są rozwiązywane względem katalogu głównego kolekcji. Ścieżki bezwzględne i ścieżki poza katalogiem głównym kolekcji są dozwolone tylko wtedy, gdy zezwala na nie filtr blockstudio/pages/allow_external_loader_path.
Strony modułu ładującego domyślnie mają generated: true. Gdy wygenerowana strona modułu ładującego zniknie z jego danych wyjściowych, Blockstudio podczas następnej synchronizacji uzna zsynchronizowany wpis za osierocony i usunie go zgodnie z filtrem blockstudio/pages/orphan_action.
Katalogi wymienione w paths są wykrywane tak jak zwykłe foldery kolekcji. Mogą zawierać pliki Markdown lub foldery page.json. Jeśli te ścieżki znajdują się poza katalogiem głównym kolekcji, obowiązuje ten sam filtr ścieżek zewnętrznych.
Użyj wpisu tekstowego, gdy zewnętrzny katalog ma zachować własne ścieżki logiczne. Użyj wpisu obiektowego, gdy katalog ma zostać zamontowany pod prefiksem ścieżki kolekcji:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
Przy tej konfiguracji cli-docs/index.md staje się w kolekcji path: "cli", a cli-docs/getting-started.md staje się path: "cli/getting-started". Prefiksy zapobiegają też kolizjom nazw generowanych stron, dzięki czemu każdy z kilku zamontowanych katalogów może zawierać index.md lub getting-started.md. Ustaw preserveNames na true w obiekcie ścieżki, jeśli jawne wartości name z metadanych frontmatter page.json lub Markdown mają zostać zachowane.
Właściwości obiektu ścieżki:
| Właściwość | Typ | Opis |
|---|---|---|
path |
string |
Lokalny katalog do wykrycia. Ścieżki względne są rozwiązywane względem katalogu głównego kolekcji. |
prefix |
string |
Opcjonalny prefiks ścieżki logicznej w obrębie kolekcji. |
preserveNames |
boolean |
Zachowuje jawne nazwy stron zamiast generować je na podstawie ścieżki z prefiksem. Domyślnie false, gdy ustawiono prefix. |
meta |
object |
Metadane scalane z każdą stroną wykrytą w tej ścieżce. W przypadku powielonych kluczy pierwszeństwo mają metadane strony. |
render |
string|object |
Definicja renderowania dla stron Markdown z tej ścieżki, zastępująca definicję loadera render. |
Renderowanie Markdown za pomocą komponentu
Przy użyciu render strony Markdown wykryte przez loader są renderowane przez renderer stron, zamiast być przechowywane jako bloki:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
Nadal są to strony Markdown: typ treści, ścieżka treści, odpowiedzi .md i frontmatter pozostają bez zmian. Synchronizacja zapisuje jeden blok blockstudio/page, którego wewnętrzne HTML to skonwertowana wartość Markdown, oczyszczana, gdy kolekcja oczyszcza swoją treść, zamiast sparsowanych bloków, dzięki czemu post_content zachowuje tekst dokumentu. Renderer otrzymuje tę wartość HTML jako slot i może odczytać źródło z page.content_path. Ścieżki względne są rozwiązywane względem katalogu głównego kolekcji; zewnętrzny filtr ścieżek działa tak samo jak dla ścieżek. Strona, której frontmatter ustawia własne render lub render: false, jest pomijana.
Układy
Plik layout.php opakowuje renderowanie strony opartej na pliku w interfejsie. Nie zastępuje zsynchronizowanego post_content zapisanego w WordPress ani nie opakowuje obszaru edytora. Układ jest uruchamiany wyłącznie przy żądaniach pojedynczych stron w interfejsie.
W przypadku kolekcji umieść layout.php obok pages.json, aby opakować każdą stronę tej kolekcji w interfejsie:
<?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() wyświetla treść strony, którą WordPress normalnie renderowałby przez the_content. Jeśli układ nie wyświetla blockstudio_page_content(), zawartość strony jest celowo ukryta.
Układy mogą korzystać z funkcji pomocniczych strony:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
Zagnieżdżone strony spoza kolekcji mogą również dziedziczyć najbliższy nadrzędny layout.php w drzewie pages. W przypadku stron kolekcji układ katalogu głównego kolekcji jest zapisany w każdym zsynchronizowanym wpisie i uwzględniany w odcisku strony, więc zmiany układu zostaną zastosowane przy następnej synchronizacji.
Układy rendererów
Układem może być również wpis renderera, na przykład layout.tsx dla renderera rejestrującego layouts: ["layout.tsx"]. Jest on wyszukiwany w tych samych miejscach co layout.php, a opcjonalny plik layout.data.php obok niego pełni funkcję loadera danych. W czasie renderowania renderer otrzymuje kind: "layout" i wyrenderowaną treść strony jako slot, z takim samym priorytetem the_content jak layout.php. Katalog może zawierać layout.php albo jeden układ renderera, ale nie oba; jednoczesne występowanie obu elementów powoduje błąd wykrywania. Błąd układu wywołuje blockstudio/pages/layout_error i pozostawia treść strony bez otaczającej ją struktury, tak jak w przypadku layout.php.
Tryb edycji bloków
Właściwość blockEditingMode określa sposób edytowania bloków w edytorze. Ustaw domyślną wartość dla strony w page.json i nadpisuj ją dla poszczególnych elementów w szablonie:
{
"name": "about",
"title": "About Us",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
| Wartość | Opis |
|---|---|
"default" |
Pełna edycja. Bloki można zaznaczać, przenosić i edytować |
"contentOnly" |
Tylko edycja tekstu. Tekst bloku można edytować, ale ustawienia i struktura są zablokowane |
"disabled" |
Brak edycji. Bloki są całkowicie nieinteraktywne |
Nadpisania dla poszczególnych elementów ustawia się jako atrybuty HTML na dowolnym elemencie (<h1>, <p>, <div> itd.) lub na elementach <block>. Nadrzędne bloki kontenerów nadpisanych elementów są automatycznie ustawiane na contentOnly, aby ich elementy podrzędne pozostały dostępne. To kaskadowe działanie przebiega od nadpisanego elementu do głównego elementu strony, więc wystarczy ustawić blockEditingMode na elementach, które mają być edytowalne.
Blokada szablonu
Właściwość templateLock określa, jak użytkownicy mogą edytować stronę w edytorze:
| Wartość | Dodawanie/usuwanie | Przenoszenie | Edycja treści |
|---|---|---|---|
"all" |
Nie | Nie | Nie |
"insert" |
Nie | Tak | Tak |
"contentOnly" |
Nie | Nie | Tak |
false |
Tak | Tak | Tak |
Po ustawieniu templateLock, Blockstudio wyłącza możliwość odblokowywania bloków za pomocą UI edytora.
Trasy wirtualne
Niektóre dokumenty nie mają odpowiadającego im wpisu: wygenerowane z danych odniesienie do komponentu, katalog lub obszar konta. Zarejestruj je jako trasy wirtualne zamiast samodzielnie podłączać template_redirect:
add_action( 'init', function () {
Blockstudio\Virtual_Routes::register(
'components',
function ( $component, string $rest ) {
get_header();
echo my_component_page( $component );
get_footer();
},
[
'prefix' => true,
'match' => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
'title' => fn ( $component ) => my_component_title( $component ),
'urls' => fn () => my_component_paths(),
]
);
} );
Ścieżka jest względna względem strony głównej witryny. W przypadku prefix trasa obsługuje również każdą ścieżkę podrzędną, a match otrzymuje jej pozostałą część (pusty ciąg dla samej trasy) i zwraca wartość przekazywaną funkcji zwrotnej renderowania albo null, aby pozostawić URL dla WordPress, które następnie standardowo odpowiada na 404. Funkcja zwrotna renderowania wyświetla dokument lub zwraca go jako ciąg znaków; title to ciąg znaków albo funkcja zamknięcia, która otrzymuje dopasowaną wartość.
W przypadku dopasowanego żądania Blockstudio uniemożliwia WordPress oznaczenie go jako 404, a redirect_canonical przekierowanie go, usuwa stan pojedynczej strony zgłaszany przez główne zapytanie, ustawia status (domyślnie status, 200) i renderuje dokument z priorytetem template_redirect Virtual_Routes::PRIORITY. Dzieje się to zaraz po otwarciu bufora wyjściowego przez Blockstudio z priorytetem Assets::BUFFER_PRIORITY, więc gotowy dokument otrzymuje zasoby bloków, spakowane zasoby UI i skompilowane Tailwind jak każda strona, a także przed redirect_canonical z priorytetem 10. Procedura obsługi samodzielnie renderująca cały dokument musi również działać po Assets::BUFFER_PRIORITY, inaczej przetwarzanie zostanie pominięte. Ścieżki z urls (domyślnie sama ścieżka trasy, jeśli nie jest trasą prefiksową) są dodawane do kompilacji wstępnego renderowania statycznego, a Virtual_Routes::urls() zwraca je jako bezwzględne adresy URL mapy witryny.
Virtual_Routes::match( $path ) rozwiązuje ścieżkę tak jak żądanie.
Działanie synchronizacji
Wpisy stron zmieniają się wyłącznie w wyniku jawnej operacji synchronizacji:
wp bs pages sync
Polecenie wykrywa pełny wykaz źródeł, tworzy lub aktualizuje zmienione wpisy, usuwa potwierdzone osierocone wpisy, odświeża konfigurację tras kolekcji i skompilowanej templateFor oraz raportuje wprowadzone zmiany. Dodaj --authoritative, aby zastąpić zarządzaną zawartość zamiast zachowywać treść edytora powiązaną z kluczami, oraz --full, aby oznaczyć przebieg jako pełne uzgadnianie niezależnie od zapisanej tożsamości źródła:
wp bs pages sync --authoritative --full
Standardowe żądania do frontendu, panelu administracyjnego, AJAX, REST, cron i ogólne żądania inicjalizacyjne WP-CLI nie przeprowadzają pełnego wykrywania stron, nie odpytują zarządzanego rejestru uzgodnień ani nie zapisują wpisów stron. Korzystają z wcześniej zsynchronizowanych wpisów WordPress oraz zwięzłej konfiguracji kolekcji i szablonów typów wpisów, zapisanej podczas ostatniej jawnej operacji. Przy nowej instalacji lub aktualizacji może zostać jednorazowo przeskanowany manifest kolekcji, aby przywrócić metadane routingu; ten bootstrap tylko do odczytu nigdy nie synchronizuje treści. Uwierzytelniony endpoint odświeżania Canvas, uruchamiany na żądanie, jest jawną operacją autorską API: Canvas wywołuje go raz po otwarciu obszaru roboczego, aby nowo dodane lub zmienione źródła pojawiły się w początkowym rejestrze. Tryb na żywo wywołuje tę samą granicę, gdy wykryje zmianę źródła strony.
Blockstudio\Pages::init() rejestruje teraz wyłącznie procedury obsługi uruchamiane podczas żądania. Integracje, które wcześniej przekazywały argument force do tej metody, muszą zamiast tego wywołać Blockstudio\Pages::reconcile() lub uruchomić wp bs pages sync.
Aby zapobiec nadpisaniu strony po ręcznych zmianach, ustaw "sync": false w page.json.
Przenośne lokalizacje źródłowe
Zsynchronizowane pliki motywu są przechowywane jako lokalizacje względne względem motywu, a nie jako bezwzględne ścieżki instalacji. Pliki motywu potomnego i nadrzędnego zachowują odrębne tożsamości, nawet jeśli mają tę samą nazwę względną. Funkcje pomocnicze stron nadal zwracają rozwiązane wartości bezwzględne template_path, content_path, layout_path i directory dla bieżącego żądania.
Dzięki temu synchronizacja CLI i żądania internetowe mogą korzystać z różnych katalogów głównych systemu plików, jak w przypadku hostingu z ograniczonym dostępem, bez zakłócania odpowiedzi Markdown, układów, skanowania edytora Tailwind ani śledzenia źródeł prerenderowania. Istniejące bezwzględne ścieżki motywów są przeliczane przy odczycie, gdy nazwa katalogu motywu pozostaje bez zmian. Do ich odczytu nie jest wymagana synchronizacja, migracja bazy danych ani zapis metadanych podczas obsługi żądania; podczas następnej jawnej synchronizacji zostaną zapisane przenośne lokalizacje.
Katalog motywu będący dowiązaniem symbolicznym, na przykład do kopii roboczej używanej podczas programowania, zapisuje te same lokalizacje theme: niezależnie od tego, czy źródło odczytano przez dowiązanie, czy przez jego cel, i rozwiązuje je względem skonfigurowanego katalogu motywu.
Pliki poza aktywnymi motywami potomnym i nadrzędnym są nadal obsługiwane pod skonfigurowanymi ścieżkami bezwzględnymi, z uwzględnieniem ograniczeń open_basedir PHP. Nie można ich automatycznie przenieść: po przeniesieniu źródła zewnętrznego zaktualizuj jego skonfigurowaną ścieżkę i uruchom jawną synchronizację.
Własność pól wpisu
postStatus ustawia początkowy status. Kolejne synchronizacje zachowują istniejące statusy: szkic, oczekujący, prywatny, opublikowany i zaplanowany, także z użyciem --authoritative. Wpis nie zostanie ponownie opublikowany tylko dlatego, że w jego pliku widnieje postStatus: "publish". Dotychczasowe odzyskiwanie osieroconych wpisów działa bez zmian: jawna synchronizacja przywraca z kosza zarządzany wpis, jeśli jego źródło jest dostępne. Zablokuj stronę lub wyłącz synchronizację, aby zapobiec przywróceniu.
Plik nadal określa tytuł, uproszczoną nazwę, typ wpisu, wpis nadrzędny i skonfigurowaną kolejność w menu. Zmiana tych wartości w WordPress nie zmienia definicji źródłowej. Podczas następnej jawnej synchronizacji zostaną ponownie zastosowane wartości z pliku, a zmienione pola zostaną wymienione w pages.<name>.overwritten wraz z ostrzeżeniem w wynikach tabeli CLI. Nadal obowiązują natywne uprawnienia WordPress, w tym pusta uproszczona nazwa wpisów oczekujących, gdy użytkownik synchronizujący nie może ich opublikować.
Użyj blockstudio/pages/update_post_data w przypadku integracji, która jawnie stosuje inną politykę statusów. Bloki z kluczami zachowują treść bloków należącą do edytora; klucze nie zmieniają tego, kto odpowiada za tytuł ani uproszczoną nazwę wpisu.
W przypadku stron kolekcji odciski obejmują manifest, moduł ładujący, źródło strony, plik układu, metadane i powiązane ścieżki źródłowe. Następna jawna synchronizacja zastosuje zmiany w tych danych wejściowych.
Po usunięciu źródła kolekcji Blockstudio usuwa wygenerowaną stronę, dzięki czemu stare strony kolekcji nie pozostają po usunięciu pliku źródłowego. Domyślnie osierocone strony kolekcji są przenoszone do kosza. Użyj blockstudio/pages/orphan_action, aby zwracać trash, delete lub keep.
Podczas żądań interfejsu Blockstudio wczytuje rejestr stron na podstawie już zsynchronizowanych i opublikowanych wpisów. Strony robocze i prywatne są dostępne w panelu administracyjnym i kontekście synchronizacji, ale funkcje pomocnicze interfejsu wczytują tylko opublikowane strony.
Uzgadnianie wdrożenia
Blockstudio\Pages::reconcile() jest punktem wejścia PHP wdrożenia. Wykrywa cały docelowy wykaz, porównuje odciski źródła i mechanizmu synchronizacji, a następnie zwraca raport czytelny dla maszyn:
$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',
],
],
]);
Raport zawiera discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, wyniki dla poszczególnych stron, błędy wykrywania oraz deterministyczny sourceIdentity.
Zablokowane strony mają status: "locked" i są liczone osobno, poza stronami bez zmian. removedPages wymienia dla każdej usuniętej strony jej name, key, postId oraz faktyczne action (trash lub delete); zachowane wpisy i te, które już znajdowały się w koszu, nie są liczone jako nowo usunięte. Wyniki tabeli CLI wymieniają również utworzone, zaktualizowane, zablokowane, usunięte i zachowane pod względem treści strony wraz z identyfikatorami ich wpisów.
Po analizie składniowej i scaleniu bloków według kluczy identyczny wpis końcowy nie wywołuje wp_update_post(), nie zmienia post_modified, nie tworzy rewizji ani nie uruchamia haków aktualizacji wpisu. Jego wynik to unchanged. Gdy treść źródłowa różni się od należącej do edytora treści bloków powiązanych z kluczami, preserved: true wskazuje podjętą decyzję, a łączna liczba preserved uwzględnia ten wpis. Nowy odcisk źródła i zarządzane metadane są mimo to zapisywane, dzięki czemu następna synchronizacja bez zmian nie wykonuje żadnych działań. preserved to dodatkowa flaga, a nie wyłączny status: strona może zachować treść bloków powiązanych z kluczami, a zarazem zaktualizować tytuł określony w pliku lub dodać kolejny blok.
authoritative: true może usunąć blokadę Page Sync i zastępuje treść definicją z pliku zamiast zachowywać treść edytora powiązaną z kluczami. Przy zwykłej jawnej synchronizacji pozostaw tę opcję jako false. plan_valid: false, full: true, broad: true, brak poprzedniej tożsamości źródła lub zmieniony odcisk mechanizmu synchronizacji oznaczają przebieg jako pełne uzgadnianie (fullReconciliation w raporcie). W każdym przebiegu porównywany jest cały wykaz. Rekordy zmiany nazwy Git są wyłącznie wskazówkami dotyczącymi tożsamości. Nigdy nie zastępują porównania pełnego wykazu.
Zgodne odciski przy niezmienionych ścieżkach środowiska uruchomieniowego nie powodują zapisu wpisów ani metadanych wpisów i nie uruchamiają procedur aktualizacji. Gdy niezmienione źródło zostanie przeniesione do nowego katalogu wydania, uzgadnianie odświeża wyłącznie zapisane ścieżki szablonu, treści, układu i katalogu; nie aktualizuje post_content ani znacznika czasu modyfikacji wpisu. Brakujące zarządzane strony są usuwane dopiero po zakończeniu pełnego przebiegu uzgadniania bez błędów wykrywania ani zapisu stron.
Bezpośrednie uzgadnianie API nie oznacza wdrożenia jako pomyślnego. Po aktywowaniu i zweryfikowaniu zgodnego artefaktu statycznego oraz tras jawnie zapisz zwróconą tożsamość:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync zapisuje zwróconą tożsamość po pomyślnym przebiegu. Zwykłe inicjowanie WP-CLI rejestruje tylko zapisane typy wpisów kolekcji i reguły przepisywania adresów. Nie wykrywa ani nie synchronizuje stron.
Przypisywanie identyfikatorów wpisów
Domyślnie WordPress automatycznie przypisuje identyfikatory wpisów. Gdy strona zostanie usunięta i utworzona ponownie, jej identyfikator się zmienia, co przerywa zewnętrzne odwołania, takie jak menu lub zakodowane na stałe łącza.
Użyj postId, aby przypisać stronie stały identyfikator:
{
"name": "about",
"title": "About Us",
"postId": 42
}
Podczas tworzenia strony Blockstudio przekazuje identyfikator do WordPress za pośrednictwem import_id. Jeśli identyfikator jest dostępny, WordPress używa go dokładnie. Jeśli został już przypisany do niezwiązanego wpisu, WordPress po cichu automatycznie przypisuje nowy identyfikator.
Podczas wyszukiwania istniejących stron Blockstudio najpierw sprawdza przypisany identyfikator, a dopiero potem metadane lub uproszczoną nazwę. Oznacza to, że po usunięciu i ponownej synchronizacji strona odzyskuje ten sam identyfikator.
Scalanie bloków według kluczy
Domyślnie, gdy plik szablonu ulegnie zmianie, Blockstudio zastępuje całą zawartość wpisu nowym szablonem. Oznacza to utratę wszelkich zmian wprowadzonych w edytorze WordPress.
Dodaj atrybut key do bloków, aby zachować zmiany użytkownika podczas synchronizacji szablonów. Gdy szablon zawiera bloki z kluczami, Blockstudio scala zmiany szablonu z istniejącą zawartością wpisu zamiast ją zastępować.
Dodawanie kluczy
Użyj atrybutu key na dowolnym elemencie HTML lub <block>:
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>
<div key="features">
<p>First feature.</p>
<p>Second feature.</p>
</div>
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h2>Hero Title</h2>
<p>Hero description.</p>
</block>
<block
name="acme/testimonial"
key="featured-quote"
quote="Default quote"
/>
Klucze muszą być unikatowe w całym szablonie. Klucz chroni cały blok i całą jego zawartość. Nie trzeba przypisywać kluczy poszczególnym elementom podrzędnym bloku, który ma już klucz. Bloki z kluczami można przenosić w dowolne miejsce lub poziom zagnieżdżenia między aktualizacjami szablonu, a ich treść wprowadzona przez użytkownika zostanie zachowana.
Klucze działają tak samo w przypadku własnych bloków Blockstudio. key to strukturalne metadane Page Sync; wartości pól niestandardowych pozostają zwykłymi atrybutami Blockstudio. Gdy edytor zmieni te pola, późniejsza synchronizacja szablonu zachowa wartości edytora, a jednocześnie zastosuje niezależne zmiany szablonu. Strony utworzone przez starsze wersje, w których klucz znajdował się w danych pól niestandardowych, zostaną automatycznie zmigrowane podczas następnej synchronizacji.
Jak działa scalanie
Gdy plik szablonu ulegnie zmianie i strona zostanie ponownie zsynchronizowana:
| Blok | Działanie |
|---|---|
| Blok z kluczem | Treść użytkownika i wartości pól Blockstudio zostają zachowane. Zastosowane zostają atrybuty i struktura zarządzane przez szablon. |
| Blok bez klucza | Zostaje całkowicie zastąpiony wersją szablonu (tak samo jak bez kluczy) |
Przykłady
Zmiany użytkownika są zachowywane w blokach z kluczami:
- Szablon definiuje
<p key="intro">Default intro.</p> - Użytkownik zmienia akapit w edytorze na „Tekst wprowadzający użytkownika”.
- Programista aktualizuje szablon, dodaje nowy blok i zmienia układ
- Podczas synchronizacji akapit zachowuje treść „Tekst wprowadzający użytkownika”, a nowy układ zostaje zastosowany
Atrybuty z szablonu nadal obowiązują:
- Szablon zawiera blok okładki z
key="hero"i atrybutemurl - Programista zmienia atrybut
urlokładki, ustawiając nowe tło - Podczas synchronizacji zostaje zastosowany nowy obraz tła, ale zmiany treści użytkownika w bloku okładki zostają zachowane
Przypadki szczególne
| Scenariusz | Działanie |
|---|---|
| Nowy blok z kluczem dodany do szablonu | Pojawia się z domyślną treścią szablonu |
| Blok z kluczem usunięty z szablonu | Zostaje usunięty z wpisu |
| Zmiana typu bloku (ten sam klucz) | Szablon całkowicie zastępuje blok, bez scalania treści |
| Zduplikowane klucze | Drugie wystąpienie jest traktowane jak blok bez klucza |
| Szablon bez kluczy | Pełne zastąpienie (tak samo jak bez kluczy) |
| Wymuszona synchronizacja | Pełne zastąpienie, klucze są ignorowane |
| Zablokowany wpis | Synchronizacja nie jest wykonywana |
Łączenie z ustawieniami edycji
Klucze, templateLock i blockEditingMode łączą się, dając precyzyjną kontrolę nad tym, co klienci mogą robić. Oto typowe sposoby pracy.
Strona całkowicie zablokowana
Programista kontroluje wszystko. Strona ma statyczny układ, którego klienci nie mogą w żaden sposób zmieniać. Przydatne w przypadku stron prawnych, regulaminów usług i wszystkich stron, które powinny zmieniać się wyłącznie za pomocą kodu.
{
"name": "terms",
"title": "Terms of Service",
"templateLock": "all"
}
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>
Nie potrzeba kluczy. Szablon jest jedynym źródłem prawdy. Każda synchronizacja całkowicie nadpisuje stronę.
Zablokowany układ z edytowalną treścią
Najczęstszy wzorzec. Zablokuj strukturę strony, aby klienci nie mogli dodawać, usuwać ani przestawiać bloków, ale pozwól im edytować tekst w określonych miejscach. Klucze gwarantują zachowanie ich zmian przy aktualizacjach szablonu.
{
"name": "landing",
"title": "Landing Page",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h1 blockEditingMode="contentOnly">Edit This Title</h1>
<p blockEditingMode="contentOnly">Edit this description.</p>
</block>
<div key="features">
<h2>Features</h2>
<p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
</block>
Klient może edytować tytuł sekcji głównej, opis i wprowadzenie do funkcji. Nic więcej. Tekst przycisku, URL i obraz tła okładki są kontrolowane przez dewelopera. Gdy deweloper aktualizuje szablon (e.g., dodaje drugi przycisk), sekcje z kluczami zachowują tekst klienta.
Rozwijanie szablonu z zachowaniem treści
Dla stron, które z czasem się rozrastają. Deweloper dodaje nowe sekcje do szablonu, a każda synchronizacja dodaje nową treść bez naruszania tego, co klient już dostosował.
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<div key="testimonials">
<h2>Testimonials</h2>
<p>What our clients say.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
</block>
Podczas synchronizacji pojawiają się nowa sekcja z opiniami i przycisk. Zmiany klienta w tytule, wprowadzeniu i usługach pozostają nienaruszone.
Jednorazowy szkielet
Utwórz stronę ze wstępną strukturą, a następnie całkowicie przekaż ją klientowi. Ustaw sync na false, aby zwykła synchronizacja nigdy nie tworzyła ani nie aktualizowała strony, i utwórz ją raz za pomocą Blockstudio\Pages::force_sync('blog'). Od tej chwili klient ma pełną kontrolę nad stroną.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
wp bs pages sync pomija tę stronę, więc force_sync() tworzy ją raz. Potem klient może swobodnie dodawać, usuwać i przestawiać bloki. Zmiany szablonu są ignorowane.
Powiązania bloków
Alternatywą dla scalania według kluczy jest użycie WordPress core’owych Powiązań bloków API do łączenia bloków z metadanymi wpisu. To nie jest funkcja Blockstudio, lecz natywna funkcja WordPress API. Blockstudio po prostu przekazuje atrybut metadata do wygenerowanego znacznika bloku. Treść znajduje się w metadanych wpisu, a nie w znaczniku bloku, więc synchronizacja szablonu może swobodnie nadpisywać znacznik, ponieważ edytor odczytuje dane z metadanych, a nie z innerHTML.
Przekaż atrybut metadata dowolnemu elementowi HTML lub <block>:
<h1
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'
>
Default Title
</h1>
<p
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'
>
Default description text.
</p>
<img
metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>
Klucze metadanych muszą być zarejestrowane z włączoną opcją show_in_rest:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Klucze a powiązania
| Aspekt | Klucze | Powiązania |
|---|---|---|
| Miejsce przechowywania treści | Znacznik bloku (post_content) |
Metadane wpisu (wp_postmeta) |
| Zachowanie przy synchronizacji szablonu | Tak (scalane według klucza) | Tak (dane znajdują się w metadanych) |
Możliwość wyszukiwania przez WP_Query |
Nie | Tak (meta_query) |
| Dostępne w REST API | Nie | Tak |
| Wymaga rejestracji | Nie | Tak (register_post_meta) |
| Użytkownik może przenosić bloki | Nie (szablon narzuca strukturę) | Nie (szablon narzuca strukturę) |
Oba podejścia można stosować w tym samym szablonie. Używaj kluczy w sekcjach, w których struktura bloków ma znaczenie (e.g., grupa z wieloma elementami podrzędnymi). Używaj powiązań dla pojedynczych pól, jeśli chcesz też udostępnić dane poza edytorem bloków.
Szablony typów wpisów
Użyj templateFor, aby ustawić stronę jako domyślny szablon dla typu wpisu:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
Każdy nowy wpis tego typu rozpocznie się od zdefiniowanej struktury bloków.
Własne ścieżki
Domyślnie Blockstudio skanuje get_template_directory() . '/pages'. Dodaj kolejne ścieżki za pomocą filtra:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
Integracje środowiska uruchomieniowego, które łączą pliki z kilku katalogów głównych, mogą zastąpić skanowanie systemu plików logicznym źródłem wykrywania. Manifesty stron, układy, moduły ładujące i szablony źródłowe są wtedy rozpoznawane według ścieżki logicznej, nawet jeśli wybrane pliki znajdują się w różnych katalogach głównych.
Filtry i akcje
Wykrywanie stron, synchronizacja i routing kolekcji udostępniają następujące punkty rozszerzeń:
| Hak | Typ | Opis |
|---|---|---|
blockstudio/pages/paths |
Filtr | Dodaje katalogi, w których Blockstudio szuka źródeł stron. |
blockstudio/pages/collection_post_type_args |
Filtr | Zmienia argumenty register_post_type() dla typu wpisu kolekcji. |
blockstudio/pages/template_candidates |
Filtr | Zmienia nazwy plików szablonów uwzględnianych jako źródło strony. |
blockstudio/pages/serve_markdown |
Filtr | Włącza lub wyłącza nieprzetworzone odpowiedzi Markdown. |
blockstudio/pages/orphan_action |
Filtr | Zwraca trash, delete lub keep podczas czyszczenia osieroconych wpisów. |
blockstudio/pages/docs_allowed_html |
Filtr | Zmienia dozwolone HTML dla wygenerowanej treści dokumentacji Markdown. |
blockstudio/pages/allow_external_loader_path |
Filtr | Zezwala na paths modułu ładującego poza głównym katalogiem kolekcji. |
blockstudio/pages/manifest_scan_interval |
Filtr | Ustawia maksymalny wiek pamięci podręcznej manifestu sprzed 7.6.2, która może posłużyć do zainicjowania trwałej konfiguracji środowiska wykonawczego podczas aktualizacji. |
blockstudio/pages/create_post_data |
Filtr | Zmienia dane wpisu przed utworzeniem synchronizowanej strony. |
blockstudio/pages/update_post_data |
Filtr | Zmienia dane wpisu przed aktualizacją synchronizowanej strony. |
blockstudio/pages/sync_engine_inputs |
Filtr | Dodaje wersję parsera, mapowania lub migracji, która ma celowo jednorazowo rozszerzyć uzgadnianie. |
blockstudio/pages/post_created |
Akcja | Uruchamia się po utworzeniu wpisu synchronizowanej strony. |
blockstudio/pages/post_updated |
Akcja | Uruchamia się po zaktualizowaniu wpisu synchronizowanej strony. |
blockstudio/pages/synced |
Akcja | Uruchamia się po zakończeniu synchronizacji rejestru stron. |
blockstudio/pages/reconciled |
Akcja | Uruchamia się po jawnym uzgodnieniu wraz z raportem do odczytu maszynowego. |
blockstudio/pages/renderers |
Akcja | Rejestruje renderery stron za pomocą Blockstudio\Page_Renderers::register(). Uruchamia się raz na żądanie. |
blockstudio/pages/rendered |
Akcja | Uruchamia się po wyrenderowaniu strony komponentu; przekazuje stronę, jej HTML i jej zależności. |
blockstudio/pages/layout_error |
Akcja | Uruchamia się, gdy nie można wyrenderować układu; przekazuje błąd, ścieżkę układu i stronę. |
PHP API
// Get all registered pages.
$pages = Blockstudio\Pages::pages();
// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');
// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');
// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');
// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');
// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');
// Get a specific page.
$page = Blockstudio\Pages::get_page('about');
// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');
// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');
// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();
// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
]);
// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);
// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');
// Unlock a page.
Blockstudio\Pages::unlock('about');
// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
'extensions' => ['tsx'],
'layouts' => ['layout.tsx'],
'render' => 'my_theme_render_page',
]);
// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');
// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);
Informacje o semantyce argumentów, polach raportu i granicy zweryfikowanej tożsamości źródła znajdziesz w sekcji Uzgadnianie wdrożenia.
Funkcje pomocnicze dostępne globalnie dla szablonów i układów:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
Tablice stron zwracane przez Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() i globalne funkcje pomocnicze zawierają tożsamość zsynchronizowanego wpisu, ścieżki źródła i szablonu, metadane kolekcji i ścieżki, typ treści, zasady synchronizacji, typ i status wpisu, zasady edycji, własne metadane oraz klucz permalink. Metadane kolekcji są wczytywane z ostatniego udanego jawnego uzgodnienia. Zwykłe żądania odtwarzają te dane środowiska uruchomieniowego z utrwalonej konfiguracji i metadanych zsynchronizowanych wpisów bez odczytywania drzew źródłowych stron. Klasa Pages nie udostępnia osobnej metody permalink.
Tworzenie stron na podstawie plików
Blokowanie szablonów, tryby edycji bloków, scalanie według kluczy i kontrolowanie zakresu edycji klienta.