Preskoči na vsebino

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:

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:

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

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:

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

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

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

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

# Reference

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

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:

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

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

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

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

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

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

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:

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

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

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

JSON
{
  "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.json ohranijo svoje zbirke, njihova poddrevesa pa so iz zbirke spletnega mesta izpuščena.
  • Privzete nastavitve se uporabijo za vsako stran posebej: privzeti render velja 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
<?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:

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

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

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

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

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:

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

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

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

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:

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

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

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

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

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

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

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:

  1. Predloga določa <p key="intro">Default intro.</p>
  2. Uporabnik v urejevalniku spremeni odstavek v »Besedilo po meri.«
  3. Razvijalec posodobi predlogo, doda nov blok in spremeni postavitev
  4. Ob sinhronizaciji se ohrani odstavek »Besedilo po meri.«, uveljavi pa se nova postavitev

Atributi iz predloge se še vedno uveljavijo:

  1. Predloga vsebuje blok naslovnice z key="hero" in atributom url
  2. Razvijalec spremeni atribut url naslovnice, da uporabi novo sliko ozadja
  3. 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.

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

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.

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

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

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

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.

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

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.

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

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

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

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

Ključi metapodatkov morajo biti registrirani z omogočenim show_in_rest:

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

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

PHP
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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

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

Ustvarjanje strani iz datotek

Zaklepanje predlog, načini urejanja blokov, združevanje po ključih in nadzor nad tem, kaj lahko urejajo stranke.