Programinis atvaizdavimas
Kadangi Gutenberg tampa pagrindine priemone lengvai redaguojamoms klientų svetainėms kurti, verta visas reikalingas svetainės sritis kurti kaip blokus. Nors toks metodas tiks daugeliui, pažengusiems naudotojams ir tam tikrais atvejais gali reikėti naudoti esamus blokus ne redaktoriuje.
Blockstudio siūlo du būdus programiškai atvaizduoti blokus:
- PHP funkcijos:
bs_render_blockirbs_block, skirtos atvaizduoti naudojant PHP kodą - HTML žymos:
<bs:block-name>žymos, kurios bet kurioje puslapio vietoje pakeičiamos bloko išvestimi
Palaikomos visos specifinės Blockstudio funkcijos, pavyzdžiui, įterptiniai stiliai, scenarijai ir aprėpties stiliai.
Salelės taip pat veikia naudojant šiuos atvaizdavimo kelius. Dinaminė salelė, atvaizduota naudojant bs_render_block(), bs_block() arba bloko žymą, grąžina tą patį vietos rezervavimo žymeklį kaip ir iš įrašo turinio atvaizduotas blokas; kai šis žymeklis yra atsakyme, įterpiama viešosios svetainės dalies vykdymo aplinka.
Struktūrinės kompozicijos ir išsamūs dokumentai
Ilgalaikiams įrankiams, peržiūroms, eksportams ir komponentų galerijoms naudokite versijuotą Blockstudio\Render API. Jis priima vieną deklaraciją arba surikiuotą sąrašą ir atvaizduoja jo neišvesdamas:
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'],
]);
Kanoninė normalizuota deklaracija turi keturis raktus:
[
'name' => 'theme/card',
'attributes' => [],
'content' => '',
'children' => [],
]
data, inner, innerBlocks, root, layers ir example yra patogesnės įvesties formos, kurios normalizuojant pašalinamos. Įdėtinės deklaracijos rekursyviai atvaizduojamos tuo pačiu Blockstudio procesu.
Render::document() grąžina schemaVersion, html, body, blocks, assets, warnings ir errors. Reikšmė assets atskiria head, footer, styles, scripts, modules, interactivity, ui ir tailwind.
Blokų sąraše ir ištekliuose pateikiamos pasirinktuose šablonuose nurodytos priklausomybės, bet neįtraukiami nesusiję ir tik redaktoriui skirti ištekliai.
Išsamūs dokumentai gali nustatyti bodyClasses/bodyAttributes ir pasirinktinai apgaubti atvaizduotą turinį elementais contentElement, contentClasses ir contentAttributes. Apvalkalui galima nurodyti tik saugų elemento pavadinimą; grąžinama body reikšmė lieka neapgaubtas atvaizduotas turinys.
Parinktys head ir footer atitinkamose vietose prideda patikimą dokumento žymėjimą ir įtraukiamos į grąžinamą išteklių uždarymą.
Norėdami sukurti dokumentą aplink jau atvaizduotą HTML, pateikite žinomus jo šakninių blokų pavadinimus:
$document = Render::document_from_html(
$rendered_html,
['theme/hero', 'theme/button'],
['title' => 'Homepage preview']
);
Naudokite Render::content() serializuotam WordPress bloko turiniui. Jei vienos užklausos metu pateikiami keli nepriklausomi dokumentai, tarp jų iškvieskite Blockstudio\Batch_Render::reset(); Canvas::documents() tai atlieka automatiškai.
Atvaizdavimas ne puslapyje
Blockstudio prieš kiekvieną atvaizduojamą bloką įterpia <!--blockstudio/namespace/slug--> komentarą. Svetainės puslapyje buferis nuskaito šiuos komentarus, kad nustatytų, kokie blokai yra, įkelia jų išteklius ir pašalina komentarus prieš išsiunčiant atsaką.
Išvestyje, kuri nepraeina per šį buferį, komentarai lieka. Tai taikoma REST atsakams, sklaidos kanalams, AJAX apdorojimo funkcijoms ir HTML, kuriuos saugote arba siunčiate kitur po do_blocks(), Render::content() arba bs_render_block(). Jiems pašalinti naudokite
bs_strip_render_markers():
$html = bs_strip_render_markers(do_blocks($post->post_content));
Funkcija pašalina registruotų Blockstudio blokų komentarus ir visa kita palieka nepakeistą, įskaitant kitus HTML komentarus. Ji atpažįsta tuos pačius žymeklius, kuriuos pašalina puslapio buferis. Iškvieskite ją užregistravę blokus (init arba vėliau).
Nepašalinkite žymėjimo, kuris vis dar išvedamas į buferizuojamą svetainės puslapį. Puslapiui reikia komentarų, kad žinotų, kuriuos blokų išteklius įkelti, o Blockstudio juos pašalina pabaigoje.
Komentarų pašalinimas išteklių neprideda. Blokų CSS ir JavaScript failus įterpia tik puslapio buferis. Naudokite bs_block_assets() arba Render::document(), jei jų reikia ir turinio naudotojui.
Blokų tikrinimas
Naudokite bs_block_fields() užregistravę blokus (init arba vėliau), kad gautumėte išspręstas laukų apibrėžtis ir nereikėtų skaityti vidinių registrų:
$fields = bs_block_fields('theme/card');
if ($fields === null) {
// Unknown block, or not a Blockstudio block.
}
Grąžinama užregistruotų laukų apibrėžčių masyvas, kuriame yra atributų filtrai, išplėstiniai tinkinti laukai, perrašymai ir įdėtinės grupės, skirtukai bei kartotuvai. Blockstudio blokas be laukų grąžina []. Rezultatas yra kopija: jį pakeitus užregistruotas blokas nepasikeičia.
Tai aprašai, o ne išsaugotos reikšmės. Norėdami patikrinti išsaugotą žymėjimą, naudokite bs_validate_block(), užuot prižiūrėję atskirą laukų peržiūros priemonę. Norėdami aprašyti bloko priimamas reikšmes, naudokite bs_block_schema(). WordPress priklausantys atributai lieka atskiri.
plėtiniais pridėti laukai nėra bs_block_fields() dalis. Jiems gauti naudokite bs_block_extension_fields(). Plėtiniai parenkami pagal bloko pavadinimą, todėl tai veikia ir su pagrindiniais bei trečiųjų šalių blokais:
$fields = array_merge(
bs_block_fields('core/paragraph') ?? [],
bs_block_extension_fields('core/paragraph')
);
Grąžinamame sąraše pateikiamos kiekvieno atitinkančio plėtinio laukų apibrėžtys plėtinių registravimo tvarka; jų struktūra tokia pati kaip bs_block_fields(). Jei blokui netaikomas joks plėtinys, grąžinama []. Plėtinių reikšmės išsaugomos tame pačiame attrs.blockstudio.attributes objekte kaip ir paties bloko laukų reikšmės, todėl visi ID priklauso tai pačiai vardų sričiai. Jei du plėtiniai apibrėžia tą patį ID, grąžinamos abi apibrėžtys ir jos keičia tą pačią reikšmę; atvaizduojant taikoma vėliau užregistruoto plėtinio apibrėžtis.
Norėdami perskaityti išsaugoto bloko reikšmes taip, kaip jas gauna jo šablonas, naudokite bs_block_values().
Naudokite bs_block_assets(), kad patikrintumėte aptiktus bloko CSS ir JavaScript. Jei reikia viso peržiūros dokumento su įdėtiniais blokais ir bendromis vykdymo aplinkos priklausomybėmis, naudokite Render::document(), kaip aprašyta pirmiau.
Išsaugotų reikšmių tikrinimas
Naudokite bs_validate_block() užregistravę blokus (init arba vėliau), kad prieš išsaugodami patikrintumėte programiškai sugeneruotus arba importuotus bloko atributus:
$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.
}
Perduokite visą attrs masyvą, o ne vien blockstudio.attributes. Atvaizduojant Blockstudio priimami ir deklaruoti aukščiausio lygio laukai, o jei pateikiamos abi reikšmės, pirmenybė teikiama įdėtinėms. Pagrindinių ir trečiųjų šalių blokų plėtiniai skaito tik blockstudio.attributes. Tuščias Blockstudio blokas yra valdomas ir grąžina [], o ne null.
Tikrinimas atliekamas aiškiai paprašius ir nekeičia duomenų. Jis neatvaizduoja šablonų, nekeičia reikšmių, neišsaugo įrašų, neužklausia medijos ir nevykdo duomenų užpildymo iškvietimų. Jis nevykdomas automatiškai išsaugant, sinchronizuojant puslapius ar atvaizduojant. Tai nėra dezinfekavimo funkcija, prieigos teisių patikra ar priedo egzistavimo patikra.
Kiekviename radinyje yra šie nekintantys raktai:
[
'code' => 'unknown_option',
'path' => 'steps/1/style',
'source' => 'block',
'message' => 'This value is not among the field options.',
'value' => 'c',
'expected' => ['a', 'b'],
]
Įrankiuose naudokite code, o ne išverstą message. source yra block arba
extension. Keliuose naudojami saugyklos raktai ir nuo nulio prasidedantys
pasikartojančios grupės eilučių arba pasirinkimo indeksai, be pradinio
pasvirąja brūkšniu. Pažodiniai ~ ir / rakte išvengiami įrašant
~0 ir ~1. Aukščiausio lygio grupė prideda prefiksą savo antriniams
laukams (cta_title); anoniminės grupės ir skirtukai neprideda jokio lygio. Grupės,
kurių ID yra kitoje grupėje arba pasikartojančioje grupėje, kūrimo įrankio
nepalaikomos, todėl jų raktai nepriimami. Pranešimų laukai neturi saugomos
reikšmės. Failų laukas leidžia naudoti jį lydintį <id>__size.
Blockstudio bloko šaknyje apskaitos raktai ir visuotiniai HTML atributai,
perduodami atvaizduojamam elementui, nelaikomi nežinomais laukais. Tai
neleidžia naudoti savavališkų raktų pasikartojančios grupės eilutėse ar
plėsti pagrindinių blokų.
| Kodas | Reikšmė | expected |
|---|---|---|
unknown_field |
Nė vienas iš išsaugotų laukų nenurodo šio saugyklos rakto. | Žinomi saugyklos raktai. |
unknown_option |
Pasirinkimas nėra tarp žinomų parinkčių. | Leidžiamos parinkčių reikšmės. |
wrong_type |
Išsaugota struktūra laukui nepalaikoma. | Tikėtina saugyklos šeima arba tipas. |
too_few_rows, too_many_rows |
Esama pasikartojanti grupė nepatenka į jos min arba max. |
Eilučių riba. |
definition_conflict |
Taikomi apibrėžimai tam pačiam raktui reikalauja skirtingų saugyklos struktūrų. | Kiekvieno apibrėžimo šaltinis ir lauko tipas. |
shadowed_value |
Įdėtinė reikšmė pakeičia kitokią aukščiausio lygio lauko reikšmę. | Laimėjusi įdėtinė reikšmė. |
extension_top_level |
Šablonas gali nuskaityti aukščiausio lygio reikšmę, bet plėtinio susiejimai – ne. | Privalomas kelias po blockstudio/attributes. |
unknown_attribute |
Aukščiausio lygio Blockstudio bloko rakto atvaizdavimo kelias nenuskaito, todėl jis atmetamas. | Registruoti atributų pavadinimai, plėtinio laukai ir blockstudio. |
missing_container |
Aukščiausiame lygyje išsaugotas attributes, disabled, name arba editor, o blockstudio trūksta. |
Privalomas kelias po blockstudio. |
invalid_container |
blockstudio arba blockstudio.attributes nėra objektas. |
object. |
Jei unknown_field radinio pranešime nurodytas saugojimo raktas yra nutolęs ne daugiau kaip trimis pakeitimais, jame įvardijamas artimiausias to paties lygio raktas, kaip ir taisyklėje, taikomoje nežinomiems nustatymams: This storage key is not declared by the block or its extensions. Did you mean "title"?
expected vis tiek pateikia visus žinomus raktus.
Ieškant atitikmenų nepaisoma raidžių registro ir tikrinami tik to konteinerio saugojimo raktai. Pranešimai yra išversti; integracijos turėtų naudoti code, path ir expected, o ne analizuoti pranešimo tekstą.
Aukščiausio lygio Blockstudio bloko raktas atmetamas prieš paleidžiant šabloną, jei jis nėra registruotas atributas (jo laukas, atributas, kuriuos WordPress prideda prie supports, lock ir metadata), atitinkamo plėtinio laukas, blockstudio, apskaitos raktas arba perduodamas HTML atributas. Toks raktas, pavyzdžiui, neteisingai įvestas lauko ID arba reikšmių objektas be blockstudio apvalkalo, pateikia radinį, nes blokas atvaizduojamas be tos reikšmės. Blokai, turintys tik plėtinio laukų, netikrinami dėl aukščiausio lygio raktų.
Priimtinos struktūros atitinka atvaizdavimą: kelių parinkčių pasirinkimai ir žymimieji langeliai gali turėti sąrašą, vieną parinkties objektą arba importuotą skaliarą, įskaitant skaitinį nulį. Skaičių laukams priimamos skaitinės eilutės. Failuose gali būti priedų ID, ID objektų, sąrašų arba eilučių nuorodų. Nuorodų ir piktogramų reikšmės turi būti objektai; tinkinti laukų tipai naudoja registruotą atributo tipą.
attributes lauke laikomas porų sąrašas su netuščiu pavadinimu attribute ir skaliaru value; pasirenkami metaduomenys, pavyzdžiui, data.media, išsaugomi.
WordPress prieš atvaizdavimą patikrina registruotus aukščiausio lygio atributus, todėl gali atmesti struktūrą, priimamą blockstudio.attributes viduje. Pavyzdžiui, radijo mygtuko reikšmė "a" veikia įdėtiniame objekte, bet aukščiausiame lygyje atmetama, nes jos registruotas tipas yra object. Tokia reikšmė pateikia wrong_type.
Naudokite įdėtinį objektą tai pačiai saugojimo struktūrai, kurią įrašo redaktorius.
Trūkstami laukai nėra privalomi. Tuščios įdėtinės reikšmės (null, false, '', []) ir išjungti laukai nesukuria reikšmių klaidų. Aiškiai tuščia pasikartojanti grupė vis tiek tikrinama pagal min; nesanti arba išjungta grupė netikrinama.
Apie tuščią aukščiausio lygio reikšmę pranešama, jei WordPress ją atmeta ir vietoj jos atkuria netuščias numatytąsias reikšmes. Ta pati reikšmė įdėtiniame objekte gali ją išvalyti. Apibrėžimų konfliktai nurodomi net tada, kai raktas neturi išsaugotos reikšmės.
Statinės parinktys ir registravimo metu jau išspręstos užpildymo parinktys tikrinamos dar kartą nekviečiant užpildymo. Nuotolinės fetch parinktys ir užpildymo argumentai, kuriuose yra {attributes.*}, praleidžiami. Spalvų ir gradientų reikšmės gali būti tinkintos, nebent nustatyta disableCustomColors arba disableCustomGradients.
Tikrinamos išsaugotos reikšmės, o ne default, fallback ar redaktoriaus tikrinimo taisyklės.
Atitinkami plėtinio laukai įtraukiami į kiekvieną bloką, kuriam jie skirti. Kaip ir atvaizduojant, bloke arba jo plėtiniuose šaknyje laimi vėlesni apibrėžimai. Bloko laukas ir plėtinio laukas lieka atskirais to paties rakto apibrėžimais, todėl taikomi abu. Pasikartojančių grupių eilutėse atvaizduoklis kiekviename šaltinyje skaito pirmą lauką su atitinkančiu ID, todėl taikomos jo parinktys ir ribos. Dubliuoti apibrėžimai paliekami konfliktų diagnostikai: nesuderinamos saugyklos struktūros pateikia definition_conflict, net jei vėlesnis dublikatas atvaizduojant neskaitomas.
Funkcija tikrina vieną bloką. Tikrindami dokumentą pereikite per innerBlocks; sinchronizuoti šablonai ir kitos nuorodos automatiškai neišplečiamos. Komanda wp bs blocks validate pereina vieno ar daugiau įrašų blokus ir pateikia jų blokų kelius.
Svetainės su tinkintu atvaizdavimo metu vykdomu sprendikliu gali pritaikyti radinius nekeisdamos išsaugotų duomenų:
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);
Visada grąžinkite radinių sąrašą; grąžinus [] blokas priimamas. Šis filtras veikia tik valdomiems blokams, o null rezultatui netaikomas.
Išsaugotų reikšmių aprašymas
Naudokite bs_block_schema() po bloko registravimo (init arba naujesnėje versijoje), kad aprašytumėte bloko saugomas reikšmes, pavyzdžiui, sugeneruotumėte bloko žymėjimą įrankyje ar DI integracijoje arba patikrintumėte įvestį maršrute REST:
$schema = bs_block_schema('theme/card');
if ($schema === null) {
// No Blockstudio fields or matching extensions apply.
}
Rezultatas yra objekto, išsaugoto attrs.blockstudio.attributes, JSON schema. Ji apima bloko ir atitinkančių plėtinių laukus bei saugojimo raktus, kuriuos naudoja tikrinimas: aukščiausio lygio grupė prideda priešdėlį savo antriniams laukams, anoniminės grupės ir skirtukai neprideda lygio, o failų laukas prideda savo <id>__size papildomą lauką. Kartotuvai yra eilučių objektų sąrašai su minItems ir maxItems reikšmėmis iš min ir max. additionalProperties yra false laukų saugojimo šaknyje ir kartotuvo eilutėse. Objektų tipo laukai, pavyzdžiui, nuorodos ir pasirinktiniai objektai, gali turėti savo metaduomenis. Blokas be laukų neturi properties, todėl atitinka tik tuščią objektą.
Kiekvienas laukas aprašomas kanonine forma, kurią priima bs_validate_block():
| Laukas | Schema |
|---|---|
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block |
Eilutė. |
number, range |
Skaičius su minimum ir maximum reikšmėmis iš min ir max. |
toggle |
Loginė reikšmė. |
select, radio, checkbox |
Parinkties reikšmė arba parinkčių reikšmių sąrašas, skirtas checkbox ir multiple, su enum. |
color, gradient |
Eilutė su enum, kai nustatyta disableCustomColors arba disableCustomGradients. |
token |
Eilučių sąrašas. |
files |
Neneigiamas sveikasis priedo ID arba ID sąrašas su multiple. |
link |
Objektas su url, title ir opensInNewTab; url yra privalomas. |
icon |
Objektas su set, subSet ir icon; set ir icon yra privalomi. |
attributes |
Objektų sąrašas su netuščiu attribute ir skaliariniu value. |
repeater |
Eilučių objektų sąrašas. |
| Pasirinktiniai laukų tipai | Jų registruotas atributo tipas. |
enum pateikia parinktis, kurias tikrina tikrinimo priemonė: statines parinktis ir registravimo metu jau išspręstas užpildymo parinktis. Nuotolinės fetch parinktys ir užpildymo argumentai su {attributes.*} neturi enum. Raktas praleidžiamas, jei jo aprašuose nurodytos skirtingos saugojimo formos, nes tikrinimas pateikia visas po juo išsaugotas reikšmes. Kai bloko laukas ir plėtinio laukas naudoja tą patį raktą, enum pateikia reikšmes, kurias priima abu laukai. Bendri kartotuvai sujungia antrinius laukus ir taiko griežtesnes abiejų aprašų eilučių ribas. Kartotuvo eilutėse taikomas pirmasis lauką kiekviename šaltinyje atitinkantis ID, kaip ir atvaizduojant. Aiškiai apibrėžtas laukas, pavadintas <id>__size, turi pirmenybę prieš automatiškai pridedamą failo dydžio papildomą lauką.
Kai uždaras laukas neturi galimų pasirinkimų arba dvi taikytinos parinkčių aibės neturi bendrų reikšmių, jo kanoninė reikšmė yra null, kai pasirenkama viena reikšmė, arba tuščias sąrašas, kai pasirenkamos kelios reikšmės. Tuščias parinkčių sąrašas nepaverčia lauko neribotu. Nuotoliniai ir nuo atributų priklausantys pasirinkimai lieka atviri.
Lauko label tampa title, jo help tampa description, o default paliekamas kaip anotacija. Pačios schemos title yra bloko pavadinimas. Laukai niekada nėra privalomi, o sąlyginė logika į schemą neįtraukiama.
Apribojimams naudojami tik raktiniai žodžiai, kuriuos tikrina rest_validate_value_from_schema(), todėl schema gali būti tiesiogiai naudojama kaip REST maršruto ar galimybės įvesties schema:
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
$result = rest_validate_value_from_schema($values, $schema);
}
Schemoje aprašoma viena forma kiekvienam laukui; tikrinimas taip pat priima importuotas formas, pavyzdžiui, parinkčių objektus, skaitines eilutes ir ID objektus. Ji nepakeičia bs_validate_block(): apibrėžimų konfliktai yra konfigūracijos problemos ir vis tiek gali pateikti radinių, net jei konfliktuojantis raktas praleidžiamas. Tikrinimo filtrai taip pat gali nustatyti konkrečiai svetainei taikomas taisykles. Naudokite bs_validate_block(), kad patikrintumėte išsaugotą turinį. Svetainėse, kuriose naudojamas pasirinktinio atvaizdavimo metu veikiantis sprendiklis, schemą galima pritaikyti filtru blockstudio/blocks/attributes/schema.
PHP funkcijos
Be duomenų
Paprasčiausiu atveju funkcija priima vieną reikšmę – puslapyje atvaizduojamo bloko ID.
bs_render_block('blockstudio/cta');
Su duomenimis
Norint atvaizduoti bloką su pasirinktiniais duomenimis, vietoj vienos pirmojo parametro reikšmės reikia naudoti masyvą. Duomenų rakto reikšmė bus perduota į $attributes ir $a kintamąjį jūsų bloko šablone.
bs_render_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
]);
Įdėjimas į kitus blokus
Blokus galima įdėti vieną į kitą naudojant funkciją bs_block kartu su galingu kintamuoju $content bloko šablonuose.
<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',
]
])
]);
Mygtuko blokas bus atvaizduotas vietoj kintamojo $content bloko šablone.
Įterpti blokai, atvaizduojami naudojant bs_render_block() arba bs_block(), visada pateikia sąsajos pusėje apdorotą HTML, net kai tuo metu atvaizduojama pirminio bloko redaktoriaus peržiūra. Šablono pseudo komponentai, tokie kaip <RichText /> ir <InnerBlocks />, apdorojami prieš grąžinant įterptą bloką.
Keli turinio lizdai
Taip pat galima sukurti kelis turinio lizdus tiesiog paverčiant kintamąjį $content asociatyviuoju masyvu ir funkcijoje bs_block iškviečiant atitinkamus jo raktus.
<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']
])
]
]);
Blokų žymos
Įterpkite bet kurį bloką naudodami HTML žymos sintaksę. Palaikomi du formatai:
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
Abu formatai atvaizduoja tą patį bloką. Sintaksė <bs:> brūkšnelį paverčia vardų srities skirtuku (acme-hero virsta acme/hero). Brūkšneliai tikrinami iš kairės į dešinę, laimi pirmasis registruotas variantas, todėl išsprendžiamos ir brūkšnelių turinčios vardų sritys: <bs:acme-ui-button> tikrina acme/ui-button, tada acme-ui/button. Sintaksėje <block> visas bloko pavadinimas nurodomas kaip atributas name.
Veikia tiek Blockstudio blokai, tiek pagrindiniai WordPress blokai. Blockstudio blokai atvaizduojami per visą apdorojimo grandinę (šablonus, Tailwind, išteklius). Pagrindiniai blokai atvaizduojami naudojant WordPress blokų atvaizdavimo sistemą ir įtaisytuosius blokų atvaizduoklius.
Kaip tai veikia
Blokų žymos veikia skirtingai, atsižvelgiant į tai, kur jos pateikiamos:
Blokų šablonuose ir įrašų turinyje žymos vykdymo metu pakeičiamos atvaizduotais HTML. Rezultatas yra galutinis nurodyto bloko ženklinimas, tiesiogiai įterptas į puslapį. Redaktoriuje nėra WordPress bloko. Tai tik atvaizdavimo mechanizmas.
Puslapiuose, šablonų rinkiniuose ir svetainės šablonuose žymos paverčiamos įtaisaisiais WordPress blokais prieš sinchronizuojant failo šaltinį arba registruojant jį sistemoje WordPress. Tai reiškia, kad blokai rodomi redaktoriuje, juos galima redaguoti, jei tai palaiko paskirties vieta, ir jie pereina visą WordPress bloko gyvavimo ciklą. Žymų sintaksė yra trumpesnis būdas apibrėžti bloko turinį šablonų failuose.
Šis skirtumas svarbus: šablonuose blokų žymos pateikia išvestį, o puslapiuose, šablonų rinkiniuose ir svetainės šablonuose jos sukuria įtaisinius blokus.
Blokų šablonuose
Blokų žymos šablonuose Twig ir PHP atvaizduojamos automatiškai. Nustatymų nereikia. Tai apima sintakses <bs:> ir <block>, taip pat visas registruotas prefikso ir alternatyvių žymų formas, todėl šablonas gali jas pateikti tiesiogiai, užuot iškvietęs bs_render_block(). Išvestis atvaizduojama HTML ir tiesiogiai įterpiama į bloko šablono išvestį:
<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>
Įrašo turinyje
Puslapio lygmens atvaizdavimas (įrašo turinys, valdiklių sritys) pagal numatytuosius nustatymus išjungtas:
{
"blockTags": {
"enabled": true
}
}
Arba naudojant filtrą:
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');
Sintaksė
Savaime užsidarančios žymos:
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />
Suporuotos žymos su vidiniu turiniu:
<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>
Laisvai derinkite abi formas. Jos gali būti įdėtos viena į kitą:
<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>
Prefiksų trumpiniai
Blokų žymose taip pat galima naudoti konkrečiam projektui skirtus prefiksų trumpinius. Užregistruokite prefiksą su viena ar keliomis vardų sritimis, ir Blockstudio susieja <prefix-slug> su pirmuoju užregistruotu bloku nurodyta vardų sričių tvarka:
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 />
Pagal pirmiau pateiktą pavyzdį <theme-card> susiejama su theme-components/card, <theme-button> naudojama bsui/button, jei theme-components/button neužregistruota, o <theme-ui-feature-matrix> susiejama su theme-components/ui-feature-matrix.
Prefiksus galima ir jungti. Jei prefiksuotos žymos nepavyksta susieti tiesiogiai, o likusi dalis pati yra registruota prefikso žyma, paieška kartojama. Taip prekės ženklo prefiksas gali būti naudojamas kartu su vardų srities prefiksu:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components'];
$prefixes['ui'] = ['bsui'];
return $prefixes;
});
<theme-ui-input />
<theme-ui-input> neturi bloko theme-components/ui-input, todėl pereinama prie prefikso ui ir susiejama su bsui/input. Tiesioginės atitikties visada laimi prieš įdėtinę paiešką, o leidimo ir draudimo taisyklės taikomos galutiniam susietam blokui.
Prefiksus taip pat galite konfigūruoti faile blockstudio.json:
{
"blockTags": {
"prefixes": {
"theme": ["theme-components", "bsui"]
}
}
}
Prefiksus gali sudaryti tik mažosios raidės arba skaičiai; jie turi prasidėti raide ir negali turėti brūkšnelių. Aiškiai apibrėžti alternatyvūs pavadinimai faile blockstudio/block_tags/tag_aliases turi pirmenybę prieš prefiksų paiešką. Nežinomos prefiksuotos žymos paliekamos nepakeistos.
Prefiksai ir alternatyvios žymos tebėra patogūs kuriant turinį. Kanoninė ir perkeliama forma visada yra <bs:namespace-slug>, nes joje įrašytas tikrasis bloko pavadinimas, nepriklausomas nuo projekto filtrų:
<bs:theme-components-card />
<bs:bsui-input />
Blockstudio pavyzdžiuose, generuojamose diagnostikos ataskaitose ir programinėje išvestyje naudojama ši kanoninė forma. Projektuose, kuriuose norima pašalinti senesnį trumpinį, galima naudoti atskirą kanoninių žymų perkėlimo įrankį, kuris pirmiausia veikia bandomuoju režimu: kanoninių žymų perkėlimas. Jo nereikia paleisti WordPress.
Pagrindiniai blokai
Galima naudoti bet kurį bloką, turintį registruotą atvaizduoklį:
<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>
Arba naudojant sintaksę <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>
Leidimo ir draudimo sąrašai
Nustatykite, kuriuos blokus galima atvaizduoti naudojant žymas:
{
"blockTags": {
"enabled": true,
"allow": ["mytheme/*", "core/*"],
"deny": ["mytheme/internal-*"]
}
}
allow leidžia tik šablonus atitinkančias žymas. deny pašalina atitinkančias žymas ir turi pirmenybę. Abi parinktys palaiko * pakaitos simbolius, naudojant fnmatch(). Jos taikomos abiem sintaksėms ir atvaizdavimui tiek šablono, tiek puslapio lygmeniu.
Filtrai: blockstudio/block_tags/allow ir blockstudio/block_tags/deny.
HTML tiesioginis perdavimas
Atributai su prefiksu data- perduodami į atvaizduojamo bloko šakninį elementą. Atributai su prefiksu html- taip pat perduodami, bet prefiksas pašalinamas. Veikia su abiem sintaksėmis. Tiesiogiai perduotas atributas pakeičia esamą šakninio elemento reikšmę, o ne ją papildo, todėl html-class pakeičia paties bloko klases.
Blockstudio blokas taip pat įrašo į savo šakninį elementą visuotinius atributus, kurių nedeklaruoja kaip laukų: id, style, role, title, lang, dir, hidden, tabindex ir visus aria-* atributus. Deklaruotas laukas visada turi pirmenybę, todėl blokas su lauku title vietoj to gauna reikšmę iš $a['title']. Perduodami stiliai apdorojami per safecss_filter_attr(), filtras WordPress taikomas stiliaus atributams įrašo turinyje, o perduoti stiliai pridedami prie šablone jau nustatytų stilių.
Atributų reikšmės yra HTML, todėl išraiškos dekoduojamos vieną kartą, kai išanalizuojama žyma: title="Tom & Jerry" šabloną pasiekia kaip Tom & Jerry, o išvestyje vėl užkoduojama. Cituojamose reikšmėse gali būti >, kaip kad būna Tailwind variantuose ir animacijos selektoriuose; tai veikia tiek savaime užsidarančiose, tiek suporuotose žymose.
Bet kuris kitas bloko nedeklaruotas atributas, įskaitant class, niekada nepasiekia HTML. Kai įjungta WP_DEBUG, Blockstudio per _doing_it_wrong() pateikia kiekvieno tokio atributo ataskaitą po vieną kartą per užklausą. Deklaruokite jam lauką arba įrašykite jį kaip data-, aria- arba html- atributą.
<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>
Pasirinktiniai atvaizduokliai
Užregistruokite pasirinktinius blokų atvaizduoklius papildomiems blokų tipams. Atvaizduokliams perduodamas atributų masyvas ir vidinio turinio eilutė, o jie grąžina WordPress bloko masyvą:
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);
Jei konteinerio blokų vidinį turinį reikia išanalizuoti į antrinius blokus, tame pačiame filtre pridėkite antrą įrašą:
$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 taikomas ir blokų žymoms, ir pasirinktiniams blokams, pasirenkamiems per blockstudio/parser/element_mapping. Šį kablį tinka naudoti, kai projekto blokas, susietas su elementu, turi perkelti vidinį tekstą į lauką Blockstudio arba sukurti pasirinktinį bloko masyvą.
blockstudio/block_tags/renderers ir blockstudio/parser/renderers gauna tą patį registrą ir vienodos formos iškvietimo funkciją. Jie tebepalaikomi dėl suderinamumo ir galutinio lygmens analizatoriaus perrašymų. Filtrai vykdomi tokia tvarka:
blockstudio/block_tags/buildersblockstudio/block_tags/renderersblockstudio/parser/renderers
Vėlesnis filtras gali pakeisti atvaizduoklį, užregistruotą ankstesniu filtru.
Naudojimas programiškai
Pritaikykite žymų atvaizdavimą bet kuriai eilutei iš PHP:
$html = apply_filters('blockstudio/block_tags/render', $content);
Komponentai
Blokų žymas galima derinti su komponentais. Komponentai yra blokai, atvaizduojami tik programiškai ir niekada nerodomi redaktoriuje.
<bs:mytheme-card title="My Card" description="Card content." />
Analizatorius
Blokų žymas apdoroja lengvas eilučių analizatorius, pakeičiantis DOMDocument. Analizatorius palaiko sintakses <bs:> ir <block>, įdėtas to paties pavadinimo žymas, sekdamas jų įdėjimo gylį, cituojamas atributų reikšmes ir rekursinius konteinerio blokus. Jis sukurtas būtent šiam atvejui, veikia greičiau už DOMDocument ir WordPress WP_HTML_Tag_Processor, be to, išvengiama žinomų DOMDocument problemų, kai pašalinami vardų sričių prefiksai ir atributų pavadinimai pakeičiami mažosiomis raidėmis.
Puslapiuose, šablonų rinkiniuose ir svetainės šablonuose tas pats analizatorius taip pat apdoroja neapdorotus HTML elementus (<p>, <div>, <h1> ir kt.) ir susieja juos su atitinkamais pagrindiniais WordPress blokais.
Jei elementų susiejime <p> nurodomas registruotas ne pagrindinis Blockstudio blokas, deklaruojantis content raiškiojo teksto atributą, vidinis HTML automatiškai nukreipiamas į tą atributą content; tai apima ir įdėtines žymas, tokias kaip code ir img, susietas elementų lygmeniu. Jei pastraipoje yra tik vienas vaikinis elementas – vaizdas – ji paverčiama bloku, su kuriuo susiejamas <img>. Įdėtos blokų žymos arba blokų lygmens HTML toliau apdorojamos įprastai, kaip vidiniai blokai. <block name="core/shortcode"> išsaugo trumpinio tekstą kaip bloko turinį.