Menyusun Template dengan Tag Blok
Setelah sebuah proyek memiliki beberapa blok, template mulai saling membutuhkan. Blok fitur ingin menampilkan tiga kartu. Halaman landing menginginkan bagian dengan tombol di dalamnya. Anda dapat memanggil bs_render_block() untuk setiap blok, tetapi template yang penuh dengan pemanggilan PHP dan array bersarang sulit dibaca dan lebih sulit lagi untuk disusun bertingkat.
Tag blok memungkinkan Anda menulis blok di tempat keluarannya seharusnya muncul, sebagai tag HTML:
<bs:acme-card title="Fast" text="Rendered on the server." />
Tag yang sama memiliki dua arti berbeda, bergantung pada tempat penulisannya. Di template blok atau konten pos, tag diganti dengan HTML blok yang telah dirender. Di sumber halaman, pola, atau Template Situs, tag menjadi blok WordPress sungguhan yang muncul di editor. Panduan ini membuat beberapa blok, menyusunnya dengan kedua cara, menambahkan prefiks proyek untuk nama yang lebih singkat, lalu menunjukkan cara mengubah singkatan itu kembali ke ejaan portabel.
Blok-bloknya
Tiga blok kecil sudah cukup. Kartu dengan dua kolom:
{
"$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>
Bagian yang membungkus apa pun yang ditempatkan di dalamnya, dengan kolom heading yang dideklarasikan dengan cara yang sama seperti milik kartu:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
Dan tombol dalam namespace kedua, acme-ui/button, dengan kolom label dan href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Tag di dalam template blok
Template blok merender tag secara otomatis. Tidak perlu pengaturan. Blok fitur dapat langsung menampilkan dua kartu dan pemisah inti:
<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>
Merender acme/features menghasilkan:
<!--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>
Setiap blok Blockstudio dalam output didahului oleh komentar <!--blockstudio/namespace/slug-->. Buffer halaman menghapusnya dari respons; untuk output yang melewati buffer, gunakan bs_strip_render_markers().
Kedua sintaks tersebut setara. <bs:acme-card> menyandikan nama blok dalam tag, sedangkan <block name="acme/card"> meneruskannya sebagai atribut. Setiap atribut lainnya menjadi nilai field, sehingga title diteruskan ke templat kartu sebagai $a['title']. Blok inti juga berfungsi, dirender melalui WordPress dengan perender blok bawaan.
Tag berpasangan dan konten di dalamnya
Tag berpasangan meneruskan elemen turunannya ke blok. Untuk blok Blockstudio, elemen tersebut mengisi <InnerBlocks />, dan tag yang bersarang di dalamnya dirender terlebih dahulu:
<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>
Cara nama tag menjadi nama blok
Nama tag <bs:> tidak memiliki garis miring, jadi Blockstudio akan mencari blok. Sistem mengganti setiap tanda hubung dengan garis miring secara berurutan, dari kiri ke kanan, lalu menggunakan kandidat pertama yang terdaftar. <bs:acme-card> langsung diubah menjadi acme/card. <bs:acme-ui-button> mencoba acme/ui-button, tidak menemukan apa pun, lalu diubah menjadi acme-ui/button. Karena itu, namespace yang memiliki tanda hubung dapat digunakan tanpa konfigurasi, selama kedua kandidat tidak sama-sama tersedia.
Nama lebih singkat dengan prefiks
<bs:acme-ui-button> memang presisi, tetapi panjang. Prefiks proyek memetakan prefiks tag singkat ke satu atau beberapa namespace. Konfigurasikan di blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Atau daftarkan pemetaan yang sama dari PHP:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Kini <acme-card> diubah menjadi acme/card, dan <ui-button> menjadi acme-ui/button. Jika sebuah prefiks mencantumkan beberapa namespace, sistem akan mencobanya secara berurutan dan memilih blok terdaftar pertama. Dengan begitu, blok proyek dapat menimpa blok pustaka dengan slug yang sama.
Prefiks juga dapat disusun. <acme-ui-button> pertama-tama mencoba acme/ui-button. Blok itu tidak ada, dan bagian tag yang tersisa, ui-button, juga merupakan tag prefiks yang terdaftar, jadi resolusi berlanjut hingga acme-ui/button. Kecocokan langsung selalu diutamakan daripada yang bersarang.
<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>
Ini merender HTML yang persis sama dengan versi kanonis di atas.
Ada beberapa aturan yang berlaku untuk prefiks:
- Prefiks terdiri dari huruf kecil dan angka, dimulai dengan huruf, dan tidak mengandung tanda hubung.
- Tag berprefiks yang tidak mengarah ke blok terdaftar akan dibiarkan apa adanya dalam keluaran, sehingga
<acme-missing title="x" />tetap seperti yang ditulis. - Alias persis dari filter
blockstudio/block_tags/tag_aliasesdiutamakan daripada prefiks. Alias memetakan satu tag bertanda hubung ke satu blok; misalnya,$aliases['acme-cta'] = 'acme-ui/button';membuat<acme-cta>merender tombol.
Tag prefiks dan alias dirender dalam template blok bersama tag <bs:> dan <block> dari Blockstudio 7.5.
Atribut
Atribut yang cocok dengan ID kolom menjadi nilai kolom. Dua prefiks memiliki fungsi lain:
- Atribut
data-*disalin ke elemen akar blok yang dirender. - Atribut
html-*disalin ke elemen akar dengan prefiks dihapus, sehinggahtml-id="intro"menjadiid="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 menetapkan atribut, bukan menambahkannya: kelas acme-card wp-block-acme-card milik blok akan hilang. Jika pemanggil perlu menambahkan kelas ke blok, deklarasikan kolom untuk kelas tersebut lalu gabungkan di template.
Atribut lain yang bukan kolom terdeklarasi akan dihapus. class="wide" biasa pada <bs:acme-card> akan merender kartu tanpa atribut tersebut. Blockstudio 7.7 melaporkan atribut semacam itu dengan pemberitahuan _doing_it_wrong() saat WP_DEBUG aktif.
Tag yang sama di sumber halaman
Di halaman berbasis file, pola, dan Template Situs, tag tidak dirender. Tag diubah menjadi blok saat sumber diurai, sehingga muncul di editor. Sumber halaman ini:
<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>
diurai menjadi markup blok ini (baris baru ditambahkan agar mudah dibaca):
<!-- 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 -->
Nilai kolom ditempatkan di bawah blockstudio.attributes, tempat blok Blockstudio menyimpannya, dan paragraf serta kedua blok di dalamnya menjadi blok anak bagian tersebut. Prefiks dan alias diubah di sini sama seperti di template.
Tag di konten pos
Konten yang ditulis di editor atau disimpan di widget tidak dipindai secara default. Aktifkan perenderan tingkat halaman di blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
Setelah itu, tag di the_content dan widget_text dirender pada prioritas 5. Pengaturan yang sama mendaftarkan filter untuk merender tag dalam string apa pun:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Batasi tag yang boleh dirender menggunakan pola allow dan deny, yang menerima wildcard fnmatch() dan berlaku untuk setiap sintaks serta kedua mode perenderan:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Dengan aturan tersebut, <acme-ui-button> dan <bs:acme-ui-button> dibiarkan tanpa dirender dalam keluaran. deny diutamakan daripada allow. Filter blockstudio/block_tags/allow dan blockstudio/block_tags/deny mengubah daftar yang sama dari PHP.
Analisis memeriksa ejaan kanonis
Ekstensi PHPStan memvalidasi tag blok di template PHP, Twig, dan Blade. Kolom atau nama blok yang salah eja dilaporkan bersama blok yang cocok dengannya:
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
Pada versi 7.6, ini mencakup tag <bs:> dan <block>. Tag prefiks seperti <acme-card txt="..."> tidak diperiksa. Blockstudio 7.7 memperluas aturan ke tag prefiks, sumber halaman, dan elemen HTML yang dipetakan; petunjuknya juga mencantumkan atribut global yang dapat diteruskan oleh tag.
Ubah singkatan ke ejaan kanonis
Tag prefiks dan alias memudahkan proyek. Tag tersebut hanya dapat diubah jika filter dan pengaturan proyek dimuat. Jadi, template yang disalin ke proyek lain, pustaka blok, atau konteks agen pemrograman akan kehilangan maknanya. <bs:namespace-slug> mencatat nama blok yang sebenarnya dan dapat diubah di mana pun. Karena itu, contoh, diagnostik, dan keluaran yang dihasilkan oleh Blockstudio sendiri menggunakannya.
Perintah mandiri mengubah singkatan ke ejaan tersebut. Ambil contoh proyek yang sumbernya masih menggunakan bentuk singkat, termasuk alias, tag untuk blok yang sudah tidak ada, dan contoh di dalam sampel kode:
<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>
Perintah ini tidak memuat WordPress, jadi konfigurasi proyek harus disediakan sebagai file JSON di luar pohon yang dipindai:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Mulai dengan uji coba, yang juga merupakan pilihan default:
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.
Laporan mencantumkan setiap pemetaan yang akan diterapkan dan setiap kasus yang tidak dapat dipastikan:
{
"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" }
]
}
Laporan ini diringkas. Laporan juga mencatat konfigurasi dan hash sebelum serta sesudah untuk tiap file. Tag pembuka dan penutup bagian dihitung sebagai dua kemunculan. acme-quote cocok dengan prefiks acme, tetapi tidak menunjuk ke blok yang dikenal, sehingga dianggap tidak diketahui. acme-card di dalam <pre><code> hanyalah contoh, bukan markup, sehingga dilaporkan untuk ditinjau secara manual dan tidak pernah ditulis ulang. Hal yang sama berlaku untuk komentar HTML dan kode inline.
Penerapan ditolak selama masih ada tag yang tidak diketahui, ambigu, atau dinamis:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Perintah keluar dengan 2. Perbaiki tag yang tidak diketahui, dalam contoh ini dengan menghapusnya, lalu jalankan dengan --apply sebagai pengganti --dry-run:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Hanya nama tag yang berubah. Atribut dipertahankan byte demi byte:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Menjalankan kembali uji coba pada hasil tersebut akan melaporkan 0 changed, 0 replacements. Prefiks dapat tetap terdaftar sesudahnya, sehingga tidak ada yang rusak selama cabang lain masih menggunakan bentuk singkat.
Langkah berikutnya
- Perenderan: sintaks tag lengkap, perender kustom, dan parser.
- Pengaturan: setiap opsi
blockTags. - Membangun Halaman Berbasis File: sumber halaman yang tag-nya menjadi blok yang dapat diedit.
- Migrasi Tag Blok: semua opsi perintah migrasi.
- Memeriksa Template dengan PHPStan: menjalankan analisis untuk memvalidasi tag.