İçeriğe geç

Ö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

PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>

Twig

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:

PHP
// 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:

PHP
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; min bulunan bir tekrarlayıcı başlangıç satırlarını içerir.
  • Üst düzey değerler ile blockstudio.attributes birleş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.attributes okur.
  • Dönüş biçimleri uygulanır; böylece label değerindeki returnFormat seçimi etiketi, dosya alanı ise ek verilerini verir.
  • Devre dışı ve boş alanlar, şablondaki gibi false olur.

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
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

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

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ı alanı, URL ve özniteliklerini içeren bir nesne döndürür:

PHP

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

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
<?php if ($a['icon']) : ?>
  <div class="icon">
    <?php bs_render_icon($a['icon']); ?>
  </div>
<?php endif; ?>

Twig

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

PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
  Content
</div>

Twig

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
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>

Twig

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:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "attributes": [
        { "id": "kicker", "type": "text" },
        { "id": "title", "type": "text" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/section-header" }
    ]
  }
}
Twig
{% 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
<?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

Twig
{% for item in a.items %}
  <div class="item">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
  </div>
{% endfor %}

Alan Kalıpları Rehberi