Przejdź do treści

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:

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:

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

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:

HTML
<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:

HTML
<!-- 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ść.

Markdown
---
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.

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.

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:

Powłoka
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:

PHP
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.

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 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:

HTML
<!-- 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.

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

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:

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 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.

Kod
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"
  }
}
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' ).

JSON
{
  "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.json zachowują 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ść render dotyczy 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
<?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:

PHP
'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
<?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
<?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:

PHP
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:

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>
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:

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

Ś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:

Powłoka
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:

Powłoka
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:

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

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ść:

PHP
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:

JSON
{
  "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>:

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

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:

  1. Szablon definiuje <p key="intro">Default intro.</p>
  2. Użytkownik zmienia akapit w edytorze na „Tekst wprowadzający użytkownika”.
  3. Programista aktualizuje szablon, dodaje nowy blok i zmienia układ
  4. Podczas synchronizacji akapit zachowuje treść „Tekst wprowadzający użytkownika”, a nowy układ zostaje zastosowany

Atrybuty z szablonu nadal obowiązują:

  1. Szablon zawiera blok okładki z key="hero" i atrybutem url
  2. Programista zmienia atrybut url okładki, ustawiając nowe tło
  3. 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.

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>

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.

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 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ł.

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>

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ą.

JSON
{
  "name": "blog",
  "title": "Blog",
  "sync": false
}
HTML
<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>:

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

Klucze metadanych muszą być zarejestrowane z włączoną opcją show_in_rest:

PHP
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:

JSON
{
  "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:

PHP
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 logicz­nym ź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

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

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:

PHP
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.