Pereiti prie turinio

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:

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:

JSON
{
  "name": "intro",
  "title": "Intro",
  "markdown": "# Intro\n\nThis page is generated from inline markdown."
}
JSON
{
  "name": "notice",
  "title": "Notice",
  "html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}

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:

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

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

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

JSON
{
  "name": "docs-reference",
  "title": "Reference",
  "path": "reference",
  "sync": true
}
Markdown
---
title: API Reference
order: 20
---

# Reference

This page uses `page.json` with Markdown content.

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:

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

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

Text
pages/legal-notice/
  page.json
  page.tsx
  data.php
JSON
{
  "name": "legal-notice",
  "title": "Legal Notice",
  "slug": "legal-notice",
  "postStatus": "publish",
  "render": { "entry": "page.tsx", "data": "data.php" }
}

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

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

PHP
add_action(
	'blockstudio/pages/renderers',
	static function (): void {
		Blockstudio\Page_Renderers::register(
			'react',
			array(
				'extensions' => array( 'tsx' ),
				'layouts'    => array( 'layout.tsx' ),
				'render'     => 'my_theme_render_page',
			)
		);
	}
);

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:

PHP
function my_theme_render_page( array $request ): array {
	return array(
		'html'         => '<main>...</main>',
		'dependencies' => array( '/abs/path/to/a/file/the/render/read.tsx' ),
		'assets'       => array( array( 'path' => '/abs/path/to/page.js' ) ),
	);
}

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

Kodas
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
    loader.php
JSON
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "postTypeArgs": {
    "label": "Docs",
    "rewrite": {
      "slug": "docs"
    },
    "supports": ["title", "editor", "page-attributes"]
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}
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' ).

JSON
{
  "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.json aprašai išlaiko savo rinkinius, o jų poaibiai neįtraukiami į svetainės rinkinį.
  • Numatyti nustatymai taikomi kiekvienam puslapiui atskirai: numatytoji render taikoma 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
<?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:

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

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

JSON
{
  "name": "about",
  "title": "About Us",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>
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:

PHP
add_action( 'init', function () {
    Blockstudio\Virtual_Routes::register(
        'components',
        function ( $component, string $rest ) {
            get_header();
            echo my_component_page( $component );
            get_footer();
        },
        [
            'prefix' => true,
            'match'  => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
            'title'  => fn ( $component ) => my_component_title( $component ),
            'urls'   => fn () => my_component_paths(),
        ]
    );
} );

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

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

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

PHP
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
  'renames' => [
    [
      'from' => 'pages/old/index.php',
      'to' => 'pages/new/index.php',
    ],
  ],
]);

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

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

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

HTML
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>

<div key="features">
  <p>First feature.</p>
  <p>Second feature.</p>
</div>

<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h2>Hero Title</h2>
  <p>Hero description.</p>
</block>

<block
  name="acme/testimonial"
  key="featured-quote"
  quote="Default quote"
/>

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:

  1. Šablone apibrėžiama <p key="intro">Default intro.</p>
  2. Naudotojas redaktoriuje pakeičia pastraipą į „Pasirinktinis įžanginis tekstas.“
  3. Kūrėjas atnaujina šabloną, prideda naują bloką ir pakeičia maketą
  4. Sinchronizavus pastraipoje lieka „Pasirinktinis įžanginis tekstas.“, o pritaikomas naujas maketas

Šablono atributai vis tiek pritaikomi:

  1. Šablone yra viršelio blokas su key="hero" ir atributu url
  2. Kūrėjas pakeičia viršelio atributą url į naują fono paveikslėlį
  3. 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.

JSON
{
  "name": "terms",
  "title": "Terms of Service",
  "templateLock": "all"
}
HTML
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>

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

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Title</h1>
  <p blockEditingMode="contentOnly">Edit this description.</p>
</block>

<div key="features">
  <h2>Features</h2>
  <p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">Contact Us</block>
</block>

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

HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
<div key="testimonials">
  <h2>Testimonials</h2>
  <p>What our clients say.</p>
</div>
<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
</block>

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.

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

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

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

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

Meta raktai turi būti užregistruoti įjungus show_in_rest:

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

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

PHP
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

PHP
// Get all registered pages.
$pages = Blockstudio\Pages::pages();

// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');

// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');

// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');

// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');

// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');

// Get a specific page.
$page = Blockstudio\Pages::get_page('about');

// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');

// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');

// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();

// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
]);

// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);

// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');

// Unlock a page.
Blockstudio\Pages::unlock('about');

// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
  'extensions' => ['tsx'],
  'layouts' => ['layout.tsx'],
  'render' => 'my_theme_render_page',
]);

// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');

// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);

Argumentų semantiką, ataskaitos laukus ir patikrintą šaltinio tapatybės ribą žr. Diegimo sutikrinimas.

Šablonams ir maketams prieinamos visuotinės pagalbinės funkcijos:

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

Puslapių kūrimas iš failų

Šablonų užrakinimas, blokų redagavimo režimai, jungimas pagal raktus ir klientui prieinamo redagavimo valdymas.