Liigu sisu juurde

Lehed

Lehed on failipõhised mallid, mis sünkroonitakse WordPress andmebaasi postitustena. Sünkroonimine toimub selgesõnaliselt: käivitage wp bs pages sync või kutsuge välja Pages API, kui soovite lähtekoodi muudatused rakendada. Esilehe laadimine või WordPress administraatori vaade ei tuvasta kõiki lehti ega muuda lehepostitusi.

Lehti saab määratleda ühe page.json kaustana, eraldiseisvate Markdown failidena või kogumina, millel on pages.json manifest. Kogumid sobivad dokumentatsiooni, teadmistebaaside, sihtlehtede teekide või mis tahes pesastatud lehtede hulga jaoks, mida soovite failidest luua.

page.json

JSON-iga määratletud lehe jaoks lisage konfiguratsioonifail page.json:

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

Omadused

Atribuut Tüüp Vaikeväärtus Kirjeldus
name string nõutav Lehe kordumatu tunnus
title string Nimest automaatselt Lehe pealkiri
slug string Sama mis nimi Lehe URL slug
path string "." Loogiline tee kogumi sees
order integer 0 Sünkroonitud postituse menüüjärjestus
postType string "page" WordPress postituse tüüp
postStatus string "draft" Uute postituste olek (publish, draft, pending, private)
postId integer – Kinnita leht konkreetse WordPress postituse ID-ga
blockEditingMode string – Plokkide muutmise režiim: "default", "contentOnly" või "disabled"
templateLock string|false "all" Lukustusrežiim: "all", "insert", "contentOnly" või false
templateFor string|null null Määra postituse tüübi vaikemalliks
sync boolean true Määrab, kas tavaline selgesõnaline kooskõlastamine võib postituse luua või seda värskendada
render string|object|false – Renderda leht registreeritud leherenderdajaga (vt Komponentlehed)

page.json-is, esipäises ja laadimiskirjetes tuntakse ära järgmised võtmed: blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock ja title. Kõik loetlemata võtmed salvestatakse lehe massiivi meta alla.

Sisuallikad

Lehe määratlus otsustab, milline WordPress postitus peaks olemas olema. Sisuallikas määrab, milline plokimärgistus sellesse postitusse kirjutatakse.

Kui lehekaustas on page.json, otsib Blockstudio samast kaustast lähtefaili järgmises järjekorras:

Fail Kasutus
index.php HTML-laadne plokimärgistus, loetakse muutmata kujul (PHP koodi ei käivitata)
index.blade.php Blade malli sisu
index.twig Twig malli sisu
index.md Markdown sisu

page.json võib kõrvuti asuva faili asemel sisaldada ka tekstisisest markdown või html:

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

Kogumid lisavad veel kaks allikarežiimi:

  • otse kogumipuust leitavad Markdown failid.
  • loader.php tagastatud laadijakirjed.

Laadijakirjed võivad kasutada vorminguid markdown, html või content koos väärtusega contentType. Need võivad viidata ka kohalikule file või template failile. Faili- ja malliallikate tüüp tuletatakse laiendist, välja arvatud juhul, kui contentType on selgesõnaliselt määratud.

Toetatud contentType väärtused on php, blade, twig, markdown ja html. Esmalt teisendatakse Markdown väärtuseks HTML, seejärel parsitakse see natiivseteks WordPress plokkideks. Allikad PHP, Blade, Twig ja HTML läbivad tavapärase Blockstudio leheparseri.

Tuumaplokkide klassid

Elementi HTML kaardistatud tuumaploki class muutub selle ploki className-ks. Selgesõnaline tuumaploki silt võib kasutada otse väärtust className. Mõlemad vormid säilitavad ploki salvestatud ümbrise klassid koos klassidega, mille loob WordPress:

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

Kui mõlemad omadused on olemas, on className ülimuslik. See teisendus kehtib ainult tuumaplokkidele: kohandatud ploki kaardistus jätab selle välja class muutmata. Nupu stiiliklassid, nagu is-style-outline, kuuluvad nupu ümbrisele, mitte selle lingile.

Käivitage wp bs pages sync, et rakendada varem sünkroonitud lehtedele parseri parandused. Parseri uuendused tuvastatakse järgmisel selgesõnalisel sünkroonimisel ilma lähtefaili muutmata. Lukustatud lehtedel ja lehtedel, millel on sync: false, kehtivad tavapärased kaitsemeetmed; esiotsa päringud seda sünkroonimist kunagi ei käivita.

Serialiseeritud WordPress plokid

Lehtede ja mustrite allikad võivad sisaldada ka serialiseeritud plokke, mis on kopeeritud WordPress koodiredaktorist:

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

Kui lähte sisaldab <!-- wp:... --> plokieraldajat, kasutab Blockstudio kogu lähte töötlemiseks WordPress algset plokiparserit. Atribuudid, pesastatud plokid, dünaamilised plokid, näiteks päringutsükkel, ja Blockstudio plokid säilitavad oma serialiseeritud struktuuri. Plokikommentaaridest väljaspool olev HTML jääb algupäraseks vabavormiliseks HTML-ks; seda ei teisendata täiendavateks plokkideks. Ära sega Blockstudio HTML plokisilte selle vorminguga, eeldades, et need teisendatakse. Tavalised HTML kommentaarid ei vali serialiseeritud plokkide režiimi.

Markdown lehed

Kasutage Markdown, kui soovite hoida proosat failides, kuid muuta see pärast sünkroonimist redigeeritavaks WordPress plokisisuks. Sünkroonimise ajal teisendatakse Markdown allikas plokimärgistuseks. Sünkroonitud postitus sisaldab plokke, mitte töötlemata Markdown sisu.

Markdown saab kasutada kolmel viisil:

Allikas Kas esiosaandmed on nõutud? Märkused
Eraldiseisev pages/example/index.md Jah Esiosaandmed määravad lehe identiteedi.
page.json koos failiga index.md Ei page.json määratleb lehe ja Markdown annab sisu.
Markdown kogumi sees Ei Kogum tuletab asukohast name ja path.

Eraldiseisev index.md ilma esiosaandmeteta jäetakse vahele, sest Blockstudio ei sisalda sünkroonimiseks vajalikku lehe identiteeti. Kogumis olevad Markdown failid ei vaja esiosaandmeid, sest selle identiteedi määravad kogumi manifest ja failitee.

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

# About

This Markdown content is synced as native WordPress blocks.

Võite ühendada page.json faili ka failiga index.md. Sel juhul määratleb page.json lehe ja index.md annab sisu. Faili index.md esiosaandmed kirjutavad vastavad page.json väärtused üle.

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.

Kogumi Markdown puhul saab failiteest lehe loogiline asukoht, kui esiosaandmetes pole seda muudetud:

Fail Vaikimisi asukoht
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

Tundmatud esiosaandmete võtmed säilitatakse lehe massiivis meta. Nii saate lisada andmeid, näiteks section või description, ning lugeda neid objektist PHP API.

Markdown parsitakse kujul GitHub Flavored Markdown. Toorfaili HTML kasutamine on lubatud, ebaturvalised lingid eemaldatakse ja ilma selgesõnalise ID-ta pealkirjadele antakse püsiv ID. Pesastatud YAML esiosaandmete jaoks on vaja komplektis olevat parserit YAML.

Toores Markdown

Markdown failiallikad võivad välistele tööriistadele ja dokumentatsiooni tarbijatele pakkuda algset allika Markdown. Tekstisisene Markdown ei pärine failist, seega sünkroonitakse see plokkideks, kuid toorest .md vastust ei väljastata.

Pärige lehte sufiksiga .md, näiteks https://example.com/docs/reference.md. Või saatke tavalisele lehe URL-le päis Accept: text/markdown:

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

Esiosaandmed eemaldatakse vastusest. Edukate toor-Markdown vastuste päised Content-Type: text/markdown ja X-Robots-Tag: noindex ning kanooniline päis Link suunatakse tagasi lehe HTML-i. Puuduva .md korral tagastatakse tegelik 404.

Kooskõlastus toimib koos staatilise eeleelrenderdusega: päringut, mille Accept päis sisaldab text/markdown, ei teenindata kunagi eeleelrenderduse vahemälust ega varase teenindamise lisamoodulist, vaid see jõuab WordPress ja Markdown töötlejani. Eeleelrenderdatud HTML vastused, lehe HTML, mis kasutab ka Markdown läbirääkimist, ja Markdown, millele vastatakse Accept kaudu, saadavad Vary: Accept, nii et vahemälud, mis arvestavad Vary väärtusega, hoiavad need lahus. URL alusel vahemällu salvestav CDN peab selliste päringute vahemälust möödumiseks lisama oma reegli. Pages::negotiates_markdown( $post_id ) näitab, kas leht vastab Markdown päringutele.

Kogumis säilitab Markdown toore Markdown jaoks sama URL kuju:

Lehe URL Toores Markdown URL
/docs/ /docs.md
/docs/getting-started/ /docs/getting-started.md
/docs/guide/install/ /docs/guide/install.md

Toore Markdown vastused saab keelata filtriga blockstudio/pages/serve_markdown:

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

Markdown-põhisele lehele mittevastav .md URL tagastab 404 ainult siis, kui tee asub lehekogumi sees. Väljaspool kõiki kogumeid jätab Blockstudio päringu WordPress ja teiste pistikprogrammide käsitleda.

Komponentlehed

Komponentlehe renderdab leherenderdaja, selle asemel et see plokkidena salvestataks. Blockstudio ei sisalda renderdajat. Teema või plugin registreerib selle enda hallatavate kirjetefailide jaoks, näiteks page.tsx jaoks React renderdaja, ning Blockstudio kutsub seda lehe, WordPress postituse ja renderdatud pesa sisuga.

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 on selgesõnaline. Kataloog, kus on index.php ja page.tsx, kuid puudub render, jääb tavaliseks leheks, nii et renderdaja lisamine ei renderda olemasolevat lehte kaks korda. Vormid on järgmised:

Väärtus Tähendus
"page.tsx" Ainult kirje, andmelaadurita
{ "entry": "page.tsx", "data": "data.php" } Kirje ja andmelaadur
{ "entry": "page.tsx", "renderer": "react" } Kirje selgesõnalise renderdaja ID-ga
false Renderdajat pole, isegi kui kogumi vaikeväärtuses on üks nimetatud

Teed lahendatakse lehe kataloogi suhtes või laadimiskirjete puhul kogumi juurkataloogi suhtes. Need peavad jääma avastamisallika sisse, välja arvatud juhul, kui blockstudio/pages/allow_external_loader_path seda lubab. Kui renderer puudub, kasutatakse renderdajat, mis võtab enda alla kirje laiendi. Kui render viitab puuduvale kirje- või andmefailile, tundmatule renderdajale või laiendile, mida ükski renderdaja ei toeta, on tegemist avastamisveaga, mis peatab kooskõlastamise enne, kui midagi kustutatakse.

Mida sünkroonimine salvestab

Sünkroonimine salvestab ühe blockstudio/page ploki. Kui lehe kataloogis on ka allikas index.*, parsitakse seda nagu iga muud leheallikat ning sellest saavad ploki sisemised plokid ehk pesa:

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

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

Hoidke WordPress hallatavat sisu, näiteks lühikoode, pesas. Ainult ühest lühikoodist koosnev allikas, näiteks [download_checkout], salvestatakse plokina core/shortcode, nii et selle väljundi ümber ei lisata lõiku. See jääb asukohta post_content, mistõttu has_shortcode() kontrollid leiavad selle üles; võtmega pesaplokid liidetakse redaktori muudatustega nagu pesastatud võtmega plokid ning do_shortcode laiendab lühikoodid ühe korra tavapärase the_content prioriteediga, pärast seda, kui renderdaja on neile ümbrise lisanud.

Renderduse definitsioon salvestatakse koos postitusega kaasaskantavate theme:-teedena. Lehe sõrmejälg hõlmab definitsiooni, mitte kirje ega andmelaaduri baite: page.tsx või data.php muutmine jätab postituse muutmata ning muudatus jõuab külastajateni renderduse ja staatilise eelrenderdamise graafi kaudu. Graaf salvestab kirje, andmelaaduri ja kõik failid, millest renderdaja teatab.

Renderdaja registreerimine

Registreerige renderdajad toimingul blockstudio/pages/renderers. See käivitub päringu kohta ühe korra enne esimest avastamist või renderdamist, nii et wp bs pages sync ja kasutajaliidese päringud näevad sama registrit.

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

Renderdaja ID-d kirjutatakse väiketähtedega. Laiend või paigutuse nimi võib kuuluda ainult ühele renderdajale ning layout.php jääb Blockstudio enda paigutuseks. Kutsutav funktsioon saab ühe päringu:

Võti Väärtus
kind page või renderdaja paigutuse korral layout
renderer Renderdaja ID
entry Kirje absoluutne tee
data Andmelaaduri absoluutne tee või null
page Kanoonilised leheandmed, sealhulgas meta
post_id WordPress postituse ID
slot Renderdatud pesa sisu või paigutuse korral lehe sisu
context frontend, rest, feed või cli

See tagastab HTML, renderdamisel loetud failid ja valikulised varad:

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 pärineb päringu tüübist, mitte kunagi külastajalt, seega ei saa renderdaja sisselogitud ja anonüümse kasutaja baitide pariteeti selle lugemisega rikkuda. Kui renderdaja ebaõnnestub, visatakse viga: leht ei renderda tühja sisu. REST redaktori eelvaates kuvab plokk selle asemel veateate märkusena. Pärast edukat renderdamist saab blockstudio/pages/rendered toiming lehe, HTML ja selle sõltuvused.

assets loetleb skripti- ja stiilifailid, mida leht vajab. Neid töödeldakse nagu ploki varasid (*.inline.* tava, ES moodulid, minimeerimine ja ?ver) ning leht lisab need üks kord sama puhvri kaudu, mida kasutatakse ploki varade lisamiseks, nii et eelpärenderdatud leht sisaldab neid. Vara võib määrata version, et asendada oma ?ver väärtus. Väljaspool renderdajat saab sama kanalit kasutada Blockstudio\Assets::register_owner() kaudu, mis tagastab lisatava markerkommentaari.

Redaktor

Redaktoris kuvab blockstudio/page lehe serveris renderdatud eelvaadet, kus pesa on sisemiste plokkidena, mis järgivad lehe templateLock. Plokki ei saa lisada, paljundada ega teise ploki sisse paigutada.

Lehekogumid

Kogum on kaust, milles on pages.json manifest. See koondab mitu leheallikat ühe kogumi slug’i alla, rakendab vaikeväärtusi, toetab pesastatud teid ja võib automaatselt registreerida spetsiaalse postitusetüübi.

Kood
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"
  }
}
Atribuut Tüüp Kirjeldus
collection / slug / name string Kogu lühinimi. collection on kõige selgem vorm ja sellest saab avalik URL baas.
title string Inimloetav kogu pealkiri.
postType string Genereeritud lehtede postituse tüüp. Vaikimisi page. Kui seda pole, registreerib Blockstudio selle.
postTypeArgs object Argumendid, mis edastatakse register_post_type()-le, kui Blockstudio registreerib kogu postituse tüübi.
defaults object Vaikimisi lehe atribuudid, mida rakendatakse igale kogu lehele. Vaikimisi render rakendatakse lehele ainult siis, kui selle kirje on lehekataloogis olemas.
scope string collection (vaikimisi) või site. Vt Saidi kogud.
meta object Kohandatud kogu metaandmed. Tundmatud manifestivõtmed salvestatakse samuti asukohta meta.

Kogumi lehtede asukohad on loogilised teed. path: "guide/install"-iga leht sünkroonitakse objekti guide alamlehena ning guide sünkroonitakse kogumi juurkausta alamlehena, kui need ülemlehed on olemas.

Kui hierarhilises kogumis on pesastatud leht, kuid vahepealse ülemlehe allikat pole, loob Blockstudio sellele teele tühja konteinerlehe, et WordPress hierarhia oleks täielik. Mittehierarhiliste postitusetüüpide puhul (need, mis ei toeta ülemlehte page-attributes) tühje konteinereid ei looda. Need suunatakse salvestatud kogumitee alusel, mistõttu võivad teed guide/install ja setup/install koos eksisteerida, kuigi mõlemad lõpevad väärtusega install.

Kogumi postitusetüübid ja URL-id

Määrake kogumi manifestis postType, et sünkroonida kõik kogumi lehed selle postitusetüübiga. Sama väärtust pole vaja failis defaults korrata. Üksikud lehed saavad postType väärtuse esiosaandmetes või failis page.json siiski üle kirjutada.

Kui postitusetüüpi pole olemas, registreerib Blockstudio selle koos väärtusega show_in_rest: true, lehelaadse redaktoriga ning kogumi slug’iga avaliku URL baasina. Registreerimisargumente saab muuta väljaga postTypeArgs. Kogumi postitusetüüpide URL-i ümberkirjutamise reegleid värskendatakse automaatselt, kui registreeritud kogumi postitusetüübid või ümberkirjutamise argumendid muutuvad; püsilinke WordPress pole vaja uuesti salvestada.

Kogumi URL-id koosnevad kogumi slug’ist ja iga lehe loogilisest asukohast path:

Lähtefaili tee Avalik URL
path: "." /docs/
path: "getting-started" /docs/getting-started/
path: "guide/install" /docs/guide/install/

See URL mudel töötab nii hierarhiliste kui ka mittehierarhiliste kogumi postitüüpidega. Blockstudio suunab ka topelt-URL-id, näiteks /docs/docs/ või /docs/docs/getting-started/, kanoonilisele aadressile URL.

Kogumilehed avaldavad toore Markdown samadel URL-idel (vt Toores Markdown).

Kui muudate kogumi tüübi väärtuselt postType: "page" kohandatud postitüübiks, migreerib Blockstudio juba sünkroonitud kogumipostitused olemasolevasse asukohta, kui salvestatud lehe identiteet vastab. Nii säilivad postituste ID-d, metaandmed ja olemasolev sisu ning välditakse vanatüübiliste postituste dubleerimist. Aegunud kogumipostitused koristatakse kõigi postituse olekute lõikes vastavalt filtrile blockstudio/pages/orphan_action.

Saidi kogud

Manifest, millel on "scope": "site", rühmitab kõik selle all olevad lehed neid kogulehtedeks muutmata. Kasutage seda saidi lehtede puu juurkaustas, et rakendada ühiseid vaikeväärtusi ja loetleda saidi lehed funktsiooniga 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" }
  }
}

Saidi kogu lehed säilitavad täpselt sama identiteedi, mis neil oli ilma manifestita, nii et selle lisamisel olemasolevasse puusse ei uuendata ühtegi postituse rida ega looda ega visata midagi prügikasti:

  • Võtmed jäävad globaalseteks: Pages::get_page( 'home' ) ja salvestatud lehe võtmed vastavad endiselt üksteisele.
  • URL-id jäävad WordPress lehe URL-ideks. Kogu ümberkirjutusreegleid, püsiviida filtrit ega kahekordse URL ümbersuunamist ei rakendata ning tühje konteinerlehti ei genereerita.
  • Loogilised teed, lühinimed, ülemlehed ja allikaidentiteedid on samad mis eraldiseisvatel lehtedel ning paigutused lahendatakse lähima eellase järgi.
  • Pesastatud pages.json manifestid säilitavad oma kogud ja nende alampuud jäetakse saidi kogust välja.
  • Vaikeväärtusi rakendatakse lehekaupa: vaikimisi render rakendatakse ainult lehtedele, mille kirje on kataloogis olemas, nii et lühikoodide ja Markdown lehed säilitavad oma allikad.

Kogumilaadurid

Kogumid võivad sisaldada usaldatud kohalikku loader.php. Kasutage seda siis, kui kogumilehed pärinevad teisest kohalikust allikast, näiteks välisest dokumentatsiooni kaustast, paketist või genereeritud manifestist.

Laadur käivitub lehtede selgesõnalise avastamise ja sünkroonimise ajal. See peaks olema deterministlik ja kohalik. Vältige kaugallikast sisu toomist loader.php kaudu, sest see seoks juurutuse sünkroonimise selle teenusega.

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

Laadur võib tagastada massiivi, mille võtmed on pages, meta ja paths:

Võti Kirjeldus
pages Lehemassiivide loend. Iga leht toetab samu tuvastatud võtmeid nagu page.json ja Markdown frontmatter.
meta Metaandmed, mis liidetakse iga laaduri loodud lehe massiiviga meta.
paths Täiendavad kohalikud kataloogid, mida selle kogu osana läbi otsida. Kirjed võivad olla stringid või teerajad.
render renderi määratlus igale Markdown lehele, mis leitakse asukohast paths.

Lühivormina võib laadur tagastada lihtsalt lehemassiivide loendi.

Laaduri lehekirjed võivad sisu esitada järgmistel viisidel:

Kuju Kirjeldus
markdown Reasisene Markdown sisu.
html Reasisene HTML sisu.
content + contentType Üldine reasisene sisu. contentType peab lahenduma väärtuseks markdown või html.
file Kohaliku faili allikas. Tüüp tuletatakse laiendist, välja arvatud juhul, kui määratud on contentType.
template file alias.

Laaduri failiviited võivad osutada allikatele PHP, Blade, Twig, Markdown või HTML. Suhtelised teed lahendatakse kogumi juurkataloogist lähtudes. Absoluutsed teed ja kogumi juurkataloogist väljapoole jäävad teed on lubatud ainult siis, kui filter blockstudio/pages/allow_external_loader_path neid lubab.

Laadurilehed kasutavad vaikimisi väärtust generated: true. Kui genereeritud laadurileht kaob laaduri väljundist, käsitleb Blockstudio sünkroonitud postitust järgmisel sünkroonimisel orvuna ning koristab selle filtri blockstudio/pages/orphan_action järgi.

Loendis paths olevaid katalooge avastatakse nagu tavalisi kogumi kaustu. Need võivad sisaldada Markdown faile või page.json kaustu. Kui need teed asuvad kogumi juurkataloogist väljaspool, kehtib sama väliste teede filter.

Kasutage stringkirjet, kui väline kataloog peaks säilitama oma loogilised teed. Kasutage objektkirjet, kui kataloog tuleb ühendada kogumi teeprefiksi alla:

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

Selle seadistusega muutub cli-docs/index.md kogumis väärtuseks path: "cli" ja cli-docs/getting-started.md väärtuseks path: "cli/getting-started". Prefiksid aitavad vältida ka genereeritud lehenimede kokkupõrkeid, nii et igas ühendatud kataloogis võivad olla näiteks index.md või getting-started.md. Määrake teepõhisel objektil preserveNames väärtuseks true, kui soovite säilitada sõnaselged name väärtused, mis pärinevad page.json või Markdown esilehe metaandmetest.

Teepõhise objekti atribuudid:

Atribuut Tüüp Kirjeldus
path string Kohalik kataloog, mida läbi otsida. Suhtelised teed lahendatakse kogu juurkausta suhtes.
prefix string Valikuline loogilise tee prefiks kogu sees.
preserveNames boolean Säilita selgesõnalised lehenimed, selle asemel et genereerida nimed prefiksiga teest. Vaikimisi false, kui prefix on määratud.
meta object Metaandmed, mis liidetakse igale sellelt teelt leitud lehele. Lehe taseme metaandmed on duplikaatvõtmete korral ülimuslikud.
render string|object Selle tee Markdown lehtede renderi määratlus, mis alistab laaduri render.

Markdown renderdamine komponendi kaudu

Kui kasutatakse render, renderdatakse laaduri leitud Markdown lehed leherenderdaja kaudu, mitte ei salvestata neid plokkidena:

PHP
<?php

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

Need jäävad Markdown lehtedeks: sisutüüp, sisutee, .md vastused ja frontmatter ei muutu. Sünkroonimisel salvestatakse üks blockstudio/page plokk, mille sisemine HTML on teisendatud Markdown, mis puhastatakse, kui kogu puhastab oma sisu, mitte parsitud plokid, nii et post_content säilitab dokumendi teksti. Renderdaja saab pesa kujul HTML ja võib allikat lugeda asukohast page.content_path. Suhtelised teed lahendatakse kogu juurkausta suhtes; välise tee filter rakendub samamoodi nagu nende teede puhul. Leht, mille frontmatter määrab ise väärtuse render või render: false, jäetakse välja.

Paigutused

layout.php fail ümbritseb failipõhise lehe kasutajaliidese renderdust. See ei asenda sünkroonitud post_content, mis on salvestatud asukohta WordPress, ega ümbritse redaktori lõuendit. Paigutus käivitub ainult üksiklehe kasutajaliidese päringute korral.

Kogumite puhul asetage layout.php faili pages.json kõrvale, et ümbritseda selle kogumi iga kasutajaliidese lehte:

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() kuvab lehe sisu, mille WordPress renderdaks tavaliselt the_content kaudu. Kui paigutus ei väljasta blockstudio_page_content(), on lehe sisu tahtlikult peidetud.

Paigutused saavad kasutada lehe abifunktsioone:

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

Pesastatud, kogumisse mittekuuluvad lehed võivad pärida ka lähima ülemlehe layout.php pages puus. Kogumilehtede puhul salvestatakse kogumi juurkausta paigutus igale sünkroonitud postitusele ja seda jälgitakse lehe sõrmejälje osana, nii et paigutuse muudatused rakenduvad järgmisel sünkroonimisel.

Renderdaja paigutused

Paigutus võib olla ka renderdaja kirje, näiteks layout.tsx renderdaja jaoks, mis registreerib layouts: ["layout.tsx"]. See leitakse samadest kohtadest nagu layout.php ning selle kõrval asuv valikuline layout.data.php on selle andmelaadur. Renderdamise ajal saab renderdaja kind: "layout" ja renderdatud lehe sisu kujul slot, sama the_content prioriteediga nagu layout.php puhul. Kataloogis võib olla kas layout.php või üks renderdaja paigutus, kuid mitte mõlemad; mõlema olemasolu on tuvastusviga. Paigutuse tõrke korral käivitatakse blockstudio/pages/layout_error ja lehe sisu jääb mähkimata, nagu ka layout.php puhul.

Plokkide muutmise režiim

Atribuut blockEditingMode määrab, kuidas saab redaktoris plokke muuta. Määrake lehe vaikeseade väärtuses page.json ja kirjutage see elemendipõhiselt mallis üle:

JSON
{
  "name": "about",
  "title": "About Us",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>
Väärtus Kirjeldus
"default" Täielik muutmine. Plokke saab valida, liigutada ja muuta
"contentOnly" Ainult teksti muutmine. Ploki teksti saab muuta, kuid seaded ja struktuur on lukus
"disabled" Muutmine keelatud. Plokid on täielikult mitteinteraktiivsed

Elemendipõhised ülekirjutused määratakse atribuutidena HTML igale elemendile (<h1>, <p>, <div> jne) või elementidele <block>. Ülekirjutatud elementide ülemkonteineri plokid seatakse automaatselt väärtusele contentOnly, et nende alamplokid jääksid ligipääsetavaks. See ahel liigub ülekirjutatud elemendist üles lehe juureni, seega peate määrama blockEditingMode ainult nendele elementidele, mida soovite muudetavaks teha.

Malli lukustus

Atribuut templateLock määrab, kuidas kasutajad saavad lehte redaktoris muuta:

Väärtus Lisamine/eemaldamine Liigutamine Sisu muutmine
"all" Ei Ei Ei
"insert" Ei Jah Jah
"contentOnly" Ei Ei Jah
false Jah Jah Jah

Kui määratud on templateLock, keelab Blockstudio plokkide lukustuse eemaldamise redaktori kaudu UI.

Virtuaalsed marsruudid

Mõnel dokumendil pole postitust: andmetest genereeritud komponendi viide, kataloog või kontoala. Registreerige need virtuaalsete marsruutidena, selle asemel et ise template_redirect külge haakida:

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

Tee on saidi avalehe suhtes suhteline. Kui määratud on prefix, teenindab marsruut ka kõiki selle all olevaid teid ning match saab selle ülejäänud osa (marsruudi enda puhul tühi string) ja tagastab väärtuse, mille renderdamise tagasihelistus saab, või null, et jätta URL väärtusele WordPress, mis vastab seejärel tavapäraselt 404-le. Renderdamise tagasihelistus väljastab dokumendi või tagastab selle stringina; title on string või sulund, mis saab vaste väärtuse.

Vastava päringu korral takistab Blockstudio väärtusel WordPress märkimast päringut kui 404 ning väärtusel redirect_canonical seda ümber suunamast, tühjendab põhipäringu teatatud üksiklehe oleku, saadab olekukoodi (vaikimisi status, 200) ja renderdab prioriteediga Virtual_Routes::PRIORITY funktsioonis template_redirect. See toimub kohe pärast seda, kui Blockstudio väljundpuhver avaneb funktsioonis Assets::BUFFER_PRIORITY, nii saab valmis dokument oma plokiressursid, komplekteeritud UI ressursid ja kompileeritud Tailwind nagu iga leht ning see juhtub enne redirect_canonical prioriteediga 10. Tervet dokumenti ise renderdav töötleja peab käivituma ka pärast Assets::BUFFER_PRIORITY, muidu jäetakse see töötlemine vahele. Teed asukohas urls (vaikimisi marsruudi tee ise, kui see pole prefiksmarsruut) lisatakse staatilise eellaadimise järkudele ning Virtual_Routes::urls() tagastab need saidikaardi jaoks absoluutsete URL-idena. Virtual_Routes::match( $path ) lahendab tee nii, nagu teeks seda päring.

Sünkroonimise käitumine

Lehepostitused muutuvad ainult selgesõnalise sünkroonimistoimingu kaudu:

Shell
wp bs pages sync

Käsk avastab täieliku allikate nimekirja, loob või uuendab muudetud postitused, eemaldab kinnitatud orvud, värskendab kogumite marsruutimist ja kompileeritud templateFor konfiguratsiooni ning annab muudatustest ülevaate. Lisage --authoritative, et asendada hallatav sisu võtmega seotud redaktori sisu säilitamise asemel, ja --full, et märkida käik täielikuks kooskõlastuseks olenemata salvestatud allika identiteedist:

Shell
wp bs pages sync --authoritative --full

Tavalised kasutajaliidese, halduse, AJAX-i, REST, cron ja üldised WP-CLI alglaadimispäringud ei käivita täielikku lehtede avastamist, ei päri hallatava kooskõlastuse loendit ega kirjuta lehepostitusi. Need kasutavad juba sünkroonitud WordPress postitusi ning viimase selgesõnalise toiminguga püsivalt salvestatud kompaktset kogumi- ja postitüübimalli konfiguratsiooni. Uue paigalduse või uuenduse korral võidakse marsruutimise metaandmete taastamiseks kogumi manifeste korra läbi vaadata; see kirjutuskaitstud alglaadimine ei sünkrooni kunagi sisu. Autenditud ja valikuline Canvase värskendusotspunkt on selgesõnaline sisu loomise API: Canvas kutsub seda tööruumi avamisel korra, et äsja lisatud või muudetud allikad ilmuksid esialgsesse loendisse. Reaalajarežiim kutsub sama piiri, kui tuvastab leheallika muutuse.

Blockstudio\Pages::init() registreerib nüüd ainult päringuaegsed haagid. Integratsioonid, mis andsid varem sellele meetodile argumendi force, peavad selle asemel kutsuma Blockstudio\Pages::reconcile() või käivitama wp bs pages sync.

Lehe käsitsi muutmise järel ülekirjutamise vältimiseks määrake "sync": false asukohas page.json.

Teisaldatavad allikate asukohad

Sünkroonitud teema failid salvestatakse teemaga seotud asukohtadena, mitte absoluutsete paigaldusteedena. Lapsteema ja emateema failid säilitavad eraldi identiteedid ka siis, kui neil on sama suhteline failinimi. Lehe abifunktsioonid tagastavad praeguse päringu jaoks siiski lahendatud absoluutsed väärtused template_path, content_path, layout_path ja directory.

See võimaldab CLI sünkroonimisel ja veebipäringutel kasutada eri failisüsteemi juurkaustu, nagu isoleeritud keskkonnaga hostingu korral, ilma et see häiriks Markdown vastuseid, paigutusi, redaktori Tailwind skannimist või eeltöödeldud lähtekoodi jälgimist. Olemasolevad absoluutsed teemateed teisendatakse lugemisel ümber, kui teemakataloogi nimi pole muutunud. Nende lugemiseks pole vaja sünkroonimist, andmebaasi migreerimist ega päringu ajal metaandmete kirjutamist; järgmine käsitsi käivitatud sünkroonimine salvestab kaasaskantavad asukohad.

Sümbollingina viidatud teemakataloog, näiteks arenduse väljavõtte sees asuv kataloog, salvestab samad theme: asukohad olenemata sellest, kas lähtefaili loeti sümbollingi või selle sihtkoha kaudu, ning lahendab need seadistatud teemakataloogiks.

Aktiivsest alam- ja ülemteemast väljaspool asuvaid faile toetatakse jätkuvalt nende seadistatud absoluutsetel radadel, arvestades PHP open_basedir piiranguid. Neid ei saa automaatselt teisaldada: pärast välise lähtefaili teisaldamist uuendage selle seadistatud rada ja käivitage käsitsi sünkroonimine.

Postituse välja omandiõigus

postStatus määrab algse oleku. Järgnevad sünkroonimised säilitavad olemasolevad mustandi, ootel, privaatse, avaldatud ja ajastatud olekud, ka siis, kui kasutatakse --authoritative. Mustandit ei avaldata uuesti pelgalt sellepärast, et failis on kirjas postStatus: "publish". Olemasolev orvuks jäänud sisu taastamise käitumine ei muutu: käsitsi käivitatud sünkroonimine taastab prügikasti viidud hallatava postituse, kui selle lähtefail on olemas. Taastamise vältimiseks lukustage leht või keelake sünkroonimine.

Fail määrab endiselt pealkirja, püsiviite, postituse tüübi, ülemüksuse ja seadistatud menüüjärjestuse. Nende muutmine kohas WordPress ei muuda lähtefaili määratlust. Järgmine käsitsi käivitatud sünkroonimine rakendab failis olevad väärtused uuesti ja nimetab mõjutatud väljad kohas pages.<name>.overwritten; tabeliväljundis kuvatakse hoiatus kohas CLI. Kehtivad endiselt WordPress algsed õigused, sealhulgas ootel postituste tühi püsiviide, kui sünkroonimist käivitaval kasutajal pole avaldamisõigust.

Kasutage blockstudio/pages/update_post_data integratsiooni puhul, millel on selgesõnaliselt teistsugune olekupoliitika. Võtmetega plokid säilitavad redaktori hallatava plokisisu; võtmed ei muuda postituse pealkirja ega püsiviite omandiõigust.

Kogumilehtede puhul hõlmavad sõrmejäljed manifesti, laaduri, leheallika, paigutusfaili, metaandmeid ja seotud allikateid. Järgmine selgesõnaline sünkroonimine rakendab nende sisendite muudatused.

Kogumi allika eemaldamisel eemaldab Blockstudio genereeritud lehe, et vanad kogumilehed ei jääks alles pärast lähtefaili kustutamist. Vaikimisi teisaldatakse orvuks jäänud kogumilehed prügikasti. Kasutage blockstudio/pages/orphan_action, et tagastada trash, delete või keep.

Kasutajaliidese päringute korral laadib Blockstudio leheregistri juba sünkroonitud avaldatud postitustest. Mustand- ja privaatsed lehed on saadaval haldus- ja sünkroonimiskontekstides, kuid kasutajaliidese abifunktsioonid laadivad ainult avaldatud lehti.

Juurutuse kooskõlastamine

Blockstudio\Pages::reconcile() on PHP juurutuse sisendpunkt. See avastab kogu soovitud loendi, võrdleb allika ja sünkroonimismootori sõrmejälgi ning tagastab masinloetava aruande:

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

Aruanne sisaldab discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, lehepõhiseid tulemusi, avastamisel ilmnenud vigu ja deterministlikku sourceIdentity.

Lukustatud lehtedel on status: "locked" ja neid loendatakse muutmata lehtedest eraldi. removedPages loetleb iga eemaldatud lehe kohta selle name, key, postId ja tegeliku action (trash või delete); alles jäetud või juba prügikasti viidud postitusi ei loendata uutena eemaldatutena. CLI tabeliväljundis nimetatakse samuti loodud, uuendatud, lukustatud ja eemaldatud lehti ning lehti, mille sisu säilitati, koos nende postituste ID-dega.

Pärast parsimist ja võtmetega ühendamist ei kutsuta identse lõpliku postituse korral wp_update_post(), ei muudeta väärtust post_modified, ei looda uut redaktsiooni ega käivitata postituse uuendamise hook’e. Selle tulemuseks on unchanged. Kui lähtefaili sisu erineb redaktori hallatavast võtmetega sisust, näitab preserved: true seda otsust ning tipptaseme preserved loendur arvestab selle hulka. Uus lähtefaili sõrmejälg ja hallatavad metaandmed salvestatakse siiski, nii et järgmisel muutumatul sünkroonimisel ei tehta midagi. preserved on lisamärgend, mitte välistav olek: leht võib säilitada võtmetega sisu, uuendades samal ajal failis määratud pealkirja või lisades teise ploki.

authoritative: true võib eemaldada lehe sünkroonimise luku ja asendab sisu failimääratlusega, selle asemel et säilitada võtmega seotud redaktori sisu. Tavapärase selgesõnalise sünkroonimise korral jätke see false. plan_valid: false, full: true, broad: true, eelmise allika identiteedi puudumine või muutunud sünkroonimismootori sõrmejälg märgib käigu täielikuks kooskõlastuseks (aruandes fullReconciliation). Iga käik võrdleb sellest hoolimata kogu loendit. Kirjed Git ümbernimetamise kohta on ainult identiteedi vihjed. Need ei asenda kunagi kogu loendi võrdlemist.

Võrdsete sõrmejälgede ja muutumatute käitusaja teede korral ei tehta postituse ega postmeta kirjutusi ning uuendamise haake ei käivitata. Kui muutumatu allikas teisaldatakse uude väljalaskekataloogi, värskendab kooskõlastamine ainult selle püsivalt salvestatud malli-, sisu-, paigutuse- ja kataloogiteid; see ei uuenda väärtust post_content ega postituse muutmise ajatemplit. Puuduvad hallatavad lehed eemaldatakse alles pärast seda, kui kogu kooskõlastuskäik lõpeb avastamis- ja lehe kirjutamise vigadeta.

Otsene API kooskõlastamine ei märgi juurutust edukaks. Pärast vastava staatilise artefakti ja marsruutide aktiveerimist ning kontrollimist salvestage tagastatud identiteet selgesõnaliselt:

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

wp bs pages sync salvestab tagastatud identiteedi pärast edukat käiku. Tavaline WP-CLI alglaadimine registreerib ainult püsivalt salvestatud kogumi postitüübid ja ümberkirjutusreeglid. See ei avasta ega sünkrooni lehti.

Postituse ID kinnistamine

Vaikimisi määrab WordPress postituse ID-d automaatselt. Kui leht kustutatakse ja luuakse uuesti, muutub ID ning välisviited, näiteks menüüviited või kõvakodeeritud lingid, lähevad katki.

Kasutage postId, et kinnistada lehele kindel ID:

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

Lehe loomisel edastab Blockstudio ID väärtusele WordPress parameetri import_id kaudu. Kui ID on saadaval, kasutab WordPress seda täpselt. Kui ID on juba seotud mõne muu postitusega, määrab WordPress vaikselt automaatselt uue ID.

Olemasolevate lehtede otsimisel kontrollib Blockstudio kinnistatud ID-d enne metaandmeid või püsiviita. Seega omandab leht kustutamise ja uuesti sünkroonimise korral sama ID tagasi.

Võtmega plokkide ühendamine

Vaikimisi asendab Blockstudio mallifaili muutumisel kogu postituse sisu uue malliga. See tähendab, et kõik WordPress redaktoris tehtud muudatused lähevad kaotsi.

Lisage plokkidele atribuut key, et säilitada kasutajate muudatused mallide sünkroonimise vahel. Kui mall sisaldab võtmega plokke, ühendab Blockstudio malli muudatused olemasoleva postituse sisuga, selle asemel et kogu sisu asendada.

Võtmete lisamine

Kasutage atribuuti key igal elemendil HTML või elemendil <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"
/>

Võtmed peavad olema kogu mallis unikaalsed. Võti kaitseb tervet plokki ja kogu selle sisu. Võtmega ülemploki sees pole vaja üksikutele alamplokkidele võtmeid määrata. Võtmega plokke võib malli uuenduste vahel liigutada mis tahes asukohta või pesastustasemele ning nende kasutaja sisu säilib.

Võtmed toimivad samamoodi ka kohandatud plokkide Blockstudio puhul. key on struktuurne lehe sünkroonimise metaandmestik; kohandatud välja väärtused jäävad tavalisteks Blockstudio atribuutideks. Kui redaktori kasutaja neid välju muudab, säilitab hilisem malli sünkroonimine redaktori väärtused ning rakendab samal ajal sõltumatud mallimuudatused. Vanemate versioonidega loodud lehtedel, kus võti asub kohandatud välja andmetes, viiakse see järgmisel sünkroonimisel automaatselt õigesse kohta.

Kuidas ühendamine toimib

Kui mallifail muutub ja leht sünkroonitakse uuesti:

Plokk Käitumine
Võtmega plokk Kasutaja sisu ja välja Blockstudio väärtused säilivad. Rakendatakse mallile kuuluvad atribuudid ja struktuur.
Võtmeta plokk Asendatakse täielikult malliversiooniga (sama tulemus kui võtmeteta)

Näited

Kasutaja muudatused säilivad võtmega plokkides:

  1. Mall määratleb <p key="intro">Default intro.</p>
  2. Kasutaja muudab lõiku redaktoris tekstiks "Custom intro text."
  3. Arendaja uuendab malli, lisab uue ploki ja muudab paigutust
  4. Sünkroonimisel säilib lõigus tekst "Custom intro text." ning rakendatakse uus paigutus

Malli atribuudid rakenduvad endiselt:

  1. Mallis on katteplokk atribuudiga key="hero" ja atribuudiga url
  2. Arendaja muudab katteploki atribuudi url uueks taustapildiks
  3. Sünkroonimisel rakendatakse uus taustapilt, kuid kasutaja sisumuudatused katteploki sees säilivad

Erijuhud

Olukord Käitumine
Mallile lisatakse uus võtmega plokk Ilmub malli vaikesisuga
Võtmega plokk eemaldatakse mallist Kustutatakse postitusest
Ploki tüüp muutub (sama võti) Mall on täielikult ülimuslik, sisu ei ühendata
Korduvad võtmed Teist esinemist käsitletakse võtmeta plokina
Mallis pole võtmeid Täielik asendamine (sama käitumine nagu võtmeteta)
Sundsünkroonimine Täielik asendamine, võtmeid eiratakse
Lukustatud postitus Sünkroonimist ei toimu

Ühendamine muutmise juhtelementidega

Võtmed, templateLock ja blockEditingMode annavad täpse kontrolli selle üle, mida kliendid saavad teha ja mida mitte. Siin on levinud töövoomustrid.

Täielikult lukustatud leht

Arendaja juhib kõike. Leht on staatiline paigutus, mida kliendid üldse muuta ei saa. Sobib juriidilistele lehtedele, kasutustingimustele või mis tahes lehele, mida peaks saama muuta ainult koodi kaudu.

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>

Võtmeid pole vaja. Mall on ainus tõeallikas. Iga sünkroonimine kirjutab kogu lehe üle.

Lukustatud paigutus muudetava sisuga

Kõige tavalisem muster. Lukustage lehe struktuur, et kliendid ei saaks plokke lisada, eemaldada ega ümber korraldada, kuid lubage neil teksti kindlates kohtades muuta. Võtmed tagavad, et nende muudatused säilivad malli uuendamisel.

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 saab muuta juhtpealkirja, kirjeldust ja funktsioonide sissejuhatust. Mitte midagi muud. Nupu tekst, URL ja kaanepildi taust on arendaja hallata. Kui arendaja malli uuendab (e.g., lisab teise nupu), säilitavad võtmetega jaotised kliendi teksti.

Täienev mall säilitatud sisuga

Lehtedele, mis aja jooksul kasvavad. Arendaja lisab mallile uusi jaotisi ning iga sünkroonimine lisab uue sisu, muutmata seda, mida klient on juba kohandanud.

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>

Uus iseloomustuste jaotis ja nupp ilmuvad sünkroonimisel. Kliendi muudatused pealkirjas, sissejuhatuses ja teenustes jäävad puutumata.

Ühekordne karkass

Loo leht algse struktuuriga ja anna see seejärel täielikult üle. Määra sync väärtuseks false, et tavapärane sünkroonimine lehte ei loo ega uuenda, ning loo see üks kord käsuga Blockstudio\Pages::force_sync('blog'). Pärast seda kuulub leht täielikult kliendile.

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

wp bs pages sync jätab selle lehe vahele, seega loob force_sync() selle üks kord. Seejärel saab klient plokke vabalt lisada, eemaldada ja ümber järjestada. Malli muudatusi eiratakse.

Ploki sidumised

Võtmetega ühendamise alternatiiv on kasutada WordPress tuuma ploki sidumisi API plokkide ühendamiseks post metaandmetega. See pole Blockstudio funktsioon, vaid natiivne WordPress API. Blockstudio edastab atribuudi metadata lihtsalt genereeritud ploki märgendusse. Sisu asub ploki märgenduse asemel post metaandmetes, nii et malli sünkroonimine võib märgenduse vabalt üle kirjutada, sest redaktor loeb metaandmeid, mitte atribuuti innerHTML.

Edasta atribuut metadata mis tahes elemendile HTML või elemendile <block>:

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

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

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

Meta võtmed tuleb registreerida nii, et show_in_rest oleks lubatud:

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

Võtmed ja sidumised

Aspekt Võtmed Sidumised
Sisu asukoht Ploki märgendus (post_content) Post metaandmed (wp_postmeta)
Säilib malli sünkroonimisel Jah (ühendatakse võtme järgi) Jah (andmed asuvad metaandmetes)
Päringutega leitav WP_Query kaudu Ei Jah (meta_query)
Saadaval jaotises REST API Ei Jah
Vajab registreerimist Ei Jah (register_post_meta)
Kasutaja saab plokke liigutada Ei (mall kehtestab struktuuri uuesti) Ei (mall kehtestab struktuuri uuesti)

Mõlemat lähenemist saab kasutada samas mallis. Kasuta võtmeid jaotistes, kus plokistruktuur on oluline (e.g., rühm mitme alamelemendiga). Kasuta sidumisi üksikute väljade jaoks, kui soovid andmeid kättesaadavaks teha ka väljaspool plokiredaktorit.

Sisupostituse tüübi mallid

Kasuta templateFor, et määrata leht sisupostituse tüübi vaikemalliks:

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

Kõik seda tüüpi uued postitused algavad määratletud plokistruktuuriga.

Kohandatud teed

Vaikimisi skannib Blockstudio teed get_template_directory() . '/pages'. Lisa täiendavaid teid filtriga:

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

Mitmest juurkataloogist faile koondavad käitusaegsed integratsioonid võivad asendada failisüsteemi skannimise loogilise tuvastusallikaga. Lehe manifestid, paigutused, laadurid ja lähtefailide mallid lahendatakse seejärel loogilise tee järgi, isegi kui valitud failid asuvad eri juurkataloogides.

Filtrid ja toimingud

Lehtede tuvastamisel, sünkroonimisel ja kogude suunamisel on järgmised laienduspunktid:

Hook Tüüp Kirjeldus
blockstudio/pages/paths Filter Lisab katalooge, kust Blockstudio otsib lehtede lähtefaile.
blockstudio/pages/collection_post_type_args Filter Muudab kogu CPT jaoks argumente register_post_type().
blockstudio/pages/template_candidates Filter Muudab lehe lähtefaili jaoks arvestatavaid mallifailide nimesid.
blockstudio/pages/serve_markdown Filter Lülitab toored Markdown vastused sisse või välja.
blockstudio/pages/orphan_action Filter Tagastab orvuks jäänud sisu puhastamiseks trash, delete või keep.
blockstudio/pages/docs_allowed_html Filter Muudab loodud Markdown dokumentatsiooni sisu jaoks lubatud HTML.
blockstudio/pages/allow_external_loader_path Filter Lubab laadija paths asukoha väljaspool kogu juurkataloogi.
blockstudio/pages/manifest_scan_interval Filter Määrab pärandmanifesti vahemälu maksimaalse vanuse enne versiooni 7.6.2, et see saaks uuendamisel aluseks olla salvestatud käitusaegse konfiguratsiooni loomisel.
blockstudio/pages/create_post_data Filter Muudab postituse andmeid enne sünkroonitud lehe loomist.
blockstudio/pages/update_post_data Filter Muudab postituse andmeid enne sünkroonitud lehe uuendamist.
blockstudio/pages/sync_engine_inputs Filter Lisab parsija, vastenduse või migreerimisversiooni, mis peaks teadlikult laiendama ühitamist ühe korra.
blockstudio/pages/post_created Tegevus Käivitub pärast sünkroonitud lehepostituse loomist.
blockstudio/pages/post_updated Tegevus Käivitub pärast sünkroonitud lehepostituse uuendamist.
blockstudio/pages/synced Tegevus Käivitub pärast lehtede registri sünkroonimise lõpetamist.
blockstudio/pages/reconciled Tegevus Käivitub pärast käsitsi käivitatud ühitamist koos masinloetava aruandega.
blockstudio/pages/renderers Tegevus Registreerib leherenderdajad funktsiooniga Blockstudio\Page_Renderers::register(). Käivitub päringu kohta ühe korra.
blockstudio/pages/rendered Tegevus Käivitub pärast komponendilehe renderdamist, lisades lehe, selle HTML ja sõltuvused.
blockstudio/pages/layout_error Tegevus Käivitub, kui paigutust ei saa renderdada; kaasas on viga, paigutuse rada ja leht.

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

Vt juurutuse lepitamine argumentide semantikat, aruande välju ja kontrollitud lähte identiteedi piire.

Mallide ja paigutuste jaoks on saadaval globaalsed abifunktsioonid:

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

Funktsioonide Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() ja globaalsete abifunktsioonide tagastatud lehemassiivid sisaldavad sünkroonitud postituse identiteeti, lähte- ja malliteid, kogumi ja tee metaandmeid, sisutüüpi, sünkroonimispoliitikat, postituse tüüpi ja olekut, muutmispoliitikat, kohandatud metaandmeid ning permalink võtit. Kogumi metaandmed laaditakse viimasest edukast selgesõnalisest lepitamisest. Tavapäraste päringute ajal taastatakse need käitusandmed salvestatud konfiguratsioonist ja sünkroonitud postituse metaandmetest, lugemata lehe lähtepuusid. Klass Pages ei paku eraldi püsilingi meetodit.

Failipõhiste lehtede loomine

Mallide lukustamine, plokkide muutmisrežiimid, võtmetega ühendamine ja kliendi muudetava sisu juhtimine.