Öznitelikleri Oluşturma
Şablon dosyalarının içindeki tüm özniteliklere, $attributes veya $a değişkenleri ve alanın ilgili kimliği kullanılarak erişilebilir.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Öznitelikleri Programlı Olarak Yazma
Düzenleyici, kaydedilmiş değerleri blockstudio.attributes altında iç içe yerleştirir. REST API, WP-CLI, içerik taşıma işlemi veya MCP sunucusu gibi düzenleyici dışında blok yazan araçlar, WP_Block_Type üzerinde Blockstudio tarafından kaydedilen özniteliklerden bloğu keşfeder ve bunları en üst düzeyde yazar. Her iki biçim de oluşturulur:
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );
// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );
Yalnızca bloğun bildirdiği kimlikler en üst düzeyden okunur; bu nedenle WordPress öğesinin anchor, className, lock, metadata ve style gibi kendi öznitelikleri hiçbir zaman alan değeri olarak alınmaz. Aynı kimlik her iki yerde de bulunduğunda iç içe değer önceliklidir.
Öznitelikleri Programatik Olarak Okuma
Şablon dışında çalışan kod; örneğin save_post üzerindeki yapılandırılmış veriler, dışa aktarımlar, arama dizinleme veya bir render_block filtresi, çoğu zaman kayıtlı bir bloğun değerlerini şablonun gördüğü biçimde gerektirir. bs_block_values(), bloğu oluşturmadan bu değerleri döndürür. Blok kaydından sonra (init veya daha sonra), parse_blocks() içindeki eksiksiz attrs dizisiyle çağırın:
foreach (parse_blocks($post->post_content) as $block) {
if ($block['blockName'] === null) {
continue;
}
$a = bs_block_values($block['blockName'], $block['attrs']);
if ($a === null) {
// Not a Blockstudio block, and no extension applies.
continue;
}
echo esc_html($a['title'] ?? '');
}
Sonuç, alan kimliğine göre anahtarlanmış, şablondaki $a dizisidir:
- Alan varsayılanları uygulanır;
minbulunan bir tekrarlayıcı başlangıç satırlarını içerir. - Üst düzey değerler ile
blockstudio.attributesbirleştirilir ve iç içe değer öncelik kazanır. Üst düzeyden yalnızca tanımlı kimlikler okunur; WordPress, örneğin bir seçim dizesi gibi, alanın kayıtlı türüyle eşleşmeyen üst düzey değeri, oluşturma sırasında olduğu gibi kaldırır. - Eşleşen uzantı alanları varsayılanlarıyla birlikte dahil edilir. Çekirdek veya üçüncü taraf bir bloğun uzantısı, oluşturma sırasında olduğu gibi yalnızca
blockstudio.attributesokur. - Dönüş biçimleri uygulanır; böylece
labeldeğerindekireturnFormatseçimi etiketi, dosya alanı ise ek verilerini verir. - Devre dışı ve boş alanlar, şablondaki gibi
falseolur.
null, ne bloğun ne de bir uzantının Blockstudio tarafından yönetildiği anlamına gelir. Alan içermeyen bir Blockstudio bloğu [] döndürür.
İşlev, oluşturmayla aynı dönüştürmeyi çalıştırır; bu nedenle aynı yan etkileri vardır: dosya alanları ekleri sorgular, data döndürmeyen bir blok alanı başvurulan bloğu oluşturur ve her değer için blockstudio/blocks/attributes/render filtresi çalışır. Bloğun kendi şablonunu oluşturmaz ve innerBlocks çözümlemez; bunları kendiniz dolaşın. Kod alanı, çağrılar arasında farklılık gösteren, oluşturulmuş bir %selector% kimliğini korur.
Çözümleme mevcut WordPress bağlamını kullanır. Blok sayaçları ve innerBlocks gibi yalnızca oluşturma sırasında kullanılan meta veriler oluşturulmaz; öznitelik oluşturma filtreleri, tamamen oluşturulmuş bloğun meta verileri yerine blok adını alır.
Dönüştürülmemiş kayıtlı değerleri almak için bir seçenek yoktur. Bunları okumak için attrs dizisini doğrudan okuyun veya denetlemek için bs_validate_block() kullanın.
Boş Değerler
Alan boşsa veya hiçbir seçenek seçilmemişse öznitelik değerleri false döndürür.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Karmaşık Türler
Dosyalar
Varsayılan olarak (returnFormat yoksa veya "returnFormat": "object" ise) dosya alanı, ekin verilerini içeren bir dizi döndürür. "multiple": true kullanıldığında bu dizilerden oluşan bir liste döndürür. Eki artık mevcut olmayan dosya false olur.
| Anahtar | Açıklama |
|---|---|
ID |
Ek kimliği. |
title |
Ek başlığı. |
alt |
Alternatif metin. Boşsa ek başlığı kullanılır. |
caption |
Alt yazı. |
description |
Açıklama. |
href |
Ek sayfasının kalıcı bağlantısı. |
url |
Dosyanın URL. Boyut açılır listesindeki ("size": true) değer, seçilen boyutun URL değeridir. |
sizes |
Aşağıda açıklanan, kayıtlı her görsel boyutunun URL değeri ve boyutları. |
PHP
<?php if ($a['image']) :
$image = $a['image'];
$sizes = $image['sizes'] ?? [];
?>
<img
src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
alt="<?php echo esc_attr($image['alt']); ?>"
<?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
width="<?php echo esc_attr($sizes['large-width']); ?>"
height="<?php echo esc_attr($sizes['large-height']); ?>"
<?php endif; ?>
/>
<?php endif; ?>
Twig
{% if a.image %}
<img
src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
alt="{{ a.image.alt|e('html_attr') }}"
{% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
width="{{ a.image.sizes['large-width']|e('html_attr') }}"
height="{{ a.image.sizes['large-height']|e('html_attr') }}"
{% endif %}
/>
{% endif %}
sizes, kayıtlı her görsel boyutu için bir giriş ve ayrıca full içerir: boyut adı altında URL, <size>-width ve <size>-height altında ise boyutlar bulunur. Ek için oluşturulmamış bir WordPress, boyutlarıyla birlikte özgün dosyaya çözülür. WordPress bir görseli veya önizlemeyi çözümlüyorsa sizes anahtarı bulunmaz. Örneğin, oluşturulmuş önizlemesi olmayan bir PDF’de sizes bulunmaz; ancak önizleme meta verileri olan bir PDF’de görsel boyutları olabilir. Kayıtlı görsel boyutu yoksa veya files/sizes filtresi bunları devre dışı bırakıyorsa sizes, null olur. Bu filtre eşlemeyi kısaltabilir; bu nedenle yukarıdaki örneklerde olduğu gibi boyutları okumadan önce ilgili boyutun mevcut olduğunu denetleyin.
Nesnede width, height, mime, type veya size anahtarları yoktur. Boyutları sizes üzerinden okuyun veya wp_get_attachment_image() ve get_post_mime_type() gibi işlevlerle birlikte ID kullanın.
Dönüş biçimleri
returnFormat, alanın döndürdüğü değeri değiştirir:
returnFormat |
Değer |
|---|---|
"object" (varsayılan) |
Yukarıda açıklanan dizi. |
"id" |
Kaydedildiği biçimiyle ek kimliği veya "multiple": true ile kimliklerden oluşan bir liste. |
"url" |
Dize olarak URL veya "multiple": true ile URL’lerden oluşan bir liste. Görseller, returnSize ile ayarlanan boyutu (varsayılan full) kullanır; diğer dosyalar ise kendi dosya URL değerini kullanır. |
Bağlantı
Bağlantı alanı, URL ve özniteliklerini içeren bir nesne döndürür:
PHP
<?php if ($a['link']) : ?>
<a
href="<?php echo $a['link']['url']; ?>"
target="<?php echo $a['link']['target']; ?>"
>
<?php echo $a['link']['title']; ?>
</a>
<?php endif; ?>
Twig
{% if a.link %}
<a href="{{ a.link.url }}" target="{{ a.link.target }}">
{{ a.link.title }}
</a>
{% endif %}
Simge
Simge alanı, set, subSet ve icon anahtarlarını içeren bir nesne döndürür. SVG’yi çıkarmak için bs_render_icon() ve bs_icon() yardımcı işlevlerini kullanın:
PHP
<?php if ($a['icon']) : ?>
<div class="icon">
<?php bs_render_icon($a['icon']); ?>
</div>
<?php endif; ?>
Twig
{% if a.icon %}
<div class="icon">
{{ bs_icon(a.icon) }}
</div>
{% endif %}
bs_render_icon() SVG’yi doğrudan yankılar. bs_icon() ise dize olarak döndürür.
Öznitelikler
Öznitelikler alan türü, HTML öznitelikleri olarak oluşturulacak {attribute, value} çiftlerinden oluşan bir dizi döndürür. Bunları çıkarmak için bs_render_data_attributes() kullanın:
PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
Content
</div>
Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
Content
</div>
bs_render_data_attributes() öznitelikleri doğrudan yankılar. bs_data_attributes() ise dizeyi döndürür.
Grup
Grup alanları, alt öznitelik kimliklerinin başına grup adını ekler. Grup alanlarını temiz bir diziye çıkarmak için bs_get_group() kullanın:
PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>
Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>
Bu, öznitelik anahtarlarından grup önekini kaldırır. Örneğin $a['settings_title'], $group['title'] olur.
Yardımcı işlev, grubun yeniden kullanılan özel bir alandan geldiği durumda da çalışır:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"attributes": [
{ "id": "kicker", "type": "text" },
{ "id": "title", "type": "text" }
]
}
]
}
{
"blockstudio": {
"attributes": [
{ "type": "custom/section-header" }
]
}
}
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>
Tekrarlayıcı
Tekrarlayıcı öğeleri arasında döngü yapın:
PHP
<?php foreach ($a['items'] as $item) : ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['description']; ?></p>
</div>
<?php endforeach; ?>
Twig
{% for item in a.items %}
<div class="item">
<h3>{{ item.title }}</h3>
<p>{{ item.description }}</p>
</div>
{% endfor %}