Siirry sisältöön

Sivut

Sivut ovat tiedostopohjaisia malleja, jotka synkronoidaan WordPress-tietokantaan julkaisuina. Synkronointi tehdään erikseen: suorita wp bs pages sync tai kutsu Sivut-API, kun haluat ottaa lähdemuutokset käyttöön. Käyttöliittymän lataaminen tai WordPress-hallinta ei koskaan etsi kaikkia sivuja eikä muuta sivujulkaisuja.

Sivun voi määrittää yksittäisenä page.json-kansiona, irrallisena Markdown-tiedostona tai kokoelmana, jolla on pages.json-manifesti. Kokoelmat sopivat dokumentaatioon, tietämyskantoihin, aloitussivukirjastoihin ja muihin sisäkkäisten sivujen kokonaisuuksiin, jotka halutaan luoda tiedostoista.

page.json

JSON-määritetylle sivulle lisätään page.json-asetustiedosto:

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

Ominaisuudet

Ominaisuus Tyyppi Oletus Kuvaus
name string pakollinen Sivun yksilöllinen tunniste
title string Nimen perusteella automaattisesti Sivun otsikko
slug string Sama kuin nimi Sivun URL-polkutunnus
path string "." Looginen polku kokoelman sisällä
order integer 0 Synkronoidun julkaisun valikkojärjestys
postType string "page" WordPress-julkaisun tyyppi
postStatus string "draft" Uusien julkaisujen tila (publish, draft, pending, private)
postId integer – Kiinnitä sivu tiettyyn WordPress-julkaisutunnukseen
blockEditingMode string – Lohkoeditorin tila: "default", "contentOnly" tai "disabled"
templateLock string|false "all" Lukitustila: "all", "insert", "contentOnly" tai false
templateFor string|null null Aseta julkaisutyypin oletusmalliksi
sync boolean true Määrittää, voiko tavallinen eksplisiittinen täsmäytys luoda tai päivittää julkaisun
render string|object|false – Hahmonna sivu rekisteröidyllä sivuhahmontimella (katso Komponenttisivut)

Tunnistetut avaimet ovat page.json-määritysten, frontmatterin ja lataajan merkintöjen yhteydessä seuraavat: blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock ja title. Kaikki yllä luettelemattomat avaimet tallennetaan sivun meta-taulukkoon.

Sisältölähteet

Sivumääritys päättää, minkä WordPress-julkaisun pitäisi olla olemassa. Sisältölähde määrittää, mikä lohkomerkintä kirjoitetaan kyseiseen julkaisuun.

Kun sivukansiossa on page.json, Blockstudio etsii viereistä lähdetiedostoa seuraavassa järjestyksessä:

Tiedosto Käyttö
index.php HTML-tyylinen lohkomerkintä luetaan sellaisenaan (PHP-koodia ei suoriteta)
index.blade.php Blade-mallin sisältö
index.twig Twig-mallin sisältö
index.md Markdown-sisältö

page.json voi sisältää myös rivinsisäisen markdown– tai html-sisällön viereisen tiedoston sijaan:

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

Kokoelmissa on kaksi muuta lähdetilaa:

  • Markdown tiedostoa löydetty suoraan kokoelmapuusta.
  • Lataajan merkinnät palautettu kohteesta loader.php.

Lataajan merkinnöissä voi käyttää markdown, html tai content yhdessä arvon contentType kanssa. Ne voivat viitata myös paikalliseen file– tai template-tiedostoon. Tiedosto- ja mallilähteiden tyyppi päätellään tiedostopäätteen perusteella, ellei contentType-arvoa määritetä erikseen.

Tuetut contentType-arvot ovat php, blade, twig, markdown ja html. Markdown muunnetaan ensin muotoon HTML ja jäsennetään sitten natiiveiksi WordPress-lohkoiksi. Lähteet PHP, Blade, Twig ja HTML käsitellään tavallisen Blockstudio-sivujäsentimen kautta.

Core-lohkojen luokat

class elementissä HTML, joka on yhdistetty core-lohkoon, muuttuu lohkon arvoksi className. Eksplisiittinen core-lohkon tunniste voi käyttää suoraan arvoa className. Molemmat muodot säilyttävät lohkon tallennetun kääreen luokat sekä tunnisteen WordPress tuottamat luokat:

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

Jos molemmat ominaisuudet ovat käytössä, className on etusijalla. Tämä muunnos koskee vain core-lohkoja: mukautetun lohkon määritys säilyttää class-kenttänsä ennallaan. Painikkeen tyyliluokat, kuten is-style-outline, kuuluvat painikkeen kääreeseen, eivät sen linkkiin.

Suorita wp bs pages sync, jotta jäsenninkorjaukset otetaan käyttöön aiemmin synkronoiduilla sivuilla. Jäsentimen päivitykset tunnistetaan seuraavassa nimenomaisessa synkronoinnissa ilman lähdetiedoston muokkausta. Lukitut sivut ja sivut, joilla on sync: false, säilyttävät normaalit suojauksensa; käyttöliittymää edeltävät pyynnöt eivät käynnistä tätä synkronointia.

Sarjoitetut WordPress-lohkot

Sivu- ja kuviolähteet voivat sisältää myös sarjoitettuja lohkoja, jotka on kopioitu tunnisteen WordPress koodieditorista:

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

Kun lähde sisältää <!-- wp:... -->-lohkon erottimen, Blockstudio käyttää koko lähteeseen WordPress-järjestelmän omaa lohkop jäsentäjää. Attribuutit, sisäkkäiset lohkot, dynaamiset lohkot, kuten Query Loop, ja Blockstudio-lohkot säilyttävät serialisoidun rakenteensa. Lohkokommenttien ulkopuolinen HTML pysyy natiivina vapaamuotoisena HTML-sisältönä; sitä ei muunnetta lisälohkoiksi. Älä sekoita tämän muodon kanssa Blockstudio-järjestelmän HTML-lohkomerkintöjä ja oleta, että ne muunnetaan. Tavalliset HTML-kommentit eivät valitse serialisoitujen lohkojen tilaa.

Markdown-sivut

Käytä Markdown-muotoa, kun haluat tekstin olevan tiedostoissa mutta muuttuvan synkronoinnin jälkeen muokattavaksi WordPress-lohkojen sisällöksi. Markdown-lähde muunnetaan synkronoinnin aikana lohkomerkinnäksi. Synkronoitu julkaisu tallentaa lohkot, ei raakaa Markdown-sisältöä.

Markdown-muotoa voi käyttää kolmella tavalla:

Lähde Etutiedot pakolliset? Huomautukset
Erillinen pages/example/index.md Kyllä Etutiedot määrittävät sivun tunnisteen.
page.json ja index.md Ei page.json määrittää sivun ja Markdown sisältöä varten.
Markdown kokoelman sisällä Ei Kokoelma päättelee name– ja path-arvot tiedoston sijainnista.

Erillinen index.md ilman etutietoja ohitetaan, koska Blockstudio-lähteellä ei ole synkronointiin tarvittavaa sivutunnistetta. Kokoelman Markdown-lähteet eivät tarvitse etutietoja, koska kokoelman manifesti ja tiedostopolku määrittävät tunnisteen.

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

# About

This Markdown content is synced as native WordPress blocks.

Voit yhdistää myös page.json– ja index.md-muodot. Tällöin page.json määrittää sivun ja index.md sisältää sisällön. Tiedoston index.md-etutiedot ohittavat vastaavat page.json-arvot.

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.

Kokoelman Markdown-muodossa tiedostopolusta tulee looginen sivupolku, ellei etutiedoissa määritetä toisin:

Tiedosto Oletuspolku
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

Tuntemattomat etutietojen avaimet säilytetään sivun meta-taulukossa. Näin sivulle voi liittää esimerkiksi arvoja section tai description ja lukea ne kohteesta PHP API.

Markdown jäsennetään muodossa GitHub Flavored Markdown. Raaka HTML on sallittu, turvattomat linkit poistetaan ja otsikoille annetaan pysyvä tunnus, jos sitä ei ole määritetty. Sisäkkäiset YAML-etutiedot edellyttävät mukana toimitettua YAML-jäsennintä.

Raaka Markdown

Markdown-tiedostolähteet voivat tarjota alkuperäisen lähteen Markdown-muodossa ulkoisille työkaluille ja dokumentaation lukijoille. Rivinsisäisellä Markdown-sisällöllä ei ole lähdetiedostoa, joten se synkronoidaan lohkoiksi mutta siitä ei palauteta raakaa .md-sisältöä.

Pyydä sivua lisäämällä loppuun .md, esimerkiksi https://example.com/docs/reference.md. Voit myös lähettää Accept: text/markdown-otsakkeen tavalliseen sivun URL-osoitteeseen:

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

Etutiedot poistetaan vastauksesta. Onnistuneissa raaoissa Markdown-vastauksissa lähetetään otsakkeet Content-Type: text/markdown ja X-Robots-Tag: noindex sekä kanoninen Link-otsake takaisin HTML-sivulle. Puuttuvat .md-reitit palauttavat oikean 404-virheen.

Neuvottelu toimii staattisen esirenderöinnin kanssa: pyyntöä, jonka Accept-otsake sisältää arvon text/markdown, ei koskaan vastata esirenderöintivarastosta tai varhaisen tarjoilun drop-inistä, joten se päätyy kohteeseen WordPress ja Markdown-käsittelijään. Esirenderöidyt HTML-vastaukset, sellaisen sivun HTML, joka neuvottelee myös Markdown-arvosta, sekä Markdown-vastaukset, jotka toimitetaan kohteen Accept kautta, lähettävät arvon Vary: Accept, joten Vary huomioivat välimuistit pitävät nämä erillään. CDN, joka avaimoi välimuistinsa pelkän URL-arvon perusteella, tarvitsee oman sääntönsä välimuistin ohittamiseen tällaisissa pyynnöissä. Pages::negotiates_markdown( $post_id ) kertoo, vastaako sivu Markdown-pyyntöihin.

Kokoelman Markdown säilyttää saman URL-rakenteen raakaa Markdown-sisältöä varten:

Sivun URL Raaka Markdown URL
/docs/ /docs.md
/docs/getting-started/ /docs/getting-started.md
/docs/guide/install/ /docs/guide/install.md

Poista raakojen Markdown-vastausten käyttö suodattimella blockstudio/pages/serve_markdown:

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

.md URL, joka ei johda kohteeseen Markdown perustuvaan sivuun, palauttaa arvon 404 vain, jos polku kuuluu sivukokoelmaan. Kaikkien kokoelmien ulkopuolella Blockstudio jättää pyynnön WordPress-kohteen ja muiden lisäosien käsiteltäväksi.

Komponenttisivut

Komponenttisivu hahmonnetaan sivuhahmontimella lohkoihin tallentamisen sijaan. Blockstudio ei sisällä hahmonninta. Teema tai lisäosa rekisteröi sellaisen käsittelemiään merkintätiedostoja varten, esimerkiksi page.tsx-tiedostojen React-hahmontimen, ja Blockstudio kutsuu sitä sivun, WordPress-julkaisun ja hahmonnetun paikkasisällön kanssa.

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 määritetään eksplisiittisesti. Hakemisto, jossa on index.php ja page.tsx mutta ei render, pysyy tavallisena sivuna, joten hahmontimen lisääminen ei hahmonna olemassa olevaa sivua kahdesti. Muodot ovat seuraavat:

Arvo Merkitys
"page.tsx" Vain merkintä, ei tietolataajaa
{ "entry": "page.tsx", "data": "data.php" } Merkintä ja tietolataaja
{ "entry": "page.tsx", "renderer": "react" } Merkintä, jossa on eksplisiittinen hahmontimen tunnus
false Ei hahmonninta, vaikka kokoelman oletusarvossa nimettäisiin sellainen

Polut ratkaistaan sivuhakemiston perusteella tai lataajamerkintöjen osalta kokoelman juuren perusteella. Niiden on pysyttävä etsintälähteen sisällä, ellei blockstudio/pages/allow_external_loader_path salli niitä. Jos renderer puuttuu, käytetään hahmonninta, joka käsittelee merkinnän tiedostopäätettä. render, joka viittaa puuttuvaan merkintä- tai datatiedostoon, tuntemattomaan hahmontimeen tai tiedostopäätteeseen, jota mikään hahmonnin ei käsittele, aiheuttaa etsintävirheen ja estää täsmäytyksen ennen kuin mitään poistetaan.

Mitä synkronointi tallentaa

Synkronointi tallentaa yhden blockstudio/page-lohkon. Kun sivuhakemistossa on myös index.*-lähde, se jäsennetään kuten mikä tahansa sivulähde, ja siitä tulee lohkon sisäkkäisten lohkojen sisältö eli sen paikkasisältö:

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

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

Pidä WordPress-sisältö, kuten lyhytkoodit, paikkasisällössä. Jos lähde sisältää vain yhden lyhytkoodin, kuten [download_checkout], se tallennetaan core/shortcode-lohkoksi, joten sen ympärille ei lisätä kappaletta. Se säilyy muodossa post_content, joten has_shortcode()-tarkistukset löytävät sen, avaimelliset paikkalohkot yhdistyvät editorin muutoksiin kuten sisäkkäiset avainlohkoissa tapahtuvat muutokset, ja do_shortcode laajentaa lyhytkoodit kerran niiden tavallisessa the_content-prioriteetissa sen jälkeen, kun hahmonnin on kehystänyt ne.

Hahmonnusmääritys tallennetaan julkaisun mukana siirrettävinä theme:-polkuina. Sivun sormenjälki kattaa määrityksen, ei merkinnän tai tietolataajan tavujonoa: tiedoston page.tsx tai data.php muokkaaminen ei muuta julkaisua, vaan muutokset näkyvät kävijöille hahmonnuksen ja staattisen esihahmonnusgraafin kautta. Graafi kirjaa merkinnän, tietolataajan ja kaikki tiedostot, jotka hahmonnin ilmoittaa.

Hahmontimen rekisteröinti

Rekisteröi hahmontimet toiminnolla blockstudio/pages/renderers. Se suoritetaan kerran pyyntöä kohden ennen ensimmäistä etsintää tai hahmonnusta, joten wp bs pages sync ja käyttöliittymän pyynnöt näkevät saman rekisterin.

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

Hahmontimen tunnukset ovat pienaakkosilla. Tiedostopääte tai asettelun nimi voi kuulua vain yhdelle hahmontimelle, ja layout.php pysyy Blockstudion omana asetteluna. Kutsuttavalle välitetään yksi pyyntö:

Avain Arvo
kind page tai layout, kun kyseessä on hahmontimen asettelu
renderer Hahmontimen tunnus
entry Merkinnän absoluuttinen polku
data Tietolataajan absoluuttinen polku tai null
page Sivun kanoniset tiedot, mukaan lukien meta
post_id WordPress-julkaisun tunnus
slot Hahmonnettu paikkasisältö tai asettelun sivusisältö
context frontend, rest, feed tai cli

Se palauttaa HTMLn, hahmonnuksen lukemat tiedostot ja valinnaiset resurssit:

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 tulee pyynnön tyypistä, ei koskaan kävijältä, joten renderöijä ei voi rikkoa kirjautuneiden ja anonyymien tavujen yhdenmukaisuutta lukemalla sitä. Jos renderöijä epäonnistuu, se heittää virheen: sivua ei renderöidä tyhjällä rungolla. REST-editorin esikatselussa lohko näyttää virheen sen sijaan ilmoituksena. Onnistuneen renderöinnin jälkeen blockstudio/pages/rendered-toiminto saa sivun, HTML ja sen riippuvuudet.

assets luettelee sivun tarvitsemat skripti- ja tyylitiedostot. Ne käsitellään lohko-omaisuuksien tavoin (*.inline.*-käytäntö, ES-moduulit, pienennys ja ?ver), ja sivu tulostaa ne kerran saman puskurin kautta, jolla lohko-omaisuudet tulostetaan, joten ne kulkevat mukana esirenderöidyssä sivussa. Ominaisuus voi asettaa version korvaamaan sen ?ver-arvon. Renderöijän ulkopuolinen koodi voi käyttää samaa kanavaa Blockstudio\Assets::register_owner()-toiminnon kautta, joka palauttaa tulostettavan merkkikommentin.

Muokkain

Muokkaimessa blockstudio/page näyttää palvelimella renderöidyn sivun esikatselun, jossa paikka on sisäisinä lohkoina, jotka noudattavat sivun templateLock-määritystä. Lohkoa ei voi lisätä, monistaa tai sisällyttää toiseen lohkoon.

Sivukokoelmat

Kokoelma on kansio, jossa on pages.json-manifesti. Se kokoaa useita sivulähteitä saman kokoelmatunnisteen alle, soveltaa oletusarvoja, tukee sisäkkäisiä polkuja ja voi rekisteröidä oman julkaisutyypin automaattisesti.

Koodi
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"
  }
}
Ominaisuus Tyyppi Kuvaus
collection / slug / name string Kokoelman polkutunnus. collection on selkein muoto, ja siitä muodostetaan julkinen URL-perusta.
title string Ihmisluettava kokoelman otsikko.
postType string Luotaville sivuille käytettävä sisältötyyppi. Oletusarvo on page. Jos sitä ei ole olemassa, Blockstudio rekisteröi sen.
postTypeArgs object register_post_type()-funktiolle välitettävät argumentit, kun Blockstudio rekisteröi kokoelman sisältötyypin.
defaults object Oletussivun ominaisuudet, joita sovelletaan jokaiseen kokoelman sivuun. Oletus-render koskee sivua vain, kun sen hakemistossa on sitä vastaava merkintä.
scope string collection (oletus) tai site. Katso Sivustokokoelmat.
meta object Kokoelman mukautetut metatiedot. Myös tuntemattomat manifestiavaimet tallennetaan kohteeseen meta.

Kokoelman sivupolut ovat loogisia polkuja. Polulla path: "guide/install" varustettu sivu synkronoidaan kohteen guide alisivuksi, ja guide synkronoidaan kokoelman juuren alisivuksi, jos kyseiset yläsivut ovat olemassa.

Jos hierarkkisessa kokoelmassa on sisäkkäinen sivu mutta väliin jäävää ylätason lähdettä ei ole, Blockstudio luo kyseiselle polulle tyhjän säilösivun, jotta WordPress-hierarkia pysyy täydellisenä. Ei-hierarkkiset julkaisutyypit, jotka eivät tue ylätason sivuja ominaisuudella page-attributes, eivät luo tyhjiä säilöjä. Niiden reititys perustuu tallennettuun kokoelmapolkuun, joten sisäkkäiset polut, kuten guide/install ja setup/install, voivat olla rinnakkain, vaikka molempien lopussa on install.

Kokoelmien julkaisutyypit ja URL-osoitteet

Määritä kokoelman manifestissa postType, jotta kaikki kokoelman sivut synkronoidaan kyseiseen julkaisutyypiin. Samaa arvoa ei tarvitse toistaa kohdassa defaults. Yksittäiset sivut voivat silti ohittaa arvon postType etutiedoissa tai kohdassa page.json.

Jos julkaisutyypiä ei ole olemassa, Blockstudio rekisteröi sen asetuksilla show_in_rest: true, sivumaisella muokkausnäkymällä ja kokoelman tunnisteella julkisena URL-peruspolkuna. Rekisteröinnin argumentit voi ohittaa kohdassa postTypeArgs. Kokoelman julkaisutyypin uudelleenkirjoitussäännöt päivitetään automaattisesti, kun rekisteröity julkaisutyppi tai sen uudelleenkirjoitusargumentit muuttuvat, joten asetusta WordPress ei tarvitse tallentaa uudelleen.

Kokoelman URL-osoitteissa käytetään kokoelman tunnistetta ja kunkin sivun loogista path-polkua:

Lähdepolku Julkinen URL
path: "." /docs/
path: "getting-started" /docs/getting-started/
path: "guide/install" /docs/guide/install/

Tämä URL malli toimii sekä hierarkkisten että ei-hierarkkisten kokoelmapostaustyyppien kanssa. Blockstudio uudelleenohjaa myös kaksinkertaiset URL-osoitteet, kuten /docs/docs/ tai /docs/docs/getting-started/, kanoniseen osoitteeseen URL.

Kokoelmasivut tarjoavat raakamuotoisen Markdown:n samoissa URL-osoitteissa (katso Raaka Markdown).

Jos vaihdat kokoelman postType: "page"-tyypistä mukautetuksi postaustyypiksi, Blockstudio siirtää jo synkronoidut kokoelmapostaukset paikoilleen, kun niiden tallennettu sivutunniste vastaa. Näin postausten tunnukset, metatiedot ja nykyinen sisältö säilyvät, eikä vanhalla tyypillä luoda kaksoiskappaleita. Vanhentuneet kokoelmapostaukset siivotaan kaikista postausten tiloista blockstudio/pages/orphan_action-suodattimen mukaisesti.

Sivustokokoelmat

Manifesti, jossa on "scope": "site", ryhmittelee kaikki sen alla olevat sivut muuttamatta niitä kokoelman sivuiksi. Käytä sitä sivuston sivupuun juuressa yhteisten oletusarvojen asettamiseen ja sivuston sivujen luettelointiin toiminnolla 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" }
  }
}

Sivustokokoelman sivujen tunnisteet pysyvät täsmälleen samoina kuin ilman manifestia. Sen lisääminen olemassa olevaan puuhun ei siis päivitä sisältörivejä eikä luo tai poista mitään:

  • Avaimet pysyvät yleisinä: Pages::get_page( 'home' ) ja tallennetut sivuavaimet vastaavat edelleen toisiaan.
  • URL-osoitteet pysyvät sivujen WordPress-osoitteina. Kokoelman uudelleenkirjoitussääntöjä, pysyvän linkin suodatinta tai kaksinkertaisen URL-uudelleenohjausta ei käytetä, eikä tyhjiä säilösivuja luoda.
  • Loogiset polut, polkutunnukset, yläsivut ja lähteen tunnisteet ovat samat kuin erillisillä sivuilla, ja asettelut määräytyvät lähimmän esi-isän mukaan.
  • Sisäkkäiset pages.json-manifestit säilyttävät omat kokoelmansa, eikä niiden alipuuta sisällytetä sivustokokoelmaan.
  • Oletusarvot koskevat sivuja yksitellen: oletus-render koskee vain sivuja, joiden hakemistossa on sitä vastaava merkintä. Siksi lyhytkoodien ja Markdown-sivujen lähteet säilyvät ennallaan.

Kokoelmien lataajat

Kokoelmiin voi sisällyttää luotetun paikallisen loader.php-lataajan. Käytä sitä, kun kokoelmasivut tulevat toisesta paikallisesta lähteestä, kuten ulkoisesta dokumentaatiokansiosta, paketista tai luodusta manifestista.

Lataaja suoritetaan sivujen nimenomaisen etsinnän ja synkronoinnin aikana. Sen tulee olla deterministinen ja paikallinen. Vältä etäsisällön hakemista lähteestä loader.php, sillä se tekisi käyttöönoton synkronoinnista riippuvaisen kyseisestä palvelusta.

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

Lataaja voi palauttaa taulukon, jonka avaimet ovat pages, meta ja paths:

Avain Kuvaus
pages Sivutaulukoiden luettelo. Jokainen sivu tukee samoja tunnistettuja avaimia kuin page.json– ja Markdown-etumäärittelyt.
meta Metatiedot, jotka yhdistetään jokaisen lataajan luoman sivun meta-taulukkoon.
paths Kokoelman osana etsittävät paikalliset lisähakemistot. Merkinnät voivat olla merkkijonoja tai polkuobjekteja.
render renderöintimääritys jokaiselle kohteesta paths löydetylle Markdown-sivulle.

Lyhennysmerkintänä lataaja voi palauttaa suoraan sivutaulukoiden luettelon.

Lataajan sivumerkinnöissä sisältö voidaan antaa seuraavilla tavoilla:

Muoto Kuvaus
markdown Sisäinen Markdown-sisältö.
html Sisäinen HTML-sisältö.
content + contentType Yleinen sisäinen sisältö. Kohteen contentType on oltava joko markdown tai html.
file Paikallinen tiedostolähde. Tyyppi päätellään tiedostopäätteestä, ellei contentType ole määritetty.
template Kohteen file vaihtoehtoinen nimi.

Lataajan tiedostoviittaukset voivat osoittaa lähteisiin PHP, Blade, Twig, Markdown tai HTML. Suhteelliset polut ratkaistaan kokoelman juuresta. Absoluuttiset polut ja kokoelman juuren ulkopuoliset polut ovat sallittuja vain, jos blockstudio/pages/allow_external_loader_path-suodatin sallii ne.

Lataajan sivujen oletusarvo on generated: true. Kun luotu lataajasivu poistuu lataajan tulosteesta, Blockstudio käsittelee synkronoitua postausta orpona seuraavassa synkronoinnissa ja siivoaa sen blockstudio/pages/orphan_action-suodattimen mukaisesti.

Kohdassa paths luetellut hakemistot käydään läpi kuten tavalliset kokoelmakansiot. Ne voivat sisältää Markdown-tiedostoja tai page.json-kansioita. Jos nämä polut ovat kokoelman juuren ulkopuolella, niihin sovelletaan samaa ulkoisten polkujen suodatinta.

Käytä merkkijonomerkintää, kun ulkoisen hakemiston tulee säilyttää omat loogiset polkunsa. Käytä objektimerkintää, kun hakemisto tulee liittää kokoelmaan polkuliitteen alle:

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

Tällä asetuksella cli-docs/index.md muuttuu kokoelmassa poluksi path: "cli" ja cli-docs/getting-started.md poluksi path: "cli/getting-started". Etuliitteet estävät myös luotujen sivunimien törmäykset, joten kukin liitetty hakemisto voi sisältää esimerkiksi index.md tai getting-started.md. Aseta polkuobjektin preserveNames arvoksi true, jos haluat säilyttää nimenomaiset name-arvot, jotka tulevat lähteistä page.json tai Markdown-etutiedoista.

Polkuobjektin ominaisuudet:

Ominaisuus Tyyppi Kuvaus
path string Etsittävä paikallinen hakemisto. Suhteelliset polut ratkaistaan kokoelman juuresta alkaen.
prefix string Valinnainen loogisen polun etuliite kokoelman sisällä.
preserveNames boolean Säilytä sivujen nimenomaiset nimet sen sijaan, että nimet muodostettaisiin etuliitteen sisältävästä polusta. Oletusarvo on false, kun prefix on asetettu.
meta object Metatiedot, jotka yhdistetään jokaiseen tästä polusta löydettyyn sivuun. Sivutason metatiedot ohittavat päällekkäiset avaimet.
render string|object Renderöintimääritys tämän polun Markdown-sivuille, joka ohittaa lataajan määrityksen render.

Kohteen Markdown renderöinti komponentin kautta

Kun käytössä on render, lataajan löytämät Markdown-sivut renderöidään sivun renderöijän kautta sen sijaan, että ne tallennettaisiin lohkoina:

PHP
<?php

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

Ne pysyvät Markdown-sivuina: sisältötyyppi, sisältöpolku, .md-vastaukset ja etumäärittelyt eivät muutu. Synkronointi tallentaa yhden blockstudio/page-lohkon, jonka sisäinen HTML on muunnettu Markdown ja kokoelman sisältöä puhdistettaessa puhdistettu, jäsennettyjen lohkojen sijaan, jotta post_content säilyttää dokumentin tekstin. Renderöijä saa kyseisen HTML-arvon paikkana ja voi lukea lähteen kohteesta page.content_path. Suhteelliset polut ratkaistaan kokoelman juuresta alkaen; ulkoisten polkujen suodatinta käytetään samalla tavalla kuin poluissa. Sivua, jonka etumäärittelyssä asetetaan oma render tai render: false, ei sisällytetä.

Asetteluja

layout.php-tiedosto käärii tiedostopohjaisen sivun käyttöliittymässä tapahtuvan renderöinnin. Se ei korvaa synkronoitua post_content-sisältöä, joka tallennetaan kohteeseen WordPress, eikä se kääri editorin piirtoaluetta. Asettelu suoritetaan vain yksittäisen sivun käyttöliittymäpyynnöissä.

Kokoelmissa voit kääriä kokoelman jokaisen käyttöliittymäsivun sijoittamalla layout.php-tiedoston kohteen pages.json viereen:

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() tulostaa sivun rungon, jonka WordPress normaalisti renderöisi kohteen the_content kautta. Jos asettelu ei tulosta kohdetta blockstudio_page_content(), sivun sisältö piilotetaan tarkoituksella.

Asetteluissa voi käyttää sivun aputoimintoja:

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

Myös sisäkkäiset sivut, jotka eivät kuulu kokoelmaan, voivat periä lähimmän ylemmän tason layout.php-asettelun kohteen pages puussa. Kokoelmasivuilla kokoelman juuriasettelu tallennetaan jokaiseen synkronoituun postaukseen ja sitä seurataan osana sivun sormenjälkeä, joten asettelumuutokset tulevat käyttöön seuraavassa synkronoinnissa.

Renderöijäasettelut

Asettelu voi olla myös renderöijämerkintä, kuten layout.tsx renderöijälle, joka rekisteröi kohteen layouts: ["layout.tsx"]. Se etsitään samoista paikoista kuin layout.php, ja sen vieressä oleva valinnainen layout.data.php toimii sen datalataajana. Renderöijä saa renderöinnin aikana kind: "layout"-arvon ja renderöidyn sivusisällön arvona slot samalla the_content-prioriteetilla kuin layout.php. Hakemistossa voi olla joko layout.php tai yksi renderöijäasettelu, ei molempia; molempien sisältävä hakemisto aiheuttaa etsintävirheen. Asettelun virhe käynnistää tapahtuman blockstudio/pages/layout_error ja jättää sivun sisällön käärimättä, kuten layout.php-tapauksessa.

Lohkojen muokkaustila

blockEditingMode-ominaisuus määrittää, miten lohkoja voi muokata editorissa. Aseta sivutason oletusarvo kohteessa page.json ja ohita se elementtikohtaisesti mallipohjassa:

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>
Arvo Kuvaus
"default" Täysi muokkaus. Lohkoja voi valita, siirtää ja muokata.
"contentOnly" Vain tekstin muokkaus. Lohkojen tekstiä voi muokata, mutta asetukset ja rakenne on lukittu.
"disabled" Ei muokkausta. Lohkot eivät ole lainkaan vuorovaikutteisia.

Elementtikohtaiset ohitukset määritetään HTML-attribuutteina mille tahansa elementille (<h1>, <p>, <div> jne.) tai <block>-elementeille. Ohitettujen elementtien yläpuoliset säilölohkot asetetaan automaattisesti arvoon contentOnly, jotta niiden lapset pysyvät käytettävissä. Tämä periytyminen etenee ohitetusta elementistä sivun juureen, joten sinun tarvitsee asettaa blockEditingMode vain niille elementeille, joita haluat muokattaviksi.

Mallipohjan lukitus

templateLock-ominaisuus määrittää, miten käyttäjät voivat muokata sivua editorissa:

Arvo Lisää/poista Siirrä Muokkaa sisältöä
"all" Ei Ei Ei
"insert" Ei Kyllä Kyllä
"contentOnly" Ei Ei Kyllä
false Kyllä Kyllä Kyllä

Kun templateLock on asetettu, Blockstudio estää lohkojen lukituksen poistamisen editorin UI-toiminnolla.

Virtuaaliset reitit

Joidenkin dokumenttien taustalla ei ole postausta: ne voivat olla datasta luotu komponenttiviite, luettelo tai käyttäjätilanäkymä. Rekisteröi ne virtuaalisiksi reiteiksi sen sijaan, että kytkisit itse toimintoon 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(),
        ]
    );
} );

Polku on suhteessa sivuston etusivuun. Kun prefix on käytössä, reitti palvelee myös kaikkia sen alapuolisia polkuja. match saa loppuosan (tyhjän merkkijonon itse reitille) ja palauttaa arvon, jonka renderöintikutsu saa, tai arvon null, jolloin URL jää kohteen WordPress käsiteltäväksi, joka vastaa sitten tavalliseen tapaan kohteeseen 404. Renderöintikutsu tulostaa dokumentin tai palauttaa sen merkkijonona; title on merkkijono tai sulkeuma, joka saa osuman arvon.

Täsmäävällä pyynnöllä Blockstudio estää WordPress-toimintoa merkitsemästä sitä 404-tilaksi ja redirect_canonical-toimintoa uudelleenohjaamasta sitä, tyhjentää pääkyselyn ilmoittaman yksittäisen kohteen tilan, lähettää tilakoodin (oletuksena status, 200) ja renderöi prioriteetilla Virtual_Routes::PRIORITY template_redirect. Tämä tapahtuu heti, kun Blockstudion tulospuskuri avautuu kohdassa Assets::BUFFER_PRIORITY, joten valmiiseen dokumenttiin tulevat lohkojen resurssit, paketoidut UI-resurssit ja käännetyt Tailwind-tiedostot kuten mille tahansa sivulle, ennen prioriteetin 10 kohtaa redirect_canonical. Kokonaisen dokumentin itse renderöivän käsittelijän on toimittava myös kohdan Assets::BUFFER_PRIORITY jälkeen, tai käsittely jää väliin. Kohdan urls polut (oletuksena itse reitin polku, jos kyseessä ei ole etuliitereitti) lisätään staattisiin esirenderöityihin koontiversioihin, ja Virtual_Routes::urls() palauttaa ne absoluuttisina URL-osoitteina sivustokarttaa varten. Virtual_Routes::match( $path ) ratkaisee polun samalla tavalla kuin pyyntö.

Synkronoinnin toiminta

Sivupostaukset muuttuvat vain nimenomaisen synkronointitoiminnon kautta:

Shell
wp bs pages sync

Komento etsii kaikki lähteet, luo tai päivittää muuttuneet postaukset, poistaa vahvistetut orvot, päivittää kokoelmareitityksen ja käännetyn templateFor-määrityksen sekä raportoi muutokset. Lisää --authoritative, jos haluat korvata hallitun sisällön säilyttämättä avainkohtaisesti editorin sisältöä, ja --full, jos haluat merkitä suorituksen täsmäytysraportissa aina täydeksi lähteen tallennetusta tunnisteesta riippumatta:

Shell
wp bs pages sync --authoritative --full

Tavalliset käyttöliittymän, ylläpidon, AJAXin, REST-, cron- ja yleiset WP-CLI-käynnistyspyynnöt eivät etsi kaikkia sivuja, hae hallittujen sisältöjen täsmäytysluetteloa eivätkä kirjoita sivupostauksia. Ne käyttävät jo synkronoituja WordPress-postauksia sekä edellisessä nimenomaisessa toiminnossa tallennettua tiivistä kokoelma- ja postaustyyppimallipohjien määritystä. Uusi asennus tai päivitys voi lukea kokoelman manifestit kerran reitityksen metatietojen palauttamiseksi; tämä vain lukutilassa tapahtuva käynnistys ei synkronoi sisältöä. Tunnistettu ja erikseen käyttöön otettava Canvas-päivitysreitti on nimenomainen sisällöntuotannon API: Canvas kutsuu sitä kerran työtilan avautuessa, jotta uudet tai muuttuneet lähteet näkyvät alkuluettelossa. Live-tila kutsuu saman toiminnon, kun se havaitsee sivulähteen muutoksen.

Blockstudio\Pages::init() rekisteröi nyt vain pyyntöaikaisia koukkuja. Integraatioiden, jotka aiemmin välittivät menetelmälle argumentin force, on kutsuttava kohdetta Blockstudio\Pages::reconcile() tai suoritettava kohde wp bs pages sync.

Estä sivun ylikirjoitus manuaalisten muutosten jälkeen asettamalla "sync": false kohteessa page.json.

Siirrettävät lähdesijainnit

Synkronoidut teematiedostot tallennetaan teemaan suhteutettuina sijainteina absoluuttisten asennuspolkujen sijaan. Lapsiteemojen ja pääteemojen tiedostoilla on erilliset tunnisteet, vaikka niiden suhteelliset tiedostonimet olisivat samat. Sivuapufunktiot palauttavat edelleen nykyistä pyyntöä varten ratkaistut absoluuttiset template_path-, content_path-, layout_path– ja directory-arvot.

Näin CLI synkronointi ja verkkopyynnöt voivat käyttää eri tiedostojärjestelmän juuria esimerkiksi eristetyssä hosting-ympäristössä rikkomatta Markdown vastauksia, asetteluja, editorin Tailwind skannausta tai esirenderöinnin lähdeseurantaa. Olemassa olevien absoluuttisten teemahakemistopolkujen juuret määritetään uudelleen luettaessa, jos teeman hakemiston nimi ei ole muuttunut. Niiden lukeminen ei edellytä synkronointia, tietokantasiirtoa eikä metatietojen kirjoittamista pyynnön aikana; seuraava erikseen käynnistetty synkronointi tallentaa siirrettävät sijainnit.

Symbolisena linkkinä toimivan teemahakemiston (esimerkiksi kehitystyöpuuhun osoittavan) theme:-sijainnit ovat samat riippumatta siitä, luettiinko lähde linkin vai sen kohteen kautta, ja ne ratkaistaan määritettyyn teemahakemistoon.

Aktiivisten ali- ja yläteemojen ulkopuolisia tiedostoja tuetaan edelleen niiden määritetyissä absoluuttisissa sijainneissa PHPopen_basedir-rajoitusten mukaisesti. Niiden sijaintia ei päivitetä automaattisesti: kun ulkoinen lähde siirretään, päivitä sen määritetty polku ja suorita synkronointi erikseen.

Artikkelikenttien omistajuus

postStatus asettaa alkutilan. Seuraavat synkronoinnit säilyttävät olemassa olevat luonnos-, odottaa hyväksyntää-, yksityinen-, julkaistu- ja ajastettu-tilat myös --authoritative-tilassa. Luonnosta ei julkaista uudelleen vain siksi, että sen tiedostossa lukee postStatus: "publish". Orpojen palautuksen nykyinen toiminta säilyy ennallaan: erikseen käynnistetty synkronointi palauttaa roskakoriin siirretyn hallitun artikkelin, jos sen lähde on olemassa. Lukitse sivu tai poista synkronointi käytöstä estääksesi palautuksen.

Tiedosto omistaa edelleen otsikon, polkutunnuksen, artikkelityypin, ylätason ja määritetyn valikkojärjestyksen. Näiden muokkaaminen kohdassa WordPress ei muuta lähdemääritelmää. Seuraava erikseen käynnistetty synkronointi ottaa tiedoston arvot uudelleen käyttöön ja nimeää muuttuneet kentät kohdassa pages.<name>.overwritten sekä näyttää varoituksen kohdan CLI taulukossa. WordPressn natiivioikeudet ovat edelleen voimassa, myös tyhjä polkutunnus odottavilla artikkeleilla silloin, kun synkronoinnin suorittava käyttäjä ei voi julkaista niitä.

Käytä blockstudio/pages/update_post_data integraatioon, joka omistaa nimenomaisesti erilaisen tilakäytännön. Avaimelliset lohkot säilyttävät editorin hallitseman lohkosisällön; avaimet eivät muuta artikkelin otsikon tai polkutunnuksen omistajuutta.

Kokoelmasivujen sormenjälki kattaa manifestin, lataajan, sivulähteen, asettelutiedoston, metatiedot ja niihin liittyvät lähdepolut. Seuraava nimenomainen synkronointi ottaa näihin syötteisiin tehdyt muutokset käyttöön.

Kun kokoelman lähde poistetaan, Blockstudio poistaa luodun sivun, jotta vanhat kokoelmasivut eivät jää näkyviin lähdetiedoston poistamisen jälkeen. Oletusarvoisesti orvoiksi jääneet kokoelmasivut siirretään roskakoriin. Käytä kohdetta blockstudio/pages/orphan_action palauttaaksesi arvon trash, delete tai keep.

Käyttöliittymäpyynnöissä Blockstudio lataa sivurekisterin jo synkronoiduista julkaistuista postauksista. Luonnokset ja yksityiset sivut ovat käytettävissä ylläpito- ja synkronointikonteksteissa, mutta käyttöliittymän aputoiminnot lataavat vain julkaistut sivut.

Käyttöönoton täsmäytys

Blockstudio\Pages::reconcile() on PHP-käyttöönoton aloituspiste. Se etsii koko halutun sisältöluettelon, vertaa lähteen ja synkronointimoottorin sormenjälkiä sekä palauttaa koneellisesti luettavan raportin:

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

Raportti sisältää discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, sivukohtaiset tulokset, etsintävirheet sekä deterministisen sourceIdentity.

Lukituilla sivuilla on status: "locked", ja ne lasketaan erikseen muuttumattomista sivuista. removedPages luettelee jokaisen poistetun sivun name, key, postId ja todellisen action (trash tai delete); säilytettyjä tai jo roskakoriin siirrettyjä artikkeleita ei lasketa uusiksi poistoiksi. CLI-taulukon tulosteessa mainitaan myös luodut, päivitetyt, lukitut, poistetut ja sisältönsä säilyttäneet sivut niiden artikkelitunnuksineen.

Jäsennyksen ja avaimellisen yhdistämisen jälkeen identtinen lopullinen artikkeli ei kutsu funktiota wp_update_post(), muuta arvoa post_modified, luo versiota eikä käynnistä artikkelin päivityskoukkuja. Sen tulos on unchanged. Kun lähteen sisältö poikkeaa editorin hallitsemasta avaimellisesta sisällöstä, preserved: true ilmaisee tämän päätöksen, ja ylätason preserved-laskuri sisältää sen. Uusi lähteen sormenjälki ja hallitut metatiedot tallennetaan silti, joten seuraava muuttumaton synkronointi ei tee mitään. preserved on lisälippu, ei yksinomainen tila: sivu voi säilyttää avaimellisen sisällön ja samalla päivittää tiedoston hallitseman otsikon tai lisätä toisen lohkon.

authoritative: true voi vapauttaa Page Sync -lukituksen ja korvaa sisällön tiedostomäärityksellä säilyttämättä avainkohtaisesti editorin sisältöä. Jätä se arvoon false tavallista nimenomaista synkronointia varten. plan_valid: false, full: true, broad: true, puuttuva aiemman lähteen tunniste tai muuttunut synkronointimoottorin sormenjälki merkitsee suorituksen täydelliseksi täsmäytykseksi (raportin arvo fullReconciliation). Koko sisältöluettelo verrataan joka suorituksessa joka tapauksessa. Git uudelleennimeämistietueet ovat vain tunnistevihjeitä. Ne eivät koskaan korvaa koko luettelon vertailua.

Jos sormenjäljet ovat samat ja ajonaikaiset polut ennallaan, postausta tai postauksen metatietoja ei kirjoiteta eikä päivityskoukkuja suoriteta. Kun ennallaan oleva lähde siirtyy uuteen julkaistuun hakemistoon, täsmäytys päivittää vain tallennetut mallipohjan, sisällön, asettelun ja hakemiston polut; se ei päivitä kohdetta post_content eikä postauksen muokkausaikaleimaa. Puuttuvat hallitut sivut poistetaan vasta, kun koko täsmäytys on valmis ilman etsintä- tai sivun kirjoitusvirheitä.

Suora API-täsmäytys ei merkitse käyttöönottoa onnistuneeksi. Kun vastaava staattinen artefakti ja reitit on aktivoitu ja tarkistettu, tallenna palautettu tunniste nimenomaisesti:

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

wp bs pages sync tallentaa palautetun tunnisteen onnistuneen suorituksen jälkeen. Tavallinen WP-CLI-käynnistys rekisteröi vain tallennetut kokoelmien postaustyypit ja uudelleenkirjoitussäännöt. Se ei etsi eikä synkronoi sivuja.

Postauksen tunnuksen kiinnitys

Oletusarvoisesti WordPress määrittää postausten tunnukset automaattisesti. Jos sivu poistetaan ja luodaan uudelleen, tunnus muuttuu ja ulkoiset viittaukset, kuten valikot tai kovakoodatut linkit, rikkoutuvat.

Kiinnitä sivu tiettyyn tunnukseen kohteella postId:

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

Sivua luodessaan Blockstudio välittää tunnuksen kohteelle WordPress kohteen import_id kautta. Jos tunnus on vapaa, WordPress käyttää sitä täsmälleen. Jos tunnus on jo muun kuin siihen liittyvän postauksen käytössä, WordPress määrittää hiljaisesti uuden tunnuksen automaattisesti.

Olemassa olevia sivuja etsiessään Blockstudio tarkistaa ensin kiinnitetyn tunnuksen ja vasta sitten metatiedot tai lyhyen tunnuksen. Kun sivu siis poistetaan ja synkronoidaan uudelleen, se saa saman tunnuksen takaisin.

Avaimellisten lohkojen yhdistäminen

Oletusarvoisesti Blockstudio korvaa mallipohjatiedoston muuttuessa postauksen koko sisällön uudella mallipohjalla. Tällöin kaikki WordPress-editorissa tehdyt muutokset menetetään.

Lisää lohkoihin key-attribuutti, jotta käyttäjien muutokset säilyvät mallipohjan synkronointien välillä. Kun mallipohja sisältää avaimellisia lohkoja, Blockstudio yhdistää mallipohjan muutokset postauksen nykyiseen sisältöön sen sijaan, että korvaisi sen.

Avainten lisääminen

Käytä key-attribuuttia missä tahansa HTML-elementissä tai <block>-elementissä:

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

Avainten on oltava yksilöllisiä koko mallipohjassa. Avain suojaa koko lohkon ja kaiken sen sisällön. Avaimellisen ylälohkon yksittäisille lapsille ei tarvitse määrittää omia avaimia. Avaimellisia lohkoja voi siirtää mihin tahansa kohtaan tai sisennystasolle mallipohjapäivitysten välillä, ja niiden käyttäjäsisältö säilyy.

Avaimet toimivat samalla tavalla myös mukautetuissa Blockstudio-lohkoissa. key on rakenteellista Page Sync -metatietoa; mukautettujen kenttien arvot ovat edelleen tavallisia Blockstudio-attribuutteja. Kun editorissa näitä kenttiä muutetaan, myöhempi mallipohjan synkronointi säilyttää editorin arvot ja ottaa samalla käyttöön mallipohjan erilliset muutokset. Vanhemmilla versioilla luotujen sivujen avain, joka on mukautetun kentän datan sisällä, siirretään automaattisesti seuraavassa synkronoinnissa.

Yhdistämisen toiminta

Kun mallipohjatiedosto muuttuu ja sivu synkronoidaan uudelleen:

Lohko Toiminta
Avaimellinen lohko Käyttäjän sisältö ja kentän Blockstudio-arvot säilytetään. Mallipohjan omat attribuutit ja rakenne otetaan käyttöön.
Avaimeton lohko Korvataan kokonaan mallipohjan versiolla (kuten ilman avaimia).

Esimerkkejä

Käyttäjän muutokset säilyvät avaimellisissa lohkoissa:

  1. Mallipohjassa määritetään <p key="intro">Default intro.</p>
  2. Käyttäjä muokkaa editorissa kappaleen tekstiksi ”Mukautettu esittelyteksti.”
  3. Kehittäjä päivittää mallipohjan, lisää uuden lohkon ja muuttaa asettelua.
  4. Synkronoinnin jälkeen kappaleessa säilyy teksti ”Mukautettu esittelyteksti.” ja uusi asettelu otetaan käyttöön.

Mallipohjan attribuutit otetaan silti käyttöön:

  1. Mallipohjassa on kansilohko, jossa on key="hero" ja url-attribuutti.
  2. Kehittäjä vaihtaa kannen url-attribuutin uudeksi taustakuvaksi.
  3. Synkronoinnin jälkeen uusi taustakuva otetaan käyttöön, mutta käyttäjän sisältömuutokset kannen sisällä säilyvät.

Erikoistapaukset

Tilanne Toiminta
Mallipohjaan lisätään uusi avaimellinen lohko Näkyviin tulee mallipohjan oletussisällöllä
Avaimellinen lohko poistetaan mallipohjasta Poistetaan postauksesta
Lohkon tyyppi muuttuu (sama avain) Mallipohja korvaa lohkon kokonaan, sisältöä ei yhdistetä
Päällekkäiset avaimet Toista esiintymää käsitellään avaimettomana
Mallipohjassa ei ole avaimia Koko sisältö korvataan (kuten ilman avaimia)
Pakotettu synkronointi Koko sisältö korvataan, avaimet ohitetaan
Lukittu postaus Ei synkronointia

Yhdistäminen muokkausasetuksiin

Avaimet, templateLock ja blockEditingMode antavat tarkat keinot hallita sitä, mitä asiakkaat voivat tehdä. Tässä on yleisiä työnkulkumalleja.

Täysin lukittu sivu

Kehittäjä hallitsee kaikkea. Sivu on staattinen asettelu, johon asiakkaat eivät voi koskea lainkaan. Sopii lakisivuille, käyttöehdoille ja muille sivuille, joiden pitäisi muuttua vain koodin kautta.

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>

Avaimia ei tarvita. Mallipohja on ainoa totuuden lähde. Jokainen synkronointi korvaa koko sivun.

Lukittu asettelu, muokattava sisältö

Yleisin malli. Lukitse sivun rakenne, jotta asiakkaat eivät voi lisätä, poistaa tai järjestellä lohkoja, mutta anna heidän muokata tekstiä tietyissä kohdissa. Avaimet varmistavat, että muutokset säilyvät mallipohjapäivitysten yhteydessä.

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>

Asiakas voi muokata otsikkoa, kuvausta ja ominaisuuksien esittelyä. Ei mitään muuta. Painikkeen teksti, URL ja kansikuva ovat kehittäjän hallinnassa. Kun kehittäjä päivittää mallipohjaa (e.g., lisää toisen painikkeen), avainrakenteiset osiot säilyttävät asiakkaan tekstin.

Kehittyvä mallipohja, jonka sisältö säilyy

Sivuille, jotka kasvavat ajan myötä. Kehittäjä lisää mallipohjaan uusia osioita, ja jokainen synkronointi lisää uuden sisällön koskematta asiakkaan jo mukauttamaan sisältöön.

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>

Uusi suositusosio ja painike ilmestyvät synkronoinnin yhteydessä. Asiakkaan otsikkoon, esittelyyn ja palveluihin tekemät muutokset säilyvät ennallaan.

Kertaluonteinen runko

Luo sivu aloitusrakenteella ja luovuta se sitten kokonaan asiakkaalle. Aseta sync arvoon false, jotta normaali synkronointi ei koskaan luo tai päivitä sivua, ja luo se kerran komennolla Blockstudio\Pages::force_sync('blog'). Sen jälkeen sivu on kokonaan asiakkaan hallinnassa.

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

wp bs pages sync ohittaa tämän sivun, joten force_sync() luo sen kerran. Sen jälkeen asiakas voi lisätä, poistaa ja järjestellä lohkoja vapaasti. Mallipohjan muutokset ohitetaan.

Lohkosidonnat

Vaihtoehto avainrakenteiselle yhdistämiselle on käyttää WordPress coren Lohkosidontoja API lohkojen yhdistämiseen artikkelin metatietoihin. Tämä ei ole Blockstudio-ominaisuus, vaan natiivi WordPress API. Blockstudio välittää metadata-attribuutin luodulle lohkomerkinnälle. Sisältö sijaitsee artikkelin metatiedoissa lohkomerkinnän sijaan, joten mallipohjan synkronointi voi korvata merkinnän vapaasti, koska editori lukee tiedot metatiedoista eikä innerHTML:stä.

Välitä metadata-attribuutti mille tahansa HTML- tai <block>-elementille:

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-avaimet on rekisteröitävä niin, että show_in_rest on käytössä:

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

Avaimet ja sidonnat

Ominaisuus Avaimet Sidonnat
Sisällön tallennuspaikka Lohkomerkintä (post_content) Artikkelin metatiedot (wp_postmeta)
Säilyy mallipohjan synkronoinnissa Kyllä (yhdistetään avaimen perusteella) Kyllä (tiedot ovat metatiedoissa)
Kyseltävissä WP_Query:n kautta Ei Kyllä (meta_query)
Käytettävissä REST API:ssa Ei Kyllä
Edellyttää rekisteröintiä Ei Kyllä (register_post_meta)
Käyttäjä voi siirtää lohkoja Ei (mallipohja asettaa rakenteen uudelleen) Ei (mallipohja asettaa rakenteen uudelleen)

Molempia tapoja voi käyttää samassa mallipohjassa. Käytä avaimia osioissa, joissa lohkorakenne on tärkeä (e.g. esimerkiksi ryhmä, jossa on useita lapsielementtejä). Käytä sidontoja yksittäisille kentille, kun haluat tietojen olevan käytettävissä myös lohkoeditorin ulkopuolella.

Artikkelityypin mallipohjat

Määritä templateFor-toiminnolla sivu artikkelityypin oletusmallipohjaksi:

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

Kaikki uudet kyseisen tyypin artikkelit alkavat määritellyllä lohkorakenteella.

Mukautetut polut

Oletusarvoisesti Blockstudio etsii kohteesta get_template_directory() . '/pages'. Lisää polkuja suodattimella:

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

Suorituksenaikaiset integraatiot, jotka kokoavat tiedostoja useista juurihakemistoista, voivat korvata tiedostojärjestelmän haun loogisella etsintälähteellä. Sivumanifestit, asettelut, lataajat ja lähdemallipohjat ratkaistaan tällöin loogisen polun perusteella, vaikka valitut tiedostot sijaitsevat eri juurihakemistoissa.

Suodattimet ja toiminnot

Sivujen etsintä, synkronointi ja kokoelmien reititys tarjoavat seuraavat laajennuskohdat:

Koukku Tyyppi Kuvaus
blockstudio/pages/paths Suodatin Lisää hakemistoja, joista Blockstudio etsii sivujen lähteitä.
blockstudio/pages/collection_post_type_args Suodatin Muokkaa kokoelman CPT:n register_post_type()-argumentteja.
blockstudio/pages/template_candidates Suodatin Muokkaa sivun lähteelle huomioitavia mallipohjien tiedostonimiä.
blockstudio/pages/serve_markdown Suodatin Ota käyttöön tai poista käytöstä käsittelemättömät Markdown-vastaukset.
blockstudio/pages/orphan_action Suodatin Palauta orpojen siivousta varten trash, delete tai keep.
blockstudio/pages/docs_allowed_html Suodatin Muokkaa luodun Markdown-dokumentaatiosisällön sallittuja HTML-arvoja.
blockstudio/pages/allow_external_loader_path Suodatin Salli lataajan paths kokoelman juurihakemiston ulkopuolella.
blockstudio/pages/manifest_scan_interval Suodatin Aseta vanhan, 7.6.2-edeltävän manifestivälimuistin enimmäisikä; välimuisti voi alustaa tallennetun suoritusajan määrityksen päivityksen yhteydessä.
blockstudio/pages/create_post_data Suodatin Muokkaa artikkelin tietoja ennen synkronoidun sivun luomista.
blockstudio/pages/update_post_data Suodatin Muokkaa artikkelin tietoja ennen synkronoidun sivun päivittämistä.
blockstudio/pages/sync_engine_inputs Suodatin Lisää jäsentimen, määrityksen tai siirron version, jonka on tarkoituksella laajennettava täsmäytystä kerran.
blockstudio/pages/post_created Toiminto Suoritetaan synkronoidun sivuartikkelin luomisen jälkeen.
blockstudio/pages/post_updated Toiminto Suoritetaan synkronoidun sivuartikkelin päivittämisen jälkeen.
blockstudio/pages/synced Toiminto Suoritetaan sivurekisterin synkronoinnin päätyttyä.
blockstudio/pages/reconciled Toiminto Suoritetaan erikseen käynnistetyn täsmäytyksen jälkeen koneellisesti luettavan raportin kanssa.
blockstudio/pages/renderers Toiminto Rekisteröi sivujen renderöijät kohteeseen Blockstudio\Page_Renderers::register(). Suoritetaan kerran pyyntöä kohden.
blockstudio/pages/rendered Toiminto Suoritetaan komponenttisivun renderöinnin jälkeen sivun, sen HTML-tietojen ja riippuvuuksien kanssa.
blockstudio/pages/layout_error Toiminto Suoritetaan, kun asettelua ei voida renderöidä; mukana ovat virhe, asettelun polku ja sivu.

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

Katso Käyttöönoton sovitus, josta löydät argumenttien semantiikan, raporttikentät ja varmennetun lähdeidentiteetin rajauksen.

Yleisiä aputoimintoja on käytettävissä mallipohjille ja asetteluille:

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()– ja Blockstudio\Pages::children()-toimintojen sekä yleisten aputoimintojen palauttamat sivutaulukot sisältävät synkronoidun artikkelin tunnisteen, lähde- ja mallipohjapolut, kokoelman ja polun metatiedot, sisältötyypin, synkronointikäytännön, artikkelityypin ja tilan, muokkauskäytännön, mukautetut metatiedot sekä permalink-avaimen. Kokoelman metatiedot ladataan viimeisimmästä onnistuneesta nimenomaisesta sovituksesta. Tavallisissa pyynnöissä nämä suorituksenaikaiset tiedot muodostetaan uudelleen pysyvistä määrityksistä ja synkronoitujen artikkelien metatiedoista lukematta sivulähdehakemistoja. Pages-luokka ei tarjoa erillistä kestolinkkimenetelmää.

Tiedostopohjaisten sivujen rakentaminen

Mallipohjien lukitseminen, lohkojen muokkaustilat, avainrakenteinen yhdistäminen ja asiakkaiden muokattavissa olevien asioiden hallinta.