Siirry sisältöön

Mallien koostaminen lohkotunnisteilla

Kun projektissa on muutama lohko, mallit alkavat tarvita toisiaan. Ominaisuuslohko haluaa tulostaa kolme korttia. Laskeutumissivu tarvitsee osion, jonka sisällä on painike. Voit kutsua kutakin erikseen komennolla bs_render_block(), mutta sisäkkäisiä taulukoita sisältävää PHP-kutsujen mallia on vaikea lukea ja vielä vaikeampi sisäkkäistää.

Lohkotunnisteilla voit kirjoittaa lohkon suoraan siihen kohtaan, johon sen tuloste kuuluu, käyttämällä HTML-tunnistetta:

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

Sama tunniste tarkoittaa eri asiaa sen mukaan, missä se kirjoitetaan. Lohkomallissa tai sisältötekstissä se korvataan lohkon renderöidyllä HTML-arvolla. Sivun, kuvion tai Site Template -lähteessä siitä tulee oikea WordPress-lohko, joka näkyy editorissa. Tässä oppaassa luodaan muutama lohko, koostetaan niitä molemmilla tavoilla, lisätään projektietuliite lyhyempiä nimiä varten ja näytetään, miten lyhenteet palautetaan siirrettävään kirjoitusasuun.

Lohkot

Kolme pientä lohkoa riittää. Kortissa on kaksi kenttää:

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>

Osio kietoo sisäänsä kaiken sille sijoitetun, ja siinä on kenttä heading, joka on määritetty samalla tavalla kuin kortin kenttä:

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

Toisessa nimiavaruudessa on painike acme-ui/button, jossa on kentät label ja href:

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

Tunnisteet lohkomallissa

Lohkomallit renderöivät tunnisteet automaattisesti. Asetusta ei tarvita. Ominaisuuslohko voi tulostaa suoraan kaksi korttia ja ydinerottimen:

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>

Komennon acme/features renderöinti tuottaa seuraavan tuloksen:

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>

Jokaista tulosteen Blockstudio-lohkoa edeltää <!--blockstudio/namespace/slug-->-kommentti. Sivupuskuri poistaa sen vastauksesta. Jos tuloste ohittaa puskurin, käytä bs_strip_render_markers(). Molemmat syntaksit ovat samanarvoisia. <bs:acme-card> koodaa lohkon nimen tunnisteeseen, ja <block name="acme/card"> välittää sen määritteenä. Jokaisesta muusta määritteestä tulee kentän arvo, joten title välittyy korttimallille arvona $a['title']. Myös ydinkomponentit toimivat: ne renderöidään sisäänrakennetuilla lohkojen renderöijillä WordPress kautta.

Paritunnisteet ja sisäinen sisältö

Paritunniste välittää lapsielementtinsä lohkolle. Blockstudio-lohkon tapauksessa ne täyttävät kentän <InnerBlocks />, ja sisäkkäiset tunnisteet renderöidään ensin:

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>

Miten tunnisteen nimestä tulee lohkon nimi

Tunnisteen <bs:> nimessä ei ole vinoviivaa, joten Blockstudio etsii sopivaa nimeä. Se korvaa yhdysmerkit yksi kerrallaan vasemmalta oikealle ja valitsee ensimmäisen rekisteröidyn ehdokkaan. <bs:acme-card> ratkeaa ensimmäisellä yrityksellä muotoon acme/card. <bs:acme-ui-button> kokeilee ensin nimeä acme/ui-button, ei löydä vastaavuutta ja ratkeaa sitten nimeksi acme-ui/button. Yhdysmerkkejä sisältävät nimiavaruudet toimivat siis ilman asetuksia, kunhan molemmat ehdokkaat eivät ole olemassa.

Lyhyemmät nimet etuliitteillä

<bs:acme-ui-button> on täsmällinen mutta pitkä. Projektietuliite yhdistää lyhyen tunniste-etuliitteen yhteen tai useampaan nimiavaruuteen. Määritä se tiedostossa blockstudio.json:

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

Tai rekisteröi sama määritys kohteesta PHP:

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

	return $prefixes;
} );

Nyt <acme-card> ratkeaa nimeksi acme/card ja <ui-button> nimeksi acme-ui/button. Jos etuliite sisältää useita nimiavaruuksia, niitä kokeillaan järjestyksessä ja ensimmäinen rekisteröity lohko voittaa. Näin projektin lohko voi syrjäyttää samankaltaisen kirjastolohkon, jolla on sama lyhyt nimi.

Etuliitteitä voi myös yhdistää. <acme-ui-button> kokeilee ensin nimeä acme/ui-button. Kyseistä lohkoa ei ole, ja tunnisteen loppuosa ui-button on itse rekisteröity etuliitetunniste, joten ratkaisu etenee nimeen acme-ui/button. Suora vastaavuus voittaa aina sisäkkäisen.

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>

Tästä renderöityy täsmälleen sama HTML kuin yllä olevasta kanonisesta versiosta.

Etuliitteisiin sovelletaan muutamaa sääntöä:

  • Etuliite koostuu pienistä kirjaimista ja numeroista, alkaa kirjaimella eikä sisällä yhdysmerkkejä.
  • Jos etuliitteellinen tunniste ei vastaa rekisteröityä lohkoa, se jätetään tulosteeseen ennalleen. Esimerkiksi <acme-missing title="x" /> säilyy sellaisenaan.
  • blockstudio/block_tags/tag_aliases-suodattimen tarkat aliakset ohittavat etuliitteet. Alias yhdistää yhdysmerkillisen tunnisteen yhteen lohkoon. Esimerkiksi $aliases['acme-cta'] = 'acme-ui/button'; saa <acme-cta> renderöimään painikkeen.

Etuliite- ja aliastunnisteet renderöidään lohkomalleissa rinnakkain tunnisteiden <bs:> ja <block> kanssa versiosta Blockstudio 7.5 alkaen.

Attribuutit

Kentän tunnusta vastaavista määritteistä tulee kenttäarvoja. Kahdella etuliitteellä on toinen tehtävä:

  • data-*-määritteet kopioidaan renderöidyn lohkon juurielementtiin.
  • html-*-määritteet kopioidaan juurielementtiin siten, että etuliite poistetaan. Esimerkiksi html-id="intro" muuttuu muotoon 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 asettaa määritteen; se ei lisää arvoa siihen: lohkon omat luokat acme-card wp-block-acme-card katoavat. Jos kutsujan pitäisi voida lisätä luokkia lohkoon, määritä niitä varten kenttä ja yhdistä arvot mallissa.

Muut määritteet, jotka eivät ole määritettyjä kenttiä, pudotetaan. Pelkkä class="wide" tunnisteessa <bs:acme-card> renderöi kortin ilman kyseistä määritettä. Versio Blockstudio 7.7 ilmoittaa tällaisista määritteistä _doing_it_wrong()-huomautuksella, kun WP_DEBUG on käytössä.

Samat tunnisteet sivulähteissä

Tiedostopohjaisilla sivuilla, kuvioissa ja Site Templates -malleissa tunnisteita ei renderöidä. Ne muunnetaan lohkoiksi lähdekoodia jäsennettäessä, joten ne näkyvät editorissa. Tämä sivulähde:

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>

jäsentyy seuraavaksi lohkomerkinnäksi (rivinvaihdot lisätty luettavuuden vuoksi):

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

Kenttäarvot sijoitetaan kohteen blockstudio.attributes alle; tätä paikkaa Blockstudio-lohkot käyttävät arvojen tallentamiseen. Kappaleesta ja kahdesta sisälohkosta tulee osion sisälohkoja. Etuliitteet ja aliakset ratkeavat samalla tavalla kuin malleissa.

Tunnisteet sisältöteksteissä

Editorissa kirjoitettua tai vimpaimiin tallennettua sisältöä ei oletusarvoisesti tarkisteta. Ota sivutason renderöinti käyttöön kohdassa blockstudio.json:

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

Tunnisteet kohteissa the_content ja widget_text renderöidään tämän jälkeen prioriteetilla 5. Sama asetus rekisteröi suodattimen, joka renderöi tunnisteet mistä tahansa merkkijonosta:

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

Rajoita renderöitäviä tunnisteita kuvioilla allow ja deny. Ne hyväksyvät fnmatch()-jokerimerkit ja koskevat kaikkia syntakseja sekä kumpaakin renderöintitilaa:

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

Kun tämä sääntö on käytössä, <acme-ui-button> ja <bs:acme-ui-button> jäävät tulosteeseen renderöimättöminä. deny ohittaa kohteen allow. Suodattimet blockstudio/block_tags/allow ja blockstudio/block_tags/deny muokkaavat samoja luetteloita kohteesta PHP.

Analyysi tarkistaa kanonisen kirjoitusasun

PHPStan-laajennus tarkistaa lohkotunnisteet malleissa PHP, Twig ja Blade. Väärin kirjoitettu kentän tai lohkon nimi ilmoitetaan yhdessä sen lohkon kanssa, johon tunniste ratkesi:

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

Versiossa 7.6 tämä koskee tunnisteita <bs:> ja <block>. Etuliitetunniste, kuten <acme-card txt="...">, ohittaa tarkistuksen. Versio Blockstudio 7.7 laajentaa säännön etuliitetunnisteisiin, sivulähteisiin ja yhdistettyihin HTML-elementteihin; sen vihjeessä luetellaan yleiset määritteet, joita tunniste voi välittää.

Palauta lyhenteet kanoniseen kirjoitusasuun

Etuliite- ja aliastunnisteet helpottavat projektin käyttöä. Ne ratkeavat vain siellä, missä projektin suodattimet ja asetukset on ladattu, joten toiseen projektiin tai lohkokirjastoon kopioitu malli tai koodausagentin konteksti menettää niiden merkityksen. <bs:namespace-slug> tallentaa lohkon oikean nimen ja toimii kaikkialla. Siksi Blockstudio käyttää sitä omissa esimerkeissään, diagnostiikassaan ja luodussa tulosteessaan.

Erillinen komento muuntaa lyhenteet tähän kirjoitusasuun. Oletetaan projekti, jonka lähteissä on yhä lyhyitä muotoja, myös alias, tunniste jo poistettua lohkoa varten ja esimerkki koodinäytteen sisällä:

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>

Komento ei lataa kohdetta WordPress, joten se ottaa projektin asetukset JSON-tiedostoina, jotka säilytetään skannattavan hakemistopuun ulkopuolella:

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

Aloita kuivaharjoittelulla, joka on myös oletusasetus:

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.

Raportissa luetellaan kaikki käytettävät muunnokset ja tapaukset, joiden merkitystä se ei arvaa:

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

Raporttia on tässä lyhennetty. Se sisältää myös asetusten ja tiedostokohtaiset tiivisteet ennen muutosta ja sen jälkeen. Osion alku- ja lopputunniste lasketaan kahdeksi esiintymäksi. acme-quote vastaa etuliitettä acme, mutta ei nimeä tunnettua lohkoa, joten se on tuntematon. Kohteessa <pre><code> oleva acme-card on esimerkki, ei merkintää, joten se ilmoitetaan tarkistettavaksi käsin eikä sitä koskaan kirjoiteta uudelleen. Sama koskee HTML-kommentteja ja koodin sisäistä tekstiä.

Muutosten käyttöönotto estetään, jos jäljellä on tuntemattomia, monitulkintaisia tai dynaamisia tunnisteita:

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

Komento palauttaa virhekoodin 2. Korjaa tuntematon tunniste poistamalla se ja suorita sitten komento valitsimella --apply valitsimen --dry-run sijaan:

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

Vain tunnisteiden nimet muuttuvat. Määritteet säilyvät tavu tavulta:

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

Kun kuivaharjoittelu suoritetaan uudelleen tuloksen päällä, raportissa näkyy 0 changed, 0 replacements. Etuliitteet voi jättää rekisteröidyiksi, joten mikään ei rikkoudu, vaikka muut haarat käyttäisivät edelleen lyhyttä muotoa.

Seuraavat vaiheet