Ugrás a tartalomhoz

Oldalak

Az oldalak fájlalapú sablonok, amelyek bejegyzésekként szinkronizálódnak a WordPress adatbázissal. A szinkronizálás kifejezetten indítható: futtassa a wp bs pages sync parancsot, vagy hívja meg az Oldalak API elemet, amikor alkalmazni kívánja a forrás módosításait. A frontend vagy a WordPress adminfelület betöltése soha nem végez teljes oldalfelderítést, és nem módosítja az oldalbejegyzéseket.

Az oldalak meghatározhatók egyetlen page.json mappaként, önálló Markdown fájlként vagy gyűjteményként, pages.json jegyzékkel. A gyűjtemények hasznosak dokumentációhoz, tudásbázisokhoz, céloldalkönyvtárakhoz, illetve bármilyen olyan beágyazott oldalkészlethez, amelyet fájlokból kell létrehozni.

page.json

A JSON által definiált oldalhoz adjon hozzá egy page.json konfigurációs fájlt:

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

Tulajdonságok

Tulajdonság Típus Alapértelmezett érték Leírás
name string kötelező Az oldal egyedi azonosítója
title string Automatikusan a névből Az oldal címe
slug string A névvel megegyező Az oldal URL slugja
path string "." Logikai útvonal egy gyűjteményen belül
order integer 0 A szinkronizált bejegyzés menüsorrendje
postType string "page" WordPress bejegyzéstípus
postStatus string "draft" Új bejegyzések állapota (publish, draft, pending, private)
postId integer – Az oldal hozzárendelése egy adott WordPress bejegyzésazonosítóhoz
blockEditingMode string – Blokkszerkesztési mód: "default", "contentOnly" vagy "disabled"
templateLock string|false "all" Zárolási mód: "all", "insert", "contentOnly" vagy false
templateFor string|null null Alapértelmezett sablonként való beállítás egy bejegyzéstípushoz
sync boolean true Meghatározza, hogy a normál, kifejezett egyeztetés létrehozhatja vagy frissítheti-e a bejegyzést
render string|object|false – Az oldal megjelenítése regisztrált oldalletöltővel (lásd: Komponensoldalak)

A page.json, az előtéradatok és a betöltőbejegyzések körében az ismert kulcsok közé tartozik a blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock és title. A fent fel nem sorolt kulcsok az oldal meta tömbjében tárolódnak.

Tartalomforrások

Az oldaldefiníció határozza meg, melyik WordPress bejegyzésnek kell léteznie. A tartalomforrás határozza meg, milyen blokkjelölés kerüljön a bejegyzésbe.

Ha egy oldalmappa tartalmaz page.json fájlt, a Blockstudio a testvérforrásfájlokat a következő sorrendben keresi:

Fájl Használat
index.php HTML-szerű blokkjelölés, változtatás nélkül beolvasva (a PHP kód nem fut le)
index.blade.php Blade sablontartalom
index.twig Twig sablontartalom
index.md Markdown tartalom

A page.json testvérfájl helyett beágyazott markdown vagy html tartalmat is megadhat:

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

A gyűjtemények két további forrásmódot kínálnak:

  • Markdown fájlok, amelyeket közvetlenül a gyűjtemény fájából talál meg.
  • Betöltőbejegyzések, amelyeket a loader.php ad vissza.

A betöltőbejegyzésekben a contentType segítségével a markdown, html vagy content használható. Hivatkozhatnak helyi file vagy template fájlra is. A fájl- és sablonforrások típusát a rendszer a kiterjesztésből állapítja meg, hacsak a contentType nincs kifejezetten beállítva.

A támogatott contentType értékek: php, blade, twig, markdown és html. A Markdown először HTML formátumba alakul, majd natív WordPress blokkokká kerül feldolgozásra. A PHP, Blade, Twig és HTML források a szokásos Blockstudio oldal-feldolgozón keresztül mennek.

Osztályok az alapblokkokon

Egy class egy HTML elemen, amely alapblokkhoz van rendelve, annak className értékévé válik. Egy explicit alapblokkcímke közvetlenül használhatja a className-t. Mindkét forma megőrzi a blokk mentett burkolóelemének osztályait, a WordPress által generált osztályok mellett:

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

Ha mindkét tulajdonság meg van adva, a className élvez elsőbbséget. Ez az átalakítás csak az alapblokkokra vonatkozik: egyéni blokkleképezés esetén a class mező változatlan marad. A gombstílus-osztályok, például a is-style-outline, a gomb burkolóeleméhez tartoznak, nem a hivatkozáshoz.

Futtassa a wp bs pages sync parancsot a korábban szinkronizált oldalak elemzőjavításainak alkalmazásához. Az elemző frissítéseit a következő explicit szinkronizálás ismeri fel forrásfájl-módosítás nélkül. A zárolt oldalak és a sync: false elemet tartalmazó oldalak megőrzik szokásos védelmüket; a frontend-kérések soha nem végzik el ezt a szinkronizálást.

Szerializált WordPress blokkok

Az oldalak és minták forrásai a WordPress kódszerkesztőből másolt szerializált blokkokat is tartalmazhatnak:

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

Ha a forrás <!-- wp:... --> blokkelválasztót tartalmaz, a Blockstudio a teljes forráshoz a WordPress natív blokkfeldolgozóját használja. Az attribútumok, a beágyazott blokkok, a dinamikus blokkok, például a Query Loop, valamint a Blockstudio blokkok megőrzik szerializált szerkezetüket. A blokkkommenteken kívüli HTML natív szabad formájú HTML marad; nem képez további blokkokat. Ne keverje a Blockstudio HTML blokkjeleit ezzel a formátummal, és ne számítson arra, hogy átalakulnak. A szokásos HTML kommentek nem választják ki a szerializált blokk módot.

Markdown oldalak

Akkor használja a Markdown formátumot, ha a prózai tartalmat fájlokban szeretné tárolni, de szinkronizálás után szerkeszthető WordPress blokktartalomként kívánja megjeleníteni. A szinkronizálás során a Markdown forrás blokkjelöléssé alakul. A szinkronizált bejegyzés blokkokat tárol, nem a nyers Markdown törzset.

A Markdown háromféleképpen használható:

Forrás Kell előtartalom? Megjegyzések
Önálló pages/example/index.md Igen Az előtartalom adja meg az oldal azonosítóját.
page.json és index.md együtt Nem A page.json definiálja az oldalt, a Markdown pedig a tartalmat adja.
Markdown gyűjteményben Nem A gyűjtemény a fájl helye alapján következtet a name és path értékére.

Az előtartalom nélküli önálló index.md fájl kimarad, mert a Blockstudio nem rendelkezik az oldal szinkronizálásához szükséges azonosítóval. A gyűjteményben található Markdown fájlokhoz nem kell előtartalom, mert a gyűjteményjegyzék és a fájl útvonala megadja az azonosítót.

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

# About

This Markdown content is synced as native WordPress blocks.

A page.json párosítható index.md fájllal is. Ebben az esetben a page.json definiálja az oldalt, a index.md pedig a tartalmat adja. A index.md fájl előtartalma felülírja az egyező page.json értékeket.

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.

Gyűjteménybeli Markdown esetén a fájl útvonala lesz az oldal logikai útvonala, hacsak az előtartalom felül nem írja:

Fájl Alapértelmezett útvonal
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

Az ismeretlen előtartalomkulcsok az oldal meta tömbjében maradnak. Így olyan adatokat is csatolhat, mint a section vagy a description, majd kiolvashatja őket a PHP API elemből.

A Markdown feldolgozása GitHub Flavored Markdown formátumban történik. Nyers HTML is használható, a nem biztonságos hivatkozások eltávolításra kerülnek, az explicit azonosító nélküli címsorok pedig stabil azonosítót kapnak. A beágyazott YAML előtartalomhoz szükség van a csomagban foglalt YAML feldolgozóra.

Nyers Markdown

A Markdown fájlból származó források elérhetővé tehetik az eredeti forrás-Markdown tartalmat külső eszközök és dokumentációs fogyasztók számára. A beágyazott Markdown-nak nincs forrásfájlja, ezért blokkokká szinkronizálódik, de nem ad nyers .md választ.

Kérje le az oldalt egy .md utótaggal, például https://example.com/docs/reference.md formában. Vagy küldjön egy Accept: text/markdown fejlécet a normál oldal-URL kéréshez:

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

Az előtartalom kimarad a válaszból. A sikeres nyers Markdown válaszok visszaküldik az Content-Type: text/markdown és X-Robots-Tag: noindex fejléceket, valamint egy kanonikus Link fejlécet a HTML oldalra. A hiányzó .md útvonalak valódi 404 választ adnak.

Az egyeztetés statikus előállítású oldalakkal is működik: az olyan kérésekre, amelyek Accept fejléce tartalmazza a text/markdown értéket, soha nem a statikus tároló vagy a korai kiszolgálást végző kiegészítő válaszol; a kérés eljut a WordPress-hoz és a Markdown kezelőhöz. Az előállított HTML válaszok, az olyan oldal HTML eleme, amely a Markdown formátumot is egyezteti, valamint a Accept útján megválaszolt Markdown a Vary: Accept értéket küldi, így az Vary fejlécet figyelembe vevő gyorsítótárak elkülönítik a két változatot. Az olyan CDN gyorsítótárnak, amely kizárólag az URL alapján tárol, saját szabállyal kell megkerülnie a gyorsítótárat ezeknél a kéréseknél. A Pages::negotiates_markdown( $post_id ) jelzi, hogy egy oldal válaszol-e Markdown kérésekre.

A gyűjtemény Markdown a nyers Markdown esetén is megtartja ugyanazt az URL alakot:

Oldal-URL Nyers Markdown URL
/docs/ /docs.md
/docs/getting-started/ /docs/getting-started.md
/docs/guide/install/ /docs/guide/install.md

A nyers Markdown válaszok kikapcsolásához használja a blockstudio/pages/serve_markdown szűrőt:

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

Az a .md URL, amely nem egy Markdown által kezelt oldalra vezet, csak akkor ad vissza 404 értéket, ha az útvonal egy oldalakhoz tartozó gyűjteményen belül van. Minden gyűjteményen kívül a Blockstudio érintetlenül hagyja a kérést, hogy azt a WordPress vagy más bővítmények kezelhessék.

Komponensoldalak

A komponensoldalt egy oldalletöltő jeleníti meg, nem blokkokként tárolódik. A Blockstudio nem tartalmaz oldalletöltőt. Egy téma vagy bővítmény regisztrál egyet az általa kezelt belépési fájlokhoz, például egy React oldalletöltőt a page.tsx fájlhoz, és a Blockstudio átadja neki az oldalt, a WordPress bejegyzést és a megjelenített foglalttartalmat.

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

A render kifejezett beállítás. Ha egy könyvtárban van index.php és page.tsx, de nincs render, az továbbra is normál oldal marad, így egy oldalletöltő hozzáadása soha nem jelenít meg kétszer egy meglévő oldalt. A formák:

Érték Jelentés
"page.tsx" Csak belépési fájl, adatbetöltő nélkül
{ "entry": "page.tsx", "data": "data.php" } Belépési fájl és adatbetöltő
{ "entry": "page.tsx", "renderer": "react" } Belépési fájl explicit megjelenítőazonosítóval
false Nincs megjelenítő, még akkor sem, ha a gyűjtemény alapértelmezettje megad egyet

Az útvonalak az oldal könyvtárához, a betöltőbejegyzések esetén pedig a gyűjtemény gyökeréhez képest oldódnak fel. A felderítési forráson belül kell maradniuk, kivéve, ha a blockstudio/pages/allow_external_loader_path ezt engedélyezi. Ha nincs megadva renderer, a bejegyzés kiterjesztését kezelő megjelenítő használatos. Ha a render hiányzó bejegyzésre vagy adatfájlra, ismeretlen megjelenítőre vagy olyan kiterjesztésre hivatkozik, amelyet egyetlen megjelenítő sem kezel, felderítési hiba történik, és az egyeztetés még bármi törlése előtt meghiúsul.

Mit tárol a szinkronizálás

A szinkronizálás egyetlen blockstudio/page blokkot tárol. Ha az oldal könyvtárában index.* forrás is található, azt a rendszer bármely más oldalforráshoz hasonlóan elemzi, és a blokk belső blokkjaivá, vagyis a foglalat tartalmává alakítja:

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

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

A WordPress által kezelt tartalmakat, például a rövidkódokat, a foglalatban tartsa. Ha a forrás egyetlen rövidkód, például [download_checkout], akkor core/shortcode blokként tárolódik, ezért a kimenet köré nem kerül bekezdés. A tartalom a post_content részben marad, így a has_shortcode() ellenőrzései is látják; a kulcsokkal ellátott foglalatblokkok a szerkesztői módosításokkal ugyanúgy egyesülnek, mint a beágyazott, kulcsokkal ellátott blokkok; a do_shortcode pedig a szokásos the_content prioritással, a megjelenítő által köréjük épített keret után egyszer bontja ki a rövidkódokat.

A megjelenítési definíció a bejegyzéssel együtt hordozható theme: útvonalakként tárolódik. Az oldal ujjlenyomata a definíciót veszi figyelembe, nem a belépési fájl vagy az adatbetöltő bájtjait: a page.tsx vagy data.php módosítása nem változtatja meg a bejegyzést, a látogatók pedig a megjelenítésen és a statikus előzetes megjelenítés gráfján keresztül érik el a módosításokat; ez rögzíti a belépési fájlt, az adatbetöltőt és minden olyan fájlt, amelyet a megjelenítő jelent.

Megjelenítő regisztrálása

A megjelenítőket a blockstudio/pages/renderers művelethez regisztrálja. Ez kérésenként egyszer, az első felderítés vagy megjelenítés előtt fut le, így a wp bs pages sync és a frontend kérések ugyanazt a regisztert használják.

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

A megjelenítőazonosítók kisbetűsek. Egy kiterjesztés vagy elrendezésnév csak egy megjelenítőhöz tartozhat, a layout.php pedig továbbra is a Blockstudio saját elrendezése. A hívható elem egyetlen kérést kap:

Kulcs Érték
kind page, vagy layout megjelenítői elrendezés esetén
renderer Megjelenítőazonosító
entry Abszolút belépésifájl-útvonal
data Abszolút adatbetöltő-útvonal vagy null
page Kanonikus oldaladatok, beleértve a meta értéket
post_id WordPress bejegyzésazonosító
slot Megjelenített foglalattartalom vagy elrendezés esetén az oldal tartalma
context frontend, rest, feed vagy cli

A megjelenítő az HTML elemet, a megjelenítés során beolvasott fájlokat és az opcionális erőforrásokat adja vissza:

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

A context a kérés típusából származik, nem a látogatótól, így a renderelő nem ronthatja el a bejelentkezett és névtelen kérések bájtazonosságát azzal, hogy kiolvassa. Ha a renderelő hibát jelez, kivételt dob: az oldal nem üres törzstartalommal jelenik meg. A REST szerkesztői előnézetben a blokk ehelyett értesítésként jeleníti meg a hibát. Sikeres renderelés után a blockstudio/pages/rendered művelet megkapja az oldalt, a HTML értéket és a függőségeit.

A assets felsorolja az oldalhoz szükséges parancsfájl- és stílusfájlokat. Ezekre ugyanaz a feldolgozás vonatkozik, mint a blokkok eszközeire: a *.inline.* konvenció, az ES-modulok, a minifikálás és a ?ver. Az oldal egyszer írja ki őket, ugyanazon a pufferen keresztül, amely a blokkok eszközeit is kiírja, így az előrenderelt oldal is tartalmazza őket. Egy eszköz beállíthatja a version értékét, hogy felülírja a ?ver értékét. A renderelőn kívüli kód ugyanezt a csatornát használhatja a Blockstudio\Assets::register_owner() segítségével, amely visszaadja a kiírandó jelölőkommentet.

Szerkesztő

A szerkesztőben a blockstudio/page az oldal szerveroldalon renderelt előnézetét mutatja, amelyben a helykitöltő belső blokkokként jelenik meg, követve az oldal templateLock értékét. A blokk nem szúrható be, nem duplikálható, és másik blokkba sem ágyazható be.

Oldalgyűjtemények

A gyűjtemény egy pages.json jegyzéket tartalmazó mappa. Sok oldaltartalmat csoportosít egyetlen gyűjteményazonosító alá, alapértelmezéseket alkalmaz, támogatja a beágyazott útvonalakat, és automatikusan regisztrálhat egy önálló bejegyzéstípust.

Kód
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
    loader.php
JSON
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "postTypeArgs": {
    "label": "Docs",
    "rewrite": {
      "slug": "docs"
    },
    "supports": ["title", "editor", "page-attributes"]
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}
Tulajdonság Típus Leírás
collection / slug / name string Gyűjteményazonosító. A collection a legegyértelműbb forma, és ez lesz a nyilvános URL alapja.
title string A gyűjtemény ember által olvasható címe.
postType string A létrehozott oldalak bejegyzéstípusa. Alapértelmezés szerint page. Ha nem létezik, a Blockstudio regisztrálja.
postTypeArgs object A register_post_type() számára átadott argumentumok, amikor a Blockstudio regisztrálja a gyűjtemény bejegyzéstípusát.
defaults object A gyűjtemény minden oldalára alkalmazott alapértelmezett oldaltulajdonságok. Az alapértelmezett render csak akkor vonatkozik egy oldalra, ha a bejegyzése szerepel az oldal könyvtárában.
scope string collection (alapértelmezett) vagy site. Lásd: Webhelygyűjtemények.
meta object Egyéni gyűjtemény-metaadatok. Az ismeretlen jegyzékbeli kulcsok szintén a meta helyen tárolódnak.

A gyűjtemény oldalainak útvonalai logikai útvonalak. A path: "guide/install" értékű oldal a guide gyermekeként, a guide értékű pedig a gyűjtemény gyökérmappájának gyermekeként szinkronizálódik, ha ezek a szülőoldalak léteznek.

Ha egy hierarchikus gyűjteményben van egy beágyazott oldal, de egy köztes szülő tartalomforrása nem létezik, a Blockstudio üres tárolóoldalt hoz létre az adott útvonalon, hogy a WordPress hierarchia teljes maradjon. A nem hierarchikus bejegyzéstípusok, amelyek nem támogatják a page-attributes szülőt, nem hoznak létre üres tárolóoldalakat. A tárolt gyűjteményútvonal alapján irányítják a kéréseket, így az olyan beágyazott útvonalak, mint a guide/install és a setup/install, akkor is megférnek egymás mellett, ha mindkettő végződése install.

Gyűjtemény-bejegyzéstípusok és URL-ek

Állítsa be a postType értéket a gyűjteményjegyzékben, hogy a gyűjtemény minden oldala az adott bejegyzéstípusba szinkronizálódjon. Ugyanezt az értéket nem kell megismételnie a defaults fájlban. Az egyes oldalak előtartalmukban vagy page.json értékkel továbbra is felülírhatják a postType értékét.

Ha a bejegyzéstípus nem létezik, a Blockstudio regisztrálja azt show_in_rest: true értékkel, oldalszerű szerkesztőbeállítással, a gyűjteményazonosítót használva nyilvános URL alapként. A regisztráció argumentumait a postTypeArgs írhatja felül. A rendszer automatikusan frissíti a gyűjtemény bejegyzéstípusainak útvonal-átírási szabályait, ha változik a regisztrált típus vagy az útvonal-átírás argumentuma, így nem kell újra mentenie a WordPress közvetlen hivatkozásait.

A gyűjtemény URL-jeit a gyűjteményazonosító és az egyes oldalak logikai path útvonala alkotja:

Forrás elérési útja Nyilvános URL
path: "." /docs/
path: "getting-started" /docs/getting-started/
path: "guide/install" /docs/guide/install/

Ez a URL modell hierarchikus és nem hierarchikus gyűjtemény-bejegyzéstípusokhoz egyaránt működik. A Blockstudio az olyan duplikált URL-eket is a kanonikus URL címre irányítja át, mint a /docs/docs/ vagy a /docs/docs/getting-started/.

A gyűjteményoldalak ugyanazokon az URL-eken teszik elérhetővé a nyers Markdown-t (lásd: Nyers Markdown).

Ha egy gyűjteményt postType: "page" értékről egyéni bejegyzéstípusra módosít, a Blockstudio helyben migrálja a már szinkronizált gyűjteménybejegyzéseket, ha a tárolt oldalazonosítójuk egyezik. Így megmaradnak a bejegyzésazonosítók, a metaadatok és a meglévő tartalom, és elkerülhetők a régi típusú duplikált bejegyzések. Az elavult gyűjteménybejegyzéseket az összes bejegyzésállapotban eltávolítja a blockstudio/pages/orphan_action szűrőnek megfelelően.

Webhelygyűjtemények

A "scope": "site" értéket tartalmazó jegyzék az alatta lévő összes oldalt csoportosítja anélkül, hogy gyűjteményoldalakká alakítaná őket. Használja a webhely oldalfájának gyökerében a közös alapértékek alkalmazásához és a webhely oldalainak blockstudio_page_tree( 'my-site' ) segítségével történő felsorolásához.

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

A webhelygyűjtemény oldalai pontosan ugyanazzal az identitással rendelkeznek a jegyzék nélkül is, ezért egy ilyen hozzáadása egy meglévő fához nem módosítja a bejegyzéssorokat, és semmit sem hoz létre vagy helyez a kukába:

  • A kulcsok globálisak maradnak: a Pages::get_page( 'home' ) és a tárolt oldalkulcsok továbbra is egyeznek.
  • Az URL-ek továbbra is WordPress oldal-URL-ek. Nem érvényesülnek gyűjteményes átírási szabályok, permalink-szűrő vagy kettős URL átirányítás, és nem jönnek létre üres tárolóoldalak.
  • A logikai útvonalak, azonosítók, szülők és forrásazonosságok megegyeznek az önálló oldalakéival, az elrendezések pedig a legközelebbi ős alapján oldódnak fel.
  • A beágyazott pages.json jegyzékek megtartják saját gyűjteményeiket, az aloldalaik pedig kimaradnak a webhelygyűjteményből.
  • Az alapértékek oldalanként érvényesülnek: az alapértelmezett render csak azokra az oldalakra vonatkozik, amelyek bejegyzése szerepel a könyvtárban, így a rövidkódos és Markdown oldalak megtartják forrásaikat.

Gyűjteménybetöltők

A gyűjtemények megbízható, helyi loader.php-t is tartalmazhatnak. Akkor használja, ha a gyűjtemény oldalai más helyi forrásból származnak, például külső dokumentációs mappából, csomagból vagy generált jegyzékből.

A betöltő a kifejezett oldalészlelés és szinkronizálás során fut. Legyen determinisztikus és helyi. Kerülje a távoli tartalom lekérését a loader.php-ból, mert ez a telepítések szinkronizálását az adott szolgáltatástól tenné függővé.

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

A betöltő olyan tömböt adhat vissza, amelynek kulcsai pages, meta és paths:

Kulcs Leírás
pages Oldaltömbök listája. Minden oldal ugyanazokat a felismert kulcsokat támogatja, mint a page.json és a Markdown frontmatter.
meta Minden betöltő által létrehozott oldal meta tömbjébe egyesített metaadatok.
paths További helyi könyvtárak, amelyeket a gyűjtemény részeként kell felderíteni. A bejegyzések lehetnek karakterláncok vagy útvonalobjektumok.
render renderelési definíció minden, a paths alapján felderített Markdown oldalhoz.

Rövidítésként a betöltő közvetlenül is visszaadhatja az oldaltömbök listáját.

A betöltő oldalbejegyzései az alábbi módokon adhatnak meg tartalmat:

Forma Leírás
markdown Beágyazott Markdown-tartalom.
html Beágyazott HTML-tartalom.
content + contentType Általános beágyazott tartalom. A contentType feloldásának markdown-t vagy html-t kell eredményeznie.
file Helyi fájlforrás. A típus a kiterjesztésből következtethető ki, kivéve ha be van állítva a contentType.
template A file aliasa.

A betöltő fájlhivatkozásai mutathatnak PHP, Blade, Twig, Markdown vagy HTML forrásokra. A relatív elérési utak a gyűjtemény gyökeréből oldódnak fel. Abszolút elérési utak és a gyűjtemény gyökerén kívüli útvonalak csak akkor engedélyezettek, ha a blockstudio/pages/allow_external_loader_path szűrő ezt megengedi.

A betöltő oldalainak alapértelmezett értéke generated: true. Ha egy generált betöltőoldal eltűnik a betöltő kimenetéből, a Blockstudio a következő szinkronizáláskor árva bejegyzésként kezeli a szinkronizált bejegyzést, amelyet a blockstudio/pages/orphan_action szűrőnek megfelelően távolít el.

A paths alatt felsorolt könyvtárakat a rendszer a szokásos gyűjteménymappákhoz hasonlóan deríti fel. Tartalmazhatnak Markdown fájlokat vagy page.json mappákat. Ha ezek az útvonalak a gyűjtemény gyökerén kívülre esnek, ugyanaz a külső útvonalakat szabályozó szűrő érvényes rájuk.

Karakterlánc-bejegyzést akkor használjon, ha a külső könyvtárnak meg kell őriznie a saját logikai útvonalait. Objektumbejegyzést akkor használjon, ha a könyvtárat a gyűjtemény egy útvonal-előtagja alá kell csatolni:

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

Ezzel a beállítással a gyűjteményben a cli-docs/index.md értéke path: "cli", a cli-docs/getting-started.md értéke pedig path: "cli/getting-started" lesz. Az előtagok az oldalnevek ütközését is megakadályozzák, így több csatolt könyvtár is tartalmazhat index.md-t vagy getting-started.md-t. Ha az page.json vagy Markdown frontmatter explicit name értékeit szeretné megőrizni, állítsa az preserveNames értékét true-re az útvonalobjektumban.

Az útvonalobjektum tulajdonságai:

Tulajdonság Típus Leírás
path string Felderítendő helyi könyvtár. A relatív útvonalak feloldása a gyűjtemény gyökerétől történik.
prefix string Opcionális logikai útvonal-előtag a gyűjteményen belül.
preserveNames boolean A kifejezetten megadott oldalnevek megtartása az előtagos útvonalból képzett nevek helyett. Alapértelmezés szerint false, ha a prefix be van állítva.
meta object Az ezen az útvonalon felderített minden oldalhoz hozzáadott metaadatok. Az oldalszintű metaadatok elsőbbséget élveznek az azonos kulcsoknál.
render string|object Renderelési definíció az útvonal Markdown oldalaihoz, felülírva a betöltő render értékét.

Markdown renderelése komponensen keresztül

A render használatakor a betöltő által felderített Markdown oldalak blokkokként való tárolás helyett egy oldalrenderelőn keresztül jelennek meg:

PHP
<?php

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

Ezek továbbra is Markdown oldalak maradnak: a tartalomtípus, a tartalom útvonala, a .md válaszok és a frontmatter változatlan. A szinkronizálás egyetlen blockstudio/page blokkot tárol, amelynek belső HTML értéke a konvertált Markdown, amelyet a gyűjtemény tartalomszűrése esetén megtisztít, nem pedig elemzett blokkokat, így a post_content megőrzi a dokumentum szövegét. A renderelő ezt a HTML értéket kapja meg helykitöltőként, és a forrást a page.content_path helyről olvashatja be. A relatív útvonalak feloldása a gyűjtemény gyökerétől történik; a külső útvonalszűrő ugyanúgy érvényes rájuk, mint az útvonalakra. Azok az oldalak kimaradnak, amelyek saját render vagy render: false értéket állítanak be a frontmatterben.

Elrendezések

Egy layout.php fájl körbeveszi a fájlalapú oldal frontend-megjelenítését. Nem helyettesíti a WordPress alatt tárolt, szinkronizált post_content-t, és nem veszi körbe a szerkesztő vásznát. Az elrendezés csak egyedi frontendkéréseknél fut.

Gyűjtemények esetében helyezze a layout.php-t a pages.json mellé, hogy a gyűjtemény minden frontendoldalát körbevegye:

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>

A blockstudio_page_content() írja ki az oldal törzsét, amelyet a WordPress rendszerint a the_content segítségével jelenít meg. Ha egy elrendezés nem írja ki a blockstudio_page_content()-t, az oldal tartalma szándékosan rejtve marad.

Az elrendezések az alábbi oldalsegédfüggvényeket használhatják:

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

A beágyazott, nem gyűjteményhez tartozó oldalak a pages fában örökölhetik a legközelebbi őselem layout.php-ét is. A gyűjteményoldalak esetében a gyűjtemény gyökér-elrendezése minden szinkronizált bejegyzésben tárolódik, és az oldal ujjlenyomatának részeként van figyelve, így az elrendezés változásai a következő szinkronizáláskor érvénybe lépnek.

Renderelő-elrendezések

Az elrendezés lehet renderelőbejegyzés is, például a layout.tsx egy olyan renderelőhöz, amely regisztrálja a layouts: ["layout.tsx"] elemet. Ugyanazokon a helyeken található meg, mint a layout.php, és a mellette lévő opcionális layout.data.php az adatbetöltője. Rendereléskor a renderelő megkapja a kind: "layout" értéket és az oldal renderelt tartalmát a slot formájában, a layout.php-tel azonos the_content prioritással. Egy könyvtárban layout.php vagy egy renderelő-elrendezés lehet, mindkettő nem; ha mindkettő megtalálható, az felderítési hibát jelent. Elrendezéshiba esetén a rendszer kiváltja a blockstudio/pages/layout_error eseményt, és a lap tartalmát burkolatlanul hagyja, ahogy a layout.php esetében is.

Blokkszerkesztési mód

A blockEditingMode tulajdonság határozza meg, hogyan szerkeszthetők a blokkok a szerkesztőben. Állítson be alapértelmezést az oldalhoz a page.json helyen, és írja felül elemenként a sablonban:

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>
Érték Leírás
"default" Teljes szerkesztés. A blokkok kijelölhetők, áthelyezhetők és szerkeszthetők.
"contentOnly" Csak szövegszerkesztés. A blokkok szövege szerkeszthető, de a beállítások és a szerkezet zárolva vannak.
"disabled" Nincs szerkesztés. A blokkok teljesen nem interaktívak.

Elemenkénti felülírásokat HTML attribútumként adhat meg bármely elemen (<h1>, <p>, <div> stb.) vagy <block> elemeknél. A felülírt elemek őskonténer-blokkjai automatikusan contentOnly értéket kapnak, így a gyermekelemek elérhetők maradnak. Ez a láncolat a felülírt elemtől az oldal gyökeréig halad felfelé, ezért csak azokon az elemeken kell beállítania az blockEditingMode értékét, amelyeket szerkeszthetővé szeretne tenni.

Sablonzárolás

A templateLock tulajdonság határozza meg, hogyan szerkeszthetik a felhasználók az oldalt a szerkesztőben:

Érték Hozzáadás/eltávolítás Áthelyezés Tartalom szerkesztése
"all" Nem Nem Nem
"insert" Nem Igen Igen
"contentOnly" Nem Nem Igen
false Igen Igen Igen

Ha be van állítva a templateLock, a Blockstudio letiltja a blokkok feloldását a szerkesztő UI felületén.

Virtuális útvonalak

Egyes dokumentumok mögött nincs bejegyzés: például az adatokból generált komponensreferencia, katalógus vagy fiókfelület. Regisztrálja őket virtuális útvonalként, ahelyett hogy saját maga kezelné a template_redirect-t:

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

Az útvonal a webhely kezdőlapjához viszonyított. A prefix használatakor az útvonal az összes alatta lévő útvonalat is kiszolgálja, az match pedig megkapja a fennmaradó részt (az útvonal saját maga esetén üres karakterláncot), és visszaadja az értéket, amelyet a renderelési visszahívás megkap, vagy null értéket ad vissza, hogy a URL a WordPress kezelésére hagyja, amely aztán a szokásos módon válaszol a 404 kérésre. A renderelési visszahívás kiírja a dokumentumot, vagy karakterláncként adja vissza; az title karakterlánc vagy olyan lezárás, amely megkapja az egyezés értékét.

Egyező kérés esetén a Blockstudio megakadályozza, hogy a WordPress 404-ként jelölje meg, a redirect_canonical pedig átirányítsa; törli a fő lekérdezés által jelzett egyedi állapotot, elküldi az állapotot (alapértelmezés szerint status és 200), majd template_redirect prioritással renderel Virtual_Routes::PRIORITY. Ez közvetlenül azután történik, hogy a Blockstudio kimeneti puffere megnyílik a Assets::BUFFER_PRIORITY helyen, így az elkészült dokumentum az oldalhoz hasonlóan megkapja a blokk eszközeit, a csomagolt UI eszközöket és a lefordított Tailwind fájlokat, még a redirect_canonical 10-es prioritású futása előtt. Az egész dokumentumot önállóan renderelő kezelőnek a Assets::BUFFER_PRIORITY után is futnia kell, különben ez a feldolgozás kimarad. A urls útvonalai (alapértelmezés szerint maga az útvonal, ha nem előtagos útvonalról van szó) hozzáadódnak a statikus előrenderelés buildjeihez, a Virtual_Routes::urls() pedig abszolút URL-ként adja vissza őket webhelytérképhez. A Virtual_Routes::match( $path ) úgy old fel egy útvonalat, ahogy egy kérés tenné.

Szinkronizálási viselkedés

Az oldalbejegyzések csak kifejezett szinkronizálási művelettel változnak:

Shell
wp bs pages sync

A parancs felderíti a források teljes jegyzékét, létrehozza vagy frissíti a módosult bejegyzéseket, eltávolítja a megerősített árvákat, frissíti a gyűjtemények útvonalkezelését és a lefordított templateFor konfigurációt, majd jelentést készít a változásokról. Adja hozzá a --authoritative kapcsolót, ha a kulcsokhoz kötött szerkesztői tartalom megőrzése helyett a kezelt tartalmat szeretné lecserélni, és a --full kapcsolót, ha azt szeretné, hogy a művelet a tárolt forrásazonosítótól függetlenül teljes egyeztetésként legyen jelentve:

Shell
wp bs pages sync --authoritative --full

A szokásos frontend-, adminisztrációs, AJAX-, REST-, cron- és általános WP-CLI rendszerindítási kérések nem végzik el a teljes oldalészlelést, nem kérdezik le a kezelt egyeztetési jegyzéket, és nem írnak oldalbejegyzéseket. A már szinkronizált WordPress bejegyzéseket, valamint az utolsó kifejezett műveletkor elmentett, tömör gyűjtemény- és bejegyzéstípus-konfigurációt használják. Hideg telepítés vagy frissítés esetén a rendszer egyszer átvizsgálhatja a gyűjteményjegyzékeket az útvonalkezelési metaadatok visszaállításához; ez a csak olvasási rendszerindítás soha nem szinkronizál tartalmat. A hitelesített, bekapcsolható Canvas-frissítési végpont egy kifejezett szerzői API: a Canvas egyszer meghívja a munkaterület megnyitásakor, hogy az újonnan hozzáadott vagy módosult források megjelenjenek a kezdeti jegyzékben. Az élő mód ugyanezt a végpontot hívja meg, amikor oldalforrás-változást észlel.

A Blockstudio\Pages::init() mostantól csak a kéréskori hookokat regisztrálja. Azoknak az integrációknak, amelyek korábban force argumentumot adtak át ennek a metódusnak, ehelyett a Blockstudio\Pages::reconcile() metódust kell hívniuk, vagy a wp bs pages sync parancsot kell futtatniuk.

Ha meg szeretné akadályozni egy oldal felülírását a kézi szerkesztést követően, állítsa be a "sync": false értékét a page.json helyen.

Hordozható forráshelyek

A szinkronizált témfájlok a telepítési útvonal helyett a témához viszonyított helyekként tárolódnak. A gyermek- és szülőtémák fájljai akkor is külön identitást kapnak, ha relatív fájlnevük megegyezik. Az oldal segédfüggvényei továbbra is feloldott, abszolút template_path, content_path, layout_path és directory értékeket adnak vissza az aktuális kéréshez.

Ez lehetővé teszi, hogy a CLI szinkronizálás és a webes kérések eltérő fájlrendszergyökereket használjanak, például elkülönített tárhelyen, anélkül, hogy ez megzavarná a Markdown válaszokat, elrendezéseket, a szerkesztő Tailwind-vizsgálatát vagy az előzetes renderelés forráskövetését. A meglévő abszolút témabeli útvonalak beolvasáskor új alapra kerülnek, ha a témakönyvtár neve nem változott. Beolvasásukhoz nincs szükség szinkronizálásra, adatbázis-migrációra vagy a kérés idején végzett metaadat-írásra; a következő explicit szinkronizálás már a hordozható helyeket tárolja.

Ha egy témakönyvtár szimbolikus hivatkozás, például egy fejlesztési munkakönyvtárra mutat, ugyanazokat a theme: helyeket tárolja attól függetlenül, hogy a forrást a hivatkozáson vagy a célján keresztül olvasták be, és a konfigurált témakönyvtárra oldja fel őket.

Az aktív gyermek- és szülőtémákon kívüli fájlok továbbra is támogatottak a konfigurált abszolút útvonalukon, a PHP open_basedir korlátozásainak betartásával. Ezek nem helyezhetők át automatikusan: külső forrás áthelyezése után frissítse a konfigurált útvonalát, majd futtasson explicit szinkronizálást.

Bejegyzésmezők tulajdonjoga

A postStatus állítja be a kezdeti állapotot. A későbbi szinkronizálások megőrzik a meglévő piszkozat, függőben lévő, privát, közzétett és ütemezett állapotokat, a --authoritative használatakor is. A piszkozat nem kerül ismét közzétételre pusztán azért, mert a fájlban ez szerepel: postStatus: "publish". Az árván maradt bejegyzések meglévő helyreállítási viselkedése változatlan: explicit szinkronizálás visszaállítja a kukába helyezett, kezelt bejegyzést, ha a forrása jelen van. A visszaállítás megakadályozásához zárolja az oldalt, vagy tiltsa le a szinkronizálást.

A fájl továbbra is a cím, a slug, a bejegyzéstípus, a szülő és a konfigurált menüsorrend forrása. Ezek szerkesztése a WordPress felületén nem változtatja meg a forrásdefiníciót. A következő explicit szinkronizálás ismét alkalmazza a fájl értékeit, és megnevezi az érintett mezőket a pages.<name>.overwritten felületén, figyelmeztetéssel a CLI táblázatos kimenetében. A WordPress natív jogosultságai továbbra is érvényesek, ideértve a függőben lévő bejegyzések üres slugját is, ha a szinkronizálást végző felhasználó nem teheti közzé őket.

Használja a blockstudio/pages/update_post_data megoldást olyan integrációhoz, amely kifejezetten más állapotkezelési szabályzatot alkalmaz. A kulcsokkal ellátott blokkok megőrzik a szerkesztő által kezelt blokktartalmat; a kulcsok nem változtatják meg a bejegyzés címének vagy slugjának tulajdonjogát.

A gyűjteményoldalak esetében az ujjlenyomatok a jegyzéket, a betöltőt, az oldalforrást, az elrendezésfájlt, a metaadatokat és a kapcsolódó forrásútvonalakat is lefedik. A következő kifejezett szinkronizálás érvényesíti ezeknek a bemeneteknek a változásait.

Ha egy gyűjtemény forrása megszűnik, a Blockstudio eltávolítja a generált oldalt, így a régi gyűjteményoldalak nem maradnak meg a forrásfájl törlése után. Alapértelmezés szerint az árva gyűjteményoldalak a kukába kerülnek. A blockstudio/pages/orphan_action segítségével a trash, delete vagy keep értékét adhatja vissza.

Frontendkéréseknél a Blockstudio a már szinkronizált, közzétett bejegyzésekből tölti be az oldalregisztert. A piszkozat- és privát oldalak az adminisztrációs és szinkronizálási környezetekben érhetők el, a frontend-segédfüggvények azonban csak a közzétett oldalakat töltik be.

Telepítési egyeztetés

A Blockstudio\Pages::reconcile() a PHP telepítés belépési pontja. Felderíti a teljes kívánt jegyzéket, összehasonlítja a források és a szinkronizáló motor ujjlenyomatait, majd géppel feldolgozható jelentést ad vissza:

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

A jelentés tartalmazza a következőket: discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, oldalankénti eredményeket, felderítési hibákat és egy determinisztikus sourceIdentity értéket.

A zárolt oldalak status: "locked" értékkel rendelkeznek, és a változatlan oldalaktól elkülönítve szerepelnek a számlálásban. A removedPages minden eltávolított oldal name, key, postId és tényleges action értékét sorolja fel (trash vagy delete); a megtartott vagy már korábban a kukába helyezett bejegyzések nem számítanak újonnan eltávolítottnak. A CLI táblázatos kimenete a létrehozott, frissített, zárolt, eltávolított és tartalommegőrzött oldalakat is felsorolja a bejegyzésazonosítóikkal.

A feldolgozás és a kulcsok alapján történő összevonás után a végleges bejegyzés változatlansága esetén nem történik wp_update_post()-hívás, nem változik a post_modified, nem jön létre új verzió, és nem futnak le a bejegyzésfrissítési horgok. Az eredmény: unchanged. Ha a forrás tartalma eltér a szerkesztő által kezelt, kulcsokkal ellátott tartalomtól, a preserved: true jelzi ezt a döntést, és a felső szintű preserved számláló tartalmazza ezt az esetet. Az új forrás-ujjlenyomatot és a kezelt metaadatokat ettől függetlenül rögzíti, így a következő, változatlan szinkronizálás már nem végez módosítást. A preserved kiegészítő jelző, nem kizárólagos állapot: egy oldal megőrizheti a kulcsokkal ellátott tartalmat úgy is, hogy közben frissül a fájl által meghatározott címe, vagy újabb blokk kerül hozzá.

A authoritative: true feloldhatja az oldalszinkronizálási zárolást, és a kulcsokhoz kötött szerkesztői tartalom megőrzése helyett lecseréli a tartalmat a fájldefiníció alapján. Hagyja false értéken a szokásos, kifejezett szinkronizáláshoz. A plan_valid: false, full: true, broad: true, a korábbi forrásazonosító hiánya vagy a szinkronizáló motor megváltozott ujjlenyomata teljes egyeztetésként jelöli meg a műveletet (fullReconciliation a jelentésben). Mindkét esetben minden művelet összehasonlítja a teljes jegyzéket. A Git átnevezési rekordok csak azonosságra utaló tippek. Soha nem helyettesítik a teljes jegyzék összehasonlítását.

A változatlan útvonalakkal rendelkező, egyező ujjlenyomatok nem írnak bejegyzést vagy bejegyzés-metaadatot, és nem váltanak ki frissítési hookokat. Ha egy változatlan forrás új kiadási könyvtárba kerül, az egyeztetés csak a tárolt sablont, tartalmat, elrendezést és könyvtárútvonalakat frissíti; a post_content értékét és a módosítási időbélyeget nem változtatja meg. A hiányzó kezelt oldalak eltávolítása csak akkor történik meg, ha a teljes egyeztetési folyamat felderítési és oldalírási hibák nélkül befejeződik.

A közvetlen API egyeztetés nem jelöli sikeresként a telepítést. A megfelelő statikus műtermék és útvonalak aktiválása és ellenőrzése után mentse el kifejezetten a visszaadott azonosítót:

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

A wp bs pages sync sikeres művelet után tárolja a visszaadott azonosítót. A szokásos WP-CLI rendszerindítás csak a tárolt gyűjtemény-bejegyzéstípusokat és átírásokat regisztrálja. Nem derít fel és nem szinkronizál oldalakat.

Bejegyzésazonosítók rögzítése

Alapértelmezés szerint a WordPress automatikusan rendel bejegyzésazonosítókat. Ha törölnek, majd újra létrehoznak egy oldalt, megváltozik az azonosítója, ami megszakítja a külső hivatkozásokat, például a menüket vagy a rögzített linkeket.

A postId használatával rögzítheti az oldalt egy adott azonosítóhoz:

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

Az oldal létrehozásakor a Blockstudio átadja az azonosítót a WordPress számára a import_id segítségével. Ha az azonosító szabad, a WordPress pontosan azt használja. Ha egy másik, nem kapcsolódó bejegyzés már foglalja az azonosítót, a WordPress csendben automatikusan új azonosítót rendel hozzá.

Meglévő oldalak keresésekor a Blockstudio először a rögzített azonosítót ellenőrzi, majd a metaadatokat vagy a slugot. Ez azt jelenti, hogy törlés és újbóli szinkronizálás után az oldal visszakapja ugyanazt az azonosítót.

Kulcshoz kötött blokkok összevonása

Alapértelmezés szerint egy sablonfájl módosításakor a Blockstudio lecseréli a teljes bejegyzéstartalmat az új sablonra. Ez azt jelenti, hogy a WordPress szerkesztőben végzett módosítások elvesznek.

Adjon key attribútumot a blokkokhoz, hogy a felhasználói módosítások a sablon szinkronizálásai között is megmaradjanak. Ha egy sablon kulcsokkal ellátott blokkokat tartalmaz, a Blockstudio összevonja a sablon módosításait a meglévő bejegyzéstartalommal ahelyett, hogy lecserélné azt.

Kulcsok hozzáadása

Használja a key attribútumot bármely HTML- vagy <block>-elemen:

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

A kulcsoknak a teljes sablonban egyedinek kell lenniük. Egy kulcs a teljes blokkot és annak minden tartalmát védi. Kulccsal ellátott szülőn belül nem kell külön kulcsot adnia az egyes gyermekelemeknek. A kulcsos blokkok a sablonfrissítések között bármely pozícióba vagy beágyazási szintre áthelyezhetők, a felhasználói tartalmuk pedig továbbra is megmarad.

A kulcsok ugyanígy működnek az egyéni Blockstudio blokkokkal is. A key a Page Sync szerkezeti metaadata; az egyéni mezők értékei továbbra is szokásos Blockstudio attribútumok maradnak. Ha egy szerkesztő módosítja ezeket a mezőket, a későbbi sablonszinkronizálás megőrzi a szerkesztő értékeit, miközben a sablon független módosításait is alkalmazza. A régebbi verziókkal létrehozott, az egyéni mezőadatokba ágyazott kulccsal rendelkező oldalak a következő szinkronizáláskor automatikusan migrálódnak.

Az összevonás működése

Ha egy sablonfájl módosul, és az oldalt újra szinkronizálják:

Blokk Viselkedés
Kulcsos blokk A felhasználói tartalom és a Blockstudio mezőértékek megmaradnak. A sablonhoz tartozó attribútumok és szerkezet érvénybe lépnek.
Kulcs nélküli blokk Teljes egészében a sablonverzió váltja fel (ugyanúgy, mint kulcsok nélkül)

Példák

A kulcsos blokkokban megmaradnak a felhasználói módosítások:

  1. A sablon meghatározza a <p key="intro">Default intro.</p> elemet
  2. A felhasználó a szerkesztőben „Egyéni bevezető szöveg.” szövegre módosítja a bekezdést.
  3. A fejlesztő frissíti a sablont, új blokkot ad hozzá, és módosítja az elrendezést.
  4. Szinkronizáláskor a bekezdésben megmarad az „Egyéni bevezető szöveg.”, miközben az új elrendezés is érvénybe lép.

A sablon attribútumai továbbra is érvényesülnek:

  1. A sablon tartalmaz egy borítóblokkot key="hero" és egy url attribútummal.
  2. A fejlesztő a borító url attribútumát egy új háttérképre módosítja.
  3. Szinkronizáláskor érvénybe lép az új háttérkép, a borítón belüli felhasználói tartalommódosítások viszont megmaradnak.

Szélső esetek

Eset Viselkedés
Új kulcsos blokk kerül a sablonba Megjelenik a sablon alapértelmezett tartalmával
Kulcsos blokk törlése a sablonból Törlődik a bejegyzésből
Megváltozik a blokk típusa (azonos kulcs) Teljes egészében a sablon az irányadó, nincs tartalom-összevonás
Duplikált kulcsok A második előfordulást kulcs nélküliként kezeli a rendszer
Nincs kulcs a sablonban Teljes csere történik (ugyanúgy, mint kulcsok nélkül)
Kényszerített szinkronizálás Teljes csere történik, a kulcsokat figyelmen kívül hagyja a rendszer
Zárolt bejegyzés Egyáltalán nem szinkronizálódik

Szerkesztési vezérlőkkel kombinálva

A kulcsok, a templateLock és a blockEditingMode együttesen részletes szabályozást adnak afelett, hogy az ügyfelek mit tehetnek és mit nem. Íme néhány gyakori munkafolyamat-minta.

Teljesen zárolt oldal

A fejlesztő mindent kézben tart. Az oldal statikus elrendezésű, amelyhez az ügyfelek egyáltalán nem nyúlhatnak. Hasznos jogi oldalakhoz, szolgáltatási feltételekhez vagy bármely olyan oldalhoz, amely csak kódmódosítással változhat.

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>

Nincs szükség kulcsokra. A sablon az egyetlen hiteles forrás. Minden szinkronizálás teljes egészében felülírja az oldalt.

Zárolt elrendezés szerkeszthető tartalommal

A leggyakoribb minta. Zárolja az oldal szerkezetét, hogy az ügyfelek ne adhassanak hozzá, ne távolíthassanak el és ne rendezhessenek át blokkokat, de engedje meg nekik a szöveg szerkesztését meghatározott helyeken. A kulcsok biztosítják, hogy módosításaik a sablonfrissítések után is megmaradjanak.

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>

Az ügyfél szerkesztheti a főcím, a leírás és a funkcióbemutató szövegét. Semmi mást. A gomb szövegét, a URL elemet és a borító háttérképét a fejlesztő szabályozza. Amikor a fejlesztő frissíti a sablont (e.g., hozzáad egy második gombot), a kulcsokkal azonosított szakaszok megőrzik az ügyfél szövegét.

Folyamatosan bővülő sablon, megőrzött tartalommal

Idővel bővülő oldalakhoz. A fejlesztő új szakaszokat ad a sablonhoz, és minden szinkronizálás hozzáadja az új tartalmat anélkül, hogy módosítaná azt, amit az ügyfél már testre szabott.

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>

Az új vélemények szakasz és a gomb megjelenik a szinkronizáláskor. Az ügyfél címét, bevezetőjét és szolgáltatásait érintő módosítások változatlanok maradnak.

Egyszeri kiinduló váz

Hozzon létre egy oldalt kiinduló szerkezettel, majd adja át teljes egészében. Állítsa a sync értékét false értékre, hogy a normál szinkronizálás soha ne hozza létre vagy frissítse az oldalt, és hozza létre egyszer a Blockstudio\Pages::force_sync('blog') segítségével. Ezután az oldal teljes egészében az ügyfélé.

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

A wp bs pages sync kihagyja ezt az oldalt, ezért a force_sync() egyszer létrehozza. Ezután az ügyfél szabadon hozzáadhatja, eltávolíthatja és átrendezheti a blokkokat. A sablon módosításai nem érvényesülnek.

Blokk-kötések

A kulcsok szerinti összevonás alternatívája a WordPress alapfunkciójának Blokk-kötések API használata, amellyel a blokkok a bejegyzés metaadataihoz kapcsolhatók. Ez nem Blockstudio-funkció, hanem natív WordPress API. A Blockstudio egyszerűen átadja a metadata attribútumot a létrehozott blokkjelölésnek. A tartalom a bejegyzés metaadataiban él a blokkjelölés helyett, így a sablon szinkronizálása szabadon felülírhatja a jelölést, mert a szerkesztő a metaadatokból olvas, nem az innerHTML-ből.

Adja át a metadata attribútumot bármely HTML vagy <block> elemnek:

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

A metaadatkulcsokat regisztrálni kell úgy, hogy a show_in_rest engedélyezve legyen:

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

Kulcsok és kötések

Szempont Kulcsok Kötések
A tartalom tárolási helye Blokkjelölés (post_content) Bejegyzés-metaadat (wp_postmeta)
Megmarad a sablon szinkronizálása után Igen (kulcs szerint összevonva) Igen (az adatok a metaadatokban vannak)
Lekérdezhető a WP_Query segítségével Nem Igen (meta_query)
Elérhető a REST API felületén Nem Igen
Regisztráció szükséges Nem Igen (register_post_meta)
A felhasználó áthelyezheti a blokkokat Nem (a sablon visszaállítja a szerkezetet) Nem (a sablon visszaállítja a szerkezetet)

Mindkét megközelítés használható ugyanabban a sablonban. Használjon kulcsokat azoknál a szakaszoknál, ahol fontos a blokk szerkezete (e.g., több gyermekelemet tartalmazó csoport). Az egyes mezőkhöz használjon kötéseket, ha azt is szeretné, hogy az adatok a blokk szerkesztőjén kívül is elérhetők legyenek.

Bejegyzéstípus-sablonok

A templateFor segítségével állíthat be egy oldalt egy bejegyzéstípus alapértelmezett sablonjaként:

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

Az adott típus minden új bejegyzése a meghatározott blokkszerkezettel indul.

Egyéni elérési utak

Alapértelmezés szerint a Blockstudio a get_template_directory() . '/pages' útvonalat vizsgálja. További útvonalakat a következő szűrővel adhat hozzá:

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

A több gyökérből származó fájlokat összeállító futásidejű integrációk a fájlrendszer vizsgálatát logikai felderítési forrással helyettesíthetik. Az oldaljegyzékek, elrendezések, betöltők és forrássablonok ezután logikai útvonal alapján oldódnak fel, még akkor is, ha a kiválasztott fájlok különböző gyökerekben találhatók.

Szűrők és műveletek

Az oldalak felderítése, szinkronizálása és a gyűjtemények útvonalkezelése a következő bővítési pontokat teszi elérhetővé:

Horgony Típus Leírás
blockstudio/pages/paths Szűrő Könyvtárakat ad hozzá, amelyeket a Blockstudio átvizsgál az oldalforrások kereséséhez.
blockstudio/pages/collection_post_type_args Szűrő Módosítja a gyűjtemény CPT-jének register_post_type() argumentumait.
blockstudio/pages/template_candidates Szűrő Módosítja az oldalforrásként figyelembe vett sablonfájlneveket.
blockstudio/pages/serve_markdown Szűrő Engedélyezi vagy letiltja a nyers Markdown válaszokat.
blockstudio/pages/orphan_action Szűrő Árvák törlésekor a következők egyikét adja vissza: trash, delete vagy keep.
blockstudio/pages/docs_allowed_html Szűrő Módosítja a generált Markdown dokumentációs tartalom engedélyezett HTML értékeit.
blockstudio/pages/allow_external_loader_path Szűrő Engedélyezi a betöltő paths útvonalát a gyűjtemény gyökerén kívül is.
blockstudio/pages/manifest_scan_interval Szűrő Beállítja a régi, 7.6.2 előtti jegyzék-gyorsítótár maximális korát, amely frissítéskor a megőrzött futásidejű konfiguráció kezdőértékéül szolgálhat.
blockstudio/pages/create_post_data Szűrő Módosítja a bejegyzésadatokat a szinkronizált oldal létrehozása előtt.
blockstudio/pages/update_post_data Szűrő Módosítja a bejegyzésadatokat a szinkronizált oldal frissítése előtt.
blockstudio/pages/sync_engine_inputs Szűrő Hozzáad egy olyan elemző-, leképezési vagy migrációs verziót, amelynek egyszeri egyeztetési bővítést kell kiváltania.
blockstudio/pages/post_created Művelet A szinkronizált oldalbejegyzés létrehozása után fut le.
blockstudio/pages/post_updated Művelet A szinkronizált oldalbejegyzés frissítése után fut le.
blockstudio/pages/synced Művelet Az oldalak jegyzékének szinkronizálása után fut le.
blockstudio/pages/reconciled Művelet Explicit egyeztetés után fut le, a géppel feldolgozható jelentéssel.
blockstudio/pages/renderers Művelet Oldalrenderelők regisztrálása a Blockstudio\Page_Renderers::register() segítségével. Kérésenként egyszer fut le.
blockstudio/pages/rendered Művelet Egy komponensoldal renderelése után fut le az oldallal, annak HTML értékével és függőségeivel.
blockstudio/pages/layout_error Művelet Akkor fut le, ha egy elrendezés nem renderelhető; megkapja a hibát, az elrendezés útvonalát és az oldalt.

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

A Telepítési egyeztetés dokumentum ismerteti az argumentumok szemantikáját, a jelentés mezőit és a hitelesített forrásazonosság határát.

Globális segédfüggvények érhetők el a sablonokhoz és elrendezésekhez:

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

A Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() által visszaadott oldaltömbök és a globális segédfüggvények tartalmazzák a szinkronizált bejegyzés azonosítóját, a forrás- és sablonútvonalakat, a gyűjteményre és útvonalra vonatkozó metaadatokat, a tartalomtípust, a szinkronizálási szabályt, a bejegyzéstípust és állapotot, a szerkesztési szabályt, az egyéni metaadatokat, valamint egy permalink kulcsot. A gyűjtemény metaadatai az utolsó sikeres, kifejezett egyeztetésből töltődnek be. A normál kérések a futásidejű adatokat a tartós konfigurációból és a szinkronizált bejegyzések metaadataiból állítják össze, az oldalforrások könyvtárainak beolvasása nélkül. A Pages osztály nem biztosít külön metódust az állandó hivatkozás lekérésére.

Fájlalapú oldalak készítése

Sablonzárolás, blokk szerkesztési módok, kulcs szerinti összevonás és az ügyfél által szerkeszthető tartalmak szabályozása.