Şablonları Blok Etiketleriyle Birleştirme
Bir projede birkaç blok olduğunda şablonların birbirine ihtiyacı olmaya başlar. Özellikler bloğu üç kart yazdırmak ister. Açılış sayfası, içinde bir düğme bulunan bir bölüm ister. Her biri için bs_render_block() çağırabilirsiniz; ancak iç içe dizilerle dolu bir şablonda PHP çağrıları kullanmak okumayı ve iç içe yerleştirmeyi zorlaştırır.
Blok etiketleri, bir bloğu çıktısının yer alacağı yere HTML etiketi olarak yazmanıza olanak tanır:
<bs:acme-card title="Fast" text="Rendered on the server." />
Aynı etiket, yazıldığı yere bağlı olarak iki farklı anlama gelir. Bir blok şablonunda veya yazı içeriğinde bloğun oluşturulmuş HTML öğesiyle değiştirilir. Bir sayfa, desen veya Site Template kaynağında ise düzenleyicide görünen gerçek bir WordPress bloğuna dönüşür. Bu kılavuz birkaç blok oluşturur, bunları iki şekilde birleştirir, kısa adlar için proje öneki ekler ve ardından bu kısaltmaları taşınabilir yazıma dönüştürmeyi gösterir.
Bloklar
Üç küçük blok yeterlidir. İki alanlı bir kart:
{
"$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>
İçine yerleştirilen her şeyi saran ve karttakiyle aynı şekilde tanımlanmış bir heading alanı olan bölüm:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
İkinci ad alanında acme-ui/button bulunan, label ve href alanlarına sahip bir düğme:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Blok şablonunda etiketler
Blok şablonları etiketleri otomatik işler. Herhangi bir ayar gerekmez. Bir özellikler bloğu doğrudan iki kart ve bir çekirdek ayırıcı yazdırabilir:
<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 işlendiğinde şu çıktı üretilir:
<!--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>
Çıktıdaki her Blockstudio bloğunun önünde bir <!--blockstudio/namespace/slug--> yorumu bulunur. Sayfa arabelleği bunu yanıttan kaldırır; arabelleği atlayan çıktılar için bs_strip_render_markers() kullanın.
İki sözdizimi eşdeğerdir. <bs:acme-card> blok adını etikette kodlar, <block name="acme/card"> ise bunu bir öznitelik olarak iletir. Diğer tüm öznitelikler alan değerine dönüşür; bu nedenle title, kart şablonuna $a['title'] olarak ulaşır. Çekirdek bloklar da yerleşik blok oluşturucular aracılığıyla WordPress üzerinden işlenir.
Eşleşen etiketler ve iç içerik
Eşleşen bir etiket, alt öğelerini bloğa aktarır. Blockstudio bloğunda bunlar <InnerBlocks /> alanını doldurur; iç içe etiketler önce işlenir:
<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>
Etiket adı blok adına nasıl dönüşür
<bs:> etiketi adında eğik çizgi yoktur; bu yüzden Blockstudio bir eşleşme bulur. Her kısa çizgiyi soldan sağa sırayla eğik çizgiyle değiştirir ve kayıtlı olan ilk adayı kullanır. <bs:acme-card> ilk denemede acme/card olarak çözümlenir. <bs:acme-ui-button>, acme/ui-button değerini dener, sonuç bulamaz ve ardından acme-ui/button olarak çözümlenir. Bu nedenle kısa çizgi içeren ad alanları, iki adayın da mevcut olmaması koşuluyla yapılandırma gerektirmeden çalışır.
Öneklerle daha kısa adlar
<bs:acme-ui-button> açık ve kesindir ancak uzundur. Proje öneki, kısa bir etiket önekini bir veya daha fazla ad alanına bağlar. Bunu blockstudio.json içinde yapılandırın:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Aynı eşlemeyi PHP üzerinden de kaydedebilirsiniz:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Artık <acme-card>, acme/card olarak; <ui-button> ise acme-ui/button olarak çözümlenir. Bir önek birden çok ad alanı içerdiğinde bunlar sırayla denenir ve kayıtlı ilk blok kullanılır. Böylece bir proje bloğu, aynı kısa ada sahip kitaplık bloğunun önüne geçebilir.
Önekler iç içe de kullanılabilir. <acme-ui-button> önce acme/ui-button değerini dener. Bu blok mevcut değildir; etiketin geri kalanı olan ui-button kendi başına kayıtlı bir önek etiketi olduğundan çözümleme devam edip acme-ui/button değerine ulaşır. Doğrudan eşleşme her zaman iç içe eşleşmeden önce gelir.
<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>
Bu, yukarıdaki standart sürümle tamamen aynı HTML öğesini oluşturur.
Öneklerle ilgili birkaç kural vardır:
- Önek küçük harflerden ve rakamlardan oluşur, bir harfle başlar ve kısa çizgi içermez.
- Kayıtlı bir blokla eşleşmeyen önekli etiket çıktıda değiştirilmeden bırakılır; yani
<acme-missing title="x" />yazıldığı gibi kalır. blockstudio/block_tags/tag_aliasesfiltresindeki tam takma adlar öneklerden önce gelir. Bir takma ad, kısa çizgi içeren bir etiketi tek bir bloğa bağlar. Örneğin$aliases['acme-cta'] = 'acme-ui/button';,<acme-cta>etiketinin düğmeyi oluşturmasını sağlar.
Önek ve takma ad etiketleri, Blockstudio 7.5’teki <bs:> ve <block> etiketleriyle birlikte blok şablonlarında işlenir.
Öznitelikler
Alan kimliğiyle eşleşen öznitelikler alan değerlerine dönüşür. İki önek farklı işler yapar:
data-*öznitelikleri oluşturulan bloğun kök öğesine kopyalanır.html-*öznitelikleri, önekleri kaldırılarak kök öğeye kopyalanır; böylecehtml-id="intro",id="intro"haline gelir.
<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 özniteliği ayarlar, ona ekleme yapmaz: bloğun kendi acme-card wp-block-acme-card sınıfları silinir. Çağıran kod bloğa sınıf ekleyecekse bunun için bir alan tanımlayın ve şablonda birleştirin.
Tanımlı bir alan olmayan diğer tüm öznitelikler atılır. <bs:acme-card> üzerinde düz bir class="wide", kartı bu öznitelik olmadan oluşturur. WP_DEBUG açıkken Blockstudio 7.7, bu tür öznitelikleri _doing_it_wrong() bildirimiyle raporlar.
Sayfa kaynaklarında aynı etiketler
dosya tabanlı sayfalarda, desenlerde ve Site Template’lerde etiketler işlenmez. Kaynak ayrıştırılırken bloklara dönüştürülür ve düzenleyicide görünürler. Bu sayfa kaynağı:
<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>
şu blok işaretlemesine ayrıştırılır (okumayı kolaylaştırmak için satır sonları eklendi):
<!-- 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 -->
Alan değerleri blockstudio.attributes altına yerleşir; Blockstudio blokları da bunları burada saklar. Paragraf ve iki iç blok, bölümün iç bloklarına dönüşür. Önekler ve takma adlar burada, şablonlardakiyle aynı şekilde çözümlenir.
Yazı içeriğindeki etiketler
Düzenleyicide yazılan veya bileşenlerde saklanan içerik varsayılan olarak taranmaz. Sayfa düzeyinde işlemeyi blockstudio.json içinde etkinleştirin:
{
"blockTags": {
"enabled": true
}
}
Böylece the_content ve widget_text içindeki etiketler 5 önceliğinde işlenir. Aynı ayar, herhangi bir dizedeki etiketleri işlemek için de filtre kaydeder:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Hangi etiketlerin işlenebileceğini fnmatch() joker karakterlerini kabul eden ve her sözdizimiyle her iki işleme kipine uygulanan allow ve deny kalıplarıyla sınırlayın:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Bu kural uygulandığında <acme-ui-button> ve <bs:acme-ui-button> çıktıda işlenmeden bırakılır. deny, allow öğesinden önce gelir. blockstudio/block_tags/allow ve blockstudio/block_tags/deny filtreleri, PHP kaynaklı aynı listeleri değiştirir.
Analiz, standart yazımı denetler
PHPStan uzantısı, PHP, Twig ve Blade şablonlarındaki blok etiketlerini doğrular. Yanlış yazılmış bir alan veya blok adı, eşleştiği blokla birlikte bildirilir:
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 sürümünde bu denetim <bs:> ve <block> etiketlerini kapsar. <acme-card txt="..."> gibi önek etiketleri denetlenmeden geçer. Blockstudio 7.7, kuralı önek etiketlerine, sayfa kaynaklarına ve eşlenmiş HTML öğelerine genişletir; ipucunda etiketin aktarabileceği genel öznitelikler listelenir.
Kısaltmaları standart yazıma dönüştürme
Önek ve takma ad etiketleri projeye kolaylık sağlar. Yalnızca projenin filtreleri ve ayarları yüklendiğinde çözümlenir; dolayısıyla başka bir projeye kopyalanan şablonda, blok kitaplığında veya kodlama aracısının bağlamında anlamını yitirir. <bs:namespace-slug> gerçek blok adını kaydeder ve her yerde çözümlenir. Bu nedenle Blockstudio kendi örneklerinde, tanılama iletilerinde ve oluşturduğu çıktıda bu yazımı kullanır.
Tek başına çalışan bir komut, kısaltmaları bu yazıma dönüştürür. Kaynaklarında takma ad, artık var olmayan bir bloğa ait etiket ve bir kod örneği içindeki etiket de dahil kısa biçimlerin kullanıldığı bir proje ele alalım:
<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>
Komut WordPress yüklemez; bu nedenle taranan ağacın dışında tutulan proje yapılandırmasını JSON dosyaları olarak alır:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Değişiklikleri uygulamadan çalıştırmayla başlayın; bu aynı zamanda varsayılan seçenektir:
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.
Raporda, uygulanacak her eşleme ve tahmin edilmeyecek her durum listelenir:
{
"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" }
]
}
Rapor burada kısaltılmıştır. Raporda ayrıca yapılandırma kaydedilir ve her dosya için önceki ve sonraki özet değerleri tutulur. Bölümün açılış ve kapanış etiketleri iki kullanım sayılır. acme-quote, acme önekiyle eşleşir ancak bilinen bir blok adı belirtmez; bu yüzden bilinmiyor olarak değerlendirilir. <pre><code> içindeki acme-card, işaretleme değil örnektir; bu nedenle elle incelenmek üzere bildirilir ve hiçbir zaman yeniden yazılmaz. Aynı durum HTML yorumları ve satır içi kod için de geçerlidir.
Bilinmeyen, belirsiz veya dinamik etiketler kaldığı sürece değişiklikler uygulanmaz:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Komut 2 ile çıkar. Bilinmeyen etiketi (burada onu kaldırarak) düzeltin ve --dry-run yerine --apply ile çalıştırın:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Yalnızca etiket adları değişir. Öznitelikler bayt düzeyinde korunur:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Sonuç üzerinde değişiklikleri uygulamadan çalıştırma yeniden yapıldığında 0 changed, 0 replacements bildirilir. Önekler bundan sonra da kayıtlı kalabilir; böylece kısa biçimi kullanan diğer dallarda hiçbir şey bozulmaz.
Sonraki adımlar
- İşleme: etiket sözdiziminin tamamı, özel işleyiciler ve ayrıştırıcı.
- Ayarlar: tüm
blockTagsseçenekleri. - Dosya Tabanlı Sayfalar Oluşturma: etiketlerin düzenlenebilir bloklara dönüştüğü sayfa kaynakları.
- Blok Etiketi Geçişi: geçiş komutunun tüm seçenekleri.
- Denetlenen Şablonlar: PHPStan⟧: etiketleri doğrulayan analizi çalıştırma.