Puslapiai
Puslapiai yra failais pagrįsti šablonai, kurie sinchronizuojami su WordPress duomenų baze kaip įrašai. Sinchronizavimas vykdomas aiškiai: kai norite pritaikyti šaltinio pakeitimus, paleiskite wp bs pages sync arba iškvieskite puslapių API. Įkeliant svetainės sąsają ar WordPress administravimo aplinką, visas puslapių aptikimas neatliekamas ir puslapių įrašai nekeičiami.
Puslapius galima apibrėžti viename page.json aplanke, kaip atskirus Markdown failus arba kaip rinkinį su pages.json manifestu. Rinkiniai naudingi dokumentacijai, žinių bazėms, nukreipimo puslapių bibliotekoms ar bet kokiems įdėtų puslapių rinkiniams, kuriuos norima generuoti iš failų.
page.json
Norėdami apibrėžti puslapį naudodami JSON, pridėkite konfigūracijos failą page.json:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
Savybės
| Ypatybė | Tipas | Numatytoji reikšmė | Aprašymas |
|---|---|---|---|
name |
string |
privaloma | Unikalus puslapio identifikatorius |
title |
string |
Automatiškai pagal pavadinimą | Puslapio pavadinimas |
slug |
string |
Toks pats kaip pavadinimas | URL puslapio nuorodos fragmentas |
path |
string |
"." |
Loginis kelias kolekcijoje |
order |
integer |
0 |
Sinchronizuojamo įrašo meniu tvarka |
postType |
string |
"page" |
WordPress įrašo tipas |
postStatus |
string |
"draft" |
Naujų įrašų būsena (publish, draft, pending, private) |
postId |
integer |
– | Prisegti puslapį prie konkretaus WordPress įrašo ID |
blockEditingMode |
string |
– | Blokų redagavimo režimas: "default", "contentOnly" arba "disabled" |
templateLock |
string|false |
"all" |
Užrakinimo režimas: "all", "insert", "contentOnly" arba false |
templateFor |
string|null |
null |
Nustatyti kaip numatytąjį įrašo tipo šabloną |
sync |
boolean |
true |
Nurodo, ar įprastas aiškus suderinimas gali sukurti arba atnaujinti įrašą |
render |
string|object|false |
– | Atvaizduoti puslapį naudojant registruotą puslapių atvaizduoklį (žr. Komponentų puslapiai) |
Tarp page.json, frontmatter ir įkėlimo įrašų atpažįstami raktai: blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock ir title. Bet koks aukščiau nenurodytas raktas saugomas puslapio masyve meta.
Turinio šaltiniai
Puslapio apibrėžtis nurodo, kuris WordPress įrašas turi egzistuoti. Turinio šaltinis nurodo, koks blokų žymėjimas įrašomas į tą įrašą.
Kai puslapio aplanke yra page.json, Blockstudio ieško gretimo šaltinio failo tokia tvarka:
| Failas | Paskirtis |
|---|---|
index.php |
Į HTML panašus blokų žymėjimas, skaitomas toks, koks yra (PHP kodas nevykdomas) |
index.blade.php |
Blade šablono turinys |
index.twig |
Twig šablono turinys |
index.md |
Markdown turinys |
page.json taip pat gali turėti įterptą markdown arba html turinį vietoj gretimo failo:
{
"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>"
}
Rinkiniai suteikia dar du šaltinio režimus:
- Markdown failai, tiesiogiai aptinkami rinkinio medyje.
- Įkėlimo įrašai, grąžinami iš
loader.php.
Įkėlimo įrašuose galima naudoti markdown, html arba content su contentType. Jie taip pat gali nurodyti vietinį file arba template. Failų ir šablonų šaltinių tipas nustatomas pagal plėtinį, nebent aiškiai nustatyta contentType reikšmė.
Palaikomos contentType reikšmės: php, blade, twig, markdown ir html. Markdown pirmiausia konvertuojamas į HTML, o tada analizuojamas ir paverčiamas vietiniais WordPress blokais. PHP, Blade, Twig ir HTML šaltiniai apdorojami įprastu Blockstudio puslapių analizatoriumi.
Pagrindinių blokų klasės
HTML elementui priskirtas class, kuris susietas su pagrindiniu bloku, tampa jo className.
Aiškiai nurodyto pagrindinio bloko žymoje galima tiesiogiai naudoti className. Abi formos išsaugo bloko įrašyto apvalkalo klases kartu su klasėmis, kurias generuoja WordPress:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
Jei yra abi savybės, pirmenybė teikiama className. Šis konvertavimas taikomas tik pagrindiniams blokams: pasirinktinio bloko susiejimas palieka jo lauką class nepakeistą. Mygtuko stiliaus klasės, pavyzdžiui, is-style-outline, priklauso mygtuko apvalkalui, o ne jo nuorodai.
Paleiskite wp bs pages sync, kad pritaikytumėte analizatoriaus pataisas anksčiau sinchronizuotiems puslapiams. Analizatoriaus atnaujinimai atpažįstami kito aiškaus sinchronizavimo metu, net jei šaltinio failas nebuvo redaguotas. Užrakintiems puslapiams ir puslapiams su sync: false toliau taikomos įprastos apsaugos; priekinės dalies užklausos niekada nevykdo šio sinchronizavimo.
Serijuoti WordPress blokai
Puslapių ir šablonų šaltiniuose taip pat gali būti serijuotų blokų, nukopijuotų iš WordPress kodo rengyklės:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
Kai šaltinyje yra <!-- wp:... --> blokų skirtukas, Blockstudio visam šaltiniui naudoja savąjį WordPress blokų analizatorių. Atributai, įdėtiniai blokai, dinaminiai blokai, pvz., „Query Loop“, ir Blockstudio blokai išsaugo savo serializuotą struktūrą. Už blokų komentarų ribų esantis HTML lieka savuoju laisvo formato HTML; jis nesusiejamas su papildomais blokais. Nemaišykite Blockstudio HTML blokų žymų su šiuo formatu tikėdamiesi, kad jos bus konvertuotos. Įprasti HTML komentarai neįjungia serializuotų blokų režimo.
Markdown puslapiai
Naudokite Markdown, kai tekstas turi būti saugomas failuose, bet po sinchronizavimo tapti redaguojamu WordPress blokų turiniu. Sinchronizavimo metu šaltinis Markdown paverčiamas blokų žymėjimu. Sinchronizuotame įraše saugomi blokai, o ne neapdorotas Markdown turinys.
Markdown galima naudoti trimis būdais:
| Šaltinis | Reikia frontmatter? | Pastabos |
|---|---|---|
Atskiras pages/example/index.md |
Taip | Frontmatter pateikia puslapio tapatybę. |
page.json ir index.md |
Ne | page.json apibrėžia puslapį, o Markdown pateikia turinį. |
| Markdown rinkinyje | Ne | Rinkinys pagal failo vietą nustato name ir path. |
Atskiras index.md failas be frontmatter praleidžiamas, nes Blockstudio neturi sinchronizuotino puslapio tapatybės. Rinkinio Markdown nereikia frontmatter, nes šią tapatybę nurodo rinkinio manifestas ir failo kelias.
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
Taip pat galite susieti page.json su index.md. Tokiu atveju page.json apibrėžia puslapį, o index.md pateikia turinį. index.md esantis frontmatter pakeičia atitinkamas page.json reikšmes.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
title: API Reference
order: 20
---
# Reference
This page uses `page.json` with Markdown content.
Rinkinio Markdown atveju failo kelias tampa loginiu puslapio keliu, nebent jį pakeičia frontmatter:
| Failas | Numatytoji vieta |
|---|---|
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 |
Nežinomi frontmatter raktai išsaugomi puslapio meta masyve. Taip galima pridėti tokius duomenis kaip section ar description ir nuskaityti juos iš PHP API.
Markdown analizuojamas kaip GitHub Flavored Markdown. Leidžiamas neapdorotas HTML, nesaugios nuorodos pašalinamos, o antraštėms be aiškaus ID priskiriamas nekintantis ID. Įdėtajam YAML frontmatter reikia kartu pateikiamo YAML analizatoriaus.
Neapdorotas Markdown
Markdown failų šaltiniai gali pateikti pirminio šaltinio Markdown išorinėms priemonėms ir dokumentacijos naudotojams. Įterptasis Markdown neturi šaltinio failo, todėl sinchronizuojamas į blokus, bet negrąžina neapdoroto .md atsako.
Užklauskite puslapio su priesaga .md, pvz., https://example.com/docs/reference.md. Arba siųskite antraštę Accept: text/markdown įprastam puslapio URL:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
Frontmatter pašalinamas iš atsako. Sėkmingi neapdoroti Markdown atsakymai siunčia Content-Type: text/markdown, X-Robots-Tag: noindex ir kanoninę Link antraštę atgal į HTML puslapį. Neradus .md maršruto, grąžinamas tikras 404.
Turinio derybos veikia kartu su statiniu išankstiniu atvaizdavimu: užklausa, kurios antraštėje Accept yra text/markdown, niekada neatsakoma iš išankstinio atvaizdavimo saugyklos ar ankstyvo aptarnavimo papildinio, todėl ji pasiekia WordPress ir Markdown apdorojimo priemonę. Iš anksto atvaizduoti HTML atsakymai, puslapio, kuriame taip pat deramasi dėl Markdown, HTML, ir per Accept apdorojami Markdown atsakymai siunčia Vary: Accept, todėl Vary paisančios talpyklos juos atskiria. CDN, kurios talpyklos raktas priklauso tik nuo URL, reikia atskiros taisyklės, kad tokioms užklausoms būtų apeinama talpykla. Pages::negotiates_markdown( $post_id ) nurodo, ar puslapis atsako į Markdown užklausas.
Rinkinio Markdown neapdorotam Markdown išlaiko tą pačią URL struktūrą:
| Puslapio URL | Neapdoroto Markdown URL |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
Išjunkite neapdorotus Markdown atsakymus naudodami filtrą blockstudio/pages/serve_markdown:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Užklausa .md URL, kurios nepavyksta susieti su puslapiu, pagrįstu Markdown, grąžina 404 tik tuo atveju, jei kelias patenka į puslapių rinkinį. Už visų rinkinių ribų Blockstudio užklausos neperima, kad ją apdorotų WordPress ar kiti papildiniai.
Komponentų puslapiai
Komponentų puslapį atvaizduoja puslapio atvaizduoklis, o ne saugo kaip blokus. Blockstudio nepateikia atvaizduoklio. Tema arba papildinys užregistruoja atvaizduoklį jo tvarkomiems įrašo failams, pavyzdžiui, React atvaizduoklį, skirtą page.tsx, o Blockstudio iškviečia jį su puslapiu, WordPress įrašu ir atvaizduotu vietos turiniu.
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 nurodomas aiškiai. Aplankas su index.php ir page.tsx, bet be render, lieka įprastu puslapiu, todėl pridėjus atvaizduoklį esamas puslapis niekada neatvaizduojamas dukart. Galimi šie variantai:
| Reikšmė | Reikšmė |
|---|---|
"page.tsx" |
Tik įrašas, be duomenų įkėlimo funkcijos |
{ "entry": "page.tsx", "data": "data.php" } |
Įrašas ir duomenų įkėlimo funkcija |
{ "entry": "page.tsx", "renderer": "react" } |
Įrašas su aiškiai nurodytu atvaizduoklio ID |
false |
Atvaizduoklio nėra, net jei kolekcijos numatytoji reikšmė jį nurodo |
Keliai nustatomi pagal puslapio aplanką arba, įkėlimo įrašų atveju, pagal kolekcijos šakninį aplanką. Jie turi likti aptikimo šaltinyje, nebent tai leidžia blockstudio/pages/allow_external_loader_path. Jei nenurodytas renderer, naudojamas atvaizduoklis, kuris prisiima įrašo failo plėtinį. Jei render nurodo neegzistuojantį įrašo ar duomenų failą, nežinomą atvaizduoklį arba plėtinį, kurio neprisiima nė vienas atvaizduoklis, aptinkama klaida ir suderinimas nutraukiamas prieš pašalinant bet ką.
Ką išsaugo sinchronizavimas
Sinchronizuojant išsaugomas vienas blockstudio/page blokas. Jei puslapio aplanke taip pat yra index.* šaltinis, jis apdorojamas kaip bet kuris puslapio šaltinis ir tampa bloko vidiniais blokais – jo vietos turiniu:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
Vietos turinyje palikite WordPress valdomą turinį, pavyzdžiui, trumpuosius kodus. Šaltinis, kurį sudaro tik vienas trumpasis kodas, pavyzdžiui, [download_checkout], saugomas kaip core/shortcode blokas, todėl aplink jo išvestį nededama pastraipa. Jis lieka post_content, todėl jį mato has_shortcode() patikros, raktą turintys vietos blokai sujungiami su redaktoriaus pakeitimais taip pat, kaip įdėtieji raktą turintys blokai, o do_shortcode išplečia trumpuosius kodus vieną kartą, įprastu the_content prioritetu, po to, kai juos apgaubia atvaizduoklis.
Atvaizdavimo apibrėžtis kartu su įrašu saugoma kaip perkeliamieji theme: keliai. Puslapio kontrolinis atspaudas apima apibrėžtį, bet ne įrašo ar duomenų įkėlimo failo turinį: redaguojant page.tsx arba data.php įrašas nesikeičia, o lankytojus pakeitimai pasiekia per atvaizdavimą ir statinio išankstinio atvaizdavimo grafą, kuriame įrašomas įrašas, duomenų įkėlimo funkcija ir kiekvienas atvaizduoklio nurodytas failas.
Atvaizduoklio registravimas
Registruokite atvaizduoklius naudodami veiksmą blockstudio/pages/renderers. Jis iškviečiamas kartą per užklausą, prieš pirmąjį aptikimą ar atvaizdavimą, todėl wp bs pages sync ir priekinės dalies užklausos mato tą patį registrą.
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',
)
);
}
);
Atvaizduoklių ID rašomi mažosiomis raidėmis. Plėtinys arba maketo pavadinimas gali priklausyti tik vienam atvaizduokliui, o layout.php lieka atskiru Blockstudio maketu. Iškviečiamas objektas gauna vieną užklausą:
| Raktas | Reikšmė |
|---|---|
kind |
page arba layout, jei tai atvaizduoklio maketas |
renderer |
Atvaizduoklio ID |
entry |
Absoliutus įrašo kelias |
data |
Absoliutus duomenų įkėlimo failo kelias arba null |
page |
Kanoniniai puslapio duomenys, įskaitant meta |
post_id |
WordPress įrašo ID |
slot |
Atvaizduotas vietos turinys arba puslapio turinys, jei tai maketas |
context |
frontend, rest, feed arba cli |
Grąžinamas HTML, atvaizduojant perskaityti failai ir pasirinktiniai ištekliai:
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 gaunamas iš užklausos tipo, o ne iš lankytojo, todėl
atvaizduoklis negali sugadinti prisijungusių ir anonimų baitų pariteto jį skaitydamas. Jei atvaizduoklio vykdymas nepavyksta, išmetama klaida: puslapis neatvaizduojamas su tuščiu turiniu. REST redaktoriaus peržiūroje blokas klaidą rodo kaip pranešimą. Sėkmingai atvaizdavus, veiksmas blockstudio/pages/rendered gauna puslapį,
HTML ir jo priklausomybes.
assets nurodo puslapiui reikalingus scenarijų ir stilių failus. Jiems taikomas blokų išteklių apdorojimas (*.inline.* konvencija, ES moduliai, minifikavimas ir ?ver), o puslapis juos įrašo vieną kartą per tą patį buferį, kuris įrašo blokų išteklius, todėl iš anksto atvaizduotas puslapis juos išsaugo. Išteklius gali nustatyti version, kad pakeistų savo ?ver reikšmę. Kodas už atvaizduoklio ribų gali naudoti tą patį kanalą per Blockstudio\Assets::register_owner(), kuris grąžina įrašytiną žymeklio komentarą.
Redaktorius
Redaktoriuje blockstudio/page rodo serverio atvaizduotą puslapio peržiūrą, kurioje lizdas yra vidiniai blokai, pavaldūs puslapio templateLock. Bloko negalima įterpti, dubliuoti ar įdėti į kitą bloką.
Puslapių rinkiniai
Rinkinys – tai aplankas su pages.json manifestu. Jame sugrupuojami daugelio puslapių šaltiniai pagal vieną rinkinio trumpąjį pavadinimą, taikomos numatytosios reikšmės, palaikomi įdėtieji keliai ir galima automatiškai užregistruoti atskirą įrašo tipą.
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"
}
}
| Savybė | Tipas | Aprašymas |
|---|---|---|
collection / slug / name |
string |
Rinkinio trumpasis pavadinimas. collection yra aiškiausia forma ir tampa viešosios URL pagrindu. |
title |
string |
Žmogui suprantamas rinkinio pavadinimas. |
postType |
string |
Sugeneruotų puslapių įrašo tipas. Pagal numatymą naudojama page. Jei jo nėra, Blockstudio jį užregistruoja. |
postTypeArgs |
object |
Argumentai, perduodami register_post_type(), kai Blockstudio užregistruoja rinkinio įrašo tipą. |
defaults |
object |
Numatytojiems puslapiams taikomos savybės. Numatytoji render taikoma puslapiui tik tada, kai jo įrašas yra puslapių kataloge. |
scope |
string |
collection (numatytoji) arba site. Žr. Svetainės rinkiniai. |
meta |
object |
Pasirinktiniai rinkinio metaduomenys. Nežinomi aprašo raktai taip pat saugomi meta. |
Rinkinio puslapių keliai yra loginiai. Puslapis su path: "guide/install" sinchronizuojamas kaip guide antrinis puslapis, o guide sinchronizuojamas kaip rinkinio šakninio puslapio antrinis puslapis, jei tokie tėviniai puslapiai yra.
Jei hierarchiniame rinkinyje yra įdėtasis puslapis, bet nėra tarpinio tėvinio šaltinio, Blockstudio tam keliui sugeneruoja tuščią konteinerio puslapį, kad WordPress hierarchija būtų užbaigta. Nehierarchiniams įrašų tipams (nepalaikantiems tėvinio puslapio funkcijos page-attributes) tušti konteineriai negeneruojami. Jie nukreipiami pagal išsaugotą rinkinio kelią, todėl gali būti kartu ir įdėtieji keliai, pvz., guide/install ir setup/install, nors abu baigiasi install.
Rinkinio įrašų tipai ir URL adresai
Rinkinio manifeste nustatykite postType, kad visi rinkinio puslapiai būtų sinchronizuojami su to tipo įrašais. Tos pačios reikšmės nereikia kartoti defaults. Atskiri puslapiai vis tiek gali pakeisti postType reikšmę frontmatter arba page.json.
Jei įrašo tipo nėra, Blockstudio jį užregistruoja su show_in_rest: true, puslapiams pritaikyta rengyklės sąranka ir rinkinio trumpuoju pavadinimu kaip viešuoju URL pagrindu. Registravimo argumentus galima pakeisti per postTypeArgs. Rinkinio įrašo tipo perrašymo taisyklės automatiškai atnaujinamos, kai pasikeičia užregistruoti rinkinio įrašų tipai arba perrašymo argumentai, todėl nereikia iš naujo išsaugoti WordPress nuolatinių nuorodų.
Rinkinio URL adresus sudaro rinkinio trumpasis pavadinimas ir kiekvieno puslapio loginis path:
| Šaltinio kelias | Viešas URL |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
Šis URL modelis veikia tiek hierarchiniams, tiek nehierarchiniams kolekcijų įrašų tipams. Blockstudio taip pat nukreipia dvigubus URL, pvz., /docs/docs/ arba /docs/docs/getting-started/, į kanoninį URL.
Kolekcijų puslapiuose pateikiamas neapdorotas Markdown tais pačiais URL (žr. Neapdorotas Markdown).
Jei pakeisite kolekcijos tipą iš postType: "page" į tinkintą įrašo tipą, Blockstudio vietoje perkels jau sinchronizuotus kolekcijos įrašus, jei jų išsaugota puslapio tapatybė sutampa. Taip išsaugomi įrašų ID, metaduomenys ir esamas turinys, išvengiant pasenusio tipo įrašų dublikatų. Pasenę kolekcijos įrašai išvalomi visose įrašų būsenose pagal filtrą blockstudio/pages/orphan_action.
Svetainės rinkiniai
Aprašas su "scope": "site" sugrupuoja visus po juo esančius puslapius, nepaversdamas jų rinkinio puslapiais. Naudokite jį svetainės puslapių medžio šaknyje, kad pritaikytumėte bendrus numatytuosius nustatymus ir išvardytumėte svetainės puslapius naudodami 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" }
}
}
Svetainės rinkinio puslapiai išlaiko lygiai tokią pačią tapatybę, kokią turėjo be aprašo, todėl pridėjus aprašą prie esamo medžio, įrašų eilutės nepasikeičia ir niekas nesukuriama ar neištrinama:
- Raktai lieka bendri:
Pages::get_page( 'home' )ir saugomi puslapių raktai sutampa. - URL išlieka WordPress puslapių URL. Netaikomos rinkinio perrašymo taisyklės, nuolatinių nuorodų filtras ar dvigubų URL peradresavimas, taip pat negeneruojami tušti konteinerių puslapiai.
- Loginiai keliai, trumpieji pavadinimai, tėviniai puslapiai ir šaltinio tapatybės išlieka kaip atskirų puslapių, o maketai parenkami pagal artimiausią protėvį.
- Įdėtieji
pages.jsonaprašai išlaiko savo rinkinius, o jų poaibiai neįtraukiami į svetainės rinkinį. - Numatyti nustatymai taikomi kiekvienam puslapiui atskirai: numatytoji
rendertaikoma tik puslapiams, kurių kataloge yra jos įrašas, todėl trumpųjų kodų ir Markdown puslapių šaltiniai lieka galioti.
Kolekcijų įkėlimo programos
Kolekcijose gali būti patikima vietinė loader.php. Naudokite ją, kai kolekcijų puslapiai gaunami iš kito vietinio šaltinio, pavyzdžiui, išorinės dokumentacijos aplanko, paketo ar sugeneruoto manifesto.
Įkėlimo programa vykdoma aiškiai nurodant aptikti puslapius ir sinchronizuoti. Ji turėtų
būti deterministinė ir vietinė. Venkite gauti nuotolinį turinį iš loader.php,
nes dėl to diegimo sinchronizavimas priklausytų nuo tos paslaugos.
<?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',
),
),
);
Įkėlimo programa gali grąžinti masyvą su raktais pages, meta ir paths:
| Raktas | Aprašymas |
|---|---|
pages |
Puslapių masyvų sąrašas. Kiekviename puslapyje palaikomi tie patys atpažįstami raktai kaip ir page.json bei Markdown priekiniuose metaduomenyse. |
meta |
Metaduomenys, sujungiami su kiekvieno įkėliklio sugeneruoto puslapio meta masyvu. |
paths |
Papildomi vietiniai katalogai, aptinkami kaip šio rinkinio dalis. Įrašai gali būti eilutės arba kelio objektai. |
render |
atvaizdavimo apibrėžtis kiekvienam Markdown puslapiui, aptiktam iš paths. |
Kaip trumpesnį variantą įkėlimo programa gali grąžinti paprastą puslapių masyvų sąrašą.
Įkėlimo programos puslapių įrašuose turinį galima pateikti šiais būdais:
| Forma | Aprašymas |
|---|---|
markdown |
Įterptinis Markdown turinys. |
html |
Įterptinis HTML turinys. |
content + contentType |
Bendro pobūdžio įterptinis turinys. contentType turi būti išspręstas į markdown arba html. |
file |
Vietinio failo šaltinis. Tipas nustatomas pagal plėtinį, nebent nustatyta contentType. |
template |
file sinonimas. |
Įkėlimo programos failų nuorodos gali nurodyti PHP, Blade, Twig, Markdown arba HTML šaltinius. Santykiniai keliai nustatomi nuo kolekcijos šakninio katalogo. Absoliutieji keliai ir keliai už kolekcijos šakninio katalogo ribų leidžiami tik tada, jei filtras blockstudio/pages/allow_external_loader_path juos leidžia.
Pagal numatytuosius nustatymus įkėlimo programos puslapiai priskiriami generated: true. Kai sugeneruotas įkėlimo programos puslapis dingsta iš jos išvesties, Blockstudio per kitą sinchronizavimą traktuoja sinchronizuotą įrašą kaip našlaitį; jis išvalomas pagal filtrą blockstudio/pages/orphan_action.
Katalogai, nurodyti paths, aptinkami kaip įprasti kolekcijų aplankai. Juose gali būti Markdown failų arba page.json aplankų. Jei šie keliai yra už kolekcijos šakninio katalogo ribų, taikomas tas pats išorinių kelių filtras.
Naudokite eilutės įrašą, jei išorinis katalogas turi išlaikyti savo loginius kelius. Naudokite objekto įrašą, jei katalogas turi būti prijungtas po kolekcijos kelio prefiksu:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
Su šia konfigūracija kolekcijoje cli-docs/index.md tampa path: "cli", o cli-docs/getting-started.md tampa path: "cli/getting-started". Prefiksai taip pat apsaugo sugeneruotų puslapių pavadinimus nuo konfliktų, todėl keliuose prijungtuose kataloguose gali būti index.md arba getting-started.md. Nustatykite kelio objekto preserveNames į true, jei norite išsaugoti aiškias name reikšmes iš page.json arba Markdown frontmatter.
Kelio objekto savybės:
| Savybė | Tipas | Aprašymas |
|---|---|---|
path |
string |
Vietinis katalogas, kurį reikia aptikti. Santykiniai keliai skaičiuojami nuo rinkinio šakninio katalogo. |
prefix |
string |
Pasirinktinis loginio kelio prefiksas rinkinyje. |
preserveNames |
boolean |
Išsaugoti aiškius puslapių pavadinimus, užuot generavus juos iš kelio su prefiksu. Kai nustatytas prefix, numatytoji reikšmė yra false. |
meta |
object |
Metaduomenys, sujungiami su kiekvienu iš šio kelio aptiktu puslapiu. Puslapio lygmens metaduomenys turi pirmenybę, kai raktai sutampa. |
render |
string|object |
Šio kelio Markdown puslapių atvaizdavimo apibrėžtis, pakeičianti įkėliklio render. |
Markdown atvaizdavimas per komponentą
Naudojant render, įkėliklio aptikti Markdown puslapiai atvaizduojami per puslapio atvaizduoklį, o ne saugomi kaip blokai:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
Jie lieka Markdown puslapiais: turinio tipas, turinio kelias, .md atsakymai ir priekiniai metaduomenys nepakinta. Sinchronizavimas išsaugo vieną blockstudio/page bloką, kurio vidinis HTML yra konvertuotas Markdown; jei rinkinys apvalo turinį, jis taip pat apvalomas. Taip išsaugomas dokumento tekstas post_content, o ne išanalizuoti blokai. Atvaizduoklis gauna šį HTML kaip lizdą ir gali skaityti šaltinį iš page.content_path. Santykiniai keliai skaičiuojami nuo rinkinio šakninio katalogo; išorinio kelio filtras taikomas taip pat kaip keliams. Puslapis, kurio priekiniuose metaduomenyse nustatyta nuosava render arba render: false, neįtraukiamas.
Maketai
layout.php failas apgaubia failais pagrįsto puslapio atvaizdavimą naudotojo sąsajoje. Jis nepakeičia sinchronizuoto post_content, saugomo WordPress, ir neapgaubia redaktoriaus drobės. Maketas vykdomas tik atskirų puslapių naudotojo sąsajos užklausoms.
Kolekcijoms įdėkite layout.php šalia pages.json, kad jis apgaubtų kiekvieną tos kolekcijos puslapį naudotojo sąsajoje:
<?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() išveda puslapio turinį, kurį WordPress paprastai atvaizduotų per the_content. Jei maketas neišveda blockstudio_page_content(), puslapio turinys tyčia paslepiamas.
Maketuose galima naudoti puslapio pagalbines funkcijas:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
Įdėtiniai puslapiai, nepriklausantys kolekcijai, taip pat gali paveldėti artimiausio protėvinio layout.php maketą pages medyje. Kolekcijų puslapių kolekcijos šakninio katalogo maketas saugomas kiekviename sinchronizuotame įraše ir stebimas kaip puslapio kontrolinio atspaudo dalis, todėl maketo pakeitimai pritaikomi per kitą sinchronizavimą.
Atvaizduoklio maketai
Maketą taip pat galima pateikti kaip atvaizduoklio įrašą, pavyzdžiui, layout.tsx, skirtą atvaizduokliui, kuris registruoja layouts: ["layout.tsx"]. Jis randamas tose pačiose vietose kaip ir layout.php, o šalia esantis pasirinktinis layout.data.php yra jo duomenų įkėliklis. Atvaizdavimo metu atvaizduokliui perduodama kind: "layout" ir atvaizduotas puslapio turinys kaip slot, taikant tokį patį the_content prioritetą kaip ir layout.php. Kataloge gali būti layout.php arba vienas atvaizduoklio maketas, bet ne abu; jei yra abu, aptikimo metu įvyksta klaida. Nepavykus maketui suaktyvinamas blockstudio/pages/layout_error, o puslapio turinys paliekamas be apvalkalo, kaip ir layout.php atveju.
Blokų redagavimo režimas
blockEditingMode savybė valdo, kaip galima redaguoti blokus redaktoriuje. Nustatykite numatytąją reikšmę puslapio lygmeniu faile page.json, o šablone kiekvienam elementui nustatykite kitą reikšmę:
{
"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>
| Reikšmė | Aprašymas |
|---|---|
"default" |
Visas redagavimas. Blokus galima pasirinkti, perkelti ir redaguoti |
"contentOnly" |
Galima redaguoti tik tekstą. Blokų tekstą galima keisti, bet nustatymai ir struktūra užrakinti |
"disabled" |
Redaguoti negalima. Blokai visiškai nereaguoja į veiksmus |
Atskiriems elementams taikomi HTML atributų pakeitimai bet kuriame elemente (<h1>, <p>, <div> ir kt.) arba elementuose <block>. Tėvinių konteinerių blokams, esantiems virš pakeistų elementų, automatiškai nustatoma contentOnly reikšmė, kad jų antriniai elementai liktų pasiekiami. Šis paveldėjimas kyla nuo pakeisto elemento iki puslapio šakninio elemento, todėl blockEditingMode reikia nustatyti tik tiems elementams, kuriuos norite padaryti redaguojamus.
Šablono užraktas
templateLock savybė valdo, kaip naudotojai gali redaguoti puslapį redaktoriuje:
| Reikšmė | Pridėti / pašalinti | Perkelti | Redaguoti turinį |
|---|---|---|---|
"all" |
Ne | Ne | Ne |
"insert" |
Ne | Taip | Taip |
"contentOnly" |
Ne | Ne | Taip |
false |
Taip | Taip | Taip |
Nustačius templateLock, Blockstudio per redaktoriaus UI išjungia galimybę atrakinti blokus.
Virtualieji maršrutai
Kai kurie dokumentai neturi susieto įrašo: iš duomenų sugeneruota komponento nuoroda,
katalogas ar paskyros sritis. Užregistruokite juos kaip virtualiuosius maršrutus,
o ne patys prijungdami 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(),
]
);
} );
Kelias nurodomas santykinai nuo svetainės pradžios. Nustačius prefix, maršrutas taip pat aptarnauja
visus po juo esančius kelius, o match gauna likusią jų dalį (maršruto atveju
ji yra tuščia eilutė) ir grąžina reikšmę, kurią gauna atvaizdavimo iškvietimas, arba
null, kad URL būtų perduotas WordPress, kuris tada, kaip įprasta, pateikia atsakymą 404. Atvaizdavimo iškvietimas išveda dokumentą arba grąžina jį kaip eilutę; title yra eilutė arba uždarymas, kuriam perduodama atitikties reikšmė.
Atitinkančiai užklausai Blockstudio neleidžia WordPress pažymėti jos kaip 404, o redirect_canonical – jos peradresuoti, išvalo pagrindinės užklausos nurodomą atskiro puslapio būseną, nustato būseną (pagal numatytuosius nustatymus status, 200) ir atvaizduoja template_redirect pirmenybės lygiu Virtual_Routes::PRIORITY. Tai įvyksta iškart po to, kai Blockstudio atidaro išvesties buferį ties Assets::BUFFER_PRIORITY, todėl paruoštame dokumente, kaip ir bet kuriame puslapyje, bus blokų ištekliai, sujungti UI ištekliai ir sukompiliuotas Tailwind; tai įvyksta prieš redirect_canonical, kurio pirmenybės lygis yra 10. Tvarkyklė, pati atvaizduojanti visą dokumentą, taip pat turi veikti po Assets::BUFFER_PRIORITY, antraip šis apdorojimas bus praleistas. Keliai, esantys urls (pagal numatytuosius nustatymus tai pats maršruto kelias, kai tai nėra prefiksinis maršrutas), įtraukiami į iš anksto sugeneruojamą statinį versiją, o Virtual_Routes::urls() pateikia juos kaip absoliučiuosius URL svetainės struktūrai. Virtual_Routes::match( $path ) išsprendžia kelią taip, kaip jį išspręstų užklausa.
Sinchronizavimo veikimas
Puslapių įrašai keičiami tik aiškiai nurodžius atlikti sinchronizavimo operaciją:
wp bs pages sync
Komanda aptinka visą šaltinių sąrašą, sukuria arba atnaujina pakeistus
įrašus, pašalina patvirtintus našlaičius, atnaujina kolekcijų maršrutus ir sukompiliuotą
templateFor konfigūraciją bei pateikia pakeitimų ataskaitą. Pridėkite --authoritative,
kad vietoj raktus turinčio redaktoriaus turinio išsaugojimo būtų pakeistas valdomas turinys, ir
--full, kad eiga būtų nurodyta kaip visiškas suderinimas, nepaisant išsaugotos
šaltinio tapatybės:
wp bs pages sync --authoritative --full
Įprastos naudotojo sąsajos, administravimo, AJAX, REST, cron ir bendrosios WP-CLI paleidimo užklausos neatlieka viso puslapių aptikimo, netikrina valdomo suderinimo įrašų sąrašo ir neįrašo puslapių įrašų. Jose naudojami jau sinchronizuoti WordPress įrašai ir kompaktiška kolekcijų bei įrašų tipų šablonų konfigūracija, išsaugota per paskutinę aiškią operaciją. Nauja instaliacija ar naujinimas gali vieną kartą peržiūrėti kolekcijų manifestus, kad atkurtų maršrutų metaduomenis; šis tik skaitymo režimu veikiantis paleidimas turinio nesinchronizuoja. Autentifikuotas, pasirinktinai naudojamas „Canvas“ atnaujinimo galinis taškas yra aiški autorystės API: „Canvas“ jį iškviečia vieną kartą atidarius darbo sritį, kad nauji arba pakeisti šaltiniai būtų matomi pradiniame sąraše. Tiesioginės veiksenos režimas pasiekia tą pačią ribą, kai aptinka puslapio šaltinio pakeitimą.
Blockstudio\Pages::init() dabar registruoja tik užklausos metu veikiančius kablius. Integracijos,
kurios anksčiau šiam metodui perduodavo argumentą force, dabar turi iškviesti
Blockstudio\Pages::reconcile() arba vietoj to paleisti wp bs pages sync.
Kad puslapis nebūtų perrašytas po rankinio redagavimo, faile page.json nustatykite "sync": false.
Nešiojamosios šaltinio vietos
Sinchronizuoti temos failai saugomi kaip su tema susietos vietos, o ne kaip absoliutūs diegimo keliai. Vaikinės ir pagrindinės temos failai išlaiko atskiras tapatybes, net jei jų santykiniai failų pavadinimai sutampa. Puslapių pagalbinės funkcijos vis tiek grąžina dabartinei užklausai išspręstas absoliučias template_path, content_path, layout_path ir directory reikšmes.
Taip CLI sinchronizavimas ir žiniatinklio užklausos gali naudoti skirtingas failų sistemos šaknis, pavyzdžiui, ribotoje priegloboje, nepažeidžiant Markdown atsakymų, išdėstymų, redaktoriaus Tailwind paieškos ar išankstinio generavimo šaltinio sekimo. Esami absoliutūs temų keliai iš naujo susiejami nuskaitant, jei temos katalogo pavadinimas nepasikeitė. Norint juos nuskaityti, nereikia sinchronizavimo, duomenų bazės perkėlimo ar metaduomenų įrašymo užklausos metu; kitas aiškiai paleistas sinchronizavimas išsaugos perkeliamas vietas.
Jei temos katalogas yra simbolinė nuoroda, pavyzdžiui, į kūrimo darbinį katalogą, išsaugomos tos pačios theme: vietos, nesvarbu, ar šaltinis nuskaitytas per simbolinę nuorodą, ar per jos paskirties vietą, ir jos susiejamos su sukonfigūruotu temos katalogu.
Failai, esantys už aktyviosios antrinės ir pagrindinės temos ribų, toliau palaikomi jų sukonfigūruotuose absoliučiuose keliuose, laikantis PHP open_basedir apribojimų. Jų negalima automatiškai perkelti: perkėlę išorinį šaltinį, atnaujinkite jo sukonfigūruotą kelią ir aiškiai paleiskite sinchronizavimą.
Įrašo laukų nuosavybė
postStatus nustato pradinę būseną. Vėlesni sinchronizavimai išsaugo esamas juodraščio, laukiančio patvirtinimo, privačias, paskelbtas ir suplanuotas būsenas, taip pat ir su --authoritative. Juodraštis nepaskelbiamas iš naujo vien todėl, kad jo faile nurodyta postStatus: "publish". Esama našlaičių atkūrimo elgsena nesikeičia: aiškiai paleistas sinchronizavimas atkuria į šiukšlinę perkeltą valdomą įrašą, jei jo šaltinis yra. Norėdami išvengti atkūrimo, užrakinkite puslapį arba išjunkite sinchronizavimą.
Failui ir toliau priklauso pavadinimas, nuorodos pavadinimas, įrašo tipas, pirminis įrašas ir sukonfigūruota meniu tvarka. Pakeitus juos sistemoje WordPress, šaltinio aprašas nepasikeičia. Kitas aiškiai paleistas sinchronizavimas vėl pritaiko faile nurodytas reikšmes, o pages.<name>.overwritten išvardija paveiktus laukus; CLI lentelės išvestyje pateikiamas įspėjimas. Taip pat taikomi WordPress vietiniai leidimai, įskaitant tuščią laukiančių įrašų nuorodos pavadinimą, kai sinchronizavimą vykdantis naudotojas negali jų paskelbti.
Integracijai, kuri aiškiai valdo kitokią būsenų politiką, naudokite blockstudio/pages/update_post_data. Raktus turintys blokai išsaugo redaktoriui priklausantį blokų turinį; raktai nekeičia to, kam priklauso įrašo pavadinimas ar nuorodos pavadinimas.
Kolekcijų puslapių kontroliniai atspaudai apima manifestą, įkėlimo programą, puslapio šaltinį, maketo failą, metaduomenis ir susijusius šaltinių kelius. Per kitą aiškiai nurodytą sinchronizavimą pritaikomi šių įvesčių pakeitimai.
Pašalinus kolekcijos šaltinį, Blockstudio pašalina sugeneruotą puslapį, kad seni kolekcijos puslapiai neliktų ištrynus šaltinio failą. Pagal numatytuosius nustatymus našlaičiais tapę kolekcijos puslapiai perkeliami į šiukšlinę. Naudokite blockstudio/pages/orphan_action, kad grąžintumėte trash, delete arba keep.
Naudotojo sąsajos užklausose Blockstudio užpildo puslapių registrą jau sinchronizuotais paskelbtais įrašais. Juodraštiniai ir privatūs puslapiai pasiekiami administravimo bei sinchronizavimo kontekstuose, tačiau naudotojo sąsajos pagalbinės funkcijos užpildo registrą tik paskelbtais puslapiais.
Diegimo suderinimas
Blockstudio\Pages::reconcile() yra PHP diegimo įvesties taškas. Jis aptinka
visą numatytų elementų sąrašą, palygina šaltinių ir sinchronizavimo modulio kontrolinius atspaudus
ir grąžina kompiuterio nuskaitomą ataskaitą:
$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',
],
],
]);
Ataskaitoje pateikiami discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, kiekvieno puslapio rezultatai, aptikimo klaidos ir deterministinis sourceIdentity.
Užrakinti puslapiai turi status: "locked" ir skaičiuojami atskirai nuo nepakeistų puslapių. removedPages pateikia kiekvieno pašalinto puslapio name, key, postId ir tikrąjį action (trash arba delete); išsaugoti ar jau į šiukšlinę perkelti įrašai neskaičiuojami kaip naujai pašalinti. CLI lentelės išvestyje taip pat nurodomi sukurti, atnaujinti, užrakinti, pašalinti ir turinį išsaugoję puslapiai su jų įrašų ID.
Atlikus analizę ir sujungimą pagal raktus, jei galutinis įrašas yra identiškas, neiškviečiamas wp_update_post(), nepakeičiamas post_modified, nesukuriama nauja versija ir nesuaktyvinamos įrašo atnaujinimo kabliukų funkcijos. Rezultatas yra unchanged. Jei šaltinio turinys skiriasi nuo redaktoriaus valdomo turinio blokuose su raktais, preserved: true nurodo šį sprendimą, o į bendrą preserved skaičių jis įtraukiamas. Naujas šaltinio kontrolinis kodas ir valdymo metaduomenys vis tiek įrašomi, todėl kitas sinchronizavimas, kai niekas nepasikeitė, neatlieka veiksmų. preserved yra papildoma žyma, o ne išskirtinė būsena: puslapis gali išsaugoti turinį blokuose su raktais ir kartu atnaujinti failui priklausantį pavadinimą arba pridėti kitą bloką.
authoritative: true gali panaikinti puslapio sinchronizavimo užraktą ir pakeičia failo apibrėžties turiniu,
o ne išsaugo raktus turintį redaktoriaus turinį. Įprastam aiškiai nurodytam sinchronizavimui palikite jį false.
plan_valid: false, full: true, broad: true, ankstesnės šaltinio tapatybės nebuvimas arba pasikeitęs sinchronizavimo modulio
kontrolinis atspaudas pažymi eigą kaip visišką suderinimą (ataskaitoje – fullReconciliation). Bet kuriuo atveju kiekvienos eigos metu lyginamas visas elementų sąrašas. Git pervadinimo įrašai yra tik tapatybės užuominos. Jie niekada nepakeičia viso sąrašo palyginimo.
Kai kontroliniai atspaudai sutampa, o vykdymo metu naudojami keliai nepasikeitė, įrašai ar jų meta duomenys neįrašomi ir atnaujinimo kabliai neiškviečiami. Kai nepakitęs šaltinis perkeliamas į naują leidimo katalogą, suderinimo metu atnaujinami tik išsaugoti šablono, turinio, maketo ir katalogo keliai; post_content ir įrašo pakeitimo laiko žyma neatnaujinami. Trūkstami valdomi puslapiai pašalinami tik užbaigus visą suderinimo eigą be aptikimo ar puslapių įrašymo klaidų.
Tiesioginis API suderinimas nepažymi diegimo kaip sėkmingo. Suaktyvinę ir patikrinę atitinkamą statinį artefaktą bei maršrutus, aiškiai išsaugokite grąžintą tapatybę:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync po sėkmingos eigos išsaugo grąžintą tapatybę.
Įprastas WP-CLI paleidimas tik užregistruoja išsaugotus kolekcijų įrašų tipus
ir perrašymo taisykles. Jis neaptinka ir nesinchronizuoja puslapių.
Įrašo ID prisegimas
Pagal numatytuosius nustatymus WordPress automatiškai priskiria įrašų ID. Jei puslapis ištrinamas ir sukuriamas iš naujo, jo ID pasikeičia, todėl sugenda išorinės nuorodos, pavyzdžiui, meniu ar kodu įrašytos nuorodos.
Naudokite postId, kad priskirtumėte puslapiui konkretų ID:
{
"name": "about",
"title": "About Us",
"postId": 42
}
Kuriant puslapį, Blockstudio perduoda ID į WordPress per import_id. Jei ID laisvas, WordPress jį tiksliai panaudoja. Jei ID jau priskirtas nesusijusiam įrašui, WordPress tyliai automatiškai priskiria naują ID.
Ieškodamas esamų puslapių, Blockstudio pirmiausia patikrina prisegtą ID, o tik tada metaduomenis arba trumpąjį vardą. Tai reiškia, kad ištrynus ir vėl sinchronizavus puslapį, jis atgauna tą patį ID.
Blokų suliejimas pagal raktus
Pagal numatytuosius nustatymus, pasikeitus šablono failui, Blockstudio pakeičia visą įrašo turinį nauju šablonu. Tai reiškia, kad redaktoriuje WordPress atlikti pakeitimai prarandami.
Pridėkite blokams atributą key, kad naudotojų pakeitimai būtų išsaugoti sinchronizuojant šabloną. Kai šablone yra raktus turinčių blokų, Blockstudio sujungia šablono pakeitimus su esamu įrašo turiniu, o ne jį pakeičia.
Raktų pridėjimas
Naudokite atributą key bet kuriame elemento HTML arba elemento <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"
/>
Raktai turi būti unikalūs visame šablone. Raktas apsaugo visą bloką ir visą jo turinį. Nereikia priskirti raktų atskiriems antriniams elementams raktą turinčiame tėviniame bloke. Sinchronizuojant šabloną raktus turinčius blokus galima perkelti į bet kurią vietą ar įdėjimo lygį, o jų naudotojų turinys vis tiek bus išsaugotas.
Raktai taip pat veikia su tinkintais Blockstudio blokais. key yra struktūriniai „Page Sync“ metaduomenys;
tinkintų laukų reikšmės lieka įprastais Blockstudio atributais.
Kai redaktorius pakeičia šiuos laukus, vėliau sinchronizuojant šabloną išsaugomos redaktoriaus
reikšmės ir kartu pritaikomi nepriklausomi šablono pakeitimai. Ankstesnėse versijose
sukurti puslapiai, kurių raktas yra tinkinto lauko duomenyse, per kitą sinchronizavimą
perkeliami automatiškai.
Kaip veikia suliejimas
Pasikeitus šablono failui ir vėl sinchronizavus puslapį:
| Blokas | Veikimas |
|---|---|
| Blokas su raktu | Naudotojo turinys ir Blockstudio lauko reikšmės išsaugomos. Pritaikomi šablonui priklausantys atributai ir struktūra. |
| Blokas be rakto | Visiškai pakeičiamas šablono versija (kaip ir nenaudojant raktų) |
Pavyzdžiai
Naudotojo pakeitimai raktus turinčiuose blokuose išsaugomi:
- Šablone apibrėžiama
<p key="intro">Default intro.</p> - Naudotojas redaktoriuje pakeičia pastraipą į „Pasirinktinis įžanginis tekstas.“
- Kūrėjas atnaujina šabloną, prideda naują bloką ir pakeičia maketą
- Sinchronizavus pastraipoje lieka „Pasirinktinis įžanginis tekstas.“, o pritaikomas naujas maketas
Šablono atributai vis tiek pritaikomi:
- Šablone yra viršelio blokas su
key="hero"ir atributuurl - Kūrėjas pakeičia viršelio atributą
urlį naują fono paveikslėlį - Sinchronizavus pritaikomas naujas fono paveikslėlis, o naudotojo turinio pakeitimai viršelio bloke išsaugomi
Ribiniai atvejai
| Scenarijus | Veikimas |
|---|---|
| Į šabloną įtrauktas naujas raktą turintis blokas | Atsiranda su numatytuoju šablono turiniu |
| Iš šablono pašalintas raktą turintis blokas | Ištrinamas iš įrašo |
| Pasikeičia bloko tipas (raktas tas pats) | Visiškai taikomas šablonas, turinys nesuliejamas |
| Besidubliuojantys raktai | Antrasis pasikartojantis atvejis laikomas bloku be rakto |
| Šablone nėra raktų | Visiškai pakeičiamas (kaip ir nenaudojant raktų) |
| Priverstinis sinchronizavimas | Visiškai pakeičiamas, raktai ignoruojami |
| Užrakintas įrašas | Visai nesinchronizuojamas |
Derinimas su redagavimo valdikliais
Raktai, templateLock ir blockEditingMode leidžia tiksliai valdyti, ką klientai gali ir ko negali daryti. Štai keli įprasti darbo eigos pavyzdžiai.
Visiškai užrakintas puslapis
Kūrėjas viską valdo. Puslapio maketas yra statinis, todėl klientai apskritai negali jo keisti. Tinka teisiniams puslapiams, paslaugų teikimo sąlygoms ir visiems puslapiams, kuriuos galima keisti tik programiškai.
{
"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>
Raktų nereikia. Šablonas yra vienintelis patikimas informacijos šaltinis. Kiekvieno sinchronizavimo metu visas puslapis perrašomas.
Užrakintas maketas su redaguojamu turiniu
Dažniausiai naudojamas būdas. Užrakinkite puslapio struktūrą, kad klientai negalėtų pridėti, pašalinti ar pertvarkyti blokų, bet leiskite jiems redaguoti tekstą konkrečiose vietose. Raktai užtikrina, kad jų pakeitimai išliks atnaujinus šabloną.
{
"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>
Klientas gali redaguoti pagrindinį pavadinimą, aprašymą ir įžangą apie funkcijas. Daugiau nieko. Mygtuko tekstą, URL ir viršelio fono vaizdą valdo kūrėjas. Kai kūrėjas atnaujina šabloną (e.g., prideda antrą mygtuką), pagal raktus susieti skyriai išsaugo kliento tekstą.
Tobulėjantis šablonas su išsaugotu turiniu
Puslapiams, kurie laikui bėgant plečiasi. Kūrėjas į šabloną įtraukia naujų skyrių, o kiekvieno sinchronizavimo metu pridedamas naujas turinys, nekeičiant to, ką klientas jau pritaikė.
<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>
Sinchronizavus atsiranda naujas atsiliepimų skyrius ir mygtukas. Kliento atlikti pavadinimo, įžangos ir paslaugų pakeitimai išlieka.
Vienkartinis pradinis šablonas
Sukurkite puslapį su pradine struktūra, tada visiškai perduokite jį klientui. Nustatykite sync į false, kad įprastai sinchronizuojant puslapis nebūtų kuriamas ar atnaujinamas, ir sukurkite jį vieną kartą naudodami Blockstudio\Pages::force_sync('blog'). Po to puslapis visiškai priklauso klientui.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
wp bs pages sync praleidžia šį puslapį, todėl force_sync() jį sukuria vieną kartą. Po to klientas gali laisvai pridėti, pašalinti ir perrikiuoti blokus. Šablono pakeitimai ignoruojami.
Blokų susiejimai
Alternatyva jungimui pagal raktus – naudoti WordPress branduolio Blokų susiejimai API, kad blokai būtų susieti su įrašo metaduomenimis. Tai nėra Blockstudio funkcija, o savoji WordPress API galimybė. Blockstudio tiesiog perduoda atributą metadata generuojamam bloko žymėjimui. Turinys saugomas įrašo metaduomenyse, o ne bloko žymėjime, todėl sinchronizuojant šabloną žymėjimą galima laisvai perrašyti: redaktorius skaito duomenis iš metaduomenų, o ne iš „innerHTML“.
Perduokite atributą metadata bet kuriam elementui HTML arba <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 raktai turi būti užregistruoti įjungus show_in_rest:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Raktai ir susiejimai
| Savybė | Raktai | Susiejimai |
|---|---|---|
| Kur saugomas turinys | Bloko žymėjime (post_content) |
Įrašo metaduomenyse (wp_postmeta) |
| Išlieka sinchronizuojant šabloną | Taip (sujungiama pagal raktą) | Taip (duomenys saugomi metaduomenyse) |
Galima pateikti užklausą naudojant WP_Query |
Ne | Taip (meta_query) |
| Prieinama REST API | Ne | Taip |
| Reikalinga registracija | Ne | Taip (register_post_meta) |
| Naudotojas gali perkelti blokus | Ne (šablonas iš naujo nustato struktūrą) | Ne (šablonas iš naujo nustato struktūrą) |
Abu būdus galima naudoti tame pačiame šablone. Naudokite raktus skyriams, kuriuose svarbi blokų struktūra (e.g., grupė su keliais antriniais elementais). Susiejimus naudokite atskiriems laukams, kai norite, kad duomenys būtų pasiekiami ir už blokų redaktoriaus ribų.
Įrašų tipų šablonai
Naudokite templateFor, kad nustatytumėte puslapį kaip numatytąjį įrašų tipo šabloną:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
Visi nauji to tipo įrašai bus kuriami su apibrėžta blokų struktūra.
Tinkinti keliai
Pagal numatytuosius nustatymus Blockstudio nuskaito get_template_directory() . '/pages'. Papildomų kelių pridėkite naudodami filtrą:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
Vykdymo metu failus iš kelių šakninių katalogų sujungiančios integracijos vietoj failų sistemos skenavimo gali naudoti loginį aptikimo šaltinį. Tada puslapių manifestai, maketai, įkėlikliai ir šaltinio šablonai nustatomi pagal loginį kelią, net jei pasirinkti failai yra skirtinguose šakniniuose kataloguose.
Filtrai ir veiksmai
Puslapių aptikimui, sinchronizavimui ir kolekcijų maršrutizavimui yra numatyti šie plėtimo taškai:
| Kabliukas | Tipas | Aprašas |
|---|---|---|
blockstudio/pages/paths |
Filtras | Prideda katalogus, kuriuose Blockstudio ieško puslapių šaltinių. |
blockstudio/pages/collection_post_type_args |
Filtras | Koreguoja register_post_type() argumentus kolekcijos CPT. |
blockstudio/pages/template_candidates |
Filtras | Koreguoja šablonų failų pavadinimus, į kuriuos atsižvelgiama ieškant puslapio šaltinio. |
blockstudio/pages/serve_markdown |
Filtras | Įjungia arba išjungia neapdorotus Markdown atsakymus. |
blockstudio/pages/orphan_action |
Filtras | Grąžina trash, delete arba keep tvarkant našlaičius. |
blockstudio/pages/docs_allowed_html |
Filtras | Koreguoja leidžiamus HTML sugeneruotam Markdown dokumentacijos turiniui. |
blockstudio/pages/allow_external_loader_path |
Filtras | Leidžia įkėlimo programos paths už kolekcijos šakninio katalogo ribų. |
blockstudio/pages/manifest_scan_interval |
Filtras | Nustato didžiausią 7.6.2 ankstesnio formato aprašo podėlio amžių, per kurį jo duomenys gali būti naudojami išsaugotai vykdymo konfigūracijai atnaujinimo metu užpildyti. |
blockstudio/pages/create_post_data |
Filtras | Pakeičia įrašo duomenis prieš sukuriant sinchronizuotą puslapį. |
blockstudio/pages/update_post_data |
Filtras | Pakeičia įrašo duomenis prieš atnaujinant sinchronizuotą puslapį. |
blockstudio/pages/sync_engine_inputs |
Filtras | Prideda analizatoriaus, susiejimo arba perkėlimo versiją, kuri turėtų vieną kartą sąmoningai išplėsti suderinimą. |
blockstudio/pages/post_created |
Veiksmas | Paleidžiamas sukūrus sinchronizuoto puslapio įrašą. |
blockstudio/pages/post_updated |
Veiksmas | Paleidžiamas atnaujinus sinchronizuoto puslapio įrašą. |
blockstudio/pages/synced |
Veiksmas | Paleidžiamas baigus sinchronizuoti puslapių registrą. |
blockstudio/pages/reconciled |
Veiksmas | Paleidžiamas aiškiai atlikus suderinimą; pateikiama mašininiu būdu nuskaitoma ataskaita. |
blockstudio/pages/renderers |
Veiksmas | Užregistruoja puslapių atvaizduoklius naudodamas Blockstudio\Page_Renderers::register(). Paleidžiamas kartą per užklausą. |
blockstudio/pages/rendered |
Veiksmas | Paleidžiamas atvaizdavus komponento puslapį; pateikiamas puslapis, jo HTML ir priklausomybės. |
blockstudio/pages/layout_error |
Veiksmas | Paleidžiamas, kai nepavyksta atvaizduoti išdėstymo; pateikiama klaida, išdėstymo kelias ir puslapis. |
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]);
Argumentų semantiką, ataskaitos laukus ir patikrintą šaltinio tapatybės ribą žr. Diegimo sutikrinimas.
Šablonams ir maketams prieinamos visuotinės pagalbinės funkcijos:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() grąžinami puslapių masyvai ir visuotinės pagalbinės funkcijos apima sinchronizuoto įrašo tapatybę, šaltinio ir šablono kelius, kolekcijos bei kelio metaduomenis, turinio tipą, sinchronizavimo politiką, įrašo tipą ir būseną, redagavimo politiką, tinkintus metaduomenis bei raktą permalink. Kolekcijos metaduomenys įkeliami iš paskutinio sėkmingo aiškaus sutikrinimo. Įprastų užklausų metu šie vykdymo duomenys atkuriami iš išsaugotos konfigūracijos ir sinchronizuotų įrašų metaduomenų, neskaitant puslapių šaltinio medžių. Pages klasė neturi atskiro nuolatinės nuorodos metodo.
Šablonų užrakinimas, blokų redagavimo režimai, jungimas pagal raktus ir klientui prieinamo redagavimo valdymas.