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:
{
"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:
{
"name": "intro",
"title": "Intro",
"markdown": "# Intro\n\nThis page is generated from inline markdown."
}
{
"name": "notice",
"title": "Notice",
"html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}
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:
<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:
<!-- 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.
---
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.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
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:
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:
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.
pages/legal-notice/
page.json
page.tsx
data.php
{
"name": "legal-notice",
"title": "Legal Notice",
"slug": "legal-notice",
"postStatus": "publish",
"render": { "entry": "page.tsx", "data": "data.php" }
}
render 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ö:
<!-- 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.
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:
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.
pages/
docs/
pages.json
layout.php
index.md
guide/
install/
index.md
reference/
page.json
index.md
loader.php
{
"collection": "docs",
"title": "Documentation",
"postType": "bs_docs",
"postTypeArgs": {
"label": "Docs",
"rewrite": {
"slug": "docs"
},
"supports": ["title", "editor", "page-attributes"]
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
| 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' ).
{
"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-
renderkoskee 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
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:
'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
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 $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:
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:
{
"name": "about",
"title": "About Us",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
| 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:
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:
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:
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:
$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:
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:
{
"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ä:
<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:
- Mallipohjassa määritetään
<p key="intro">Default intro.</p> - Käyttäjä muokkaa editorissa kappaleen tekstiksi ”Mukautettu esittelyteksti.”
- Kehittäjä päivittää mallipohjan, lisää uuden lohkon ja muuttaa asettelua.
- Synkronoinnin jälkeen kappaleessa säilyy teksti ”Mukautettu esittelyteksti.” ja uusi asettelu otetaan käyttöön.
Mallipohjan attribuutit otetaan silti käyttöön:
- Mallipohjassa on kansilohko, jossa on
key="hero"jaurl-attribuutti. - Kehittäjä vaihtaa kannen
url-attribuutin uudeksi taustakuvaksi. - 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.
{
"name": "terms",
"title": "Terms of Service",
"templateLock": "all"
}
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>
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ä.
{
"name": "landing",
"title": "Landing Page",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h1 blockEditingMode="contentOnly">Edit This Title</h1>
<p blockEditingMode="contentOnly">Edit this description.</p>
</block>
<div key="features">
<h2>Features</h2>
<p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
</block>
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.
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<div key="testimonials">
<h2>Testimonials</h2>
<p>What our clients say.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
</block>
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.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<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:
<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ä:
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:
{
"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:
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
// 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:
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.