Preskoči na vsebino

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_block in bs_block za 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:

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

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

PHP
$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():

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

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

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

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

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

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

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

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

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

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

PHP
<div>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content; ?>
</div>
PHP
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.

PHP
<div>
  <?php echo $content['beforeContent']; ?>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content['afterContent']; ?>
</div>
PHP
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:

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

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

JSON
{
  "blockTags": {
    "enabled": true
  }
}

Ali prek filtra:

PHP
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');

Sintaksa

Samozapiralne oznake:

HTML
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />

Seznanjene oznake z notranjo vsebino:

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

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

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
HTML
<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:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components'];
  $prefixes['ui'] = ['bsui'];

  return $prefixes;
});
HTML
<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:

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:

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

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

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

JSON
{
  "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 &amp; 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-.

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:

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

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

  1. blockstudio/block_tags/builders
  2. blockstudio/block_tags/renderers
  3. blockstudio/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:

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.

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