Preskoči na vsebino

Sestavljanje predlog z oznakami blokov

Ko ima projekt nekaj blokov, predloge začnejo potrebovati druga drugo. Blok z značilnostmi želi izpisati tri kartice. Ciljna stran želi razdelek z gumbom. Za vsakega lahko pokličete bs_render_block(), vendar je predlogo, polno klicev PHP z ugnezdenimi polji, težko brati in še težje ugnezditi.

Oznake blokov omogočajo, da blok zapišete tam, kjer naj se prikaže njegov izpis, kot oznako HTML:

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

Ista oznaka pomeni dve različni stvari, odvisno od tega, kje je zapisana. V predlogi bloka ali vsebini prispevka se nadomesti z upodobljenim HTML bloka. Na strani, v vzorcu ali viru predloge spletnega mesta postane pravi blok WordPress, ki se prikaže v urejevalniku. V tem vodniku bomo ustvarili nekaj blokov, jih sestavili na oba načina, dodali predpono projekta za krajša imena in nato pokazali, kako te skrajšane oblike pretvoriti nazaj v prenosni zapis.

Bloki

Zadoščajo trije preprosti bloki. Kartica z dvema poljema:

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>

Razdelek, ki ovije vsebino, postavljeno vanj, s poljem heading, deklariranim enako kot polje kartice:

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

In gumb v drugem imenskem prostoru, acme-ui/button, s poljema label in href:

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

Oznake v predlogi bloka

Predloge blokov oznake upodobijo samodejno. Nastavitev ni potrebna. Blok z značilnostmi lahko neposredno izpiše dve kartici in ločilnik jedra:

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>

Upodobitev acme/features ustvari:

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>

Pred vsakim blokom Blockstudio v izhodu je komentar <!--blockstudio/namespace/slug-->. Medpomnilnik strani ga odstrani iz odziva; za izhod, ki preskoči medpomnilnik, uporabite bs_strip_render_markers(). Obe sintaksi sta enakovredni. <bs:acme-card> kodira ime bloka v oznaki, <block name="acme/card"> pa ga posreduje kot atribut. Vsak drug atribut postane vrednost polja, zato title doseže predlogo kartice kot $a['title']. Delujejo tudi osnovni bloki, izrisani prek WordPress z vgrajenimi izrisovalniki blokov.

Seznanjene oznake in notranja vsebina

Seznanjena oznaka bloku posreduje svoje podrejene elemente bloku. Pri bloku Blockstudio zapolnijo <InnerBlocks />, ugnezdene oznake pa se upodobijo najprej:

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>

Kako ime oznake postane ime bloka

Ime oznake <bs:> ne vsebuje poševnice, zato Blockstudio poišče ustrezno ime. Vsak vezaj po vrsti z leve proti desni zamenja s poševnico in uporabi prvega najdenega kandidata, ki je registriran. <bs:acme-card> se razreši kot acme/card že v prvem poskusu. <bs:acme-ui-button> poskusi acme/ui-button, ne najde ničesar, nato pa razreši acme-ui/button. Imenski prostori z vezaji torej delujejo brez kakršne koli konfiguracije, če le oba kandidata ne obstajata hkrati.

Krajša imena s predponami

<bs:acme-ui-button> je natančen, vendar dolg. Predpona projekta poveže kratko predpono oznake z enim ali več imenskimi prostori. Konfigurirajte jo v blockstudio.json:

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

Isti zemljevid lahko registrirate tudi iz PHP:

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

	return $prefixes;
} );

Zdaj se <acme-card> razreši kot acme/card, <ui-button> pa kot acme-ui/button. Če predpona vsebuje več imenskih prostorov, se preverijo po vrsti in zmaga prvi registrirani blok. Tako lahko blok projekta preglasi blok knjižnice z enakim slugom.

Predpone je mogoče tudi sestavljati. <acme-ui-button> najprej poskusi acme/ui-button. Ta blok ne obstaja, preostanek oznake, ui-button, pa je sam registrirana oznaka s predpono, zato se razreševanje nadaljuje do acme-ui/button. Neposredno ujemanje ima vedno prednost pred ugnezdenim.

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>

To upodobi popolnoma enak HTML kot zgoraj prikazana kanonična različica.

Za predpone velja nekaj pravil:

  • Predpona vsebuje male črke in številke, začne se s črko in ne vsebuje vezajev.
  • Oznaka s predpono, ki se ne razreši v registrirani blok, ostane v izpisu nespremenjena, torej <acme-missing title="x" /> ostane, kot je zapisana.
  • Natančni vzdevki iz filtra blockstudio/block_tags/tag_aliases imajo prednost pred predponami. Vzdevek poveže eno oznako z vezajem z enim blokom; na primer $aliases['acme-cta'] = 'acme-ui/button'; poskrbi, da se <acme-cta> upodobi kot gumb.

Oznake s predponami in vzdevki se upodobijo v predlogah blokov skupaj z oznakami <bs:> in <block> iz različice 7.5 Blockstudio.

Atributi

Atributi, ki se ujemajo z ID-jem polja, postanejo vrednosti polja. Dve predponi delujeta drugače:

  • Atributi data-* se kopirajo v korenski element upodobljenega bloka.
  • Atributi html-* se kopirajo v korenski element brez predpone, zato html-id="intro" postane 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 nastavi atribut, ne doda pa vrednosti k njemu: lastni razredi bloka acme-card wp-block-acme-card izginejo. Če naj klicatelj doda razrede bloku, zanje deklarirajte polje in jih združite v predlogi.

Vsak drug atribut, ki ni deklarirano polje, se zavrže. Navadna oznaka class="wide" na <bs:acme-card> upodobi kartico brez tega atributa. Blockstudio 7.7 ob vklopljenem WP_DEBUG takšne atribute sporoči z obvestilom _doing_it_wrong().

Iste oznake v virih strani

V straneh iz datotek, vzorcih in predlogah spletnih mest se oznake ne upodobijo. Pri razčlenjevanju vira se pretvorijo v bloke, zato se prikažejo v urejevalniku. Ta vir strani:

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>

se razčleni v to označbo blokov (za lažje branje so dodani prelomi vrstic):

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

Vrednosti polj se shranijo pod blockstudio.attributes, kamor jih shranjujejo bloki Blockstudio; odstavek in oba notranja bloka pa postanejo notranji bloki razdelka. Predpone in vzdevki se tu razrešijo enako kot v predlogah.

Oznake v vsebini prispevkov

Vsebina, napisana v urejevalniku ali shranjena v gradnikih, se privzeto ne pregleduje. Vklopite upodabljanje na ravni strani v blockstudio.json:

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

Oznake v the_content in widget_text se nato upodobijo s prednostjo 5. Isto stikalo registrira filter za upodabljanje oznak v poljubnem nizu:

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

S pomočjo vzorcev allow in deny omejite, katere oznake se lahko upodobijo. Sprejemajo nadomestne znake fnmatch() ter veljajo za vso sintakso in oba načina upodabljanja:

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

Ko je to pravilo uveljavljeno, <acme-ui-button> in <bs:acme-ui-button> ostaneta v izpisu neupodobljena. deny ima prednost pred allow. Filtra blockstudio/block_tags/allow in blockstudio/block_tags/deny spremenita ista seznama iz PHP.

Analiza preverja kanonični zapis

Razširitev PHPStan preverja oznake blokov v predlogah PHP, Twig in Blade. Napačno zapisano polje ali ime bloka se prikaže skupaj z blokom, v katerega se je razrešilo:

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

V različici 7.6 to zajema oznake <bs:> in <block>. Oznaka s predpono, kot je <acme-card txt="...">, se preveri brez opozorila. Blockstudio 7.7 razširi pravilo na oznake s predponami, vire strani in preslikane elemente HTML, namig pa navede globalne atribute, ki jih oznaka lahko posreduje.

Pretvorite skrajšane oblike v kanonični zapis

Oznake s predponami in vzdevki so priročne za projekt. Razrešijo se samo tam, kjer so naloženi projektni filtri in nastavitve, zato predloga, kopirana v drug projekt, knjižnico blokov ali kontekst programskega agenta, izgubi svoj pomen. <bs:namespace-slug> zabeleži pravo ime bloka in se razreši povsod; zato ga uporabljajo primeri, diagnostika in ustvarjeni izpis samega Blockstudio.

Samostojen ukaz pretvori skrajšane oblike v ta zapis. Vzemimo projekt, katerega viri še vedno uporabljajo kratke oblike, vključno z vzdevkom, oznako za blok, ki ne obstaja več, in primerom znotraj vzorca kode:

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>

Ukaz ne naloži WordPress, zato uporabi konfiguracijo projekta kot datoteke JSON, shranjene zunaj pregledovanega drevesa:

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

Najprej izvedite poskusni zagon, ki je tudi privzeta možnost:

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

Poročilo navede vse preslikave, ki bi jih uporabil, in vse primere, pri katerih ne bo ugibal:

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" }
  ]
}

Poročilo je tu skrajšano. Zabeleži tudi konfiguracijo ter zgoščene vrednosti vsake datoteke pred spremembami in po njih. Začetna in končna oznaka razdelka štejeta kot dve pojavitvi. acme-quote ustreza predponi acme, vendar ne poimenuje nobenega znanega bloka, zato je neznana. acme-card znotraj <pre><code> je primer, ne označba, zato je označen za ročni pregled in se nikoli ne prepiše; enako velja za komentarje HTML in vstavljeno kodo.

Uporaba sprememb je zavrnjena, dokler ostanejo neznane, dvoumne ali dinamične oznake:

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

Ukaz se konča s kodo 2. Popravite neznano oznako, na primer tako, da jo odstranite, in zaženite z --apply namesto z --dry-run:

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

Spremenijo se samo imena oznak. Atributi se ohranijo bajt za bajtom:

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

Če poskusni zagon znova izvedete nad rezultatom, bo poročilo pokazalo 0 changed, 0 replacements. Predpone lahko ostanejo registrirane tudi pozneje, zato ne bo nič narobe, če druge veje še vedno uporabljajo kratko obliko.

Naslednji koraki