Programski izris
Ker Gutenberg postaja glavno orodje za ustvarjanje preprosto urejljivih spletnih mest za stranke, je smiselno vsa potrebna območja spletnega mesta ustvariti kot bloke. Ta pristop bo zadostoval večini, napredni uporabniki in posebni primeri uporabe pa bodo morda potrebovali obstoječe bloke zunaj urejevalnika.
Blockstudio omogoča dva načina programskega izrisa blokov:
- Funkcije PHP:
bs_render_blockinbs_blockza izris iz kode PHP - Oznake HTML: oznake
<bs:block-name>, ki jih kjer koli na strani nadomesti izhod bloka
Podprte so vse funkcije, značilne za Blockstudio, kot so vgrajeni slogi, skripti in omejeni slogi.
Tudi Otočki delujejo prek teh poti izrisa. Dinamični
otoček, izrisan z bs_render_block(), bs_block() ali oznako bloka, vrne
isto označbo mesta kot blok, izrisan iz vsebine prispevka; izvajalno okolje
na spletnem mestu pa se vstavi, ko je ta označba prisotna v odgovoru.
Strukturirane sestave in celotni dokumenti
Za dolgotrajna orodja, predoglede, izvoze in galerije komponent uporabite
različico Blockstudio\Render API. Sprejme eno deklaracijo ali urejen
seznam in izriše vsebino brez izpisa:
use Blockstudio\Render;
$composition = [
'root' => 'theme/card',
'example' => [
'data' => [
'heading' => 'Example card',
],
'layers' => [
[
'name' => 'theme/button',
'data' => [
'label' => 'Continue',
],
],
],
],
];
$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
'title' => 'Component preview',
'contentElement' => 'main',
'contentClasses' => ['component-preview'],
]);
Standardizirana normalizirana deklaracija ima štiri ključe:
[
'name' => 'theme/card',
'attributes' => [],
'content' => '',
'children' => [],
]
data, inner, innerBlocks, root, layers in example so poenostavitve za vnos in se med normalizacijo odstranijo. Ugnezdene deklaracije se rekurzivno izrišejo po istem postopku Blockstudio.
Render::document() vrne schemaVersion, html, body, blocks,
assets, warnings in errors. Vrednost assets loči head,
footer, styles, scripts, modules, interactivity, ui in tailwind.
Seznam blokov in sredstva vključujejo odvisnosti, na katere se sklicujejo izbrane predloge,
izključujejo pa nepovezana sredstva in sredstva, namenjena samo urejevalniku.
Celotni dokumenti lahko nastavijo bodyClasses/bodyAttributes in po želji ovijejo
izrisano telo z contentElement, contentClasses in
contentAttributes. Ovoj je omejen na varno ime elementa; vrnjeni body ostane neovita izrisana vsebina.
Možnosti head in footer dodata zaupanja vredno označevanje dokumenta na
ustrezni mesti in sta vključeni v vrnjeno množico sredstev.
Če želite sestaviti dokument okoli že izrisanega HTML, navedite znana imena korenskih blokov:
$document = Render::document_from_html(
$rendered_html,
['theme/hero', 'theme/button'],
['title' => 'Homepage preview']
);
Za serializirano vsebino bloka Render::content() uporabite WordPress. Porabniki, ki v eni zahtevi upodabljajo več neodvisnih dokumentov, naj med njimi pokličejo Blockstudio\Batch_Render::reset(); Canvas::documents() to naredi samodejno.
Upodabljanje zunaj strani
Blockstudio pred vsak blok, ki ga upodobi, vstavi komentar <!--blockstudio/namespace/slug-->. Na strani na sprednjem delu spletnega mesta medpomnilnik prebere te komentarje, da ugotovi, kateri bloki so prisotni, naloži njihova sredstva in komentarje odstrani, preden pošlje odgovor.
Izhod, ki ne gre skozi ta medpomnilnik, ohrani komentarje. To velja za odgovore REST, vire, obravnavalnike AJAX in HTML, ki jih shranite ali pošljete drugam po do_blocks(), Render::content() ali bs_render_block(). Za njihovo odstranitev uporabite
bs_strip_render_markers():
$html = bs_strip_render_markers(do_blocks($post->post_content));
Funkcija odstrani komentarje registriranih blokov Blockstudio, vse drugo pa pusti nedotaknjeno, vključno z drugimi komentarji HTML. Ujema se z istimi oznakami, ki jih odstrani medpomnilnik strani. Pokličite jo po registraciji blokov (init ali pozneje).
Ne odstranite označevalnega jezika, ki je še vedno izpisan na strani na sprednjem delu spletnega mesta z aktivnim medpomnjenjem. Stran potrebuje komentarje, da ugotovi, katera sredstva blokov naj naloži, in Blockstudio jih odstrani sama na koncu.
Odstranitev komentarjev ne doda sredstev. Datoteke bloka CSS in JavaScript vstavi samo medpomnilnik strani. Uporabite bs_block_assets()ali ali Render::document(), če jih potrebuje tudi odjemalec.
Pregled blokov
Po registraciji blokov uporabite bs_block_fields() (na init ali pozneje), da pridobite razrešene definicije polj, ne da bi brali interne registre:
$fields = bs_block_fields('theme/card');
if ($fields === null) {
// Unknown block, or not a Blockstudio block.
}
Vrnjena vrednost je polje registriranih definicij polj, vključno s filtri atributov, razširjenimi polji po meri, preglasitvami ter ugnezdenimi skupinami, zavihki in ponavljalniki. Blok Blockstudio brez polj vrne []. Rezultat je kopija: če ga spremenite, se registrirani blok ne spremeni.
To so definicije, ne shranjene vrednosti. Za preverjanje veljavnosti shranjene oznake uporabite bs_validate_block(), namesto da vzdržujete ločen sprehajalnik polj. Za opis vrednosti, ki jih blok sprejema, uporabite bs_block_schema(). Atributi v lasti WordPress ostanejo ločeni.
Polja, dodana z razširitvami, niso del bs_block_fields(). Pridobite jih z bs_block_extension_fields(). Funkcija razširitve poveže z imenom bloka, zato deluje tudi za osnovne bloke in bloke drugih ponudnikov:
$fields = array_merge(
bs_block_fields('core/paragraph') ?? [],
bs_block_extension_fields('core/paragraph')
);
Vrnjena vrednost navaja definicije polj vseh ujemajočih se razširitev v vrstnem redu njihove registracije, z enako strukturo kot bs_block_fields(). Za blok, ki se ne ujema z nobeno razširitvijo, vrne []. Vrednosti razširitev so shranjene v istem objektu attrs.blockstudio.attributes kot lastne vrednosti polj bloka, zato imajo vsi ID-ji skupni imenski prostor. Če dve razširitvi določita isti ID, sta vrnjeni obe definiciji in obe urejata isto vrednost; pri upodabljanju velja definicija pozneje registrirane razširitve.
Če želite prebrati vrednosti shranjenega bloka, kot jih prejme njegova predloga, uporabite bs_block_values()za branje vrednosti shranjenega bloka.
Za pregled odkritih CSS in JavaScript bloka uporabite bs_block_assets()pregled odkritih podatkov bloka. Za celoten dokument predogleda, vključno z ugnezdenimi bloki in skupnimi odvisnostmi izvajalnega okolja, uporabite Render::document(), kot je opisano zgoraj.
Preverjanje shranjenih vrednosti
Po registraciji blokov uporabite bs_validate_block() (init ali pozneje) za programsko preverjanje atributov blokov, ustvarjenih ali uvoženih, preden jih shranite:
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);
if ($findings === null) {
// No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
// No stored-value problems were found.
} else {
// Review the findings before saving.
}
Podajte celotno polje attrs, ne le blockstudio.attributes. Upodobitev bloka Blockstudio sprejme deklarirana polja tudi na najvišji ravni, ugnezdene vrednosti pa imajo prednost, če sta podani obe obliki. Razširitve osnovnih blokov in blokov drugih ponudnikov berejo samo blockstudio.attributes. Prazni blok Blockstudio je upravljan in vrne [], ne pa null.
Preverjanje je izrecno in samo za branje. Ne upodablja predlog, spreminja vrednosti, shranjuje objav, poizveduje po predstavnostnih vsebinah ali izvaja povratnih klicev za izpolnjevanje podatkov. Ne poteka samodejno med shranjevanjem, sinhronizacijo strani ali upodabljanjem. Ni čistilnik, preverjanje pooblastil ali preverjanje obstoja priloge.
Vsaka ugotovitev vsebuje te stabilne ključe:
[
'code' => 'unknown_option',
'path' => 'steps/1/style',
'source' => 'block',
'message' => 'This value is not among the field options.',
'value' => 'c',
'expected' => ['a', 'b'],
]
V orodjih uporabite code, ne prevedene oblike message. source je block ali
extension. Poti uporabljajo ključe shrambe in indekse vrstic ponavljalnika ali izbir, ki se začnejo z ničlo,
brez začetne poševnice. Dobesedna ~ in / v ključu sta ubežani kot ~0 in
~1. Skupina na najvišji ravni doda predpono svojim podrejenim elementom (cta_title); anonimne skupine
in zavihki ne dodajo ravni. Graditelj ne podpira skupin z ID-jem znotraj druge skupine ali ponavljalnika,
zato njihovi ključi niso sprejeti. Polja za sporočila nimajo shranjene vrednosti. Polje za datoteke dovoljuje pripadajoči element <id>__size.
V korenu bloka Blockstudio ključi za vodenje evidenc in globalni atributi HTML,
posredovani upodobljenemu elementu, niso neznana polja. To ne dovoljuje poljubnih ključev v vrsticah ponavljalnika ali razširitev osnovnih blokov.
| Koda | Pomen | expected |
|---|---|---|
unknown_field |
Nobeno ohranjeno polje ne določa tega ključa shrambe. | Znani ključi shrambe. |
unknown_option |
Izbira ni med znanimi možnostmi. | Dovoljene vrednosti možnosti. |
wrong_type |
Shranjena oblika ni podprta za to polje. | Pričakovana družina ali vrsta shrambe. |
too_few_rows, too_many_rows |
Prisotni ponavljalnik je zunaj svoje spodnje ali zgornje min oziroma max meje. |
Meja števila vrstic. |
definition_conflict |
Veljavne definicije za en ključ zahtevajo različne oblike shrambe. | Vir in vrsta polja vsake definicije. |
shadowed_value |
Vgnezdena vrednost prepiše drugačno vrednost polja na najvišji ravni. | Zmagovalna vgnezdena vrednost. |
extension_top_level |
Predloga lahko prebere vrednost na najvišji ravni, vezave razširitev pa ne. | Zahtevana pot znotraj blockstudio/attributes. |
unknown_attribute |
Ključa na najvišji ravni bloka Blockstudio pot upodabljanja ne prebere in je izpuščen. | Imena registriranih atributov, polja razširitev in blockstudio. |
missing_container |
attributes, disabled, name ali editor je shranjen na najvišji ravni, blockstudio pa manjka. |
Njegova zahtevana pot znotraj blockstudio. |
invalid_container |
blockstudio ali blockstudio.attributes ni objekt. |
object. |
Sporočilo za najdbo unknown_field navede najbližji ključ shrambe na isti ravni, če se od njega razlikuje za največ tri spremembe; takšno pravilo uporabljajo neznane nastavitve: This storage key is not declared by the block or its extensions. Did you mean "title"?
expected še vedno navaja vse znane ključe.
Pri ujemanju se ne upošteva velikost črk, primerjajo pa se samo ključi shrambe iz tega vsebnika. Sporočila so prevedena; integracije naj namesto razčlenjevanja besedila sporočila uporabljajo code, path in expected.
Ključ na najvišji ravni bloka Blockstudio, ki ni registriran atribut
(njegova polja, atributi, ki jih WordPress doda za supports, lock in
metadata), polje ujemajoče se razširitve, blockstudio, ključ za vodenje evidenc ali posredovani atribut HTML, je izpuščen, preden se zažene predloga.
Tak ključ, na primer napačno zapisan ID polja ali objekt vrednosti, shranjen
brez ovoja blockstudio, povzroči opozorilo, ker se blok upodobi brez te vrednosti.
Bloki, ki vsebujejo samo polja razširitev, se ne preverjajo glede ključev na najvišji ravni.
Sprejete oblike sledijo načinu upodabljanja: večkratne izbire in potrditvena polja lahko
vsebujejo seznam, objekt ene možnosti ali uvoženo skalarno vrednost, tudi številsko ničlo.
Za števila so sprejeti nizi, ki predstavljajo števila. Polja za datoteke lahko vsebujejo ID-je prilog,
objekte ID-jev, sezname ali nize sklicev. Vrednosti povezav in ikon morajo biti objekti; vrste polj po meri uporabljajo svojo registrirano vrsto atributa.
Polje attributes vsebuje seznam parov z nepraznim imenom attribute
in skalarno vrednostjo value; neobvezni metapodatki, kot je data.media, se ohranijo.
WordPress pred upodabljanjem preveri registrirane atribute na najvišji ravni, zato lahko zavrne obliko, sprejeto znotraj blockstudio.attributes. Vrednost radio "a" na primer deluje v vgnezdenem objektu, na najvišji ravni pa je izpuščena, ker je tam njena registrirana vrsta object. Takšna vrednost sproži wrong_type.
Za enako obliko shrambe, kot jo zapiše urejevalnik, uporabite vgnezdeni objekt.
Manjkajoča polja niso obvezna. Prazne vgnezdene vrednosti (null, false, '',
[]) in onemogočena polja ne povzročijo napak vrednosti. Izrecno prazen
ponavljalnik se vseeno preveri glede na min; odsoten ali onemogočen ponavljalnik pa ne.
Prazna vrednost na najvišji ravni se prijavi, če jo WordPress izpusti in obnovi
neprazno privzeto vrednost. Ista vrednost v vgnezdenem objektu jo lahko počisti.
Spori med definicijami se prijavijo tudi, če ključ nima shranjene vrednosti.
Statične možnosti in možnosti za zapolnitev, razrešene ob registraciji, se preverijo brez ponovnega klica funkcije za zapolnitev. Možnosti oddaljenega fetch in argumenti funkcije za zapolnitev, ki vsebujejo {attributes.*}, se preskočijo. Barve in prelivi so lahko poljubni, razen če je nastavljeno disableCustomColors ali disableCustomGradients.
To preverja shranjene vrednosti, ne pa default, fallback ali pravil za preverjanje v urejevalniku.
Ujemajoča se polja razširitev so vključena za vsak blok, na katerega ciljajo. Poznejše definicije zmagajo v bloku ali njegovih razširitvah v korenu, kot pri upodabljanju.
Lastno polje bloka in polje razširitve ostaneta ločeni definiciji istega ključa, zato veljata obe. Znotraj vrstic ponavljalnika upodabljalnik v vsakem viru prebere prvo polje z ujemajočim se ID-jem, zato veljajo njegove možnosti in omejitve. Podvojene definicije se ohranijo za diagnostiko sporov:
nezdružljive oblike shrambe povzročijo definition_conflict, tudi če se poznejša podvojena definicija pri upodabljanju ne prebere.
Funkcija preveri en blok. Pri preverjanju dokumenta se sprehodite čez innerBlocks;
sinhronizirani vzorci in drugi sklici se ne razširijo samodejno. Ukaz wp bs blocks validate se sprehodi čez bloke ene ali več objav in prikaže njihove poti blokov.
Spletna mesta z lastnim razreševalnikom ob upodabljanju lahko prilagodijo ugotovitve, ne da bi spreminjala shranjene podatke:
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
if ($name !== 'my-theme/card') {
return $findings;
}
return array_values(array_filter($findings, function($finding) {
return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
}));
}, 10, 3);
Vedno vrnite seznam ugotovitev; če vrnete [], blok sprejmete. Ta filter se izvede samo za upravljane bloke, nikoli pa za rezultat null.
Opis shranjenih vrednosti
Po registraciji bloka (init ali novejši različici) uporabite bs_block_schema() za opis vrednosti, ki jih blok shranjuje, na primer za ustvarjanje oznake bloka v orodju ali integraciji z umetno inteligenco ali za preverjanje vnosa v poti REST:
$schema = bs_block_schema('theme/card');
if ($schema === null) {
// No Blockstudio fields or matching extensions apply.
}
Rezultat je shema JSON objekta, shranjenega v attrs.blockstudio.attributes. Zajema polja bloka in polja ustreznih razširitev ter ključe shrambe, ki jih uporablja preverjanje veljavnosti: predpona skupine na najvišji ravni se doda njenim podrejenim poljem, anonimne skupine in zavihki ne dodajo ravni, polje datoteke pa doda spremljevalno polje <id>__size. Ponavljalniki so seznami objektov vrstic z vrednostma minItems in maxItems iz min in max. additionalProperties je false v korenu shranjenih polj in v vrsticah ponavljalnika. Polja z vrednostjo objekta, kot so povezave in objekti po meri, lahko vsebujejo lastne metapodatke. Blok brez polj nima vrednosti properties, zato se ujema samo prazen objekt.
Vsako polje je opisano v kanonični obliki, ki jo sprejema bs_validate_block():
| Polje | Shema |
|---|---|
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block |
Niz. |
number, range |
Število z vrednostma minimum in maximum iz min in max. |
toggle |
Logična vrednost. |
select, radio, checkbox |
Vrednost možnosti ali seznam vrednosti možnosti za checkbox in multiple z vrednostjo enum. |
color, gradient |
Niz z vrednostjo enum, kadar je nastavljena možnost disableCustomColors ali disableCustomGradients. |
token |
Seznam nizov. |
files |
Nenegativni celoštevilski ID priloge ali seznam ID-jev z vrednostjo multiple. |
link |
Objekt z vrednostmi url, title in opensInNewTab; url je obvezna. |
icon |
Objekt z vrednostmi set, subSet in icon; set in icon sta obvezni. |
attributes |
Seznam objektov z neprazno vrednostjo attribute in skalarno vrednostjo value. |
repeater |
Seznam objektov vrstic. |
| Vrste polj po meri | Njihov registrirani tip atributa. |
enum navaja možnosti, ki jih preverja validacija: statične možnosti in možnosti za polnjenje, razrešene že ob registraciji. Oddaljene možnosti fetch in argumenti za polnjenje, ki vsebujejo {attributes.*}, nimajo vrednosti enum. Ključ z definicijami različnih oblik shrambe je izpuščen, ker preverjanje veljavnosti poroča o vsaki vrednosti, shranjeni pod njim. Kadar si polje bloka in polje razširitve delita ključ, enum navede vrednosti, ki jih sprejemata oba. Skupni ponavljalniki združijo podrejena polja in uporabijo strožje omejitve števila vrstic iz obeh definicij. V vrsticah ponavljalnika velja prvo polje z ujemajočim se ID-jem iz vsakega vira, tako kot pri upodabljanju. Izrecno določeno polje z imenom <id>__size ima prednost pred samodejno dodanim spremljevalnim poljem za velikost datoteke.
Kadar zaprto polje nima razpoložljivih možnosti ali se dve uporabni množici možnosti ne prekrivata, je njegova kanonična vrednost null pri enojnem izboru oziroma prazen seznam pri večkratnem izboru. Prazen seznam možnosti ne spremeni polja v neomejeno. Oddaljene možnosti in možnosti, odvisne od atributov, ostanejo odprte.
Vrednost polja label postane title, njegova vrednost help postane description, vrednost default pa se ohrani kot opomba. Lastna vrednost sheme title je naslov bloka. Polja niso nikoli obvezna, pogojna logika pa ni del sheme.
Omejitve uporabljajo samo ključne besede, ki jih preverja rest_validate_value_from_schema(), zato shema deluje neposredno kot vhodna shema poti REST ali zmožnosti:
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
$result = rest_validate_value_from_schema($values, $schema);
}
Shema opisuje en obrazec za vsako polje; preverjanje sprejema tudi uvožene oblike, kot so objekti možnosti, številski nizi in objekti ID. Ne nadomešča bs_validate_block(): konflikti definicij so težave s konfiguracijo in lahko še vedno povzročijo najdbe, tudi če je konfliktni ključ izpuščen. Filtri preverjanja lahko določajo tudi pravila za posamezno spletno mesto. Uporabite bs_validate_block() za preverjanje shranjene vsebine. Spletna mesta z lastnim razreševalnikom ob času izrisovanja lahko shemo prilagodijo s filtrom blockstudio/blocks/attributes/schema.
PHP Functions
Brez podatkov
V najpreprostejši obliki funkcija sprejme eno samo vrednost, in sicer ID bloka, ki naj bo upodobljen na strani.
bs_render_block('blockstudio/cta');
S podatki
Za upodobitev bloka z lastnimi podatki je treba namesto ene same vrednosti za prvi parameter uporabiti polje. Vrednost v ključu data bo posredovana spremenljivkama $attributes in $a znotraj predloge bloka.
bs_render_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
]);
Gnezdenje
Bloke lahko gnezdite enega v drugega s funkcijo bs_block v kombinaciji z zmogljivo spremenljivko $content v predlogah blokov.
<div>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content; ?>
</div>
echo bs_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
'content' => bs_block([
'id' => 'blockstudio/button',
'data' => [
'text' => 'Button Text',
]
])
]);
Blok gumba bo upodobljen namesto spremenljivke $content v predlogi bloka.
Vdelani bloki, upodobljeni z bs_render_block() ali bs_block(), vedno izpišejo HTML, razrešen za prikaz na spletnem mestu, tudi ko se nadrejeni blok trenutno upodablja kot predogled v urejevalniku. Psevdokomponente predloge, kot sta <RichText /> in <InnerBlocks />, se razrešijo, preden je vrnjen vdelani blok.
Več mest
Več mest za vsebino lahko ustvarite tudi tako, da spremenljivko $content preprosto pretvorite v asociativno polje in v funkciji bs_block pokličete ustrezne ključe.
<div>
<?php echo $content['beforeContent']; ?>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content['afterContent']; ?>
</div>
echo bs_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
'content' => [
'beforeContent' => bs_block([
'id' => 'blockstudio/badge',
'data' => ['text' => 'Before Content']
]),
'afterContent' => bs_block([
'id' => 'blockstudio/button',
'data' => ['text' => 'Button Text']
])
]
]);
Oznake blokov
Vdelajte kateri koli blok s sintakso oznak HTML. Podprta sta dva formata:
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
Oba upodobita isti blok. Sintaksa <bs:> spremeni vezaj v ločilo imenskega prostora (acme-hero postane acme/hero). Vezaji se preverjajo od leve proti desni in zmaga prvi registrirani kandidat, zato se razrešijo tudi imenski prostori z vezaji: <bs:acme-ui-button> preveri acme/ui-button, nato acme-ui/button. Sintaksa <block> uporabi polno ime bloka kot atribut name.
Delujejo tako bloki Blockstudio kot jedrni bloki WordPress. Bloki Blockstudio se upodabljajo skozi celoten cevovod (predloge, Tailwind, sredstva). Jedrni bloki se upodabljajo prek sistema za upodabljanje blokov v WordPress z vgrajenimi upodabljalniki blokov.
Kako deluje
Oznake blokov se obnašajo različno glede na to, kje se pojavijo:
V predlogah blokov in vsebini objav se oznake med izvajanjem nadomestijo z upodobljenim HTML. Izhod je končna oznaka navedenega bloka, neposredno vdelana v stran. V urejevalniku za te oznake ni bloka WordPress. Služijo izključno upodabljanju.
V Straneh, vzorcih in predlogah spletnega mesta se oznake pretvorijo v izvorne bloke WordPress, preden se izvorna datoteka sinhronizira ali registrira v WordPress. To pomeni, da se bloki prikažejo v urejevalniku, jih je mogoče urejati, kjer ciljna platforma to podpira, in so vključeni v celoten življenjski cikel blokov WordPress. Sintaksa oznak je okrajšava za določanje vsebine blokov v datotekah s predlogami.
Ta razlika je pomembna: oznake blokov v predlogah ustvarijo izhod, oznake blokov na straneh, v vzorcih in predlogah spletnega mesta pa ustvarijo izvorne bloke.
V predlogah blokov
Oznake blokov se samodejno upodabljajo v predlogah Twig in PHP. Nastavitev ni potrebna. To vključuje tudi sintaksi <bs:> in <block> ter vse registrirane oznake s predpono in vzdevke, zato jih lahko predloga izpiše neposredno, namesto da pokliče bs_render_block(). Izhod se upodobi HTML in neposredno vključi v izhod predloge bloka:
<div class="my-page">
<bs:mytheme-card title="Featured" />
<block name="core/separator" />
<bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
<block name="core/heading" level="2">Also WordPress</block>
<theme-card title="Prefix shorthand" />
</div>
V vsebini objave
Upodabljanje na ravni strani (vsebina objave, območja pripomočkov) je treba izrecno omogočiti:
{
"blockTags": {
"enabled": true
}
}
Ali prek filtra:
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');
Sintaksa
Samozapiralne oznake:
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />
Seznanjene oznake z notranjo vsebino:
<bs:mytheme-section layout="wide">
<p>Content inside the block.</p>
</bs:mytheme-section>
<block name="core/group">
<block name="core/paragraph">Inside a group.</block>
</block>
Kombinirajte jih po želji. Obe sintaksi sta lahko gnezdeni druga v drugi:
<bs:mytheme-section>
<block name="core/heading" level="2">Title</block>
<bs:mytheme-card title="Features" />
<block name="core/paragraph">Description text.</block>
</bs:mytheme-section>
Okrajšave s predponami
Oznake blokov lahko uporabljajo tudi okrajšave s predponami, značilnimi za projekt. Registrirajte predpono z enim ali več imenskimi prostori in Blockstudio bo razrešil <prefix-slug> v prvi registrirani blok glede na vrstni red imenskih prostorov:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components', 'bsui'];
return $prefixes;
});
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />
V zgornjem primeru se <theme-card> razreši v theme-components/card, <theme-button> se vrne na bsui/button, kadar theme-components/button ni registriran, <theme-ui-feature-matrix> pa se razreši v theme-components/ui-feature-matrix.
Predpone je mogoče tudi sestavljati. Če se oznaka s predpono ne razreši neposredno in je preostali del imena oznake sam registrirana oznaka s predpono, se razreševanje rekurzivno ponovi, zato je lahko predpona blagovne znamke nad predpono imenskega prostora:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components'];
$prefixes['ui'] = ['bsui'];
return $prefixes;
});
<theme-ui-input />
<theme-ui-input> nima bloka theme-components/ui-input, zato se iskanje nadaljuje s predpono ui in razreši bsui/input. Neposredna ujemanja imajo vedno prednost pred gnezdenim razreševanjem, pravila dovoljevanja in zavrnitve pa se uporabljajo za končno razrešeni blok.
Predpone lahko nastavite tudi v blockstudio.json:
{
"blockTags": {
"prefixes": {
"theme": ["theme-components", "bsui"]
}
}
}
Predpone lahko vsebujejo samo male črke ali številke, začeti se morajo s črko in ne smejo vsebovati vezajev. Izrecni vzdevki iz blockstudio/block_tags/tag_aliases imajo prednost pred razreševanjem predpon. Neznane oznake s predpono ostanejo nespremenjene.
Oznake s predponami in vzdevki so še naprej podprte kot priročna pomoč pri pisanju. Kanonični zapis, ki ga je mogoče prenašati med projekti, je vedno <bs:namespace-slug>, saj zabeleži pravo ime bloka in ni odvisen od projektnih filtrov:
<bs:theme-components-card />
<bs:bsui-input />
Primeri Blockstudio, ustvarjena diagnostična sporočila in programski izhod uporabljajo ta kanonični zapis. Projekti, ki želijo odstraniti starejšo okrajšano sintakso, lahko uporabijo samostojno, najprej preizkušeno na suho, selitev oznak v kanonično obliko brez zagona WordPress.
Jedrni bloki
Uporabite lahko kateri koli blok z registriranim upodabljalnikom:
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
<bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>
Ali s sintakso <block>:
<block name="core/group">
<block name="core/columns">
<block name="core/column">
<block name="core/paragraph">Left column</block>
</block>
<block name="core/column">
<block name="core/paragraph">Right column</block>
</block>
</block>
</block>
Seznama dovoljenih in zavrnjenih
Nadzorujte, katere bloke je mogoče upodabljati z oznakami:
{
"blockTags": {
"enabled": true,
"allow": ["mytheme/*", "core/*"],
"deny": ["mytheme/internal-*"]
}
}
allow omeji izbor na vzorce, ki se ujemajo. deny izloči ujemajoče se vzorce in ima prednost. Oba podpirata nadomestne znake * prek fnmatch(). Pravila veljajo za obe sintaksi ter za upodabljanje na ravni predlog in strani.
Filtra: blockstudio/block_tags/allow in blockstudio/block_tags/deny.
Neposredno posredovanje HTML
Atributi s predpono data- se posredujejo korenskemu elementu upodobljenega bloka. Posredujejo se tudi atributi s predpono html-, pri čemer se predpona odstrani. Deluje z obema sintaksama. Posredovani atribut nadomesti obstoječo vrednost korenskega elementa, namesto da bi jo združil z njo, zato html-class nadomesti lastne razrede bloka.
Blok Blockstudio na svoj korenski element prenese tudi globalne atribute, ki jih ne določa kot polja: id, style, role, title, lang, dir, hidden, tabindex in vsak atribut aria-*. Določeno polje ima vedno prednost, zato blok s poljem title namesto tega prejme vrednost iz $a['title']. Posredovani slogi se obdelajo prek safecss_filter_attr(), filter WordPress pa se uporablja za atribute sloga v vsebini objave; ti slogi se dodajo slogu, ki ga predloga že nastavi.
Vrednosti atributov so HTML, zato se entitete dekodirajo enkrat, ko je oznaka razčlenjena: title="Tom & Jerry" prispe do predloge kot Tom & Jerry, ob izhodu pa se znova ubeži. Navedene vrednosti lahko vsebujejo >, kot pri različicah Tailwind in izbirnikih animacij, tako pri samozapiralnih kot pri seznanjenih oznakah.
Kateri koli drug atribut, ki ga blok ne določa, vključno z class, nikoli ne doseže HTML. Če je omogočen WP_DEBUG, Blockstudio za vsak tak atribut enkrat na zahtevo ustvari poročilo prek _doing_it_wrong(). Zanj določite polje ali ga zapišite kot atribut data-, aria- ali html-.
<bs:mytheme-card
title="My Card"
html-class="featured-card"
html-id="main-card"
data-analytics="card-click"
/>
<block name="core/paragraph" html-class="highlight" data-section="intro">
Highlighted paragraph.
</block>
Lastni upodabljalniki
Registrirajte lastne upodabljalnike blokov za dodatne vrste blokov. Upodabljalniki sprejmejo polje atributov in niz notranje vsebine ter vrnejo polje bloka WordPress:
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
$builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
$html = '<div class="my-block">' . $inner_content . '</div>';
return [
'blockName' => 'myplugin/custom-block',
'attrs' => $attrs,
'innerBlocks' => [],
'innerHTML' => $html,
'innerContent' => [$html],
];
};
return $builders;
}, 10, 2);
Za vsebniške bloke, ki morajo razčleniti notranjo vsebino v podrejene bloke, dodajte drugi vnos znotraj istega filtra:
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
$content = ['<div class="my-wrapper">'];
foreach ($inner_blocks as $block) {
$content[] = null;
}
$content[] = '</div>';
return [
'blockName' => 'myplugin/wrapper',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '<div class="my-wrapper"></div>',
'innerContent' => $content,
];
};
blockstudio/block_tags/builders velja tako za oznake blokov kot za lastne bloke, izbrane prek blockstudio/parser/element_mapping. To je ustrezen priklopni mehanizem, kadar mora projektni blok s preslikavo elementov premakniti notranje besedilo v polje Blockstudio ali sestaviti lastno polje bloka.
blockstudio/block_tags/renderers in blockstudio/parser/renderers prejmeta isti register in obliko povratnega klica. Na voljo sta zaradi združljivosti in končnih preglasitev na ravni razčlenjevalnika. Filtra se zaženeta v tem vrstnem redu:
blockstudio/block_tags/buildersblockstudio/block_tags/renderersblockstudio/parser/renderers
Poznejši filter lahko zamenja upodabljalnik, ki ga je registriral prejšnji filter.
Programska uporaba
Upodabljanje oznak uporabite za kateri koli niz iz PHP:
$html = apply_filters('blockstudio/block_tags/render', $content);
Komponente
Oznake blokov se dobro ujemajo s komponentami Komponente. Komponente so bloki, ki se upodabljajo samo programsko in se nikoli ne prikažejo v urejevalniku.
<bs:mytheme-card title="My Card" description="Card content." />
Razčlenjevalnik
Oznake blokov obdeluje lahek pregledovalnik nizov, ki nadomesti DOMDocument. Razčlenjevalnik podpira sintaksi <bs:> in <block>, gnezdene oznake z istim imenom s sledenjem globini, navedene vrednosti atributov in rekurzivne vsebniške bloke. Zasnovan je posebej za ta primer uporabe, deluje hitreje kot DOMDocument in WordPressWP_HTML_Tag_Processor ter se izogne znanim težavam DOMDocument z odstranjevanjem predpon imenskih prostorov in pretvorbo imen atributov v male črke.
Za Strani, vzorce in predloge spletnega mesta isti razčlenjevalnik obdela tudi surove elemente HTML (<p>, <div>, <h1> itd.) in jih preslika v ustrezne jedrne bloke WordPress.
Ko preslikava elementov poveže <p> z registriranim blokom Blockstudio, ki ni jedrni blok in določa atribut richtext content, se notranji HTML samodejno usmeri v ta atribut content. To vključuje tudi vstavljene oznake, kot sta code in img, ki so preslikane na ravni blokov. Odstavek, katerega edini podrejeni element je slika, postane blok, v katerega se preslika <img>. Gnezdene oznake blokov ali HTML na ravni blokov se še vedno obdelajo z običajnim razčlenjevanjem notranjih blokov. <block name="core/shortcode"> ohrani besedilo kratke kode kot vsebino bloka.