Mallide koostamine plokisiltidega
Kui projektis on juba mitu plokki, hakkavad mallid üksteist vajama. Funktsioonide plokk soovib kuvada kolm kaarti. Maandumislehele on vaja jaotist, mille sees on nupp. Võite iga ploki jaoks kutsuda välja bs_render_block(), kuid PHP väljakutsetega ja pesastatud massiividega täidetud malli on raske lugeda ja veel raskem pesastada.
Plokisiltidega saate kirjutada ploki sinna, kuhu selle väljund kuulub, kasutades silti HTML:
<bs:acme-card title="Fast" text="Rendered on the server." />
Sama silt tähendab eri kohtadesse kirjutatuna kahte erinevat asja. Plokimallis või postituse sisus asendatakse see ploki renderdatud HTML-iga. Lehe, mustri või saidimalli allikas teisendatakse see päris WordPress plokiks, mis kuvatakse redaktoris. Selles juhendis luuakse mõned plokid, koostatakse neid mõlemal viisil, lisatakse lühemate nimede jaoks projekti eesliide ning näidatakse, kuidas need lühivormid teisaldatavaks kirjapildiks teisendada.
Plokid
Piisab kolmest väikesest plokist. Kaart kahe väljaga:
{
"$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": "" }
]
}
}
<article useBlockProps class="acme-card">
<h3><?php echo esc_html( $a['title'] ); ?></h3>
<p><?php echo esc_html( $a['text'] ); ?></p>
</article>
Jaotis, mis ümbritseb kõike, mis selle sisse paigutatakse, ning millel on heading väli, mis on määratletud samamoodi nagu kaardi väli:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
Nupp teises nimeruumis, acme-ui/button, väljadega label ja href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Sildid plokimallis
Plokimallid renderdavad sildid automaatselt. Seadistust pole vaja. Funktsioonide plokk saab otse kuvada kaks kaarti ja põhieraldaja:
<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>
acme/features renderdamisel saadakse:
<!--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>
Iga väljundis olevat plokki Blockstudio eelneb kommentaar <!--blockstudio/namespace/slug-->. Lehepuhver eemaldab selle vastusest; puhvri vahele jätva väljundi puhul kasutage bs_strip_render_markers().
Mõlemad süntaksid on samaväärsed. <bs:acme-card> kodeerib ploki nime märgendis ja <block name="acme/card"> edastab selle atribuudina. Iga muu atribuut muutub välja väärtuseks, nii et title jõuab kaardimalli kui $a['title']. Sobivad ka tuumplokid, mida renderdatakse sisseehitatud plokirenderdajatega WordPress kaudu.
Paarissildid ja sisemine sisu
Paarissilt edastab oma alamelemendid plokile. Ploki Blockstudio puhul täidavad need välja <InnerBlocks /> ning sees olevad sildid renderdatakse esmalt:
<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>
<!--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>
Kuidas sildi nimest saab ploki nimi
Sildi <bs:> nimes pole kaldkriipsu, seega otsib Blockstudio selle ise. See asendab iga sidekriipsu vasakult paremale kordamööda kaldkriipsuga ja kasutab esimest kandidaati, mis on registreeritud. <bs:acme-card> lahendatakse esimesel katsel kujule acme/card. <bs:acme-ui-button> proovib väärtust acme/ui-button, ei leia vastet ning lahendatakse seejärel kujule acme-ui/button. Sidekriipse sisaldavad nimeruumid töötavad seega ilma seadistuseta, kui mõlemad kandidaadid pole korraga olemas.
Lühemad nimed eesliidetega
<bs:acme-ui-button> on täpne, kuid pikk. Projekti eesliide seostab lühikese sildi eesliite ühe või mitme nimeruumiga. Seadistage see asukohas blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Või registreerige sama seos kaardistusena asukohast PHP:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Nüüd lahendatakse <acme-card> kujule acme/card ja <ui-button> kujule acme-ui/button. Kui eesliide loetleb mitu nimeruumi, proovitakse neid järjekorras ja võidab esimene registreeritud plokk. Nii saab projektipärane plokk varjutada sama slug’iga teegi plokki.
Eesliiteid saab ka kombineerida. <acme-ui-button> proovib esmalt väärtust acme/ui-button. Seda plokki pole olemas ja ülejäänud sildiosa ui-button on ise registreeritud eesliitega silt, seega liigub lahendamine edasi kujule acme-ui/button. Otsene vaste võidab alati pesastatud vaste.
<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>
See renderdab täpselt sama HTML nagu ülaltoodud kanooniline versioon.
Eesliidetele kehtivad mõned reeglid:
- Eesliide koosneb väiketähtedest ja numbritest, algab tähega ega sisalda sidekriipse.
- Eesliitega silt, mida ei saa ühegi registreeritud plokiga seostada, jäetakse väljundisse muutmata, nii et
<acme-missing title="x" />jääb selliseks, nagu see kirjutati. - Filtri
blockstudio/block_tags/tag_aliasestäpsed aliased on eesliidetest tähtsamad. Alias seostab ühe sidekriipsudega sildi ühe plokiga. Näiteks paneb$aliases['acme-cta'] = 'acme-ui/button';<acme-cta>nupu renderdama.
Eesliite- ja aliassildid renderdatakse plokimallides koos <bs:> ja <block> siltidega alates versioonist Blockstudio 7.5.
Atribuudid
Välja ID-ga kattuvatest atribuutidest saavad välja väärtused. Kahel eesliitel on teine ülesanne:
- Atribuudid
data-*kopeeritakse renderdatud ploki juurelemendile. - Atribuudid
html-*kopeeritakse juurelemendile ilma eesliiteta, nii ethtml-id="intro"muutub kujuleid="intro".
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
<article data-track="card" id="intro" class="featured">
<h3>Hi</h3>
<p>There</p>
</article>
html-class määrab atribuudi väärtuse, mitte ei lisa väärtust olemasolevale: ploki enda acme-card wp-block-acme-card klassid kaovad. Kui väljakutsuja peaks saama plokile klasse lisada, määratlege nende jaoks väli ja liitke see mallis olemasolevatega.
Kõik muud deklareerimata atribuudid jäetakse kõrvale. Tavaline class="wide" sildil <bs:acme-card> renderdab kaardi ilma selle atribuudita. Blockstudio 7.7 teatab sellistest atribuutidest märguandega _doing_it_wrong(), kui WP_DEBUG on sisse lülitatud.
Samad sildid lehtede allikates
Failipõhiste lehtede, mustrite ja saidimallide puhul silte ei renderdata. Allika parsimisel teisendatakse need plokkideks, nii et need kuvatakse redaktoris. See lehe allikas:
<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>
parsitakse selleks plokimärgistuseks (reavahetused lisatud loetavuse huvides):
<!-- 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 -->
Väljade väärtused paigutatakse alla blockstudio.attributes, kuhu Blockstudio plokid need salvestavad, ning jaotise sisemisteks plokkideks saavad nii lõik kui ka mõlemad sisemised plokid. Eesliited ja aliased lahendatakse siin täpselt nagu mallides.
Sildid postituse sisus
Redaktoris kirjutatud või vidinates talletatud sisu ei skannita vaikimisi. Lubage lehepõhine renderdamine asukohas blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
Seejärel renderdatakse sildid asukohtades the_content ja widget_text prioriteediga 5. Sama lüliti registreerib filtri, mis renderdab silte kõigis stringides:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Piirake renderdatavaid silte mustritega allow ja deny, mis aktsepteerivad metamärke fnmatch() ning kehtivad kõigi süntaksite ja mõlema renderdusviisi puhul:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Selle reegli korral jäävad <acme-ui-button> ja <bs:acme-ui-button> väljundisse renderdamata. deny on tähtsam kui allow. Filtrid blockstudio/block_tags/allow ja blockstudio/block_tags/deny muudavad samu loendeid asukohast PHP.
Analüüs kontrollib kanoonilist kirjapilti
Laiendus PHPStan valideerib plokisildid mallides PHP, Twig ja Blade. Valesti kirjutatud välja või ploki nime puhul teatatakse, milliseks plokiks see lahendati:
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
Versioonis 7.6 hõlmab see silte <bs:> ja <block>. Eesliitega silt, näiteks <acme-card txt="...">, läbib kontrollita. Blockstudio 7.7 laiendab reegli eesliitega siltidele, lehe allikatele ja kaardistatud HTML elementidele. Selle vihjes loetletakse globaalsed atribuudid, mida silt võib edasi anda.
Lühivormide teisendamine kanooniliseks kirjapildiks
Eesliite- ja aliassildid on projektipõhised mugavused. Need lahendatakse ainult seal, kus projekti filtrid ja seaded on laaditud. Teise projekti või plokiteeki kopeeritud mall ning koodiagendi kontekst kaotavad seetõttu oma tähenduse. <bs:namespace-slug> talletab ploki päris nime ja lahendatakse kõikjal, mistõttu Blockstudio enda näited, diagnostika ja loodud väljund kasutavad seda.
Eraldiseisev käsk asendab lühivormid selle kirjapildiga. Oletame, et projekti allikates kasutatakse endiselt lühivorme, sealhulgas aliast, silti ploki kohta, mida enam pole, ja näidet koodinäidises:
<div useBlockProps class="acme-features">
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</div>
<acme-section heading="Why Acme">
<acme-cta label="Talk to us" href="/contact" />
<acme-quote text="Missing block" />
</acme-section>
<pre><code><acme-card /> <acme-card title="Example" /></code></pre>
Käsk ei laadi WordPress, seega edastage projekti seadistus kujul JSON failidena, mida hoitakse skannitavast puust väljaspool:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Alustage kuivkäivitusega, mis on ka vaikimisi režiim:
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
Report: /tmp/acme-tags/report.json
Dry run: 2 files, 2 changed, 5 replacements, 1 unknown, 0 ambiguous, 1 manual.
Aruandes on loetletud kõik rakendatavad teisendused ning juhud, mille kohta see oletusi ei tee:
{
"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" }
]
}
Aruanne on siin lühendatud. Lisaks salvestab see seadistuse ning iga faili räsi enne ja pärast muudatust. Jaotise avamis- ja sulgemissilt lähevad arvesse kahe esinemisena. acme-quote vastab eesliitele acme, kuid ei nimeta teadaolevat plokki, seega on see tundmatu. acme-card asukohas <pre><code> on näide, mitte märgistus, mistõttu sellest teatatakse käsitsi ülevaatamiseks ja seda ei kirjutata kunagi ümber; sama kehtib kommentaaride HTML ja tekstisisese koodi kohta.
Rakendamine lükatakse tagasi, kui leidub tundmatuid, mitmetähenduslikke või dünaamilisi silte:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Käsu väljumiskood on 2. Parandage tundmatu silt (siin selle eemaldamisega) ja kasutage seejärel käsku --apply, mitte --dry-run:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Muutuvad ainult siltide nimed. Atribuudid säilivad baidi täpsusega:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Kui käivitate tulemuse peal uuesti kuivkäivituse, annab see aru 0 changed, 0 replacements. Eesliited võivad jääda registreerituks, nii et teiste harude lühivormi kasutamine ei katkesta midagi.
Järgmised sammud
- Renderdamine: kogu sildi süntaks, kohandatud renderdajad ja parser.
- Seaded: kõik valikud
blockTags. - Failipõhiste lehtede loomine: lehe allikad, kus siltidest saavad redigeeritavad plokid.
- Plokisiltide teisendamine: kõik teisenduskäsu valikud.
- Kontrollitud mallid koos PHPStan-ga: siltide valideerimiseks vajaliku analüüsi käivitamine.