Programmiliselt renderdamine
Kuna Gutenberg on muutunud klientidele hõlpsasti muudetavate veebisaitide loomisel peamiseks vahendiks, on mõistlik luua kõik vajalikud veebisaidi osad plokkidena. See lähenemine sobib enamikule, kuid edasijõudnud kasutajad ja erijuhud võivad nõuda plokkide kasutamist ka väljaspool redaktorit.
Blockstudio pakub plokkide programmiliseks renderdamiseks kahte võimalust:
- PHP funktsioonid:
bs_render_blockjabs_blockrenderdamiseks koodist PHP - HTML märgendid:
<bs:block-name>märgendid, mis asendatakse ploki väljundiga ükskõik kus lehel
Toetatud on kõik Blockstudio-i erifunktsioonid, näiteks tekstisisesed stiilid, skriptid ja piiratud ulatusega stiilid.
Ka saared töötavad nende renderdusteedega. Funktsiooniga bs_render_block() või bs_block() renderdatud dünaamiline saar või plokimärgend tagastab sama kohatäitemärgendi nagu postituse sisust renderdatud plokk. Kui see märgend on vastuses olemas, lisatakse esikülje käituskeskkond.
Struktureeritud kompositsioonid ja terviklikud dokumendid
Pika kasutuseaga tööriistade, eelvaadete, eksporditavate failide ja komponentide galeriide jaoks kasutage versioonitud Blockstudio\Render API. See võtab vastu ühe deklaratsiooni või järjestatud loendi ning renderdab selle ilma väljundit väljastamata:
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'],
]);
Kanoonilisel normaliseeritud deklaratsioonil on neli võtit:
[
'name' => 'theme/card',
'attributes' => [],
'content' => '',
'children' => [],
]
data, inner, innerBlocks, root, layers ja example on sisendi mugavussüntaksid, mis normaliseerimisel eemaldatakse. Pesastatud deklaratsioonid renderdatakse rekursiivselt sama Blockstudio töövoo kaudu.
Render::document() tagastab schemaVersion, html, body, blocks, assets, warnings ja errors. Väärtus assets eristab head, footer, styles, scripts, modules, interactivity, ui ja tailwind. Plokkide loend ja varad hõlmavad valitud mallide viidatud sõltuvusi, kuid jätavad välja sõltumatud ja ainult redaktoris kasutatavad varad.
Tervikdokumentides saab määrata väärtused bodyClasses/bodyAttributes ning soovi korral ümbritseda renderdatud sisu elementidega contentElement, contentClasses ja contentAttributes. Ümbris on piiratud lubatud elemendi nimega; tagastatud body jääb ümbritsemata renderdatud sisuks. Suvandid head ja footer lisavad usaldatud dokumendimärgistuse vastavasse kohta ning kaasatakse tagastatud varasõltuvuste hulka.
Juba renderdatud HTML ümber dokumendi koostamiseks esitage selle teadaolevad juurplokkide nimed:
$document = Render::document_from_html(
$rendered_html,
['theme/hero', 'theme/button'],
['title' => 'Homepage preview']
);
Kasutage Render::content() serialiseeritud WordPress ploki sisu jaoks. Tarbijad, kes renderdavad ühe päringu jooksul mitu sõltumatut dokumenti, peaksid nende vahel kutsuma Blockstudio\Batch_Render::reset(); Canvas::documents() teeb seda automaatselt.
Renderdamine väljaspool lehte
Blockstudio lisab iga renderdatava ploki ette kommentaari <!--blockstudio/namespace/slug-->. Esilehel loeb puhver neid kommentaare, et näha, millised plokid on olemas, laadib nende varad ja eemaldab kommentaarid enne vastuse saatmist.
Väljund, mida see puhver ei töötle, säilitab kommentaarid. See kehtib REST vastuste, voogude, AJAX-i töötlejate ning HTML kohta, mille salvestate või saadate mujale pärast do_blocks(), Render::content() või bs_render_block() kasutamist. Nende eemaldamiseks kasutage
bs_strip_render_markers():
$html = bs_strip_render_markers(do_blocks($post->post_content));
Funktsioon eemaldab registreeritud Blockstudio plokkide kommentaarid ja jätab kõik muu puutumata, sealhulgas muud HTML kommentaarid. See tuvastab samad markerid, mida eemaldab lehe puhver. Kutsuge seda pärast plokkide registreerimist (init või hiljem).
Ärge eemaldage märgendust, mis prinditakse endiselt puhvriga töödeldavale esilehele. Leht vajab kommentaare, et teada, millised plokivarad laadida, ja Blockstudio eemaldab need ise kõige lõpus.
Kommentaaride eemaldamine ei lisa varasid. Ploki CSS ja JavaScript failid lisab ainult lehe puhver. Kasutage bs_block_assets() või Render::document(), kui tarbija neid samuti vajab.
Plokkide uurimine
Kasutage pärast plokkide registreerimist (init või hiljem) funktsiooni bs_block_fields(), et saada lahendatud väljade määratlused ilma sisemisi registreid lugemata:
$fields = bs_block_fields('theme/card');
if ($fields === null) {
// Unknown block, or not a Blockstudio block.
}
Tagastatav väärtus on registreeritud väljade määratluste massiiv, sealhulgas atribuudifiltrid, laiendatud kohandatud väljad, ülekirjutused ning pesastatud rühmad, vahekaardid ja kordajad. Väljadeta Blockstudio plokk tagastab []. Tulemus on koopia: selle muutmine ei muuda registreeritud plokki.
Need on määratlused, mitte salvestatud väärtused. Salvestatud märgistuse valideerimiseks kasutage eraldi väljade läbikäija hooldamise asemel bs_validate_block(). Ploki aktsepteeritavate väärtuste kirjeldamiseks kasutage bs_block_schema(). WordPress hallatavad atribuudid jäävad eraldi.
laienduste lisatud väljad ei kuulu hulka bs_block_fields(). Nende saamiseks kasutage funktsiooni bs_block_extension_fields(). See leiab laiendused ploki nime järgi, nii et see toimib ka tuuma ja kolmandate osapoolte plokkidega:
$fields = array_merge(
bs_block_fields('core/paragraph') ?? [],
bs_block_extension_fields('core/paragraph')
);
Tagastatav väärtus sisaldab kõigi sobivate laienduste väljade määratlusi laienduste registreerimise järjekorras ja sama struktuuriga nagu bs_block_fields(). Plokk, millele ükski laiendus ei vasta, tagastab []. Laienduste väärtused salvestatakse samasse attrs.blockstudio.attributes objekti, kus on ploki enda väljade väärtused, seega kasutavad kõik ID-d ühist nimeruumi. Kui kaks laiendust määratlevad sama ID, tagastatakse mõlemad määratlused ja need muudavad sama väärtust; renderdamisel rakendub hiljem registreeritud laienduse määratlus.
Salvestatud ploki väärtuste lugemiseks kujul, nagu mall need saab, kasutage funktsiooni bs_block_values().
Ploki tuvastatud CSS ja JavaScript uurimiseks kasutage funktsiooni bs_block_assets(). Täieliku eelvaatedokumendi, sealhulgas pesastatud plokkide ja jagatud käitusaegsete sõltuvuste jaoks kasutage eespool kirjeldatud funktsiooni Render::document().
Salvestatud väärtuste valideerimine
Kasutage pärast plokkide registreerimist (init või hiljem) funktsiooni bs_validate_block(), et kontrollida programmiliselt loodud või imporditud ploki atribuute enne nende salvestamist:
$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.
}
Edastage täielik attrs massiiv, mitte ainult blockstudio.attributes. Blockstudio renderdamine aktsepteerib deklareeritud välju ka tipptasemel ning kui antakse mõlemad, eelistatakse pesastatud väärtusi. Tuuma ja kolmandate osapoolte plokkide laiendused loevad ainult väärtust blockstudio.attributes. Tühi Blockstudio plokk on hallatav ja tagastab [], mitte null.
Valideerimine toimub selgesõnaliselt ja ainult lugemiseks. See ei renderda malle, muuda väärtusi, salvesta postitusi, päri meediat ega käivita täitmise tagasikutseid. See ei käivitu automaatselt salvestamisel, lehe sünkroonimisel ega renderdamisel. See ei ole puhastaja, autoriseerimiskontroll ega kontroll selle kohta, kas manused on olemas.
Iga leid sisaldab järgmisi püsivaid võtmeid:
[
'code' => 'unknown_option',
'path' => 'steps/1/style',
'source' => 'block',
'message' => 'This value is not among the field options.',
'value' => 'c',
'expected' => ['a', 'b'],
]
Kasuta tööriistades code, mitte tõlgitud message. source on block või
extension. Teed kasutavad salvestusvõtmeid ja kordaja rea või valiku nullist algavaid indekseid, ilma alguseta kaldkriipsuta. Võtmes olevad literaalid ~ ja / paomärgistatakse kui ~0 ja
~1. Ülataseme grupp lisab oma eesliite alamväljadele (cta_title); anonüümsed grupid ja vahekaardid taset juurde ei lisa. Teise grupi või kordaja sees oleva ID-ga grupid ei ole koostaja poolt toetatud, seega nende võtmeid ei aktsepteerita. Sõnumiväljadel pole salvestatud väärtust. Failiväli lubab oma kaaslast <id>__size.
Blockstudio ploki juurtasandil ei loeta haldusvõtmeid ega globaalseid HTML atribuute, mis edastatakse renderdatavale elemendile, tundmatuteks väljadeks. See ei luba suvalisi võtmeid kordaja ridades ega tuumaplokkide laiendusi.
| Kood | Tähendus | expected |
|---|---|---|
unknown_field |
Ükski alles jäetud väli ei deklareeri seda salvestusvõtit. | Teadaolevad salvestusvõtmed. |
unknown_option |
Valik ei kuulu teadaolevate valikute hulka. | Lubatud valikuväärtused. |
wrong_type |
Salvestatud struktuur ei ole väljaga toetatud. | Oodatav salvestusperekond või tüüp. |
too_few_rows, too_many_rows |
Olemasolev kordaja jääb väljapoole selle min või max. |
Rea piirang. |
definition_conflict |
Ühe võtme kohaldatavad määratlused nõuavad erinevaid salvestusstruktuure. | Iga määratluse allikas ja väljatüüp. |
shadowed_value |
Pesastatud väärtus kirjutab üle erineva ülataseme välja väärtuse. | Võitnud pesastatud väärtus. |
extension_top_level |
Mall saab lugeda ülataseme väärtust, kuid laienduste sidumised mitte. | Selle nõutav tee asukohas blockstudio/attributes. |
unknown_attribute |
Blockstudio ploki ülataseme võtit renderdamistee ei loe ja see jäetakse välja. | Registreeritud atribuutide nimed, laiendusväljad ja blockstudio. |
missing_container |
attributes, disabled, name või editor on salvestatud ülatasemel ja blockstudio puudub. |
Selle nõutav tee asukohas blockstudio. |
invalid_container |
blockstudio või blockstudio.attributes ei ole objekt. |
object. |
Leiu unknown_field teates nimetatakse lähimat sama taseme salvestusvõtit, kui see erineb kuni kolme muudatuse võrra; seda reeglit kasutavad tundmatute seadete puhul: This storage key is not declared by the block or its extensions. Did you mean "title"?
expected loetleb endiselt kõik teadaolevad võtmed.
Võrdlemisel eiratakse suurt ja väikest algustähte ning arvesse lähevad ainult selle konteineri salvestusvõtmed. Teated tõlgitakse; integratsioonid peaksid teate teksti parsimise asemel kasutama code, path ja expected.
Blockstudio ploki ülataseme võti, mis pole registreeritud atribuut (selle väljad, atribuudid, mille WordPress lisab supports, lock ja metadata jaoks), vastava laienduse väli, blockstudio, haldusvõti ega edasi antud HTML atribuut, jäetakse enne malli käivitamist välja. Selline võti, näiteks valesti kirjutatud välja ID või väärtuste objekt, mis on salvestatud ilma ümbriseta blockstudio, annab tulemuse, sest plokk renderdatakse selle väärtuseta. Plokke, mis sisaldavad ainult laiendusvälju, ülataseme võtmete suhtes ei kontrollita.
Aktsepteeritud struktuurid järgivad renderdamist: mitmikvalikud ja märkeruudud võivad sisaldada loendit, üht valikuobjekti või imporditud skalaarväärtust, sealhulgas numbrilist nulli. Arvude puhul aktsepteeritakse arvulisi stringe. Failid võivad sisaldada manuse ID-sid, ID-objekte, loendeid või stringviiteid. Lingi- ja ikooniväärtused peavad olema objektid; kohandatud väljatüübid kasutavad registreeritud atribuuditüüpi.
attributes väli sisaldab paaride loendit, millel on mittetühi attribute nimi ja skalaarne value; valikulised metaandmed, näiteks data.media, säilitatakse.
WordPress valideerib registreeritud ülataseme atribuute enne renderdamist, mistõttu võidakse tagasi lükata struktuur, mida aktsepteeritakse objekti blockstudio.attributes sees. Näiteks raadionupu väärtus "a" töötab pesastatud objektis, kuid ülatasemel jäetakse see välja, sest seal on registreeritud tüüp object. Selline väärtus annab tulemuse wrong_type.
Kasuta sama salvestusstruktuuri jaoks pesastatud objekti, mida redaktor kirjutab.
Puuduvad väljad pole kohustuslikud. Tühjad pesastatud väärtused (null, false, '', []) ja keelatud väljad ei anna väärtusevigu. Selgesõnaliselt tühi kordaja kontrollitakse siiski vastu min; puuduvat või keelatud kordajat ei kontrollita.
Tühi ülataseme väärtus tuuakse välja, kui WordPress selle eemaldab ja taastab selle asemel mittetühja vaikeväärtuse. Sama väärtus pesastatud objektis võib selle tühjendada. Määratluste konfliktid tuuakse välja ka siis, kui võtmel pole salvestatud väärtust.
Staatilisi valikuid ja registreerimisel juba lahendatud asustusvalikuid kontrollitakse asustajat uuesti käivitamata. Kaugvalikud fetch ja asustaja argumendid, mis sisaldavad {attributes.*}, jäetakse vahele. Värvi- ja gradiendiväärtused võivad olla kohandatud, välja arvatud juhul, kui määratud on disableCustomColors või disableCustomGradients.
See kontrollib salvestatud väärtusi, mitte default, fallback ega redaktori valideerimisreegleid.
Vastavad laiendusväljad kaasatakse igasse plokki, millele need sihitud on. Hilisemad määratlused jäävad plokis või selle juure laiendustes peale, nagu renderdamisel. Ploki enda väli ja laiendusväli jäävad sama võtme eraldi määratlusteks ning mõlemat rakendatakse. Kordaja ridade sees loeb renderdaja igast allikast esimese sobiva ID-ga välja, seega kehtivad selle valikud ja piirangud. Konfliktide diagnostikaks säilitatakse korduvad määratlused: ühildumatud salvestusstruktuurid annavad definition_conflict, isegi kui hilisemat korduvat määratlust renderdamisel ei loeta.
Funktsioon kontrollib üht plokki. Dokumendi valideerimisel käi läbi innerBlocks; sünkroonitud mustreid ja muid viiteid automaatselt lahti ei laiendata. Käsk wp bs blocks validate käib läbi ühe või mitme postituse plokid ja esitab nende plokiteed.
Kohandatud renderdamisaegse lahendajaga saidid saavad tulemusi kohandada salvestatud andmeid muutmata:
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);
Tagasta alati tulemuste loend; [] tagastamine aktsepteerib ploki. See filter käivitub ainult hallatavate plokkide puhul, mitte null tulemuse korral.
Salvestatud väärtuste kirjeldamine
Kasutage bs_block_schema() pärast ploki registreerimist (init või hiljem), et kirjeldada plokki salvestatavaid väärtusi, näiteks ploki märgistuse loomiseks tööriistas või tehisintellekti integratsioonis või sisendi kontrollimiseks marsruudis REST:
$schema = bs_block_schema('theme/card');
if ($schema === null) {
// No Blockstudio fields or matching extensions apply.
}
Tulemuseks on objektis attrs.blockstudio.attributes salvestatud objekti JSON skeem. See hõlmab ploki välju ja sobivate laienduste välju koos valideerimisel kasutatavate salvestusvõtmetega: tipptaseme rühm lisab alamväljade ette prefiksi, anonüümsed rühmad ja vahelehed taset ei lisa ning failiväli lisab selle kaasvälja <id>__size. Kordusväljad on ridade objektide loendid, millel on min ja max põhjal minItems ja maxItems. additionalProperties on väljade salvestamise juurtaseme ja kordusridade piires false. Objektiväärtustega väljad, näiteks lingid ja kohandatud objektid, võivad kanda oma metaandmeid. Väljatringita plokil puudub properties, seega sobib ainult tühi objekt.
Iga välja kirjeldatakse kanoonilisel kujul, mida aktsepteerib bs_validate_block():
| Väli | Skeem |
|---|---|
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block |
String. |
number, range |
Arv koos min ja max põhjal määratud väärtustega minimum ja maximum. |
toggle |
Tõeväärtus. |
select, radio, checkbox |
Valiku väärtus või valikuväärtuste loend checkbox ja multiple jaoks koos väärtusega enum. |
color, gradient |
String koos väärtusega enum, kui on määratud disableCustomColors või disableCustomGradients. |
token |
Stringide loend. |
files |
Mitte-negatiivne täisarvuline manuse ID või ID-de loend koos väärtusega multiple. |
link |
Objekt väärtustega url, title ja opensInNewTab; url on kohustuslik. |
icon |
Objekt väärtustega set, subSet ja icon; set ja icon on kohustuslikud. |
attributes |
Objektide loend, kus igal objektil on mittetühi attribute ja skalaarne value. |
repeater |
Reaobjektide loend. |
| Kohandatud väljatüübid | Nende registreeritud atribuudi tüüp. |
enum loetleb valikud, mida valideerimine kontrollib: staatilised valikud ning registreerimisel juba lahendatud täitmisvalikud. Kaug-fetch-valikutel ja täitmisargumentidel, mis sisaldavad {attributes.*}, puudub enum. Erineva salvestuskujuga määratlusi sisaldav võti jäetakse välja, sest valideerimine annab teada kõigist selle alla salvestatud väärtustest. Kui plokiväli ja laiendusväli kasutavad sama võtit, loetleb enum väärtused, mida mõlemad aktsepteerivad. Jagatud kordusväljad ühendavad alamväljad ja rakendavad mõlema määratluse rangemaid ridade piiranguid. Kordusridade piires rakendub igast lähteallikast esimene sobiva ID-ga väli, nagu renderdamisel. Selgesõnaliselt määratud väli nimega <id>__size on automaatselt lisatud faili suuruse kaasvälja ees eelistatud.
Kui suletud väljal pole saadaolevaid valikuid või kaks rakenduvat valikukomplekti ei kattu, on selle kanooniline väärtus ühe valiku korral null ja mitme valiku korral tühi loend. Tühi valikuloend ei muuda välja piiranguteta väljaks. Kaugvalikud ja atribuudist sõltuvad valikud jäävad avatuks.
Välja label muutub title-ks, selle help muutub description-ks ja default säilitatakse annotatsioonina. Skeemi enda title on ploki pealkiri. Väljad pole kunagi kohustuslikud ja tingimusloogika ei kuulu skeemi.
Piirangutes kasutatakse ainult märksõnu, mida rest_validate_value_from_schema() kontrollib, seega sobib skeem muutmata kujul marsruudi REST või võime sisendskeemiks.
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
$result = rest_validate_value_from_schema($values, $schema);
}
Skeem kirjeldab iga välja kohta üht vormi; valideerimine aktsepteerib ka imporditud kujusid, näiteks valikuobjekte, numbrilisi stringe ja ID-objekte. See ei asenda bs_validate_block(): definitsioonide konfliktid on seadistusprobleemid ja võivad põhjustada leide ka siis, kui konfliktne võti on välja jäetud. Valideerimisfiltrid saavad kehtestada ka saidipõhiseid reegleid. Kasutage salvestatud sisu kontrollimiseks bs_validate_block(). Saidid, millel on kohandatud renderdusaegne lahendaja, saavad skeemi kohandada filtriga blockstudio/blocks/attributes/schema.
PHP funktsioonid
Andmeteta
Kõige lihtsamal kujul võtab funktsioon vastu ühe väärtuse: renderdatava ploki ID.
bs_render_block('blockstudio/cta');
Andmetega
Ploki kohandatud andmetega renderdamiseks tuleb esimese parameetri ühe väärtuse asemel kasutada massiivi. Andmevõtme väärtus edastatakse plokimalli muutujatesse $attributes ja $a.
bs_render_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
]);
Pesastamine
Plokke saab üksteise sisse pesastada, kasutades funktsiooni bs_block koos võimsa muutujaga $content plokimallides.
<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',
]
])
]);
Nupplokk renderdatakse plokimallis muutuja $content asemel.
Manustatud plokid, mis renderdatakse funktsiooniga bs_render_block() või bs_block(), väljastavad alati esikülje jaoks lahendatud HTML, isegi kui emaploki jaoks renderdatakse parajasti redaktori eelvaadet. Malli pseudokomponendid, näiteks <RichText /> ja <InnerBlocks />, lahendatakse enne manustatud ploki tagastamist.
Mitu pesa
Mitu sisupesa saab luua ka nii, et muuta muutuja $content assotsiatiivseks massiiviks ja kutsuda funktsioonis bs_block selle sobivaid võtmeid.
<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']
])
]
]);
Plokisildid
Manustage mis tahes plokk sildi süntaksiga HTML. Toetatud on kaks vormingut:
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
Mõlemad renderdavad sama ploki. Süntaks <bs:> teisendab sidekriipsu nimeruumi eraldajaks (acme-hero muutub kujule acme/hero). Sidekriipse proovitakse vasakult paremale ja võidab esimene registreeritud kandidaat, seega lahendatakse ka sidekriipse sisaldavad nimeruumid: <bs:acme-ui-button> proovib esmalt acme/ui-button ja seejärel acme-ui/button. Süntaks <block> võtab täieliku plokinime atribuudina name.
Toimivad nii Blockstudio plokid kui ka tuumiku WordPress plokid. Blockstudio plokid renderdatakse kogu töövoo kaudu (mallid, Tailwind, varad). Tuumiku plokid renderdatakse WordPress plokkide renderdussüsteemi kaudu, kasutades sisseehitatud plokirenderdajaid.
Kuidas see töötab
Plokisiltide käitumine sõltub nende asukohast:
Plokimallides ja postituse sisus asendatakse sildid käitusajal renderdatud HTML-ga. Väljund on viidatud ploki lõplik märgistus, mis on otse lehele manustatud. Nende jaoks pole redaktoris WordPress plokki. Need on ainult renderdusmehhanism.
Lehtedes, mustrites ja saidimallides teisendatakse sildid omakeelseteks WordPress plokkideks, enne kui faili allikas sünkroonitakse või registreeritakse WordPress abil. Seetõttu ilmuvad plokid redaktorisse, neid saab sihtkohas redigeerida, kui see seda toetab, ja need läbivad WordPress täieliku ploki elutsükli. Sildi süntaks on otsetee ploki sisu määratlemiseks mallifailides.
See erinevus on oluline: mallides olevad plokisildid loovad väljundi, lehtedes, mustrites ja saidimallides olevad plokisildid aga omakeelsed plokid.
Plokimallides
Plokisildid renderdatakse automaatselt mallides Twig ja PHP. Seadistusi pole vaja. See hõlmab ka süntakseid <bs:> ja <block> ning kõiki registreeritud prefiksi ja aliase silte, nii et mall saab need väljastada otse funktsiooni bs_render_block() kutsumise asemel. Väljund renderdatakse kujul HTML ja manustatakse otse ploki malli väljundisse:
<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>
Postituse sisus
Lehe taseme renderdamine (postituse sisu, vidinaalad) on valikuline:
{
"blockTags": {
"enabled": true
}
}
Või filtri kaudu:
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');
Süntaks
Isekulgevad sildid:
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />
Paarissildid sisuga:
<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>
Kasutage süntakseid vabalt koos. Kumbki neist võib pesastuda teise sisse:
<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>
Prefiksi otseteed
Plokisiltides saab kasutada ka projektipõhiseid prefiksi otseteid. Registreerige prefiks ühe või mitme nimeruumiga ja Blockstudio lahendab <prefix-slug> esimeseks registreeritud plokiks vastavas nimeruumide järjestuses:
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 />
Ülaltoodud näites lahendatakse <theme-card> kujule theme-components/card, <theme-button> kasutab varuvariandina bsui/button, kui theme-components/button pole registreeritud, ning <theme-ui-feature-matrix> lahendatakse kujule theme-components/ui-feature-matrix.
Prefikseid saab ka kombineerida. Kui prefiksiga silt ei lahendu otse ja ülejäänud tunnus on ise registreeritud prefiksisilt, jätkub lahendamine rekursiivselt, nii et brändi prefiksi peale saab lisada nimeruumi prefiksi:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components'];
$prefixes['ui'] = ['bsui'];
return $prefixes;
});
<theme-ui-input />
<theme-ui-input>-l pole theme-components/ui-input plokki, seega jätkatakse prefiksiga ui ja lahendatakse bsui/input. Otsesed vasted on alati pesastatud lahendamisest tähtsamad ning lubamis- ja keelamisreegleid rakendatakse lõplikule lahendatud plokile.
Prefikseid saab seadistada ka failis blockstudio.json:
{
"blockTags": {
"prefixes": {
"theme": ["theme-components", "bsui"]
}
}
}
Prefiksid peavad koosnema väiketähtedest või numbritest, algama tähega ega tohi sisaldada sidekriipse. Faili blockstudio/block_tags/tag_aliases selgesõnalised aliased on prefiksi lahendamisest tähtsamad. Tundmatud prefiksiga sildid jäetakse muutmata.
Prefiksi- ja aliassildid on autoritele endiselt mugavad. Kanooniline ja teisaldatav kirjapilt on alati <bs:namespace-slug>, sest see sisaldab ploki tegelikku nime ega sõltu projektifiltritest:
<bs:theme-components-card />
<bs:bsui-input />
Näidetes Blockstudio, loodud diagnostikasõnumites ja programmilises väljundis kasutatakse seda kanoonilist kirjapilti. Projektid, mis soovivad eemaldada vanema otsetee kasutuse, saavad kasutada eraldiseisvat esmalt kuivkäivitusega kanooniliste siltide üleviimist, ilma et peaksid käivitama WordPress.
Tuumiku plokid
Kasutada saab mis tahes registreeritud renderdajaga plokki:
<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>
Või süntaksiga <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>
Lubamis- ja keelamisloendid
Määrake, milliseid plokke saab siltide kaudu renderdada:
{
"blockTags": {
"enabled": true,
"allow": ["mytheme/*", "core/*"],
"deny": ["mytheme/internal-*"]
}
}
allow piirab valiku ainult sobivate mustritega. deny jätab sobivad mustrid välja ja on tähtsam. Mõlemad toetavad * metamärke funktsiooni fnmatch() kaudu. Need kehtivad mõlema süntaksi ning malli- ja lehetaseme renderdamise puhul.
Filtrid: blockstudio/block_tags/allow ja blockstudio/block_tags/deny.
HTML läbivool
Prefiksiga data- atribuudid edastatakse renderdatud ploki juurelemendile. Ka prefiksiga html- atribuudid edastatakse, kuid prefiks eemaldatakse. Toimib mõlema süntaksiga. Läbivalt edastatav atribuut asendab juurelemendi olemasoleva väärtuse, mitte ei liida väärtusi kokku, seega asendab html-class ploki enda klassid.
Plokk Blockstudio lisab oma juurelemendile ka globaalsed atribuudid, mida see väljadena ei deklareeri: id, style, role, title, lang, dir, hidden, tabindex ja kõik atribuudid aria-*. Deklareeritud väli on alati tähtsam, seega saab title väljaga plokk selle asemel väärtuse $a['title']. Edastatud stiilid läbivad safecss_filter_attr(); filter WordPress rakendub postituse sisu stiiliatribuutidele ning need lisatakse mallis juba määratud stiilile.
Atribuutide väärtused on HTML, seega dekodeeritakse olemid sildi parsimisel üks kord: title="Tom & Jerry" jõuab mallini kujul Tom & Jerry ja väljundis escapitakse uuesti. Tsiteeritud väärtused võivad sisaldada >, nagu Tailwind variandid ja animatsiooni valijad, nii isekulgevates kui ka paarissiltides.
Ükski muu atribuut, mida plokk ei deklareeri, sealhulgas class, ei jõua kunagi HTML-ni. Kui WP_DEBUG on sisse lülitatud, teatab Blockstudio igast sellisest atribuudist päringu kohta ühe korra funktsiooni _doing_it_wrong() kaudu. Deklareerige selle jaoks väli või kirjutage see atribuudina data-, aria- või 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>
Kohandatud renderdajad
Lisaplokitüüpide jaoks registreerige kohandatud plokirenderdajad. Renderdajad saavad atribuutide massiivi ja sisustringi ning tagastavad WordPress plokimassiivi:
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);
Konteinerplokkide puhul, mille sisu tuleb parsida alamplokkideks, lisage samasse filtrisse teine kirje:
$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 kehtib nii plokisiltide kui ka funktsiooniga blockstudio/parser/element_mapping valitud kohandatud plokkide kohta. See on sobiv hook juhul, kui elemendiga vastendatud projektiplokk peab teisaldama sisuteksti väljale Blockstudio või koostama kohandatud plokimassiivi.
blockstudio/block_tags/renderers ja blockstudio/parser/renderers saavad sama registri ning tagasihelistuse kuju. Need on ühilduvuse tagamiseks ja viimase taseme parseri alistuste jaoks endiselt saadaval. Filtreid käivitatakse järgmises järjekorras:
blockstudio/block_tags/buildersblockstudio/block_tags/renderersblockstudio/parser/renderers
Hilisem filter võib asendada varasema filtriga registreeritud renderdaja.
Programmiliselt kasutamine
Rakendage siltide renderdamist mis tahes stringile funktsiooniga PHP:
$html = apply_filters('blockstudio/block_tags/render', $content);
Komponendid
Plokisildid sobivad hästi kokku komponentidega. Komponendid on plokid, mida renderdatakse ainult programmiliselt ja mida redaktoris kunagi ei kuvata.
<bs:mytheme-card title="My Card" description="Card content." />
Parser
Plokisilte töötleb kerge stringiskanner, mis asendab DOMDocumenti. Parser käsitleb nii süntaksit <bs:> kui ka <block>, jälgib pesastatud samanimeliste siltide sügavust, tsiteeritud atribuudiväärtusi ja rekursiivseid konteinerplokke. See on loodud just selle kasutusjuhtumi jaoks, on võrdlustestides kiirem kui DOMDocument ja WordPress-i WP_HTML_Tag_Processor ning väldib DOMDocumenti tuntud probleeme nimeruumi prefiksite eemaldamise ja atribuutide väiketähtedeks teisendamisega.
Lehtede, mustrite ja saidimallide puhul käsitleb sama parser ka tooreid HTML-elemente (<p>, <div>, <h1> jne), vastendades need vastavateks WordPress tuumiku plokkideks.
Kui elementide vastendus seob <p> registreeritud mittetuumiku Blockstudio plokiga, millel on deklareeritud atribuut content richtext, suunatakse sisemine HTML automaatselt sellesse content atribuuti, sealhulgas plokitasemel elemendiga vastendatud tekstisisesed sildid nagu code ja img. Lõik, mille ainus alamelement on pilt, muutub plokiks, millele vastendub <img>. Pesastatud plokisildid või plokitaseme HTML jätkavad tavapärast sisemiste plokkide parsimist. <block name="core/shortcode"> säilitab ploki sisuna lühikoodi teksti.