Strani
Strani so predloge na podlagi datotek, ki se sinhronizirajo z zbirko podatkov WordPress kot objave.
Sinhronizacija je izrecna: zaženite wp bs pages sync ali pokličite Pages API, ko želite uveljaviti spremembe vira. Ob nalaganju vmesnika za obiskovalce ali skrbniškega vmesnika WordPress se celotno odkrivanje strani ne izvede in objave strani se ne spreminjajo.
Strani lahko določite v eni sami mapi page.json, kot samostojne Markdown ali kot zbirko z manifestom pages.json. Zbirke so uporabne za dokumentacijo, baze znanja, knjižnice ciljnih strani ali poljubne nabore gnezdenih strani, ki naj se ustvarijo iz datotek.
page.json
Za stran, določeno z JSON, dodajte konfiguracijsko datoteko page.json:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
Lastnosti
| Lastnost | Vrsta | Privzeto | Opis |
|---|---|---|---|
name |
string |
obvezno | Enolični identifikator strani |
title |
string |
Samodejno iz imena | Naslov strani |
slug |
string |
Enako kot ime | URL slug strani |
path |
string |
"." |
Logična pot znotraj zbirke |
order |
integer |
0 |
Vrstni red v meniju za sinhronizirano objavo |
postType |
string |
"page" |
Vrsta objave WordPress |
postStatus |
string |
"draft" |
Stanje novih objav (publish, draft, pending, private) |
postId |
integer |
– | Pripni stran določenemu ID-ju objave WordPress |
blockEditingMode |
string |
– | Način urejanja blokov: "default", "contentOnly" ali "disabled" |
templateLock |
string|false |
"all" |
Način zaklepanja: "all", "insert", "contentOnly" ali false |
templateFor |
string|null |
null |
Nastavi kot privzeto predlogo za vrsto objave |
sync |
boolean |
true |
Določa, ali lahko običajno izrecno usklajevanje ustvari ali posodobi objavo |
render |
string|object|false |
– | Upodobi stran z registriranim upodobljevalnikom strani (glejte Strani komponent) |
Med page.json, metapodatki na začetku dokumenta in vnosi nalagalnika sodijo med prepoznane ključe blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock in title. Vsak ključ, ki ni naveden zgoraj, je shranjen v polju meta strani.
Viri vsebine
Definicija strani določa, katera objava WordPress naj obstaja. Vir vsebine določa, katero označevanje blokov se zapiše v to objavo.
Ko mapa strani vsebuje page.json, Blockstudio poišče sosednjo izvorno datoteko v tem vrstnem redu:
| Datoteka | Uporaba |
|---|---|
index.php |
Označevanje blokov v slogu HTML, prebrano takšno, kot je (koda PHP se ne izvede) |
index.blade.php |
Vsebina predloge Blade |
index.twig |
Vsebina predloge Twig |
index.md |
Vsebina Markdown |
page.json lahko namesto sosednje datoteke zagotovi tudi vgrajeno vsebino markdown ali html:
{
"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>"
}
Zbirke dodajo še dva načina pridobivanja virov:
- Datoteke Markdown, odkrite neposredno v drevesu zbirke.
- Vnosi nalagalnika, vrnjeni iz
loader.php.
Vnosi nalagalnika lahko uporabljajo markdown, html ali content z contentType. Lahko kažejo tudi na lokalni file ali template. Pri virih datotek in predlog se vrsta določi iz pripone, razen če je izrecno nastavljena možnost contentType.
Podprte vrednosti contentType so php, blade, twig, markdown in html. Markdown se najprej pretvori v HTML, nato pa razčleni v izvorne bloke WordPress. Viri PHP, Blade, Twig in HTML se obdelajo z običajnim razčlenjevalnikom strani Blockstudio.
Razredi v jedrnih blokih
Razred class na elementu HTML, preslikanem v jedrni blok, postane njegov className.
Izrecna oznaka jedrnega bloka lahko neposredno uporabi className. Obe obliki ohranita
razrede na shranjenem ovoju bloka, poleg razredov, ki jih ustvari WordPress:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
Če sta prisotni obe lastnosti, ima prednost className. Ta pretvorba velja samo za jedrne bloke: preslikava bloka po meri ohrani nespremenjeno svoje polje class. Razredi sloga gumba, kot je is-style-outline, spadajo na ovoj gumba, ne na njegovo povezavo.
Zaženite wp bs pages sync, da uveljavite popravke razčlenjevalnika na predhodno sinhroniziranih straneh. Nadgradnje razčlenjevalnika se zaznajo ob naslednji izrecni sinhronizaciji, tudi če datoteke vira niste uredili. Zaklenjene strani in strani z sync: false ohranijo običajno zaščito; zahteve sprednjega dela nikoli ne sprožijo te sinhronizacije.
Serializirani bloki WordPress
Viri strani in vzorcev lahko vsebujejo tudi serializirane bloke, kopirane iz urejevalnika kode WordPress:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
Ko vir vsebuje ločilo bloka <!-- wp:... -->, Blockstudio za celoten vir uporabi izvorni razčlenjevalnik blokov WordPress. Atributi, ugnezdeni bloki, dinamični bloki, kot je Query Loop, in bloki Blockstudio ohranijo svojo serializirano strukturo. HTML zunaj komentarjev blokov ostane v izvorni prosti obliki HTML; ne preslika se v dodatne bloke. Oznak blokov HTML Blockstudio ne mešajte s tem formatom in ne pričakujte, da bodo pretvorjene. Navadni komentarji HTML ne izberejo načina serializiranih blokov.
Strani Markdown
Uporabite Markdown, kadar naj bo besedilo v datotekah, po sinhronizaciji pa postane urejljiva vsebina blokov WordPress. Vir Markdown se med sinhronizacijo pretvori v označevanje blokov. Sinhronizirana objava shrani bloke, ne surove vsebine Markdown.
Markdown lahko uporabite na tri načine:
| Vir | Zahtevani metapodatki na začetku datoteke? | Opombe |
|---|---|---|
Samostojen pages/example/index.md |
Da | Metapodatki na začetku datoteke določajo identiteto strani. |
page.json in index.md |
Ne | page.json določa stran, Markdown pa zagotavlja vsebino. |
| Markdown v zbirki | Ne | Zbirka iz lokacije datoteke izpelje name in path. |
Samostojni index.md brez metapodatkov na začetku datoteke se preskoči, ker Blockstudio nima identitete strani za sinhronizacijo. Datoteke Markdown v zbirki teh metapodatkov ne potrebujejo, saj identiteto določata manifest zbirke in pot datoteke.
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
page.json lahko povežete tudi z index.md. V tem primeru page.json določa stran, index.md pa zagotavlja vsebino. Metapodatki na začetku datoteke index.md preglasijo ujemajoče se vrednosti page.json.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
title: API Reference
order: 20
---
# Reference
This page uses `page.json` with Markdown content.
Pri zbirki Markdown postane pot datoteke logična pot strani, razen če jo preglasijo metapodatki na začetku datoteke:
| Datoteka | Privzeta pot |
|---|---|
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 |
Neznani ključi v metapodatkih na začetku datoteke se ohranijo v polju meta strani. Tako lahko dodate podatke, kot sta section ali description, in jih preberete iz PHP API.
Markdown se razčleni kot GitHub Flavored Markdown. Dovoljena je surova vsebina HTML, nevarne povezave se odstranijo, naslovi brez izrecnega ID-ja pa dobijo stabilen ID. Za gnezdene metapodatke YAML na začetku datoteke je potreben priloženi razčlenjevalnik YAML.
Surovi Markdown
Viri datotek Markdown lahko zunanjim orodjem in uporabnikom dokumentacije posredujejo izvirni vir Markdown. Vgrajeni Markdown nima izvorne datoteke, zato se sinhronizira v bloke, ne ustvari pa surovega odziva .md.
Zahtevajte stran s pripono .md, na primer https://example.com/docs/reference.md. Lahko pa pošljete glavo Accept: text/markdown običajni strani URL:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
Metapodatki na začetku datoteke se odstranijo iz odziva. Uspešni surovi odzivi Markdown pošljejo glave Content-Type: text/markdown, X-Robots-Tag: noindex in kanonično glavo Link nazaj strani HTML. Če manjka pot .md, se vrne pravi 404.
Pogajanje deluje s statičnim predizrisom: odgovor na zahtevo, katere glava Accept vsebuje text/markdown, nikoli ne pride iz shrambe predizrisanih vsebin ali dodatka za zgodnje streženje, temveč doseže WordPress in obravnavalnik Markdown. Predizrisani odgovori HTML, HTML strani, ki se pogaja tudi za Markdown, in Markdown, posredovani prek Accept, pošljejo Vary: Accept, zato jih predpomnilniki, ki upoštevajo Vary, obravnavajo ločeno. CDN, ki predpomnilnik ključi samo po URL, potrebuje lastno pravilo za obhod predpomnilnika pri takih zahtevah. Pages::negotiates_markdown( $post_id ) poroča, ali stran odgovarja na zahteve Markdown.
Zbirka Markdown pri surovem Markdown ohrani enako obliko URL:
| Stran URL | Surovi Markdown URL |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
S filrom blockstudio/pages/serve_markdown onemogočite surove odzive Markdown:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Pot URL .md, ki ne ustreza strani, podprti z Markdown, vrne 404 samo, če je pot znotraj zbirke strani. Zunaj vseh zbirk Blockstudio prepusti zahtevo v obravnavo WordPress in drugim vtičnikom.
Strani komponent
Stran komponente upodobi upodobljevalnik strani, namesto da bi bila shranjena kot bloki. Blockstudio ne vključuje upodobljevalnika. Tema ali vtičnik registrira upodobljevalnik za datoteke vnosov, ki jih obravnava, na primer upodobljevalnik React za page.tsx, in Blockstudio ga pokliče s stranjo, objavo WordPress in vsebino upodobljenega mesta.
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 je izrecen. Imenik z index.php in page.tsx, vendar brez render, ostane običajna stran, zato dodajanje upodobljevalnika obstoječe strani nikoli ne upodobi dvakrat. Oblike so:
| Vrednost | Pomen |
|---|---|
"page.tsx" |
Samo vnos, brez nalagalnika podatkov |
{ "entry": "page.tsx", "data": "data.php" } |
Vnos in nalagalnik podatkov |
{ "entry": "page.tsx", "renderer": "react" } |
Vnos z izrecnim ID-jem upodobljevalnika |
false |
Brez upodobljevalnika, tudi če je določen v privzeti nastavitvi zbirke |
Poti se razrešijo glede na imenik strani oziroma glede na koren zbirke za vnose nalagalnika. Ostati morajo znotraj vira odkrivanja, razen če to dovoljuje blockstudio/pages/allow_external_loader_path. Če ni renderer, se uporabi upodobljevalnik, ki podpira pripono vnosa. Če render navaja manjkajoč vnos ali podatkovno datoteko, neznan upodobljevalnik ali pripono, ki je ne podpira noben upodobljevalnik, gre za napako pri odkrivanju, zaradi katere usklajevanje spodleti, še preden se karkoli odstrani.
Kaj shrani sinhronizacija
Sinhronizacija shrani en blok blockstudio/page. Če je v imeniku strani tudi vir index.*, se ta razčleni kot kateri koli drug vir strani in postane notranja vsebina bloka, njegovo mesto:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
Vsebino v lasti WordPress, kot so kratke kode, ohranite na mestu. Vir, ki vsebuje samo eno kratko kodo, na primer [download_checkout], se shrani kot blok core/shortcode, zato okoli njegovega izhoda ni odstavka. Ostane v post_content, zato jo zaznajo preverjanja has_shortcode(), bloki mesta s ključi se združijo s spremembami v urejevalniku tako kot ugnezdeni bloki s ključi, do_shortcode pa kratke kode razširi enkrat, z običajno prednostno stopnjo the_content, potem ko jih upodobljevalnik ovije.
Definicija upodabljanja je shranjena z objavo kot prenosljive poti theme:. Prstni odtis strani zajema definicijo, ne pa bajtov vnosa ali nalagalnika podatkov: urejanje page.tsx ali data.php pusti objavo nespremenjeno, spremembe pa so obiskovalcem vidne prek upodabljanja in grafa predizrisovanja statične vsebine, ki beleži vnos, nalagalnik podatkov in vsako datoteko, ki jo sporoči upodobljevalnik.
Registracija upodobljevalnika
Upodobljevalnike registrirajte v dejanju blockstudio/pages/renderers. Sproži se enkrat na zahtevo, pred prvim odkrivanjem ali upodabljanjem, zato wp bs pages sync in zahteve iz ospredja uporabljajo isti register.
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',
)
);
}
);
ID-ji upodobljevalnikov so zapisani z malimi črkami. Pripona ali ime postavitve lahko pripada samo enemu upodobljevalniku, layout.php pa ostane lastna postavitev za Blockstudio. Klicljiva funkcija prejme eno zahtevo:
| Ključ | Vrednost |
|---|---|
kind |
page ali layout za postavitev upodobljevalnika postavitve |
renderer |
ID upodobljevalnika |
entry |
Absolutna pot vnosa |
data |
Absolutna pot nalagalnika podatkov ali null |
page |
Kanonični podatki strani, vključno z meta |
post_id |
ID objave WordPress |
slot |
Upodobljena vsebina mesta ali vsebina strani za postavitev |
context |
frontend, rest, feed ali cli |
Vrne HTML, datoteke, ki jih je prebralo upodabljanje, in neobvezna sredstva:
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 izhaja iz vrste zahteve in nikoli od obiskovalca, zato prikazovalnik ne more porušiti enakosti bajtov med prijavljenimi in anonimnimi uporabniki, če ga prebere. Če prikazovalnik odpove, vrže napako: stran se ne izriše s praznim telesom. V REST predogledu urejevalnika blok napako prikaže kot obvestilo. Po uspešnem izrisu dejanje blockstudio/pages/rendered prejme stran, HTML in njene odvisnosti.
assets navaja skriptne in slogovne datoteke, ki jih stran potrebuje. Zanje veljajo postopki obdelave sredstev blokov (konvencija *.inline.*, moduli ES, pomanjševanje in ?ver), stran pa jih izpiše enkrat, prek istega medpomnilnika, ki izpisuje sredstva blokov, zato jih vnaprej izrisana stran vsebuje. Sredstvo lahko nastavi version, da nadomesti svojo vrednost ?ver. Koda zunaj prikazovalnika lahko isti kanal uporabi prek Blockstudio\Assets::register_owner(), ki vrne komentar z označevalnikom za izpis.
Urejevalnik
V urejevalniku blockstudio/page prikaže strežniško izrisan predogled strani, pri čemer je reža sestavljena iz notranjih blokov, ki upoštevajo templateLock strani. Bloka ni mogoče vstaviti, podvojiti ali ugnezditi v drug blok.
Zbirke strani
Zbirka je mapa z manifestom pages.json. Pod enim slugom zbirke združuje številne vire strani, uveljavlja privzete vrednosti, podpira gnezdene poti in lahko samodejno registrira namensko vrsto objave.
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"
}
}
| Lastnost | Vrsta | Opis |
|---|---|---|
collection / slug / name |
string |
Oznaka zbirke. collection je najjasnejša oblika in postane osnova javnega URL. |
title |
string |
Naslov zbirke, berljiv ljudem. |
postType |
string |
Vrsta objave za ustvarjene strani. Privzeto je page. Če ne obstaja, jo registrira Blockstudio. |
postTypeArgs |
object |
Argumenti, posredovani funkciji register_post_type(), ko Blockstudio registrira vrsto objave zbirke. |
defaults |
object |
Privzete lastnosti strani, uporabljene za vsako stran v zbirki. Privzeti render se uporabi za stran samo, če njen vnos obstaja v imeniku strani. |
scope |
string |
collection (privzeto) ali site. Glejte Zbirke spletnih mest. |
meta |
object |
Metapodatki po meri za zbirko. Neznani ključi manifesta se prav tako shranijo v meta. |
Poti strani v zbirki so logične poti. Stran z path: "guide/install" se sinhronizira kot podrejena stran guide, guide pa kot podrejena stran korena zbirke, če te nadrejene strani obstajajo.
Če ima hierarhična zbirka gnezdeno stran, njen vmesni nadrejeni vir pa ne obstaja, Blockstudio ustvari prazno vsebniško stran za to pot, s čimer ohrani celotno hierarhijo WordPress. Nehierarhične vrste objav (brez podpore za nadrejeni element page-attributes) ne ustvarijo praznih vsebniških strani. Usmerjajo se po shranjeni poti zbirke, zato lahko soobstajajo gnezdene poti, kot sta guide/install in setup/install, čeprav se obe končata z install.
Vrste objav zbirke in URL-ji
V manifestu zbirke nastavite postType, da se vsaka stran v zbirki sinhronizira v to vrsto objave. Te iste vrednosti ni treba ponoviti v defaults. Posamezne strani lahko še vedno prepišejo postType v metapodatkih na začetku datoteke ali v page.json.
Če vrsta objave ne obstaja, jo Blockstudio registrira z show_in_rest: true, nastavitvijo urejevalnika, podobno strani, in slugom zbirke kot javno osnovo URL. postTypeArgs lahko prepiše argumente registracije. Pravila za prepis URL-jev vrst objav zbirke se samodejno osvežijo, ko se registrirane vrste objav zbirke ali argumenti za prepis spremenijo, zato vam ni treba znova shraniti stalnih povezav WordPress.
URL-ji zbirke uporabljajo slug zbirke in logično pot posamezne strani path:
| Izvorna pot | Javno URL |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
Ta URL zasnova deluje tako za hierarhične kot nehierarhične vrste objav zbirk. Blockstudio preusmeri tudi podvojene URL-je, kot sta /docs/docs/ ali /docs/docs/getting-started/, na kanonični URL.
Strani zbirk na istih URL-jih prikazujejo surovi Markdown (glejte Surovi Markdown).
Če zbirko spremenite iz postType: "page" v vrsto objav po meri, Blockstudio ob naslednji sinhronizaciji na mestu preseli že sinhronizirane objave zbirke, kadar se njihova shranjena identiteta strani ujema. Tako ohrani ID-je objav, metapodatke in obstoječo vsebino ter prepreči podvojene objave s staro vrsto. Zastarele objave zbirke se počistijo v vseh stanjih objav glede na filter blockstudio/pages/orphan_action.
Zbirke spletnih mest
Manifest z "scope": "site" združi vse strani pod njim, ne da bi jih spremenil v strani zbirke. Uporabite ga v korenu drevesa strani spletnega mesta, da uveljavite skupne privzete nastavitve in navedete strani spletnega mesta z 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" }
}
}
Strani zbirke spletnega mesta ohranijo povsem enako identiteto, kot so jo imele brez manifesta, zato dodajanje manifesta v obstoječe drevo ne posodobi nobene vrstice objave in ničesar ne ustvari ali premakne v koš:
- Ključi ostanejo globalni:
Pages::get_page( 'home' )in shranjeni ključi strani se še naprej ujemajo. - URL-ji ostanejo URL-ji strani WordPress. Ne uporabijo se pravila za prepisovanje zbirke, filter trajne povezave ali preusmeritev z dvojnim URL, prav tako se ne ustvarijo prazne strani vsebnikov.
- Logične poti, oznake, nadrejene strani in izvorne identitete ostanejo enake kot pri samostojnih straneh, postavitve pa se določijo glede na najbližjega prednika.
- Ugnezdeni manifesti
pages.jsonohranijo svoje zbirke, njihova poddrevesa pa so iz zbirke spletnega mesta izpuščena. - Privzete nastavitve se uporabijo za vsako stran posebej: privzeti
rendervelja samo za strani, katerih imenik vsebuje njegov vnos, zato strani s kratkimi kodami in Markdown ohranijo svoje vire.
Nalagalniki zbirk
Zbirke lahko vključujejo zaupanja vreden lokalni loader.php. Uporabite ga, kadar strani zbirke izvirajo iz drugega lokalnega vira, na primer zunanje mape z dokumentacijo, paketa ali ustvarjenega manifesta.
Nalagalnik se zažene med izrecnim odkrivanjem strani in sinhronizacijo. Biti mora determinističen in lokalen. Izogibajte se pridobivanju oddaljene vsebine iz loader.php, saj bi bila sinhronizacija ob uvajanju tako odvisna od te storitve.
<?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',
),
),
);
Nalagalnik lahko vrne polje s ključi pages, meta in paths:
| Ključ | Opis |
|---|---|
pages |
Seznam polj strani. Vsaka stran podpira iste prepoznane ključe kot sprednji metapodatki page.json in Markdown. |
meta |
Metapodatki, združeni v polje meta vsake strani, ustvarjene z nalagalnikom. |
paths |
Dodatni lokalni imeniki, ki jih je treba poiskati kot del te zbirke. Vnosi so lahko nizi ali objekti poti. |
render |
Definicija izrisovanja za vsako stran Markdown, odkrito v paths. |
Kot krajšo obliko lahko nalagalnik vrne goli seznam polj strani.
Vnosi strani nalagalnika lahko zagotovijo vsebino na te načine:
| Oblika | Opis |
|---|---|
markdown |
Vstavljena vsebina Markdown. |
html |
Vstavljena vsebina HTML. |
content + contentType |
Splošna vstavljena vsebina. contentType se mora razrešiti v markdown ali html. |
file |
Vir lokalne datoteke. Vrsta se določi glede na pripono, razen če je nastavljeno contentType. |
template |
Vzdevek za file. |
Sklici na datoteke v nalagalniku lahko kažejo na vire PHP, Blade, Twig, Markdown ali HTML. Relativne poti se razrešijo glede na koren zbirke. Absolutne poti in poti zunaj korena zbirke so dovoljene samo, če jih dovoljuje filter blockstudio/pages/allow_external_loader_path.
Strani nalagalnika imajo privzeto vrednost generated: true. Ko ustvarjena stran nalagalnika izgine iz izhoda nalagalnika, Blockstudio ob naslednji sinhronizaciji obravnava sinhronizirano objavo kot osirotelo in jo počisti glede na filter blockstudio/pages/orphan_action.
Imeniki, navedeni v paths, se odkrivajo kot običajne mape zbirk. Vsebujejo lahko datoteke Markdown ali mape page.json. Če so te poti zunaj korena zbirke, velja isti filter za zunanje poti.
Uporabite vnos v obliki niza, če naj zunanji imenik ohrani svoje logične poti. Če naj bo imenik priklopljen pod predpono poti zbirke, uporabite vnos v obliki objekta:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
S to konfiguracijo postane cli-docs/index.md v zbirki path: "cli", cli-docs/getting-started.md pa path: "cli/getting-started". Predpone preprečujejo tudi trke imen ustvarjenih strani, zato lahko vsak od več priklopljenih imenikov vsebuje index.md ali getting-started.md. Če želite namesto tega ohraniti izrecne vrednosti name iz sprednjih metapodatkov page.json ali Markdown, v objektu poti nastavite preserveNames na true.
Lastnosti objekta poti:
| Lastnost | Vrsta | Opis |
|---|---|---|
path |
string |
Lokalni imenik za iskanje. Relativne poti se razrešijo glede na koren zbirke. |
prefix |
string |
Izbirna predpona logične poti znotraj zbirke. |
preserveNames |
boolean |
Ohranite izrecna imena strani, namesto da ustvarite imena iz poti s predpono. Ko je nastavljeno prefix, je privzeta vrednost false. |
meta |
object |
Metapodatki, združeni z vsako stranjo, odkrito v tej poti. Metapodatki na ravni strani imajo prednost pri podvojenih ključih. |
render |
string|object |
Definicija izrisovanja za strani Markdown te poti, ki preglasi render nalagalnika. |
Izrisovanje Markdown prek komponente
Z render se strani Markdown, ki jih odkrije nalagalnik, izrišejo prek prikazovalnika strani, namesto da bi bile shranjene kot bloki:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
Ohranijo status strani Markdown: vrsta vsebine, pot vsebine, odgovori .md in sprednji metapodatki ostanejo nespremenjeni. Sinhronizacija shrani en blok blockstudio/page, katerega notranja vsebina HTML je pretvorjeni Markdown, očiščen, kadar zbirka očisti svojo vsebino, namesto razčlenjenih blokov, zato post_content ohrani besedilo dokumenta. Prikazovalnik prejme ta HTML kot režo in lahko prebere vir iz page.content_path. Relativne poti se razrešijo glede na koren zbirke; filter zunanje poti se uporabi enako kot za poti. Stran, katere sprednji metapodatki določajo njen render ali render: false, je izpuščena.
Postavitve
Datoteka layout.php ovije izris strani, ki temelji na datoteki, v ospredju spletnega mesta. Ne nadomesti sinhroniziranega post_content, shranjenega v WordPress, in ne ovije platna urejevalnika. Postavitev se izvaja samo pri zahtevah za posamezne strani v ospredju.
Za zbirke postavite layout.php poleg pages.json, da ovije vsako stran te zbirke v ospredju:
<?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() izpiše telo strani, ki bi ga WordPress običajno izrisal prek the_content. Če postavitev ne izpiše blockstudio_page_content(), je vsebina strani namenoma skrita.
Postavitve lahko uporabljajo pomožne funkcije strani:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
Gnezdene strani, ki niso del zbirke, lahko podedujejo tudi najbližji layout.php predniške strani v drevesu pages. Pri straneh zbirk je postavitev korena zbirke shranjena v vsaki sinhronizirani objavi in spremljana kot del prstnega odtisa strani, zato se spremembe postavitve upoštevajo ob naslednji sinhronizaciji.
Postavitve prikazovalnikov
Postavitev je lahko tudi vnos prikazovalnika, na primer layout.tsx za prikazovalnik, ki registrira layouts: ["layout.tsx"]. Najde se na istih mestih kot layout.php, izbirni layout.data.php ob njej pa je njen nalagalnik podatkov. Ob izrisu prikazovalnik prejme kind: "layout" in vsebino izrisane strani kot slot, z enako prednostjo the_content kot layout.php. Imenik lahko vsebuje layout.php ali eno postavitev prikazovalnika, ne pa obojega; če vsebuje oboje, gre za napako pri odkrivanju. Napaka postavitve sproži blockstudio/pages/layout_error in pusti vsebino strani neovito, tako kot pri layout.php.
Način urejanja blokov
Lastnost blockEditingMode določa, kako je mogoče urejati bloke v urejevalniku. Nastavite privzeto vrednost na ravni strani v page.json in jo preglasite za posamezne elemente v predlogi:
{
"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>
| Vrednost | Opis |
|---|---|
"default" |
Polno urejanje. Bloke je mogoče izbrati, premikati in urejati. |
"contentOnly" |
Samo urejanje besedila. Besedilo blokov je mogoče urejati, nastavitve in struktura pa so zaklenjene. |
"disabled" |
Brez urejanja. Bloki so povsem neinteraktivni. |
Preglasitve za posamezne elemente nastavite kot atribute HTML na katerem koli elementu (<h1>, <p>, <div> itd.) ali na elementih <block>. Nadrejeni vsebniški bloki preglasenih elementov se samodejno nastavijo na contentOnly, da njihovi podrejeni elementi ostanejo dostopni. Ta veriga se pomika od preglasenega elementa proti korenu strani, zato morate blockEditingMode nastaviti samo na elementih, ki jih želite omogočiti za urejanje.
Zaklep predloge
Lastnost templateLock določa, kako lahko uporabniki urejajo stran v urejevalniku:
| Vrednost | Dodajanje/odstranjevanje | Premikanje | Urejanje vsebine |
|---|---|---|---|
"all" |
Ne | Ne | Ne |
"insert" |
Ne | Da | Da |
"contentOnly" |
Ne | Ne | Da |
false |
Da | Da | Da |
Ko je nastavljen templateLock, Blockstudio onemogoči odklepanje blokov prek UI urejevalnika.
Navidezne poti
Nekateri dokumenti nimajo povezane objave: referenca komponente, ustvarjena iz podatkov, katalog ali območje računa. Registrirajte jih kot navidezne poti, namesto da sami dodate kavelj 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(),
]
);
} );
Pot je relativna glede na domačo stran spletnega mesta. Z prefix pot služi tudi vsem podrejenim potem, match pa prejme ta preostanek (prazen niz za samo pot) in vrne vrednost, ki jo prejme funkcija za izris, ali null, da prepusti URL v obdelavo WordPress, ki nato kot običajno odgovori z 404. Funkcija za izris dokument izpiše ali ga vrne kot niz; title je niz ali zaključek, ki prejme ujemajočo se vrednost.
Pri ujemajoči se zahtevi Blockstudio prepreči, da bi WordPress označil 404 in da bi redirect_canonical izvedel preusmeritev, počisti stanje posamezne strani, ki ga sporoča glavna poizvedba, pošlje stanje (privzeto status, 200) in izris izvede pri prednosti Virtual_Routes::PRIORITY za template_redirect. To je takoj za tem, ko Blockstudio odpre izhodni medpomnilnik pri Assets::BUFFER_PRIORITY, zato dokončani dokument kot vsaka stran prejme svoja sredstva blokov, združena sredstva UI in prevedeni Tailwind, še pred redirect_canonical pri prednosti 10. Upravljalnik, ki sam izriše celoten dokument, mora delovati tudi za Assets::BUFFER_PRIORITY, sicer se ta obdelava preskoči. Poti v urls (privzeto je to sama pot poti, če ne gre za predponsko pot) se dodajo v gradnje statičnega predizrisovanja, Virtual_Routes::urls() pa jih za zemljevid spletnega mesta vrne kot absolutne URL-je.
Virtual_Routes::match( $path ) razreši pot tako, kot bi jo razrešila zahteva.
Delovanje sinhronizacije
Objave strani se spremenijo samo z izrecnim postopkom sinhronizacije:
wp bs pages sync
Ukaz odkrije celoten popis virov, ustvari ali posodobi spremenjene objave, odstrani potrjene osirotele objave, osveži usmerjanje zbirk in prevedeno konfiguracijo templateFor ter poroča o spremembah. Dodajte --authoritative, da zamenjate upravljano vsebino namesto ohranjanja urejene vsebine s ključi, in --full, da postopek označite kot popolno uskladitev ne glede na shranjeno identiteto vira:
wp bs pages sync --authoritative --full
Običajne zahteve za ospredje, skrbništvo, AJAX, REST, cron in splošni začetni zagon WP-CLI ne izvedejo celotnega odkrivanja strani, ne poizvedujejo po popisu uskladitve upravljanih strani in ne zapisujejo objav strani. Uporabljajo že sinhronizirane objave WordPress ter strnjeno konfiguracijo zbirk in predlog vrst objav, shranjeno z zadnjim izrecnim postopkom. Ob prvi namestitvi ali nadgradnji se lahko enkrat pregledajo manifesti zbirk za obnovitev metapodatkov usmerjanja; ta začetni zagon samo za branje nikoli ne sinhronizira vsebine. Overjena končna točka za osvežitev platna, ki se uporablja po izbiri, je izrecna avtorska API: platno jo pokliče enkrat ob odprtju delovnega prostora, da se novi ali spremenjeni viri prikažejo v začetnem popisu. Način v živo pokliče isto mejo, ko zazna spremembo vira strani.
Blockstudio\Pages::init() zdaj registrira samo kavlje ob času zahteve. Integracije, ki so tej metodi prej posredovale argument force, morajo namesto tega poklicati Blockstudio\Pages::reconcile() ali zagnati wp bs pages sync.
Če želite preprečiti prepis strani po ročnih spremembah, nastavite "sync": false v page.json.
Prenosljive izvorne lokacije
Sinhronizirane datoteke teme so shranjene kot lokacije glede na temo, ne kot absolutne namestitvene poti. Datoteke podrejene in nadrejene teme ohranijo ločene identitete, tudi če imajo isto relativno ime datoteke. Pomožne funkcije strani še vedno vrnejo razrešene absolutne vrednosti template_path, content_path, layout_path in directory za trenutno zahtevo.
To CLI omogoča sinhronizaciji in spletnim zahtevam uporabo različnih korenskih imenikov datotečnega sistema, na primer pri gostovanju v izoliranem okolju, ne da bi to vplivalo na odzive Markdown, postavitve, pregledovanje urejevalnika Tailwind ali sledenje izvoru za vnaprejšnje upodabljanje. Obstoječe absolutne poti do tem se ob branju prilagodijo, če ime imenika teme ostane enako. Za branje teh poti niso potrebni sinhronizacija, selitev zbirke podatkov ali zapis metapodatkov med obdelavo zahtev; naslednja izrecna sinhronizacija shrani prenosljive lokacije.
Imenik teme, ki je simbolna povezava, na primer do razvojnega delovnega drevesa, shrani enake lokacije theme: ne glede na to, ali je bil vir prebran prek simbolne povezave ali prek njenega cilja, in jih razreši glede na konfigurirani imenik teme.
Datoteke zunaj aktivne podrejene in nadrejene teme so še naprej podprte na svojih konfiguriranih absolutnih poteh, ob upoštevanju omejitev PHP open_basedir. Njihove lokacije se ne posodobijo samodejno: po premiku zunanjega vira posodobite njegovo konfigurirano pot in zaženite izrecno sinhronizacijo.
Lastništvo polj objave
postStatus nastavi začetno stanje. Nadaljnje sinhronizacije ohranijo obstoječa stanja »osnutek«, »v čakanju«, »zasebno«, »objavljeno« in »načrtovano«, tudi z --authoritative. Osnutek ne bo znova objavljen zgolj zato, ker njegova datoteka vsebuje postStatus: "publish". Obstoječe vedenje pri obnovi osirotelih objav ostaja nespremenjeno: izrecna sinhronizacija obnovi v koš premaknjeno upravljano objavo, če je njen vir še prisoten. Zaklenite stran ali onemogočite sinhronizacijo, da preprečite obnovitev.
Datoteka še naprej določa naslov, polžji URL, vrsto objave, nadrejeno objavo in konfigurirani vrstni red v meniju. Če te vrednosti uredite v WordPress, s tem ne spremenite definicije vira. Naslednja izrecna sinhronizacija znova uporabi vrednosti iz datoteke in navede spremenjena polja v pages.<name>.overwritten, v tabelarnem izpisu CLI pa prikaže opozorilo. Še vedno veljajo izvorna dovoljenja WordPress, vključno s praznim polžjim URL-jem za objave v čakanju, kadar jih uporabnik, ki izvaja sinhronizacijo, ne more objaviti.
Za integracijo, ki izrecno določa drugačno politiko stanj, uporabite blockstudio/pages/update_post_data. Bloki s ključi ohranijo vsebino blokov, ki jo upravlja urejevalnik; ključi ne spremenijo lastništva naslova ali polžjega URL-ja objave.
Pri straneh zbirk prstni odtisi zajemajo manifest, nalagalnik, vir strani, datoteko postavitve, metapodatke in povezane poti do virov. Naslednja izrecna sinhronizacija uveljavi spremembe teh vhodnih podatkov.
Ko odstranite vir zbirke, Blockstudio odstrani ustvarjeno stran, da stare strani zbirke ne ostanejo po odstranitvi izvorne datoteke. Osirotele strani zbirk se privzeto premaknejo v smetnjak. Uporabite blockstudio/pages/orphan_action, da vrnete trash, delete ali keep.
Pri zahtevah za ospredje Blockstudio napolni register strani iz že sinhroniziranih objavljenih objav. Osnutki in zasebne strani so na voljo v skrbniškem okolju in pri sinhronizaciji, vendar pomožne funkcije ospredja naložijo samo objavljene strani.
Uskladitev ob uvajanju
Blockstudio\Pages::reconcile() je vstopna točka uvajanja PHP. Odkrije celoten želeni popis, primerja prstne odtise vira in mehanizma sinhronizacije ter vrne strojno berljivo poročilo:
$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',
],
],
]);
Poročilo vsebuje discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, rezultate za posamezne strani, napake pri odkrivanju in deterministični sourceIdentity.
Zaklenjene strani imajo status: "locked" in se štejejo ločeno od nespremenjenih strani. removedPages za vsako odstranjeno stran navede njen name, key, postId in dejanski action (trash ali delete); ohranjene ali že v koš premaknjene objave se ne štejejo kot na novo odstranjene. Tabelarni izpis CLI navede tudi ustvarjene, posodobljene, zaklenjene, odstranjene in po vsebini ohranjene strani z njihovimi ID-ji objav.
Po razčlenjevanju in združevanju blokov s ključi enaka končna objava ne sproži klica wp_update_post(), ne spremeni post_modified, ne ustvari revizije in ne sproži kavljev za posodobitev objave. Njen rezultat je unchanged. Če se vsebina vira razlikuje od vsebine blokov s ključi, ki jo upravlja urejevalnik, preserved: true označi to odločitev in je vključena v skupno število preserved na najvišji ravni. Novi prstni odtis vira in upravljani metapodatki se vseeno zabeležijo, zato naslednja sinhronizacija nespremenjenega vira ne naredi ničesar. preserved je dodatna zastavica in ne izključno stanje: stran lahko ohrani vsebino blokov s ključi, hkrati pa posodobi naslov, ki ga določa datoteka, ali doda drug blok.
authoritative: true lahko počisti ključavnico Page Sync in zamenja vsebino z definicijo iz datoteke namesto ohranjanja urejene vsebine s ključi. Za običajno izrecno sinhronizacijo pustite false. plan_valid: false, full: true, broad: true, manjkajoča prejšnja identiteta vira ali spremenjen prstni odtis mehanizma sinhronizacije označijo postopek kot popolno uskladitev (fullReconciliation v poročilu). V vsakem primeru se primerja celoten popis. Zapisi o preimenovanjih Git so samo namigi za določanje identitete. Nikoli ne nadomestijo primerjave celotnega popisa.
Enaki prstni odtisi ob nespremenjenih izvajalnih poteh ne povzročijo zapisov v objavo ali postmeta in ne sprožijo kavljev za posodobitev. Ko se nespremenjen vir premakne v nov imenik izdaje, uskladitev osveži samo shranjene poti predloge, vsebine, postavitve in imenika; ne posodobi post_content ali časovnega žiga spremembe objave. Manjkajoče upravljane strani se odstranijo šele po koncu celotnega postopka uskladitve brez napak pri odkrivanju ali zapisovanju strani.
Neposredna uskladitev API ne označi uvajanja kot uspešnega. Po aktivaciji in preverjanju ustreznega statičnega artefakta in poti izrecno shranite vrnjeno identiteto:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync po uspešnem postopku shrani vrnjeno identiteto. Običajni začetni zagon WP-CLI samo registrira shranjene vrste objav zbirk in pravila prepisovanja URL-jev. Strani ne odkriva ali sinhronizira.
Pripenjanje ID-jev objav
Privzeto WordPress samodejno dodeli ID-je objav. Če stran izbrišete in znova ustvarite, se ID spremeni, zato prenehajo delovati zunanje reference, kot so meniji ali povezave, zapisane v kodi.
Uporabite postId, da stran pripnete na določen ID:
{
"name": "about",
"title": "About Us",
"postId": 42
}
Pri ustvarjanju strani Blockstudio posreduje ID WordPress prek import_id. Če je ID na voljo, ga WordPress uporabi natančno. Če ga že uporablja nepovezana objava, WordPress tiho samodejno dodeli nov ID.
Pri iskanju obstoječih strani Blockstudio najprej preveri pripeti ID, nato metapodatke ali slug. Če stran izbrišete in znova sinhronizirate, tako znova pridobi isti ID.
Združevanje blokov s ključi
Ko se datoteka predloge spremeni, Blockstudio privzeto zamenja celotno vsebino objave z novo predlogo. To pomeni, da se izgubijo vse spremembe v urejevalniku WordPress.
Blokom dodajte atribut key, da se spremembe uporabnikov ohranijo med sinhronizacijami predloge. Če predloga vsebuje bloke s ključi, Blockstudio združi spremembe predloge z obstoječo vsebino objave, namesto da bi jo zamenjal.
Dodajanje ključev
Atribut key uporabite na katerem koli elementu HTML ali <block>:
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>
<div key="features">
<p>First feature.</p>
<p>Second feature.</p>
</div>
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h2>Hero Title</h2>
<p>Hero description.</p>
</block>
<block
name="acme/testimonial"
key="featured-quote"
quote="Default quote"
/>
Ključi morajo biti enolični v celotni predlogi. Ključ ščiti celoten blok in vso njegovo vsebino. Posameznim podrejenim elementom znotraj bloka s ključem ni treba dodati ključa. Bloke s ključi lahko med posodobitvami predloge premaknete kamor koli ali ugnezdite na kateri koli ravni, njihova uporabniška vsebina pa se bo ohranila.
Ključi delujejo enako tudi pri blokih po meri Blockstudio. key so strukturni metapodatki Page Sync; vrednosti polj po meri ostanejo običajni atributi Blockstudio. Ko urednik spremeni ta polja, poznejša sinhronizacija predloge ohrani urednikove vrednosti in hkrati uveljavi neodvisne spremembe predloge. Strani, ustvarjene s starejšimi različicami, ki imajo ključ znotraj podatkov polja po meri, se samodejno preselijo ob naslednji sinhronizaciji.
Kako deluje združevanje
Ko se datoteka predloge spremeni in se stran znova sinhronizira:
| Blok | Delovanje |
|---|---|
| Blok s ključem | Uporabniška vsebina in vrednosti polj Blockstudio se ohranijo. Uveljavijo se atributi in struktura, določeni s predlogo. |
| Blok brez ključa | V celoti se zamenja z različico iz predloge (enako kot brez ključev). |
Primeri
Uporabniške spremembe v blokih s ključi se ohranijo:
- Predloga določa
<p key="intro">Default intro.</p> - Uporabnik v urejevalniku spremeni odstavek v »Besedilo po meri.«
- Razvijalec posodobi predlogo, doda nov blok in spremeni postavitev
- Ob sinhronizaciji se ohrani odstavek »Besedilo po meri.«, uveljavi pa se nova postavitev
Atributi iz predloge se še vedno uveljavijo:
- Predloga vsebuje blok naslovnice z
key="hero"in atributomurl - Razvijalec spremeni atribut
urlnaslovnice, da uporabi novo sliko ozadja - Ob sinhronizaciji se uporabi nova slika ozadja, uporabniške spremembe vsebine znotraj naslovnice pa se ohranijo
Robni primeri
| Primer | Delovanje |
|---|---|
| V predlogo je dodan nov blok s ključem | Prikaže se s privzeto vsebino predloge |
| Blok s ključem je odstranjen iz predloge | Izbriše se iz objave |
| Vrsta bloka se spremeni (isti ključ) | V celoti prevlada predloga, vsebina se ne združi |
| Podvojeni ključi | Drugi pojav se obravnava kot blok brez ključa |
| Predloga ne vsebuje ključev | Popolna zamenjava (enako kot brez ključev) |
| Vsili sinhronizacijo | Popolna zamenjava, ključi so prezrti |
| Zaklenjena objava | Brez sinhronizacije |
Kombiniranje z možnostmi urejanja
S kombinacijo ključev, templateLock in blockEditingMode lahko natančno določite, kaj lahko stranke počnejo in česa ne. Tukaj je nekaj pogostih vzorcev delovnih postopkov.
Povsem zaklenjena stran
Razvijalec nadzira vse. Stran je statična postavitev, ki se je stranke sploh ne morejo dotakniti. Uporabno za pravne strani, pogoje uporabe ali katero koli stran, ki se sme spreminjati samo prek kode.
{
"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>
Ključi niso potrebni. Predloga je edini vir resnice. Vsaka sinhronizacija v celoti prepiše stran.
Zaklenjena postavitev z vsebino, ki jo je mogoče urejati
Najpogostejši vzorec. Zaklenite strukturo strani, da stranke ne morejo dodajati, odstranjevati ali preurejati blokov, hkrati pa jim omogočite urejanje besedila na določenih mestih. Ključi zagotavljajo, da se njihove spremembe ohranijo ob posodobitvah predloge.
{
"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>
Stranka lahko ureja naslov glavnega pasice, opis in uvod v funkcije. Nič drugega. Besedilo gumba, URL in sliko ozadja naslovnice določa razvijalec. Ko razvijalec posodobi predlogo (e.g, doda drugi gumb), razdelki s ključi ohranijo besedilo stranke.
Predloga, ki se razvija, z ohranjeno vsebino
Za strani, ki se sčasoma širijo. Razvijalec predlogi doda nove razdelke, pri vsaki sinhronizaciji pa se doda nova vsebina, ne da bi se poseglo v to, kar je stranka že prilagodila.
<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>
Ob sinhronizaciji se pojavita nov razdelek s pričevanji in gumb. Spremembe naslova, uvoda in storitev, ki jih je naredila stranka, ostanejo nedotaknjene.
Enkratna začetna struktura
Ustvarite stran z začetno strukturo in jo nato v celoti predajte naprej. Nastavite sync na false, da običajna sinhronizacija strani nikoli ne ustvari ali posodobi, nato pa jo enkrat ustvarite z Blockstudio\Pages::force_sync('blog'). Po tem je stran v celoti v lasti stranke.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
wp bs pages sync preskoči to stran, zato jo force_sync() ustvari enkrat. Nato lahko stranka poljubno dodaja, odstranjuje in prerazporeja bloke. Spremembe predloge so prezrte.
Vezave blokov
Alternativa združevanju po ključih je uporaba WordPresscoreove funkcije Block Bindings API za povezavo blokov z metapodatki objave. To ni funkcija Blockstudio, temveč izvorna funkcija WordPress API. Blockstudio preprosto posreduje atribut metadata v ustvarjeno oznako bloka. Vsebina je shranjena v metapodatkih objave namesto v oznaki bloka, zato lahko sinhronizacije predloge prosto prepišejo oznako, saj urejevalnik bere metapodatke, ne innerHTML.
Atribut metadata dodajte kateremu koli elementu HTML ali <block>:
<h1
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'
>
Default Title
</h1>
<p
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'
>
Default description text.
</p>
<img
metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>
Ključi metapodatkov morajo biti registrirani z omogočenim show_in_rest:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Ključi in vezave
| Vidik | Ključi | Vezave |
|---|---|---|
| Shranjevanje vsebine | Oznaka bloka (post_content) |
Metapodatki objave (wp_postmeta) |
| Ohranitev pri sinhronizaciji predloge | Da (združeno po ključu) | Da (podatki so v metapodatkih) |
Poizvedovanje prek WP_Query |
Ne | Da (meta_query) |
| Na voljo v REST API | Ne | Da |
| Zahteva registracijo | Ne | Da (register_post_meta) |
| Uporabnik lahko premika bloke | Ne (predloga znova določi strukturo) | Ne (predloga znova določi strukturo) |
Oba pristopa lahko uporabite v isti predlogi. Ključe uporabite za razdelke, pri katerih je pomembna struktura bloka (e.g, skupina z več podrejenimi bloki). Vezave uporabite za posamezna polja, kadar želite, da so podatki dostopni tudi zunaj urejevalnika blokov.
Predloge za vrste objav
Uporabite templateFor, da stran nastavite kot privzeto predlogo za vrsto objave:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
Vse nove objave te vrste se bodo začele z določeno strukturo blokov.
Poti po meri
Privzeto Blockstudio preišče get_template_directory() . '/pages'. Dodatne poti dodajte s filtrom:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
Integracije med izvajanjem, ki sestavljajo datoteke iz več korenskih map, lahko zamenjajo iskanje po datotečnem sistemu z logičnim virom odkrivanja. Manifeste strani, postavitve, nalagalnike in izvorne predloge se nato razreši po logični poti, tudi kadar so izbrane datoteke v različnih korenskih mapah.
Filtri in dejanja
Odkrivanje strani, sinhronizacija in usmerjanje zbirk omogočajo naslednje razširitvene točke:
| Kavelj | Vrsta | Opis |
|---|---|---|
blockstudio/pages/paths |
Filter | Doda imenike, v katerih Blockstudio išče vire strani. |
blockstudio/pages/collection_post_type_args |
Filter | Prilagodi argumente register_post_type() za CPT zbirke. |
blockstudio/pages/template_candidates |
Filter | Prilagodi imena datotek predlog, ki se upoštevajo za vir strani. |
blockstudio/pages/serve_markdown |
Filter | Omogoči ali onemogoči neobdelane odzive Markdown. |
blockstudio/pages/orphan_action |
Filter | Za čiščenje osirotelih virov vrne trash, delete ali keep. |
blockstudio/pages/docs_allowed_html |
Filter | Prilagodi dovoljene HTML za ustvarjeno vsebino dokumentacije Markdown. |
blockstudio/pages/allow_external_loader_path |
Filter | Dovoli paths nalagalnika zunaj korenskega imenika zbirke. |
blockstudio/pages/manifest_scan_interval |
Filter | Nastavi najdaljšo starost predpomnilnika manifesta pred 7.6.2, ki lahko ob nadgradnji zagotovi začetne podatke za trajno konfiguracijo izvajalnega okolja. |
blockstudio/pages/create_post_data |
Filter | Spremeni podatke objave pred ustvarjanjem sinhronizirane strani. |
blockstudio/pages/update_post_data |
Filter | Spremeni podatke objave pred posodobitvijo sinhronizirane strani. |
blockstudio/pages/sync_engine_inputs |
Filter | Doda različico razčlenjevalnika, preslikave ali selitve, ki naj enkrat namerno razširi usklajevanje. |
blockstudio/pages/post_created |
Dejanje | Se izvede po ustvarjanju objave sinhronizirane strani. |
blockstudio/pages/post_updated |
Dejanje | Se izvede po posodobitvi objave sinhronizirane strani. |
blockstudio/pages/synced |
Dejanje | Se izvede po končani sinhronizaciji registra strani. |
blockstudio/pages/reconciled |
Dejanje | Se izvede po izrecnem usklajevanju in prejme njegovo strojno berljivo poročilo. |
blockstudio/pages/renderers |
Dejanje | Registrira upodabljalnike strani z Blockstudio\Page_Renderers::register(). Sproži se enkrat na zahtevo. |
blockstudio/pages/rendered |
Dejanje | Se izvede po upodobitvi strani komponente; prejme stran, njen HTML in njene odvisnosti. |
blockstudio/pages/layout_error |
Dejanje | Se izvede, kadar postavitve ni mogoče upodobiti; prejme napako, pot do postavitve in stran. |
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]);
Za semantiko argumentov, polja poročila in preverjeno mejo identitete vira glejte Uskladitev uvedbe.
Za predloge in postavitve so na voljo globalne pomožne funkcije:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
Polja strani, ki jih vrnejo Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() in globalne pomožne funkcije, vključujejo identiteto sinhronizirane objave, poti do vira in predloge, metapodatke zbirke in poti, vrsto vsebine, pravilnik sinhronizacije, vrsto in stanje objave, pravilnik urejanja, metapodatke po meri ter ključ permalink. Metapodatki zbirk se naložijo iz zadnje uspešne izrecne uskladitve. Običajne zahteve rekonstruirajo te podatke izvajalnega okolja iz shranjene konfiguracije in metapodatkov sinhroniziranih objav, ne da bi brale drevesa virov strani. Razred Pages ne ponuja ločene metode za trajne povezave.
Zaklepanje predlog, načini urejanja blokov, združevanje po ključih in nadzor nad tem, kaj lahko urejajo stranke.