Lapas
Lapas ir failos balstītas veidnes, kas tiek sinhronizētas ar WordPress datubāzi kā ieraksti.
Sinhronizācija ir skaidri jāpalaiž: izpildiet wp bs pages sync vai izsauciet Pages API, kad vēlaties piemērot avota izmaiņas. Frontend vai WordPress administrēšanas daļas ielāde nekad neveic pilnu lapu atklāšanu un nemaina lapu ierakstus.
Lapas var definēt kā vienu page.json mapi, kā atsevišķus Markdown failus vai kā kolekciju ar pages.json manifestu. Kolekcijas noder dokumentācijai, zināšanu bāzēm, galveno lapu bibliotēkām vai jebkuram ligzdotu lapu kopumam, kas jāģenerē no failiem.
page.json
Lapai, kas definēta ar JSON, pievienojiet page.json konfigurācijas failu:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
Rekvizīti
| Īpašība | Tips | Noklusējums | Apraksts |
|---|---|---|---|
name |
string |
obligāts | Unikāls lapas identifikators |
title |
string |
Automātiski no nosaukuma | Lapas virsraksts |
slug |
string |
Tāds pats kā nosaukums | Lapas URL slug |
path |
string |
"." |
Loģiskais ceļš kolekcijā |
order |
integer |
0 |
Sinhronizētās ziņas izvēlnes secība |
postType |
string |
"page" |
WordPress ziņas tips |
postStatus |
string |
"draft" |
Jaunu ziņu statuss (publish, draft, pending, private) |
postId |
integer |
– | Piesaistīt lapu konkrētam WordPress ziņas ID |
blockEditingMode |
string |
– | Bloku rediģēšanas režīms: "default", "contentOnly" vai "disabled" |
templateLock |
string|false |
"all" |
Bloķēšanas režīms: "all", "insert", "contentOnly" vai false |
templateFor |
string|null |
null |
Iestatīt kā noklusējuma veidni ziņas tipam |
sync |
boolean |
true |
Norāda, vai parastā skaidrā saskaņošana var izveidot vai atjaunināt ziņu |
render |
string|object|false |
– | Attēlot lapu, izmantojot reģistrētu lapu attēlotāju (skatiet Komponentu lapas) |
Atpazītās atslēgas page.json, frontmatter un ielādētāja ierakstos ir blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock un title. Jebkura iepriekš neminēta atslēga tiek saglabāta lapas meta masīvā.
Satura avoti
Lapas definīcija nosaka, kuram WordPress ierakstam jābūt. Satura avots nosaka, kāds bloku marķējums tiek ierakstīts šajā ierakstā.
Ja lapas mapē ir page.json, Blockstudio meklē blakus esošu avota failu šādā secībā:
| Fails | Lietojums |
|---|---|
index.php |
HTML līdzīgs bloku marķējums, nolasīts nemainīts (PHP kods netiek izpildīts) |
index.blade.php |
Blade veidnes saturs |
index.twig |
Twig veidnes saturs |
index.md |
Markdown saturs |
page.json var arī ietvert markdown vai html saturu, nevis izmantot blakus esošu failu:
{
"name": "intro",
"title": "Intro",
"markdown": "# Intro\n\nThis page is generated from inline markdown."
}
{
"name": "notice",
"title": "Notice",
"html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}
Kolekcijās ir pieejami vēl divi avotu veidi:
- Markdown faili, kas atrasti tieši kolekcijas mapju kokā.
- Ielādētāja ieraksti, ko atgriež
loader.php.
Ielādētāja ierakstos var izmantot markdown, html vai content kopā ar contentType. Tie var norādīt arī uz lokālu file vai template. Failu un veidņu avotu tipu nosaka paplašinājums, ja vien contentType nav norādīts skaidri.
Atbalstītās contentType vērtības ir php, blade, twig, markdown un html. Markdown vispirms tiek pārveidots par HTML, pēc tam parsēts vietējos WordPress blokos. PHP, Blade, Twig un HTML avoti tiek apstrādāti ar parasto Blockstudio lapu parsētāju.
Pamatbloku klases
HTML elementa class, kas kartēts uz pamatbloku, kļūst par tā className.
Pamatbloka tagā var tieši izmantot className. Abos gadījumos tiek saglabātas klases bloka saglabātajā ietvarā līdzās klasēm, ko ģenerē WordPress:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
Ja ir norādītas abas īpašības, prioritāte ir className. Šī konvertēšana attiecas tikai uz pamatblokiem: pielāgota bloka kartējums saglabā tā lauku class nemainītu. Pogas stila klases, piemēram, is-style-outline, pieder pogas ietvaram, nevis tās saitei.
Palaidiet wp bs pages sync, lai piemērotu parsētāja labojumus iepriekš sinhronizētajām lapām. Parsētāja jauninājumi tiek atpazīti nākamās skaidri veiktās sinhronizācijas laikā, neveicot izmaiņas avota failā. Bloķētajām lapām un lapām ar sync: false saglabājas parastā aizsardzība; priekšgala pieprasījumi šo sinhronizāciju neveic.
Serializētie WordPress bloki
Lapu un rakstu avotos var būt arī serializēti bloki, kas kopēti no WordPress koda redaktora:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
Ja avotā ir <!-- wp:... --> bloka atdalītājs, Blockstudio visam avotam izmanto WordPress sākotnējo bloku parsētāju. Atribūti, ligzdoti bloki, dinamiskie bloki, piemēram, Query Loop, un Blockstudio bloki saglabā serializēto struktūru. HTML ārpus bloka komentāriem paliek sākotnējā brīvā formā HTML; tas netiek pārveidots par papildu blokiem. Nejauciet Blockstudio HTML bloku tagus ar šo formātu, cerot tos pārveidot. Parasti HTML komentāri neieslēdz serializēto bloku režīmu.
Markdown lapas
Izmantojiet Markdown, ja tekstam jāatrodas failos, bet pēc sinhronizācijas tam jākļūst par rediģējamu WordPress bloku saturu. Sinhronizācijas laikā Markdown avots tiek pārveidots par bloku marķējumu. Sinhronizētajā ierakstā tiek glabāti bloki, nevis neapstrādāts Markdown pamatteksts.
Markdown var izmantot trīs veidos:
| Avots | Vai nepieciešami frontmatter dati? | Piezīmes |
|---|---|---|
Atsevišķs pages/example/index.md |
Jā | Frontmatter nodrošina lapas identitāti. |
page.json kopā ar index.md |
Nē | page.json definē lapu, bet Markdown nodrošina saturu. |
| Markdown kolekcijā | Nē | Kolekcija nosaka name un path pēc faila atrašanās vietas. |
Atsevišķs index.md bez frontmatter datiem tiek izlaists, jo Blockstudio nav lapas identitātes, ko sinhronizēt. Kolekcijas Markdown nav nepieciešami frontmatter dati, jo kolekcijas manifests un faila ceļš nodrošina šo identitāti.
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
Varat arī savienot page.json ar index.md. Šādā gadījumā page.json definē lapu, bet index.md nodrošina saturu. Frontmatter dati index.md aizstāj atbilstošās page.json vērtības.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
title: API Reference
order: 20
---
# Reference
This page uses `page.json` with Markdown content.
Kolekcijas Markdown gadījumā faila ceļš kļūst par lapas loģisko ceļu, ja vien frontmatter dati to nepārraksta:
| Fails | Noklusējuma ceļš |
|---|---|
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 |
Neatpazītās frontmatter atslēgas tiek saglabātas lapas meta masīvā. Tas ļauj pievienot tādus datus kā section vai description un nolasīt tos no PHP API.
Markdown tiek parsēts kā GitHub Flavored Markdown. Ir atļauts neapstrādāts HTML, nedrošas saites tiek noņemtas, bet virsrakstiem bez skaidri norādīta ID tiek piešķirts stabils ID. Ligzdotam YAML frontmatter ir nepieciešams komplektā iekļautais YAML parsētājs.
Neapstrādāts Markdown
Markdown failu avoti var nodrošināt sākotnējo avota Markdown ārējiem rīkiem un dokumentācijas lietotājiem. Iekļautajam Markdown nav avota faila, tāpēc tas tiek sinhronizēts blokos, bet nerada neapstrādātu .md atbildi.
Pieprasiet lapu ar sufiksu .md, piemēram, https://example.com/docs/reference.md. Vai arī nosūtiet galveni Accept: text/markdown uz parasto lapas URL:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
No atbildes tiek noņemti frontmatter dati. Veiksmīgās neapstrādāta Markdown atbildēs tiek nosūtīti Content-Type: text/markdown, X-Robots-Tag: noindex un kanoniskā Link galvene atpakaļ uz HTML lapu. Ja .md maršruts nav atrasts, tiek atgriezts īsts 404.
Satura formāta pārrunas darbojas kopā ar statisku iepriekšēju renderēšanu: pieprasījums, kura Accept galvenē ir text/markdown, nekad nesaņem atbildi no iepriekšrenderēto lapu krātuves vai agrīnās apkalpošanas paplašinājuma. Tāpēc pieprasījums sasniedz WordPress un Markdown apstrādātāju. Iepriekšrenderētās HTML atbildes, lapas HTML atbilde, ja tā atbalsta arī Markdown, un Markdown atbilde, ko nodrošina Accept, nosūta Vary: Accept, tāpēc kešatmiņas, kas ievēro Vary, šos variantus glabā atsevišķi. CDN, kas kešatmiņas atslēgu veido tikai pēc URL, šādiem pieprasījumiem ir jāiestata savs noteikums kešatmiņas apiešanai. Pages::negotiates_markdown( $post_id ) norāda, vai lapa atbild uz Markdown pieprasījumiem.
Kolekcijas Markdown neapstrādātam Markdown saglabā to pašu URL struktūru:
| Lapas URL | Neapstrādāts Markdown URL |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
Atspējojiet neapstrādātas Markdown atbildes ar filtru blockstudio/pages/serve_markdown:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
.md URL, kas nenovirza uz lapu, kuras pamatā ir Markdown, atgriež 404 tikai tad, ja ceļš atrodas kādā lapu kolekcijā. Ārpus visām kolekcijām Blockstudio atstāj pieprasījumu WordPress un citu spraudņu ziņā.
Komponentu lapas
Komponenta lapa tiek attēlota ar lapas attēlotāju, nevis saglabāta kā
bloki. Blockstudio nenodrošina attēlotāju. Tēma vai spraudnis reģistrē to
ieraksta failiem, kurus tas apstrādā, piemēram, React attēlotāju
priekš page.tsx, un Blockstudio to izsauc, nododot lapu, WordPress ziņu un attēlotā slot satura rezultātu.
pages/legal-notice/
page.json
page.tsx
data.php
{
"name": "legal-notice",
"title": "Legal Notice",
"slug": "legal-notice",
"postStatus": "publish",
"render": { "entry": "page.tsx", "data": "data.php" }
}
render ir skaidri jānorāda. Direktorijs ar index.php un page.tsx, bet bez
render, paliek parasta lapa, tāpēc attēlotāja pievienošana nekad neattēlo
esošu lapu divreiz. Iespējamās formas:
| Vērtība | Nozīme |
|---|---|
"page.tsx" |
Tikai ieraksts, bez datu ielādētāja |
{ "entry": "page.tsx", "data": "data.php" } |
Ieraksts un datu ielādētājs |
{ "entry": "page.tsx", "renderer": "react" } |
Ieraksts ar skaidri norādītu attēlotāja ID |
false |
Bez attēlotāja, pat ja kolekcijas noklusējums to norāda |
Ceļi tiek atrisināti attiecībā pret lapas direktoriju vai, ielādētāja ierakstiem, pret kolekcijas sakni. Tiem jāpaliek atklāšanas avota robežās, izņemot gadījumus, kad blockstudio/pages/allow_external_loader_path tos atļauj. Ja nav norādīts renderer, tiek izmantots attēlotājs, kas apstrādā ieraksta paplašinājumu. Ja render norāda uz trūkstošu ierakstu vai datu failu, nezināmu attēlotāju vai paplašinājumu, ko neapstrādā neviens attēlotājs, rodas atklāšanas kļūda, kuras dēļ saskaņošana neizdodas, pirms kaut kas tiek izņemts.
Ko saglabā sinhronizācija
Sinhronizācija saglabā vienu blockstudio/page bloku. Ja lapas direktorijā ir arī index.* avots, tas tiek parsēts kā jebkurš lapas avots un kļūst par bloka iekšējiem blokiem — tā slotu:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
Slotā saglabājiet WordPress piederošo saturu, piemēram, īskodus. Avots, kurā ir tikai viens īskods, piemēram, [download_checkout], tiek saglabāts kā core/shortcode bloks, tāpēc ap tā izvadi netiek pievienota rindkopa. Tas paliek post_content, lai has_shortcode() pārbaudes to redzētu, atslēgoti slotu bloki saplūstu ar redaktora izmaiņām tāpat kā ligzdoti atslēgoti bloki, un do_shortcode izvērstu īskodus vienreiz savā ierastajā the_content prioritātē — pēc tam, kad attēlotājs tos ir ietvēris.
Attēlošanas definīcija tiek saglabāta kopā ar ziņu kā pārnesami theme: ceļi. Lapas pirkstu nospiedums aptver definīciju, nevis ieraksta vai datu ielādētāja baitu saturu: rediģējot page.tsx vai data.php, ziņa paliek nemainīga, un izmaiņas apmeklētājiem kļūst pieejamas, izmantojot attēlošanu un statisko pirmsatveides grafu, kurā tiek reģistrēts ieraksts, datu ielādētājs un katrs fails, par kuru ziņo attēlotājs.
Attēlotāja reģistrēšana
Reģistrējiet attēlotājus darbībā blockstudio/pages/renderers. Tā tiek izpildīta vienreiz katrā pieprasījumā pirms pirmās atklāšanas vai attēlošanas, tāpēc wp bs pages sync un frontend pieprasījumos redzams viens un tas pats reģistrs.
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',
)
);
}
);
Attēlotāju ID ir ar mazajiem burtiem. Paplašinājums vai izkārtojuma nosaukums var piederēt tikai vienam attēlotājam, un layout.php paliek Blockstudio izkārtojums. Izsaucamā funkcija saņem vienu pieprasījumu:
| Atslēga | Vērtība |
|---|---|
kind |
page vai layout, ja tas ir attēlotāja izkārtojums |
renderer |
Attēlotāja ID |
entry |
Absolūtais ieraksta ceļš |
data |
Absolūtais datu ielādētāja ceļš vai null |
page |
Kanoniskie lapas dati, tostarp meta |
post_id |
WordPress ziņas ID |
slot |
Attēlotā slot satura rezultāts vai lapas saturs izkārtojumam |
context |
frontend, rest, feed vai cli |
Tas atgriež HTML, failus, ko attēlošanas laikā nolasīja, un neobligātos resursus:
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 tiek iegūts no pieprasījuma veida, nevis no apmeklētāja, tāpēc renderētājs, to nolasot, nevar izjaukt pieteikušos un anonīmo lietotāju baitu paritāti. Ja renderētājs neizdodas, tas izmet kļūdu: lapa netiek attēlota ar tukšu pamatdaļu. REST redaktora priekšskatījumā bloks kļūdu parāda kā paziņojumu. Pēc veiksmīgas renderēšanas darbība blockstudio/pages/rendered saņem lapu, HTML un tās atkarības.
assets uzskaita lapai nepieciešamos skriptu un stilu failus. Tie tiek apstrādāti tāpat kā bloka resursi (*.inline.* konvencija, ES moduļi, minifikācija un ?ver), un lapa tos izvada vienreiz, izmantojot to pašu buferi, kurā tiek izvadīti bloka resursi, tāpēc priekšrenderēta lapa tos ietver. Resurss var iestatīt version, lai aizstātu tā vērtību ?ver. Kods ārpus renderētāja var izmantot to pašu kanālu, izmantojot Blockstudio\Assets::register_owner(), kas atgriež izvadāmo marķiera komentāru.
Redaktors
Redaktorā blockstudio/page rāda lapas servera renderēto priekšskatījumu, kurā slots ir iekšējie bloki un seko lapas templateLock. Bloku nevar ievietot, dublēt vai ievietot citā blokā.
Lapu kolekcijas
Kolekcija ir mape ar pages.json manifestu. Tā apvieno daudzus lapu avotus zem viena kolekcijas slug, piemēro noklusējuma iestatījumus, atbalsta ligzdotus ceļus un var automātiski reģistrēt īpašu ieraksta tipu.
pages/
docs/
pages.json
layout.php
index.md
guide/
install/
index.md
reference/
page.json
index.md
loader.php
{
"collection": "docs",
"title": "Documentation",
"postType": "bs_docs",
"postTypeArgs": {
"label": "Docs",
"rewrite": {
"slug": "docs"
},
"supports": ["title", "editor", "page-attributes"]
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
| Īpašība | Tips | Apraksts |
|---|---|---|
collection / slug / name |
string |
Kolekcijas slug. collection ir nepārprotamākā forma un kļūst par publisko URL bāzi. |
title |
string |
Cilvēkam saprotams kolekcijas nosaukums. |
postType |
string |
Ģenerēto lapu ierakstu tips. Pēc noklusējuma page. Ja tas neeksistē, Blockstudio to reģistrē. |
postTypeArgs |
object |
Argumenti, kas tiek nodoti register_post_type(), kad Blockstudio reģistrē kolekcijas ierakstu tipu. |
defaults |
object |
Noklusējuma lapas īpašības, kas tiek piemērotas katrai kolekcijas lapai. Noklusējuma render tiek piemērots lapai tikai tad, ja tās ieraksts atrodas lapu direktorijā. |
scope |
string |
collection (noklusējums) vai site. Skatiet Vietņu kolekcijas. |
meta |
object |
Pielāgoti kolekcijas metadati. Nezināmās manifesta atslēgas arī tiek saglabātas šeit: meta. |
Kolekcijas lapu ceļi ir loģiski ceļi. Lapa ar path: "guide/install" tiek sinhronizēta kā guide bērnlapa, bet guide tiek sinhronizēta kā kolekcijas saknes bērnlapa, ja šīs vecāklapas pastāv.
Ja hierarhiskā kolekcijā ir ligzdota lapa, bet trūkst avota starplapas vecākam, Blockstudio šajā ceļā ģenerē tukšu konteinera lapu, tādējādi saglabājot pilnīgu WordPress hierarhiju. Nehierarhiski ierakstu tipi (bez page-attributes vecākelementa atbalsta) tukšus konteinerus neģenerē. Tie veido maršrutu pēc saglabātā kolekcijas ceļa, tāpēc ligzdoti ceļi, piemēram, guide/install un setup/install, var pastāvēt līdzās, lai gan abi beidzas ar install.
Kolekciju ierakstu tipi un URL
Kolekcijas manifestā iestatiet postType, lai visas kolekcijas lapas sinhronizētu ar šo ieraksta tipu. Šī vērtība nav jāatkārto defaults. Atsevišķām lapām joprojām var norādīt citu postType, izmantojot frontmatter vai page.json.
Ja ieraksta tips neeksistē, Blockstudio to reģistrē ar show_in_rest: true, lapām piemērotu redaktora iestatījumu un kolekcijas slug kā publisko URL ceļa pamatu. Reģistrācijas argumentus var mainīt ar postTypeArgs. Kolekcijas ierakstu tipu pārrakstīšanas kārtulas tiek automātiski atjauninātas, kad mainās reģistrētie kolekcijas ierakstu tipi vai pārrakstīšanas argumenti, tāpēc WordPress pastāvīgās saites nav jāsaglabā no jauna.
Kolekcijas URL veido kolekcijas slug un katras lapas loģiskais path:
| Avota ceļš | Publisks URL |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
Šis URL modelis darbojas gan hierarhiskiem, gan nehierarhiskiem kolekciju ierakstu tipiem. Blockstudio arī novirza dubultotus URL, piemēram, /docs/docs/ vai /docs/docs/getting-started/, uz kanonisko URL.
Kolekciju lapās tajos pašos URL ir pieejams neapstrādāts Markdown (sk. Neapstrādāts Markdown).
Ja maināt kolekciju no postType: "page" uz pielāgotu ierakstu tipu, Blockstudio migrē jau sinhronizētos kolekcijas ierakstus uz vietas, ja to saglabātā lapas identitāte atbilst. Tādējādi tiek saglabāti ierakstu ID, metadati un esošais saturs, vienlaikus novēršot dublētus ierakstus ar veco tipu. Novecojušie kolekcijas ieraksti tiek iztīrīti visos ierakstu statusos atbilstoši filtram blockstudio/pages/orphan_action.
Vietņu kolekcijas
Manifests ar "scope": "site" grupē visas tajā ietvertās lapas, nepārvēršot tās par kolekcijas lapām. Izmantojiet to vietnes lapu koka saknē, lai piemērotu kopīgās noklusējuma vērtības un uzskaitītu vietnes lapas ar blockstudio_page_tree( 'my-site' ).
{
"collection": "my-site",
"title": "My Site",
"scope": "site",
"defaults": {
"postStatus": "publish",
"templateLock": "all",
"render": { "entry": "page.tsx", "data": "data.php" }
}
}
Vietnes kolekcijas lapas saglabā tieši tādu pašu identitāti, kāda tām būtu bez manifesta, tāpēc, pievienojot manifestu esošam kokam, netiek mainītas ierakstu rindas, kā arī nekas netiek izveidots vai dzēsts:
- Atslēgas paliek globālas:
Pages::get_page( 'home' )un saglabātās lapu atslēgas joprojām sakrīt. - URL adreses paliek WordPress lapu URL adreses. Netiek piemēroti kolekcijas pārrakstīšanas noteikumi, pastāvīgo saišu filtrs vai dubultās URL novirzīšana, un netiek ģenerētas tukšas konteinerlapas.
- Loģiskie ceļi, slug, vecāklapas un avota identitātes ir tādas pašas kā atsevišķām lapām, un izkārtojumi tiek atrisināti pēc tuvākā senča.
- Iegultie
pages.jsonmanifesti saglabā savas kolekcijas, un to apakškoki netiek iekļauti vietnes kolekcijā. - Noklusējuma vērtības tiek piemērotas katrai lapai atsevišķi: noklusējuma
rendertiek piemērots tikai tām lapām, kuru direktorijā ir attiecīgais ieraksts, tāpēc īskoda un Markdown lapas saglabā savus avotus.
Kolekciju ielādētāji
Kolekcijās var iekļaut uzticamu lokālu loader.php. Izmantojiet to, ja kolekciju lapas tiek iegūtas no cita lokāla avota, piemēram, ārējas dokumentācijas mapes, pakotnes vai ģenerēta manifesta.
Ielādētājs darbojas skaidri pieprasītas lapu noteikšanas un sinhronizācijas laikā. Tam jābūt deterministiskam un lokālam. Izvairieties no attāla satura iegūšanas no loader.php, jo tādējādi izvietošanas sinhronizācija būtu atkarīga no šī pakalpojuma.
<?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',
),
),
);
Ielādētājs var atgriezt masīvu ar atslēgām pages, meta un paths:
| Atslēga | Apraksts |
|---|---|
pages |
Lapu masīvu saraksts. Katra lapa atbalsta tās pašas atpazītās atslēgas, ko page.json un Markdown frontmatter. |
meta |
Metadati, kas tiek apvienoti ar katras ielādētāja ģenerētās lapas masīvu meta. |
paths |
Papildu lokālie direktoriji, kas jāatklāj kā daļa no šīs kolekcijas. Ieraksti var būt virknes vai ceļu objekti. |
render |
renderēšanas definīcija katrai Markdown lapai, kas atklāta no paths. |
Saīsinātā pierakstā ielādētājs var atgriezt vienkāršu lapu masīvu sarakstu.
Ielādētāja lapu ierakstos saturu var norādīt šādos veidos:
| Struktūra | Apraksts |
|---|---|
markdown |
Iekļauts Markdown saturs. |
html |
Iekļauts HTML saturs. |
content + contentType |
Vispārīgs iekļauts saturs. contentType ir jāatrisina kā markdown vai html. |
file |
Lokāla faila avots. Tips tiek noteikts pēc paplašinājuma, ja vien nav iestatīts contentType. |
template |
file aizstājvārds. |
Ielādētāja failu atsauces var norādīt uz PHP, Blade, Twig, Markdown vai HTML avotiem. Relatīvie ceļi tiek atrisināti no kolekcijas saknes. Absolūtie ceļi un ceļi ārpus kolekcijas saknes ir atļauti tikai tad, ja to pieļauj filtrs blockstudio/pages/allow_external_loader_path.
Ielādētāja lapām pēc noklusējuma tiek piešķirta generated: true. Ja ģenerētā ielādētāja lapa pazūd no ielādētāja izvades, nākamajā sinhronizācijā Blockstudio uzskata sinhronizēto ierakstu par bāreņierakstu, kas tiek iztīrīts atbilstoši filtram blockstudio/pages/orphan_action.
Direktoriji, kas norādīti laukā paths, tiek atklāti tāpat kā parastās kolekciju mapes. Tajos var būt Markdown faili vai page.json mapes. Ja šie ceļi atrodas ārpus kolekcijas saknes, tiek piemērots tas pats ārējo ceļu filtrs.
Izmantojiet virknes ierakstu, ja ārējam direktorijam jāsaglabā savi loģiskie ceļi. Izmantojiet objekta ierakstu, ja direktorijs jāpievieno zem kolekcijas ceļa prefiksa:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
Izmantojot šo konfigurāciju, kolekcijā cli-docs/index.md kļūst par path: "cli" un cli-docs/getting-started.md kļūst par path: "cli/getting-started". Prefiksi arī novērš ģenerēto lapu nosaukumu sadursmes, tāpēc vairākos pievienotos direktorijos var būt katrā savs index.md vai getting-started.md. Ceļa objektam iestatiet preserveNames uz true, ja jāsaglabā skaidri norādītās name vērtības no page.json vai Markdown priekšējās metadatu daļas.
Ceļa objekta rekvizīti:
| Īpašība | Tips | Apraksts |
|---|---|---|
path |
string |
Atklājamais lokālais direktorijs. Relatīvie ceļi tiek noteikti attiecībā pret kolekcijas sakni. |
prefix |
string |
Neobligāts loģiskā ceļa prefikss kolekcijā. |
preserveNames |
boolean |
Saglabāt skaidri norādītos lapu nosaukumus, nevis ģenerēt nosaukumus no ceļa ar prefiksu. Ja iestatīts prefix, pēc noklusējuma tiek izmantots false. |
meta |
object |
Metadati, kas tiek apvienoti ar katru no šī ceļa atklāto lapu. Lapas līmeņa metadatiem ir priekšroka, ja atslēgas dublējas. |
render |
string|object |
Renderēšanas definīcija šī ceļa Markdown lapām, kas aizstāj ielādētāja render. |
Markdown renderēšana, izmantojot komponentu
Izmantojot render, lapas, ko atklāj ielādētājs Markdown, tiek renderētas, izmantojot lapu renderētāju, nevis saglabātas kā bloki:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
Tās joprojām ir Markdown lapas: satura tips, satura ceļš, .md atbildes un frontmatter paliek nemainīgi. Sinhronizējot, tiek saglabāts viens blockstudio/page bloks, kura iekšējais HTML ir konvertētais Markdown, kas sanitizēts, ja kolekcija sanitizē tās saturu, nevis parsētie bloki, tāpēc post_content saglabā dokumenta tekstu. Renderētājs saņem šo HTML kā slotu un var nolasīt avotu no page.content_path. Relatīvie ceļi tiek noteikti attiecībā pret kolekcijas sakni; ārējā ceļu filtra darbība ir tāda pati kā ceļiem. Lapa tiek izlaista, ja tās frontmatter ir iestatīts render vai render: false.
Izkārtojumi
Fails layout.php aptver no faila iegūtas lapas atveidi priekšpusē. Tas neaizstāj sinhronizēto post_content, kas saglabāts laukā WordPress, un neaptver redaktora audeklu. Izkārtojums darbojas tikai atsevišķu lapu priekšpuses pieprasījumos.
Kolekcijām novietojiet layout.php blakus pages.json, lai aptvertu katru šīs kolekcijas priekšpuses lapu:
<?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() izvada lapas pamattekstu, ko WordPress parasti atveidotu, izmantojot the_content. Ja izkārtojums neizvada blockstudio_page_content(), lapas saturs tiek apzināti paslēpts.
Izkārtojumos var izmantot lapu palīgfunkcijas:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
Arī ligzdotas lapas, kas nav kolekciju lapas, var mantot tuvākā priekšteča layout.php elementu pages kokā. Kolekciju lapām kolekcijas saknes izkārtojums tiek saglabāts katrā sinhronizētajā ierakstā un uzraudzīts kā daļa no lapas pirkstu nospieduma, tāpēc izkārtojuma izmaiņas tiek atklātas nākamajā sinhronizācijā.
Renderētāja izkārtojumi
Izkārtojums var būt arī renderētāja ieraksts, piemēram, layout.tsx renderētājam, kas reģistrē layouts: ["layout.tsx"]. Tas tiek atrasts tajās pašās vietās, kur layout.php, un tam blakus var būt arī neobligāts layout.data.php datu ielādētājs. Renderēšanas laikā renderētājs saņem kind: "layout" un renderētās lapas saturu kā slot, ar tādu pašu the_content prioritāti kā layout.php. Direktorijā var būt layout.php vai viens renderētāja izkārtojums, bet ne abi; ja ir abi, rodas atklāšanas kļūda. Ja izkārtojumu neizdodas ielādēt, tiek izsaukts blockstudio/pages/layout_error, un lapas saturs paliek bez ietvara, tāpat kā tas notiek ar layout.php.
Bloku rediģēšanas režīms
Rekvizīts blockEditingMode nosaka, kā blokus var rediģēt redaktorā. Iestatiet noklusējuma vērtību lapas līmenī laukā page.json un veidnē to pārrakstiet katram elementam:
{
"name": "about",
"title": "About Us",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
| Vērtība | Apraksts |
|---|---|
"default" |
Pilna rediģēšana. Blokus var atlasīt, pārvietot un rediģēt. |
"contentOnly" |
Tikai teksta rediģēšana. Bloku tekstu var rediģēt, bet iestatījumi un struktūra ir bloķēti. |
"disabled" |
Rediģēšana nav atļauta. Bloki ir pilnībā neinteraktīvi. |
Atsevišķu elementu ignorējošās vērtības tiek iestatītas kā HTML atribūti jebkuram elementam (<h1>, <p>, <div> u. c.) vai <block> elementiem. Virsējā līmeņa konteinerbloki elementiem ar ignorējošām vērtībām tiek automātiski iestatīti uz contentOnly, lai to bērnelementi paliktu pieejami. Šī kaskāde virzās augšup no elementa ar ignorējošo vērtību līdz lapas saknei, tāpēc blockEditingMode jāiestata tikai tiem elementiem, kurus vēlaties padarīt rediģējamus.
Veidnes bloķēšana
Rekvizīts templateLock nosaka, kā lietotāji var rediģēt lapu redaktorā:
| Vērtība | Pievienot/noņemt | Pārvietot | Rediģēt saturu |
|---|---|---|---|
"all" |
Nē | Nē | Nē |
"insert" |
Nē | Jā | Jā |
"contentOnly" |
Nē | Nē | Jā |
false |
Jā | Jā | Jā |
Ja ir iestatīts templateLock, Blockstudio atspējo iespēju atbloķēt blokus, izmantojot redaktora UI.
Virtuālie maršruti
Dažiem dokumentiem nav piesaistīta ieraksta: no datiem ģenerēta komponentu atsauce, katalogs vai konta sadaļa. Reģistrējiet tos kā virtuālos maršrutus, nevis paši piesaistiet template_redirect:
add_action( 'init', function () {
Blockstudio\Virtual_Routes::register(
'components',
function ( $component, string $rest ) {
get_header();
echo my_component_page( $component );
get_footer();
},
[
'prefix' => true,
'match' => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
'title' => fn ( $component ) => my_component_title( $component ),
'urls' => fn () => my_component_paths(),
]
);
} );
Ceļš ir relatīvs pret vietnes sākumlapu. Ar prefix maršruts apkalpo arī visus tālāk esošos ceļus, un match saņem atlikušo daļu (tukšu virkni pašam maršrutam) un atgriež vērtību, ko saņem renderēšanas atzvans, vai null, lai atstātu URL apstrādāt WordPress, kas pēc tam atbild kā parasti uz 404. Renderēšanas atzvans izvada dokumentu vai atgriež to kā virkni; title ir virkne vai noslēgums, kas saņem atbilstības vērtību.
Atbilstošam pieprasījumam Blockstudio neļauj WordPress atzīmēt to kā 404 un redirect_canonical to novirzīt, notīra galvenā vaicājuma ziņoto atsevišķās lapas stāvokli, nosūta statusu (pēc noklusējuma status, 200) un atveido ar prioritāti Virtual_Routes::PRIORITY, izmantojot template_redirect. Tas notiek tūlīt pēc tam, kad Blockstudio atver izvades buferi ar Assets::BUFFER_PRIORITY, tāpēc gatavais dokuments saņem bloku resursus, komplektā iekļautos UI resursus un kompilēto Tailwind tāpat kā jebkura cita lapa, bet pirms redirect_canonical ar prioritāti 10. Apstrādātājam, kas pats atveido visu dokumentu, arī jādarbojas pēc Assets::BUFFER_PRIORITY, citādi šī apstrāde tiek izlaista. Ceļi laukā urls (pēc noklusējuma pats maršruta ceļš, ja tas nav prefiksa maršruts) tiek pievienoti statiskās iepriekšējas atveides būvējumiem, un Virtual_Routes::urls() atgriež tos kā absolūtos URL vietnes kartei. Virtual_Routes::match( $path ) atrisina ceļu tāpat kā pieprasījums.
Sinhronizācijas darbība
Lapu ieraksti mainās tikai pēc skaidri veiktas sinhronizācijas darbības:
wp bs pages sync
Komanda atklāj visu avotu inventāru, izveido vai atjaunina mainītos ierakstus, dzēš apstiprinātos bāreņierakstus, atsvaidzina kolekciju maršrutēšanas un kompilētās templateFor konfigurāciju un ziņo par veiktajām izmaiņām. Pievienojiet --authoritative, lai aizstātu pārvaldīto saturu, nevis saglabātu redaktora saturu ar atslēgām, un --full, lai ziņotu, ka šī darbība ir pilnīga salāgošana neatkarīgi no saglabātās avota identitātes:
wp bs pages sync --authoritative --full
Parastos priekšpuses, administrēšanas, AJAX, REST, cron un vispārīgos WP-CLI sāknēšanas pieprasījumos netiek veikta pilnīga lapu atklāšana, netiek vaicāts pārvaldītās salāgošanas inventārs un netiek rakstīti lapu ieraksti. Tie izmanto jau sinhronizētos WordPress ierakstus, kā arī kompaktu kolekciju un ierakstu tipa veidņu konfigurāciju, kas saglabāta pēdējās skaidri veiktās darbības laikā. Auksta instalācija vai jaunināšana var vienreiz pārskatīt kolekciju manifestus, lai atjaunotu maršrutēšanas metadatus; šī tikai lasīšanas sāknēšana nekad nesinhronizē saturu. Autentificētais, pēc izvēles aktivizējamais Canvas atsvaidzināšanas galapunkts ir skaidri izsaukta satura izveides darbība API: Canvas to izsauc vienreiz, kad tiek atvērta darbvieta, lai jaunpievienotie vai mainītie avoti parādītos sākotnējā inventārā. Tiešraides režīms izsauc to pašu robežpunktu, kad konstatē lapas avota izmaiņas.
Blockstudio\Pages::init() tagad reģistrē tikai pieprasījuma laika āķus. Integrācijām, kas iepriekš šai metodei nodeva argumentu force, tā vietā jāizsauc Blockstudio\Pages::reconcile() vai jāpalaiž wp bs pages sync.
Lai novērstu lapas pārrakstīšanu pēc manuālas rediģēšanas, iestatiet "sync": false laukā page.json.
Pārnesamas avota atrašanās vietas
Sinhronizētie tēmas faili tiek glabāti kā ar tēmu saistītas atrašanās vietas, nevis absolūti instalācijas ceļi. Bērntēmu un pamattēmu failiem ir atsevišķas identitātes, pat ja to relatīvie failu nosaukumi sakrīt. Lapu palīgfunkcijas joprojām atgriež atrisinātas absolūtās template_path, content_path, layout_path un directory vērtības pašreizējam pieprasījumam.
Tas ļauj CLI sinhronizācijai un tīmekļa pieprasījumiem izmantot dažādas failu sistēmas saknes, piemēram, mitināšanā ar ierobežotu piekļuvi, nesabojājot Markdown atbildes, izkārtojumus, redaktora Tailwind skenēšanu vai iepriekšrenderēšanas avotu izsekošanu. Esošie absolūtie tēmas ceļi tiek no jauna piesaistīti, nolasot tos, ja tēmas direktorija nosaukums nav mainījies. Lai tos nolasītu, nav nepieciešama sinhronizācija, datubāzes migrācija vai metadatu ierakstīšana pieprasījuma apstrādes laikā; nākamā skaidri palaistā sinhronizācija saglabās pārnesamās atrašanās vietas.
Ja tēmas direktorija ir simboliskā saite, piemēram, uz izstrādes darba kopiju, theme: atrašanās vietas tiek saglabātas vienādas neatkarīgi no tā, vai avots nolasīts, izmantojot simbolisko saiti vai tās mērķi, un tiek atrisinātas uz konfigurēto tēmas direktoriju.
Faili ārpus aktīvajām pakārtotajām un vecākajām tēmām joprojām tiek atbalstīti to konfigurētajos absolūtajos ceļos, ievērojot PHP open_basedir ierobežojumus. Tos nevar automātiski pārvietot: pēc ārēja avota pārvietošanas atjauniniet tā konfigurēto ceļu un skaidri palaidiet sinhronizāciju.
Ieraksta lauku īpašumtiesības
postStatus iestata sākotnējo statusu. Turpmākās sinhronizācijas saglabā esošos melnraksta, gaidošos, privātos, publicētos un ieplānotos statusus, arī ar --authoritative. Melnraksts netiek publicēts atkārtoti tikai tāpēc, ka tā failā norādīts postStatus: "publish". Esošā bāreņu ierakstu atkopšanas darbība paliek nemainīga: skaidri palaista sinhronizācija atjauno pārvietotu uz miskasti pārvaldītu ierakstu, ja tā avots ir pieejams. Lai nepieļautu atjaunošanu, bloķējiet lapu vai atspējojiet sinhronizāciju.
Fails arī turpmāk nosaka nosaukumu, slug, ieraksta veidu, vecākierakstu un konfigurēto izvēlnes secību. Šo vērtību rediģēšana WordPress nemaina avota definīciju. Nākamā skaidri palaistā sinhronizācija no jauna piemēro failā norādītās vērtības un nosauc skartos laukus pages.<name>.overwritten, bet brīdinājumu parāda CLI tabulas izvadē. Joprojām tiek piemērotas WordPress sākotnējās atļaujas, tostarp tukšs slug gaidošiem ierakstiem, ja sinhronizāciju veicošajam lietotājam nav tiesību tos publicēt.
Lietojiet blockstudio/pages/update_post_data integrācijai, kurai ir skaidri noteikta atšķirīga statusu politika. Bloki ar atslēgām saglabā redaktora pārvaldīto bloku saturu; atslēgas nemaina ieraksta nosaukuma vai slug īpašumtiesības.
Kolekciju lapu pirkstu nospiedumos ietilpst manifests, ielādētājs, lapas avots, izkārtojuma fails, metadati un saistītie avota ceļi. Nākamā skaidri veiktā sinhronizācija piemēro izmaiņas šajās ievadēs.
Kad kolekcijas avots tiek noņemts, Blockstudio noņem ģenerēto lapu, lai pēc avota faila dzēšanas nepaliktu vecās kolekcijas lapas. Pēc noklusējuma bāreņlapas tiek pārvietotas uz miskasti. Izmantojiet blockstudio/pages/orphan_action, lai atgrieztu trash, delete vai keep.
Priekšpuses pieprasījumos Blockstudio ielādē lapu reģistru no jau sinhronizētajiem publicētajiem ierakstiem. Melnrakstu un privātās lapas ir pieejamas administrēšanas un sinhronizācijas kontekstos, bet priekšpuses palīgfunkcijas ielādē tikai publicētās lapas.
Izvietošanas salāgošana
Blockstudio\Pages::reconcile() ir izvietošanas ieejas punkts PHP. Tas atklāj visu vēlamo inventāru, salīdzina avota un sinhronizācijas dzinēja pirkstu nospiedumus un atgriež mašīnlasāmu pārskatu:
$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',
],
],
]);
Pārskatā ir iekļauts discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, katras lapas rezultāti, atklāšanas kļūdas un deterministisks sourceIdentity.
Bloķētām lapām ir status: "locked", un tās uzskaita atsevišķi no nemainītajām lapām. removedPages katrai noņemtajai lapai uzrāda tās name, key, postId un faktisko action (trash vai delete); paturētie vai jau miskastē ievietotie ieraksti netiek skaitīti kā tikko noņemti. CLI tabulas izvadē ir norādītas arī izveidotās, atjauninātās, bloķētās, noņemtās un ar saglabātu saturu apstrādātās lapas, kā arī to ierakstu ID.
Pēc parsēšanas un apvienošanas pēc atslēgām identisks gala ieraksts neizsauc wp_update_post(), nemaina post_modified, neveido versiju un neizsauc ieraksta atjaunināšanas āķus. Rezultāts ir unchanged. Ja avota saturs atšķiras no redaktora pārvaldītā satura blokos ar atslēgām, preserved: true identificē šo lēmumu, un kopējā augšējā līmeņa skaitā preserved tas tiek ietverts. Jaunais avota pirkstu nospiedums un pārvaldītie metadati tik un tā tiek reģistrēti, tāpēc nākamā nemainītā sinhronizācija neko nedara. preserved ir papildu karodziņš, nevis ekskluzīvs statuss: lapa var saglabāt bloku saturu ar atslēgām, vienlaikus atjauninot faila pārvaldīto nosaukumu vai pievienojot citu bloku.
authoritative: true var noņemt Page Sync bloķēšanu un aizstāj saturu ar faila definīcijā norādīto, nevis saglabā redaktora saturu ar atslēgām. Parastai skaidri veiktai sinhronizācijai atstājiet to kā false. plan_valid: false, full: true, broad: true, trūkstoša iepriekšējā avota identitāte vai mainīts sinhronizācijas dzinēja pirkstu nospiedums atzīmē darbību kā pilnīgu salāgošanu (pārskatā fullReconciliation). Katrā darbībā tiek salīdzināts viss inventārs. Git pārdēvēšanas ieraksti ir tikai identitātes norādes. Tie nekad neaizstāj visa inventāra salīdzināšanu.
Ja pirkstu nospiedumi un izpildlaika ceļi nav mainījušies, ieraksti vai to metadati netiek rakstīti un atjaunināšanas āķi netiek izsaukti. Ja nemainīts avots tiek pārvietots uz jaunu laidiena direktoriju, salāgošana atsvaidzina tikai tā saglabātās veidnes, satura, izkārtojuma un direktorija ceļus; tā neatjaunina post_content vai ieraksta pēdējās izmaiņas laika zīmogu. Trūkstošās pārvaldītās lapas tiek dzēstas tikai pēc pilnīgas salāgošanas darbības sekmīgas pabeigšanas bez atklāšanas vai lapu ierakstīšanas kļūdām.
Tieša API salāgošana neatzīmē izvietošanu kā veiksmīgu. Pēc atbilstošā statiskā artefakta un maršrutu aktivizēšanas un pārbaudes skaidri saglabājiet atgriezto identitāti:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync saglabā atgriezto identitāti pēc sekmīgas darbības. Parastā WP-CLI sāknēšana reģistrē tikai saglabātos kolekciju ierakstu tipus un pārrakstīšanas noteikumus. Tā neatklāj un nesinhronizē lapas.
Ierakstu ID piesaiste
Pēc noklusējuma WordPress automātiski piešķir ierakstu ID. Ja lapa tiek dzēsta un izveidota no jauna, ID mainās, pārtraucot ārējās atsauces, piemēram, izvēlnes vai cieti iekodētas saites.
Izmantojiet postId, lai piesaistītu lapai konkrētu ID:
{
"name": "about",
"title": "About Us",
"postId": 42
}
Veidojot lapu, Blockstudio nodod ID uz WordPress, izmantojot import_id. Ja ID ir pieejams, WordPress to izmanto tieši. Ja šo ID jau izmanto nesaistīts ieraksts, WordPress klusi automātiski piešķir jaunu ID.
Meklējot esošās lapas, Blockstudio vispirms pārbauda piesaistīto ID un tikai pēc tam metadatus vai slug. Tas nozīmē, ka, dzēšot un atkārtoti sinhronizējot lapu, tā iegūst atpakaļ to pašu ID.
Bloku apvienošana pēc atslēgām
Pēc noklusējuma, mainoties veidnes failam, Blockstudio aizstāj visu ieraksta saturu ar jauno veidni. Tas nozīmē, ka redaktorā WordPress veiktās izmaiņas tiek zaudētas.
Pievienojiet blokiem atribūtu key, lai saglabātu lietotāju veiktās izmaiņas, sinhronizējot veidnes. Ja veidnē ir bloki ar atslēgām, Blockstudio apvieno veidnes izmaiņas ar esošo ieraksta saturu, nevis to aizstāj.
Atslēgu pievienošana
Izmantojiet atribūtu key jebkuram elementam HTML vai elementam <block>:
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>
<div key="features">
<p>First feature.</p>
<p>Second feature.</p>
</div>
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h2>Hero Title</h2>
<p>Hero description.</p>
</block>
<block
name="acme/testimonial"
key="featured-quote"
quote="Default quote"
/>
Atslēgām jābūt unikālām visā veidnē. Atslēga aizsargā visu bloku un tā saturu. Nav jāpiešķir atslēgas atsevišķiem bērnelementiem bloka iekšienē, ja vecākblokam jau ir atslēga. Blokus ar atslēgām starp veidnes atjauninājumiem var pārvietot uz jebkuru vietu vai ligzdošanas līmeni, un to lietotāja saturs joprojām tiks saglabāts.
Atslēgas darbojas tāpat arī Blockstudio pielāgotajos blokos. key ir Page Sync strukturālie metadati; pielāgoto lauku vērtības paliek parasti Blockstudio atribūti. Kad redaktorā šie lauki tiek mainīti, vēlākā veidnes sinhronizācijā tiek saglabātas redaktora vērtības, vienlaikus piemērojot neatkarīgas veidnes izmaiņas. Lapas, kas izveidotas ar vecākām versijām, kurās atslēga atradās pielāgoto lauku datos, nākamajā sinhronizācijā tiek automātiski migrētas.
Kā notiek apvienošana
Mainoties veidnes failam un lapai atkārtoti sinhronizējoties:
| Bloks | Darbība |
|---|---|
| Bloks ar atslēgu | Lietotāja saturs un lauka Blockstudio vērtības tiek saglabātas. Tiek piemēroti veidnes pārvaldītie atribūti un struktūra. |
| Bloks bez atslēgas | Pilnībā aizstāts ar veidnes versiju (tāpat kā bez atslēgām) |
Piemēri
Lietotāja veiktās izmaiņas blokos ar atslēgām tiek saglabātas:
- Veidnē definēts
<p key="intro">Default intro.</p> - Lietotājs redaktorā rediģē rindkopu, ievadot tekstu "Custom intro text."
- Izstrādātājs atjaunina veidni, pievieno jaunu bloku un maina izkārtojumu
- Sinhronizējot rindkopā tiek saglabāts teksts "Custom intro text.", bet tiek piemērots jaunais izkārtojums
Joprojām tiek piemēroti veidnes atribūti:
- Veidnē ir vāka bloks ar
key="hero"un atribūtuurl - Izstrādātājs maina vāka atribūtu
url, norādot jaunu fona attēlu - Sinhronizējot tiek lietots jaunais fona attēls, bet lietotāja satura izmaiņas vāka iekšpusē tiek saglabātas
Īpašie gadījumi
| Scenārijs | Darbība |
|---|---|
| Veidnei pievienots jauns bloks ar atslēgu | Tiek parādīts ar veidnes noklusējuma saturu |
| No veidnes noņemts bloks ar atslēgu | Tiek dzēsts no ieraksta |
| Mainās bloka tips (atslēga ir tā pati) | Pilnībā tiek izmantota veidne, saturs netiek apvienots |
| Dublētas atslēgas | Otrā sastopamā atslēga tiek uzskatīta par tādu, kuras nav |
| Veidnē nav atslēgu | Pilnīga aizstāšana (tāpat kā bez atslēgām) |
| Piespiedu sinhronizācija | Pilnīga aizstāšana, atslēgas tiek ignorētas |
| Bloķēts ieraksts | Sinhronizācija nenotiek |
Apvienošana ar rediģēšanas vadīklām
Atslēgas, templateLock un blockEditingMode ļauj precīzi kontrolēt, ko klienti var un ko nevar darīt. Tālāk sniegti biežākie darba procesu piemēri.
Pilnībā bloķēta lapa
Izstrādātājs kontrolē visu. Lapa ir statisks izkārtojums, ko klienti nevar mainīt. Piemērots juridiskām lapām, pakalpojumu lietošanas noteikumiem un jebkurai lapai, ko drīkst mainīt tikai ar kodu.
{
"name": "terms",
"title": "Terms of Service",
"templateLock": "all"
}
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>
Atslēgas nav vajadzīgas. Veidne ir vienīgais patiesības avots. Katrā sinhronizācijā lapa tiek pilnībā pārrakstīta.
Bloķēts izkārtojums ar rediģējamu saturu
Visbiežāk izmantotais modelis. Bloķējiet lapas struktūru, lai klienti nevarētu pievienot, noņemt vai pārkārtot blokus, bet ļaujiet viņiem rediģēt tekstu konkrētās vietās. Atslēgas nodrošina, ka viņu veiktās izmaiņas saglabājas arī pēc veidnes atjaunināšanas.
{
"name": "landing",
"title": "Landing Page",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h1 blockEditingMode="contentOnly">Edit This Title</h1>
<p blockEditingMode="contentOnly">Edit this description.</p>
</block>
<div key="features">
<h2>Features</h2>
<p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
</block>
Klients var rediģēt galveno virsrakstu, aprakstu un funkciju ievadtekstu. Neko citu. Pogas tekstu, URL un vāka fona attēlu kontrolē izstrādātājs. Kad izstrādātājs atjaunina veidni (e.g., pievieno otru pogu), sadaļas ar atslēgām saglabā klienta tekstu.
Attīstāma veidne ar saglabātu saturu
Lapām, kas laika gaitā aug. Izstrādātājs pievieno veidnei jaunas sadaļas, un katra sinhronizācija pievieno jauno saturu, nemainot to, ko klients jau pielāgojis.
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<div key="testimonials">
<h2>Testimonials</h2>
<p>What our clients say.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
</block>
Jaunā atsauksmju sadaļa un poga parādās pēc sinhronizācijas. Klienta veiktie virsraksta, ievada un pakalpojumu labojumi paliek neskarti.
Vienreizējs pamats
Izveidojiet lapu ar sākotnējo struktūru un pēc tam pilnībā nododiet to tālāk. Iestatiet sync uz false, lai parastā sinhronizācija lapu nekad neizveidotu vai neatjauninātu, un izveidojiet to vienreiz ar Blockstudio\Pages::force_sync('blog'). Pēc tam lapa pilnībā pieder klientam.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
wp bs pages sync izlaiž šo lapu, tāpēc force_sync() to izveido vienreiz. Pēc tam klients var brīvi pievienot, noņemt un pārkārtot blokus. Veidnes izmaiņas tiek ignorētas.
Bloku saistījumi
Alternatīva apvienošanai pēc atslēgām ir izmantot WordPress kodola Bloku saistījumus API, lai savienotu blokus ar ieraksta meta datiem. Tā nav Blockstudio funkcija, bet gan iebūvēta WordPress API iespēja. Blockstudio vienkārši nodod atribūtu metadata ģenerētajam bloka marķējumam. Saturs atrodas ieraksta meta datos, nevis bloka marķējumā, tāpēc veidnes sinhronizācija var brīvi pārrakstīt marķējumu, jo redaktors nolasa datus no meta, nevis no innerHTML.
Nododiet atribūtu metadata jebkuram elementam HTML vai elementam <block>:
<h1
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'
>
Default Title
</h1>
<p
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'
>
Default description text.
</p>
<img
metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>
Meta atslēgām jābūt reģistrētām ar iespējotu show_in_rest:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Atslēgas un saistījumi
| Aspekts | Atslēgas | Saistījumi |
|---|---|---|
| Kur glabājas saturs | Bloka marķējumā (post_content) |
Ieraksta meta datos (wp_postmeta) |
| Saglabājas pēc veidnes sinhronizācijas | Jā (apvienots pēc atslēgas) | Jā (dati atrodas meta datos) |
Pieejams vaicājumiem, izmantojot WP_Query |
Nē | Jā (meta_query) |
| Pieejams REST API | Nē | Jā |
| Nepieciešama reģistrācija | Nē | Jā (register_post_meta) |
| Lietotājs var pārvietot blokus | Nē (veidne no jauna nosaka struktūru) | Nē (veidne no jauna nosaka struktūru) |
Abas pieejas var izmantot vienā veidnē. Izmantojiet atslēgas sadaļām, kurās ir svarīga bloku struktūra (e.g., grupa ar vairākiem bērnelementiem). Izmantojiet saistījumus atsevišķiem laukiem, ja vēlaties, lai dati būtu pieejami arī ārpus bloku redaktora.
Ierakstu veidu veidnes
Izmantojiet templateFor, lai iestatītu lapu kā noklusējuma veidni kādam ierakstu veidam:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
Visi jaunie šī veida ieraksti tiks sākti ar definēto bloku struktūru.
Pielāgoti ceļi
Pēc noklusējuma Blockstudio skenē get_template_directory() . '/pages'. Pievienojiet citus ceļus ar filtru:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
Izpildlaika integrācijas, kas apvieno failus no vairākām saknēm, var aizstāt failu sistēmas skenēšanu ar loģisku atklāšanas avotu. Lapu manifesti, izkārtojumi, ielādētāji un avota veidnes pēc tam tiek atrasti pēc loģiskā ceļa, pat ja atlasītie faili atrodas dažādās saknēs.
Filtri un darbības
Lapu atklāšanai, sinhronizācijai un kolekciju maršrutēšanai ir pieejami šādi paplašināšanas punkti:
| Āķis | Veids | Apraksts |
|---|---|---|
blockstudio/pages/paths |
Filtrs | Pievieno direktorijus, kuros Blockstudio meklē lapu avotus. |
blockstudio/pages/collection_post_type_args |
Filtrs | Pielāgo register_post_type() argumentus kolekcijas CPT. |
blockstudio/pages/template_candidates |
Filtrs | Pielāgo lapas avotam atlasīto veidņu failu nosaukumus. |
blockstudio/pages/serve_markdown |
Filtrs | Iespējo vai atspējo neapstrādātas Markdown atbildes. |
blockstudio/pages/orphan_action |
Filtrs | Bāreņu ierakstu tīrīšanai atgriež trash, delete vai keep. |
blockstudio/pages/docs_allowed_html |
Filtrs | Pielāgo ģenerētā Markdown dokumentācijas satura atļauto HTML. |
blockstudio/pages/allow_external_loader_path |
Filtrs | Atļauj ielādētāja paths ārpus kolekcijas saknes. |
blockstudio/pages/manifest_scan_interval |
Filtrs | Iestata maksimālo vecumu mantotās pirms-7.6.2 manifesta kešatmiņai, no kuras jaunināšanas laikā var iegūt saglabāto izpildlaika konfigurāciju. |
blockstudio/pages/create_post_data |
Filtrs | Modificē ieraksta datus pirms sinhronizētās lapas izveides. |
blockstudio/pages/update_post_data |
Filtrs | Modificē ieraksta datus pirms sinhronizētās lapas atjaunināšanas. |
blockstudio/pages/sync_engine_inputs |
Filtrs | Pievieno parsētāja, kartējuma vai migrācijas versiju, kurai apzināti vienreiz jāpaplašina saskaņošana. |
blockstudio/pages/post_created |
Darbība | Tiek izpildīta pēc sinhronizētās lapas ieraksta izveides. |
blockstudio/pages/post_updated |
Darbība | Tiek izpildīta pēc sinhronizētās lapas ieraksta atjaunināšanas. |
blockstudio/pages/synced |
Darbība | Tiek izpildīta pēc lapu reģistra sinhronizācijas pabeigšanas. |
blockstudio/pages/reconciled |
Darbība | Tiek izpildīta pēc skaidri palaistas saskaņošanas kopā ar mašīnlasāmu pārskatu. |
blockstudio/pages/renderers |
Darbība | Reģistrē lapu renderētājus ar Blockstudio\Page_Renderers::register(). Tiek izpildīta vienreiz katrā pieprasījumā. |
blockstudio/pages/rendered |
Darbība | Tiek izpildīta pēc komponenta lapas renderēšanas, nododot lapu, tās HTML un atkarības. |
blockstudio/pages/layout_error |
Darbība | Tiek izpildīta, ja izkārtojumu neizdodas renderēt, nododot kļūdu, izkārtojuma ceļu un lapu. |
PHP API
// Get all registered pages.
$pages = Blockstudio\Pages::pages();
// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');
// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');
// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');
// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');
// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');
// Get a specific page.
$page = Blockstudio\Pages::get_page('about');
// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');
// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');
// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();
// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
]);
// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);
// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');
// Unlock a page.
Blockstudio\Pages::unlock('about');
// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
'extensions' => ['tsx'],
'layouts' => ['layout.tsx'],
'render' => 'my_theme_render_page',
]);
// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');
// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);
Argumentu semantiku, pārskata laukus un pārbaudīto avota identitātes robežu skatiet sadaļā Izvietošanas saskaņošana.
Veidnēm un izkārtojumiem ir pieejamas globālās palīgfunkcijas:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
Lapu masīvos, ko atgriež Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() un globālās palīgfunkcijas, ir iekļauta sinhronizētā ieraksta identitāte, avota un veidnes ceļi, kolekcijas un ceļa metadati, satura tips, sinhronizācijas politika, ieraksta veids un statuss, rediģēšanas politika, pielāgotie metadati un atslēga permalink. Kolekcijas metadati tiek ielādēti no pēdējās veiksmīgās tieši pieprasītās saskaņošanas. Parastie pieprasījumi šo izpildlaika informāciju atjauno no saglabātās konfigurācijas un sinhronizētā ieraksta meta datiem, nelasot lapu avotu kokus. Pages klase neatklāj atsevišķu pastāvīgās saites metodi.
Veidņu bloķēšana, bloku rediģēšanas režīmi, apvienošana pēc atslēgām un klientiem pieejamā rediģēšanas kontrole.