Pereiti prie turinio

Šablonų komponavimas naudojant blokų žymas

Kai projekte atsiranda keletas blokų, šablonams pradeda reikėti vienas kito. Funkcijų blokas nori pateikti tris korteles. Nukreipimo puslapiui reikia sekcijos su mygtuku viduje. Galite kiekvienam iš jų kviesti bs_render_block(), tačiau šabloną su daugybe PHP iškvietimų ir įdėtais masyvais sunku skaityti ir dar sunkiau įdėti į kitą šabloną.

Blokų žymomis galite įrašyti bloką ten, kur turi būti jo išvestis, kaip HTML žymą:

HTML
<bs:acme-card title="Fast" text="Rendered on the server." />

Ta pati žyma reiškia du skirtingus dalykus, priklausomai nuo to, kur ji parašyta. Bloko šablone arba įrašo turinyje ji pakeičiama sugeneruota bloko HTML išvestimi. Puslapio, šablono ar svetainės šablono šaltinyje ji tampa tikru WordPress bloku, rodomu redaktoriuje. Šiame vadove sukursime kelis blokus, komponuosime juos abiem būdais, trumpesniems pavadinimams pridėsime projekto prefiksą ir parodysime, kaip šiuos trumpinius perkelti į perkeliamą formą.

Blokai

Pakanka trijų nedidelių blokų. Kortelė su dviem laukais:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/card",
  "title": "Card",
  "blockstudio": {
    "attributes": [
      { "id": "title", "type": "text", "label": "Title", "default": "" },
      { "id": "text", "type": "textarea", "label": "Text", "default": "" }
    ]
  }
}
PHP
<article useBlockProps class="acme-card">
  <h3><?php echo esc_html( $a['title'] ); ?></h3>
  <p><?php echo esc_html( $a['text'] ); ?></p>
</article>

Sekcija, apgaubianti bet kokį į ją įdėtą turinį, su heading lauku, apibrėžtu taip pat kaip kortelės laukas:

PHP
<section useBlockProps class="acme-section">
  <h2><?php echo esc_html( $a['heading'] ); ?></h2>
  <InnerBlocks />
</section>

Ir mygtukas antroje vardų srityje – acme-ui/button – su laukais label ir href:

PHP
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>

Žymos bloko šablone

Blokų šablonai žymas atvaizduoja automatiškai. Jokių nustatymų nereikia. Funkcijų blokas gali tiesiogiai pateikti dvi korteles ir pagrindinį skirtuką:

PHP
<div useBlockProps class="acme-features">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <block name="acme/card" title="Typed" text="Fields come from block.json." />
  <block name="core/separator" />
</div>

Atvaizdavus acme/features gaunama:

HTML
<!--blockstudio/acme/features--><div class="acme-features wp-block-acme-features">
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Typed</h3>
  <p>Fields come from block.json.</p>
</article>

  <hr class="wp-block-separator has-alpha-channel-opacity">
</div>

Prieš kiekvieną išvesties Blockstudio bloką įterpiamas <!--blockstudio/namespace/slug--> komentaras. Puslapio buferis jį pašalina iš atsakymo; jei išvestis apeina buferį, naudokite bs_strip_render_markers(). Abi sintaksės yra lygiavertės. <bs:acme-card> užkoduoja bloko pavadinimą žymoje, o <block name="acme/card"> perduoda jį kaip atributą. Kiekvienas kitas atributas tampa lauko reikšme, todėl title kortelės šabloną pasiekia kaip $a['title']. Veikia ir pagrindiniai blokai: jie atvaizduojami naudojant WordPress bei integruotas blokų atvaizdavimo funkcijas.

Atidarančios ir uždarančios žymos bei vidinis turinys

Žyma su pradžios ir pabaigos žymekliais perduoda blokui savo vidinius elementus. Bloko Blockstudio atveju jie užpildo <InnerBlocks />, o viduje esančios žymos atvaizduojamos pirmiausia:

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <bs:acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
HTML
<!--blockstudio/acme/section--><section class="acme-section wp-block-acme-section">
  <h2>Why Acme</h2>
  <div>
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme-ui/button--><a class="acme-button wp-block-acme-ui-button" href="/start">Get started</a>

</div>
</section>

Kaip žymos pavadinimas tampa bloko pavadinimu

Žymos <bs:> pavadinime nėra pasvirojo brūkšnio, todėl Blockstudio jo ieško. Jis paeiliui, iš kairės į dešinę, kiekvieną brūkšnelį pakeičia pasviruoju brūkšniu ir naudoja pirmą rastą registruotą variantą. <bs:acme-card> jau pirmuoju bandymu atitinka acme/card. <bs:acme-ui-button> išbando acme/ui-button, nieko neranda ir tada atitinka acme-ui/button. Taigi vardų sritims su brūkšneliais nereikia jokios konfigūracijos, jei abu kandidatai neegzistuoja vienu metu.

Trumpesni pavadinimai su prefiksais

<bs:acme-ui-button> yra tikslus, bet ilgas pavadinimas. Projekto prefiksu trumpą žymos prefiksą galima susieti su viena ar keliomis vardų sritimis. Sukonfigūruokite jį blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "blockTags": {
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    }
  }
}

Arba užregistruokite tą patį susiejimą iš PHP:

PHP
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
	$prefixes['acme'] = array( 'acme' );
	$prefixes['ui']   = array( 'acme-ui' );

	return $prefixes;
} );

Dabar <acme-card> atitinka acme/card, o <ui-button> – acme-ui/button. Jei prefiksui priskirtos kelios vardų sritys, jos tikrinamos iš eilės ir laimi pirmasis registruotas blokas. Taip projekto blokas gali perimti tos pačios žymos bibliotekos bloko vietą.

Galima komponuoti ir prefiksus. <acme-ui-button> pirmiausia bando acme/ui-button. Šio bloko nėra, o likusi žymos dalis ui-button pati yra registruota prefikso žyma, todėl galiausiai randamas acme-ui/button. Tiesioginis atitikmuo visada turi pirmenybę prieš įdėtąjį.

HTML
<bs:acme-section heading="Why Acme">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

Tai atvaizduoja lygiai tokį patį HTML kaip ir aukščiau pateikta kanoninė versija.

Prefiksams taikomos kelios taisyklės:

  • Prefiksą sudaro mažosios raidės ir skaičiai, jis prasideda raide ir neturi brūkšnelių.
  • Prefiksinė žyma, neatitinkanti jokio registruoto bloko, išvestyje paliekama nepakeista, todėl <acme-missing title="x" /> lieka toks, koks buvo.
  • Tiksliosios slapyvardžių reikšmės iš blockstudio/block_tags/tag_aliases filtro turi pirmenybę prieš prefiksus. Slapyvardis vieną žymą su brūkšneliu susieja su vienu bloku, pavyzdžiui, $aliases['acme-cta'] = 'acme-ui/button'; leidžia atvaizduoti mygtuką kaip <acme-cta>.

Blokų šablonuose atvaizduojamos prefiksų ir slapyvardžių žymos, taip pat Blockstudio 7.5 žymos <bs:> ir <block>.

Atributai

Atributai, atitinkantys lauko ID, tampa laukų reikšmėmis. Du prefiksai veikia kitaip:

  • data-* atributai nukopijuojami į atvaizduoto bloko šakninį elementą.
  • html-* atributai nukopijuojami į šakninį elementą be prefikso, todėl html-id="intro" tampa id="intro".
HTML
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
HTML
<article data-track="card" id="intro" class="featured">
  <h3>Hi</h3>
  <p>There</p>
</article>

html-class nustato atributo reikšmę, o ne ją papildo: bloko savosios acme-card wp-block-acme-card klasės pašalinamos. Jei iškvietimas turi pridėti bloko klasių, deklaruokite joms lauką ir sujunkite reikšmes šablone.

Visi kiti atributai, kurie nėra deklaruoti laukai, pašalinami. Paprastas class="wide" ant <bs:acme-card> atvaizduoja kortelę be šio atributo. Įjungus WP_DEBUG, Blockstudio 7.7 apie tokius atributus praneša _doing_it_wrong() įspėjimu.

Tos pačios žymos puslapių šaltiniuose

Puslapiuose iš failų, šablonuose ir svetainės šablonuose žymos neatvaizduojamos. Išanalizavus šaltinį, jos paverčiamos blokais ir parodomos redaktoriuje. Štai puslapio šaltinis:

HTML
<bs:acme-section heading="Why Acme">
  <p>Everything below is a real block.</p>
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

išanalizuojamas ir gaunama tokia blokų žymė (eilutės pridėtos, kad būtų lengviau skaityti):

HTML
<!-- wp:acme/section {"blockstudio":{"attributes":{"heading":"Why Acme"}}} -->
<!-- wp:paragraph --><p>Everything below is a real block.</p><!-- /wp:paragraph -->
<!-- wp:acme/card {"blockstudio":{"attributes":{"title":"Fast","text":"Rendered on the server."}}} /-->
<!-- wp:acme-ui/button {"blockstudio":{"attributes":{"label":"Get started","href":"/start"}}} /-->
<!-- /wp:acme/section -->

Laukų reikšmės atsiduria po blockstudio.attributes, kur jas saugo Blockstudio blokai, o pastraipa ir abu vidiniai blokai tampa sekcijos vidiniais blokais. Prefiksai ir slapyvardžiai atpažįstami taip pat kaip šablonuose.

Žymos įrašų turinyje

Redaktoriuje įrašytas arba valdikliuose saugomas turinys pagal numatytuosius nustatymus nenuskaitomas. Įjunkite puslapio lygmens atvaizdavimą blockstudio.json:

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

Tada žymos the_content ir widget_text atvaizduojamos taikant prioritetą 5. Tuo pačiu perjungikliu taip pat užregistruojamas filtras, atvaizduojantis žymas bet kurioje eilutėje:

PHP
$html = apply_filters( 'blockstudio/block_tags/render', $content );

Apribokite atvaizduojamas žymas naudodami allow ir deny šablonus, kurie priima fnmatch() pakaitos simbolius ir taikomi visoms sintaksėms bei abiem atvaizdavimo režimams:

JSON
{
  "blockTags": {
    "enabled": true,
    "deny": ["acme-ui/*"]
  }
}

Nustačius šią taisyklę, <acme-ui-button> ir <bs:acme-ui-button> išvestyje paliekamos neatvaizduotos. deny turi pirmenybę prieš allow. Filtrai blockstudio/block_tags/allow ir blockstudio/block_tags/deny pakeičia tuos pačius sąrašus iš PHP.

Analizė tikrina kanoninę formą

Plėtinys PHPStan tikrina blokų žymas šablonuose PHP, Twig ir Blade. Neteisingai parašius lauką ar bloko pavadinimą, nurodomas blokas, į kurį jis buvo susietas:

Text
  3      Block tag "acme/card" has unknown attribute "txt" in index.php
         🪪  blockstudio.blockTag.attribute
  4      Block tag references unknown block "acme/cards" in index.php
         🪪  blockstudio.blockTag.unknown

7.6 versijoje tai taikoma žymoms <bs:> ir <block>. Prefiksinė žyma, pavyzdžiui, <acme-card txt="...">, patikrinama nebuvo. Blockstudio 7.7 taisyklė išplečiama prefiksinėms žymoms, puslapių šaltiniams ir susietiems HTML elementams; jos užuominoje išvardijami visuotiniai atributai, kuriuos žyma gali perduoti.

Trumpinių perkėlimas į kanoninę formą

Prefiksų ir slapyvardžių žymos patogios konkrečiame projekte. Jos atpažįstamos tik tada, kai įkeliami projekto filtrai ir nustatymai, todėl į kitą projektą, blokų biblioteką ar programavimo agento kontekstą nukopijuotas šablonas praranda savo prasmę. <bs:namespace-slug> nurodo tikrąjį bloko pavadinimą ir atpažįstamas visur, todėl Blockstudio pavyzdžiuose, diagnostiniuose pranešimuose ir sugeneruotoje išvestyje naudojama būtent ši forma.

Atskira komanda perrašo trumpinius į šią formą. Tarkime, projekte šaltiniuose vis dar naudojamos trumposios formos, taip pat slapyvardis, nebeegzistuojančio bloko žyma ir pavyzdys kodo fragmente:

PHP
<div useBlockProps class="acme-features">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</div>
PHP
<acme-section heading="Why Acme">
  <acme-cta label="Talk to us" href="/contact" />
  <acme-quote text="Missing block" />
</acme-section>
<pre><code>&lt;acme-card /&gt; <acme-card title="Example" /></code></pre>

Komanda neįkelia WordPress, todėl projekto konfigūraciją jai reikia pateikti kaip JSON failus, laikomus už skenuojamo medžio ribų:

JSON
{ "acme": ["acme"], "ui": ["acme-ui"] }
JSON
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
JSON
{ "acme-cta": "acme-ui/button" }

Pirmiausia paleiskite bandomąjį vykdymą; jis taip pat naudojamas pagal numatytuosius nustatymus:

Shell
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
  --root="$PWD" \
  --prefix-map=/tmp/acme-tags/prefixes.json \
  --known-blocks=/tmp/acme-tags/blocks.json \
  --aliases=/tmp/acme-tags/aliases.json \
  --report=/tmp/acme-tags/report.json \
  --dry-run
Text
Report: /tmp/acme-tags/report.json
Dry run: 2 files, 2 changed, 5 replacements, 1 unknown, 0 ambiguous, 1 manual.

Ataskaitoje pateikiamas kiekvienas susiejimas, kurį ji pritaikytų, ir kiekvienas atvejis, kurio ji nebandys nustatyti spėjimu:

JSON
{
  "mappings": [
    { "legacy": "acme-card", "canonical": "bs:acme-card", "block": "acme/card", "occurrences": 1 },
    { "legacy": "acme-cta", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 },
    { "legacy": "acme-section", "canonical": "bs:acme-section", "block": "acme/section", "occurrences": 2 },
    { "legacy": "acme-ui-button", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 }
  ],
  "unknown": [
    { "path": "pages/home/index.php", "line": 3, "column": 4, "tag": "acme-quote", "reason": "no-known-block" }
  ],
  "manual": [
    { "path": "pages/home/index.php", "line": 5, "column": 33, "tag": "acme-card", "reason": "code-sample" }
  ]
}

Ataskaita čia sutrumpinta. Joje taip pat įrašoma konfigūracija ir kiekvieno failo maišos reikšmės prieš pakeitimus ir po jų. Sekcijos pradžios ir pabaigos žymos skaičiuojamos kaip du atvejai. acme-quote atitinka prefiksą acme, bet nenurodo žinomo bloko, todėl laikomas nežinomu. acme-card, esantis <pre><code>, yra pavyzdys, o ne žymėjimas, todėl jis pažymimas kaip reikalaujantis peržiūros ir niekada neperrašomas. Tas pats taikoma HTML komentarams ir įterptajam kodui.

Pakeitimai nepritaikomi, kol lieka nežinomų, dviprasmiškų ar dinaminių žymų:

Text
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.

Komanda baigiama kodu 2. Ištaisykite nežinomą žymą, šiuo atveju ją pašalindami, ir paleiskite su --apply, o ne su --dry-run:

Text
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.

Keičiasi tik žymų pavadinimai. Atributai išsaugomi baitas į baitą:

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>

Dar kartą paleidus bandomąjį vykdymą pakeistam rezultatui, pateikiama 0 changed, 0 replacements. Prefiksai gali likti užregistruoti, todėl niekas nesugenda, kol kitose šakose dar naudojama trumpoji forma.

Tolesni veiksmai