WordPress Block Bindings API ile Özel Alanları Bloklara Bağlama

WordPress Block Bindings API, özel alan, yazı verisi veya eklenti tarafından hesaplanan bir değeri mevcut blokların niteliklerine bağlamayı sağlar. Böylece yalnızca dinamik veri göstermek için yeni bir blok yazmak zorunda kalmazsınız. WordPress 6.5 ile gelen altyapı; Paragraf, Başlık, Görsel ve Düğme gibi çekirdek blokları veri kaynağına bağlayabilir. WordPress 6.7 ile düzenleyici tarafındaki API genişledi; güncel WordPress sürümlerinde desteklenen blok ve nitelik listesi daha da büyüdü.

Bu rehberde önce core/post-meta kaynağıyla bir özel alanı Paragraf ve Görsel bloklarına bağlayacağız. Ardından register_block_bindings_source() ile özel bir veri kaynağı oluşturacağız. Kodların tamamı eklenti içinde çalışacak şekilde hazırlanmıştır.

Kaynak notu: Örnekler WordPress Block Editor Handbook, WordPress Developer Blog ve register_block_bindings_source() fonksiyon belgesindeki gerçek söz dizimine dayanır.

WordPress Block Bindings API nedir ve neyi çözer?

Block Bindings API, bir blok niteliği ile dinamik veri kaynağı arasında bağlantı kurar. Bağlantı blok yorumundaki metadata.bindings nesnesinde saklanır. Örneğin Paragraf bloğunun content niteliği bir yazı metasına bağlandığında, ön yüzde meta değeri görünür. Düzenleyici de bloğun bağlı olduğunu bilir ve desteklenen sürümlerde bu ilişkiyi arayüzde gösterebilir.

Temel yapı şöyledir:

<!-- wp:paragraph {
  "metadata": {
    "bindings": {
      "content": {
        "source": "core/post-meta",
        "args": { "key": "ozgur_urun_kodu" }
      }
    }
  }
} -->
<p></p>
<!-- /wp:paragraph -->

Bu örnekte üç kritik parça bulunur:

• content: Bağlanacak blok niteliğidir.
• source: Veriyi sağlayan kaynaktır. Burada WordPress çekirdeğindeki core/post-meta kullanılır.
• args.key: Okunacak meta anahtarıdır.

API’nin en büyük avantajı, veri görüntüleme ile blok tasarımını birbirinden ayırmasıdır. Editör arka plan rengini, tipografiyi ve hizalamayı değiştirebilir; geliştirici ise verinin nereden geleceğini yönetir. Tema değişse bile bağlantı blok işaretlemesinde kaldığı için içerik taşınabilirliğini korur.

Bir projede ürün kodunu göstermek için özel dinamik blok yazmıştık. Aynı değer arşiv kartında, tekil yazıda ve sorgu döngüsünde tekrar gerekli oldu. Üç ayrı blok yerine bir Paragraf varyasyonu ve tek meta bağlantısı kullanınca bakım yükü azaldı. En sık karşılaştığımız hata ise meta alanını show_in_rest olmadan kaydetmekti; değer veritabanında bulunsa da düzenleyici bağlantıyı doğru okuyamıyordu.

Dinamik blok ile Block Bindings arasındaki fark

Dinamik blok, tüm HTML çıktısını PHP render_callback ile üretebilir. Bu yöntem karmaşık koşullar, döngüler ve özel bileşenler için hâlâ gereklidir. Block Bindings ise mevcut bir bloğun belirli niteliğine değer verir. Basit metin, URL, alternatif metin veya düğme etiketi için daha az kod ister.

Özel alanı bağlamadan önce meta kaydını hazırlama

Özel alanı blokla bağlamadan önce meta anahtarını WordPress’e kaydetmelisiniz. show_in_rest => true zorunludur; çünkü blok düzenleyici yazı verisini REST API üzerinden yönetir. single, type, sanitize_callback ve yetki kontrolü de açıkça tanımlanmalıdır.

Aşağıdaki kodu ozgur-block-bindings.php adlı küçük bir eklenti dosyasına ekleyin:

<?php
/**
 * Plugin Name: Ozgur Block Bindings Örneği
 * Description: Yazı metasını çekirdek bloklara bağlar.
 * Version: 1.0.0
 */

add_action( 'init', 'ozgur_register_binding_meta' );

function ozgur_register_binding_meta() {
    register_post_meta(
        'post',
        'ozgur_urun_kodu',
        array(
            'show_in_rest'      => true,
            'single'            => true,
            'type'              => 'string',
            'sanitize_callback' => 'sanitize_text_field',
            'auth_callback'     => static function () {
                return current_user_can( 'edit_posts' );
            },
        )
    );
}

register_post_meta() belirli bir yazı türüne meta kaydeder. register_meta() da kullanılabilir; ancak yazı türü açıkça belli olduğunda ilk yöntem daha okunaklıdır. Özel yazı türünde çalışıyorsanız ilk parametreyi ilgili post type slug’ıyla değiştirin. Ayrıca register_post_type() içindeki supports dizisine custom-fields eklemek gerekebilir.

Eklentiyi etkinleştirdikten sonra bir yazıya test değeri kaydedebilirsiniz:

update_post_meta( $post_id, 'ozgur_urun_kodu', 'WP-BIND-2026' );

Gerçek eklentide $post_id sabit yazılmaz. Değeri bir meta kutusu, REST isteği, özel yönetim ekranı veya kayıt süreci üretir. Buradaki amaç, bağlantının okuyacağı veriyi hazırlamaktır.

Meta kaydı için güvenlik kontrol listesi

• Metayı yalnızca gerekli yazı türlerinde kaydedin.
• type ile gerçek veri tipini eşleştirin.
• Metin için sanitize_text_field, URL için esc_url_raw kullanın.
• Düzenleme iznini auth_callback içinde kontrol edin.
• Gizli anahtar, erişim tokeni veya kişisel veriyi ön yüzdeki bloğa bağlamayın.
• REST yanıtında görünmemesi gereken verileri show_in_rest ile açmayın.

Paragraf ve Görsel bloklarını özel alanlara bağlama

İlk bağlantıyı Code Editor üzerinden kurabilirsiniz. Yazı düzenleyicisinde sağ üstteki üç nokta menüsünden Kod düzenleyici görünümüne geçin ve Paragraf işaretlemesini ekleyin:

<!-- wp:paragraph {
  "metadata": {
    "bindings": {
      "content": {
        "source": "core/post-meta",
        "args": { "key": "ozgur_urun_kodu" }
      }
    }
  }
} -->
<p></p>
<!-- /wp:paragraph -->

Yazıyı kaydedip görsel düzenleyiciye döndüğünüzde Paragraf, ozgur_urun_kodu değerine bağlanır. Ön yüzde WP-BIND-2026 görünür. Bağlı içeriğin doğrudan düzenlenip düzenlenememesi WordPress sürümüne, veri kaynağına ve kaynak için tanımlanan düzenleyici API’sine bağlıdır.

Bir Görsel bloğunda birden fazla niteliği aynı anda bağlayabilirsiniz. Önce iki meta anahtarı kaydedin:

register_post_meta(
    'post',
    'ozgur_gorsel_url',
    array(
        'show_in_rest'      => true,
        'single'            => true,
        'type'              => 'string',
        'sanitize_callback' => 'esc_url_raw',
    )
);

register_post_meta(
    'post',
    'ozgur_gorsel_alt',
    array(
        'show_in_rest'      => true,
        'single'            => true,
        'type'              => 'string',
        'sanitize_callback' => 'sanitize_text_field',
    )
);

Ardından Görsel bloğunun url ve alt niteliklerini bağlayın:

<!-- wp:image {
  "metadata": {
    "bindings": {
      "url": {
        "source": "core/post-meta",
        "args": { "key": "ozgur_gorsel_url" }
      },
      "alt": {
        "source": "core/post-meta",
        "args": { "key": "ozgur_gorsel_alt" }
      }
    }
  }
} -->
<figure class="wp-block-image">
  <img src="" alt="" />
</figure>
<!-- /wp:image -->

Burada bağlanan adların blokta gerçekten desteklenen niteliklerle aynı olması gerekir. Yanlışlıkla src yazmak çalışmaz; Görsel bloğundaki nitelik adı url olur, HTML çıktısında bu değer src niteliğine dönüşür. Hangi niteliklerin desteklendiğini güncel Block Editor Handbook listesinden kontrol edin.

Code Editor kullanmadan bağlantı ekleme

WordPress 6.7’den itibaren çekirdek kaynaklar için düzenleyici deneyimi genişledi. Güncel sürümde blok ayarları panelindeki bağlantı veya dinamik veri kontrolleri üzerinden uygun alanı seçebilirsiniz. Arayüz sürüme ve Gutenberg eklentisinin etkin olup olmamasına göre değişebilir. Dağıtılabilir tema veya eklenti geliştiriyorsanız blok varyasyonu ya da pattern içinde metadata.bindings işaretlemesini paketlemek daha tutarlı sonuç verir.

register_block_bindings_source ile özel veri kaynağı oluşturma

core/post-meta yalnızca meta verisi için yeterlidir. Fakat fiyatı harici sistemden, site ayarından veya hesaplanan bir değerden almak isteyebilirsiniz. Bu durumda register_block_bindings_source() ile özel kaynak kaydedilir. Kaynak adı namespace/slug biçiminde olmalı ve kayıt init hook’unda yapılmalıdır.

Aşağıdaki örnek, ozgur/site-bilgisi kaynağını kaydeder. field argümanına göre site adını veya ana sayfa URL’sini döndürür:

add_action( 'init', 'ozgur_register_binding_sources' );

function ozgur_register_binding_sources() {
    register_block_bindings_source(
        'ozgur/site-bilgisi',
        array(
            'label'              => __( 'Site Bilgisi', 'ozgur-bindings' ),
            'get_value_callback' => 'ozgur_site_bilgisi_degeri',
        )
    );
}

function ozgur_site_bilgisi_degeri(
    array $source_args,
    WP_Block $block_instance,
    string $attribute_name
) {
    $field = $source_args['field'] ?? '';

    if ( 'name' === $field ) {
        return get_bloginfo( 'name' );
    }

    if ( 'url' === $field ) {
        return home_url( '/' );
    }

    return null;
}

Kaynağı Paragraf bloğunda şöyle kullanabilirsiniz:

<!-- wp:paragraph {
  "metadata": {
    "bindings": {
      "content": {
        "source": "ozgur/site-bilgisi",
        "args": { "field": "name" }
      }
    }
  }
} -->
<p></p>
<!-- /wp:paragraph -->

Callback geçerli değer bulamazsa null döndürmelidir. WordPress bağlı niteliğin bağlamını $block_instance ve $attribute_name ile iletir. Yazı kimliği gereken özel kaynaklarda uses_context tanımlanabilir:

register_block_bindings_source(
    'ozgur/hesaplanan-deger',
    array(
        'label'              => __( 'Hesaplanan Değer', 'ozgur-bindings' ),
        'get_value_callback' => 'ozgur_hesaplanan_deger',
        'uses_context'       => array( 'postId', 'postType' ),
    )
);

Bu yaklaşım Query Loop içindeki her yazı için farklı değer üretirken yararlıdır. Callback içinde doğrudan global $post değişkenine güvenmek yerine blok bağlamındaki postId değerini kullanın.

Özel kaynakta önbellek ve hata yönetimi

Harici API’yi callback içinde her blok renderında çağırmak ciddi performans sorunu oluşturur. Bir sayfada aynı kaynağı kullanan on blok varsa on ağ isteği çıkabilir. Bu nedenle uzak yanıtı transient veya kalıcı object cache ile saklayın:

function ozgur_uzak_fiyat_degeri( array $args ) {
    $product_id = absint( $args['product_id'] ?? 0 );

    if ( ! $product_id ) {
        return null;
    }

    $cache_key = 'ozgur_price_' . $product_id;
    $cached    = get_transient( $cache_key );

    if ( false !== $cached ) {
        return $cached;
    }

    $response = wp_remote_get(
        'https://api.example.com/products/' . $product_id,
        array( 'timeout' => 3 )
    );

    if ( is_wp_error( $response ) || 200 !== wp_remote_retrieve_response_code( $response ) ) {
        return null;
    }

    $data  = json_decode( wp_remote_retrieve_body( $response ), true );
    $price = sanitize_text_field( $data['price'] ?? '' );

    if ( '' === $price ) {
        return null;
    }

    set_transient( $cache_key, $price, 15 * MINUTE_IN_SECONDS );
    return $price;
}

Üretim ortamında API adresi, kimlik doğrulama yöntemi ve hata kayıtları projeye göre düzenlenmelidir. Gizli tokeni blok args alanına koymayın; blok içeriği veritabanında açık biçimde saklanır.

Düzenleyicide özel kaynağı göstermek ve düzenlemek

Sunucu tarafındaki kayıt ön yüzü çalıştırır. WordPress 6.7 ile özel kaynakların düzenleyicide değer okuyup yazabilmesi için istemci tarafı registerBlockBindingsSource() API’si kullanıma açıldı. Sunucudaki ve istemcideki kaynak adları aynı olmalıdır.

Basitleştirilmiş kayıt örneği:

import { registerBlockBindingsSource } from '@wordpress/blocks';

registerBlockBindingsSource( {
    name: 'ozgur/site-bilgisi',
    label: 'Site Bilgisi',
    getValues( { bindings } ) {
        const values = {};

        Object.entries( bindings ).forEach( ( [ attribute, binding ] ) => {
            if ( binding.args?.field === 'name' ) {
                values[ attribute ] = window.ozgurBindingData.siteName;
            }
        } );

        return values;
    },
    setValues() {
        // Salt okunur kaynak: düzenleme işlemi uygulanmıyor.
    },
    canUserEditValue() {
        return false;
    },
} );

Bu kod derlenmiş bir editör scripti olarak yüklenmelidir. Salt okunur kaynakta canUserEditValue() false döner. Yazılabilir kaynak geliştiriyorsanız setValues() içinde @wordpress/data store’ları veya güvenli bir REST endpoint kullanın. Yetki ve nonce kontrolü yalnızca JavaScript tarafına bırakılmamalıdır; sunucu endpoint’i de capability kontrolü yapmalıdır.

Editor API sözleşmesi WordPress sürümleri arasında geliştiği için paketleri belirli bir WordPress minimum sürümüyle test edin. Güncel fonksiyon imzalarını her sürümde Block Editor Handbook’tan doğrulayın.

Sık yapılan Block Bindings hataları ve teşhis adımları

Bağlı değer ön yüzde boş görünüyor

Önce meta anahtarının gerçekten kayıtlı ve dolu olduğunu doğrulayın. show_in_rest false ise editör değeri göremez. Yanlış post type ile register_post_meta() çağrılması da aynı belirtiyi üretir. WP-CLI erişiminiz varsa test için şu komut kullanılabilir:

wp post meta get 123 ozgur_urun_kodu

REST yanıtını da kontrol edin:

curl -s https://site.example/wp-json/wp/v2/posts/123?_fields=id,meta

Özel meta REST şemasında görünmüyorsa kayıt kodu çalışmıyor, alan başka post type’a kayıtlı veya izin callback’i isteği reddediyor olabilir.

Bağlantı kodu blok doğrulama hatası üretiyor

Blok yorumundaki JSON geçerli olmalıdır. Tek tırnak, sondaki gereksiz virgül veya yanlış kaçış işareti parser’ı bozar. Ayrıca boş HTML iskeleti blok tipine uygun kalmalıdır. Paragraf için

Kaynak kayıtlı fakat callback çalışmıyor

Kaydı init öncesinde veya sonrasında yanlış hook’ta yapmış olabilirsiniz. Fonksiyonun varlığını ve kaynak adını kontrol edin. Hızlı teşhis için callback içine geçici bir kayıt ekleyebilirsiniz:

error_log(
    sprintf(
        'Binding çağrıldı: source=%s attribute=%s',
        'ozgur/site-bilgisi',
        $attribute_name
    )
);

Canlı sitede sürekli error_log() bırakmayın. Test tamamlanınca kaldırın veya yapılandırılabilir bir logger kullanın.

Özel alan boşken blokta beklenmedik metin çıkıyor

Meta alanını her zaman kaydedin ve varsayılan davranışı belirleyin. register_post_meta() içinde default değeri tanımlayabilir ya da özel kaynak callback’inde boş değer için null döndürebilirsiniz. Boş değerde tüm kapsayıcının gizlenmesi gerekiyorsa yalnızca metin niteliği bağlantısı yeterli olmayabilir; koşullu render veya dinamik blok daha doğru seçimdir.

Performans aniden düşüyor

Callback sayısını Query Loop içinde ölçün. Veritabanı sorgusunu her blokta tekrarlamak yerine WordPress meta cache’inden yararlanın. Uzak isteklerde transient kullanın, kısa timeout belirleyin ve başarısız istekte ön yüz renderını bekletmeden null döndürün.

Uygulama ve yayın öncesi kontrol listesi

1. Hedef WordPress minimum sürümünü belirleyin.
2. Kullanacağınız blok ve niteliğin güncel destek listesini kontrol edin.
3. Meta alanını doğru post type için kaydedin.
4. show_in_rest, veri tipi, sanitization ve capability ayarlarını ekleyin.
5. metadata.bindings JSON’unu geçerli biçimde üretin.
6. Özel kaynakları init hook’unda kaydedin.
7. Callback’in değer yokken null döndürmesini sağlayın.
8. Harici API sonuçlarını önbelleğe alın.
9. Editör ve ön yüz değerlerinin aynı olduğunu doğrulayın.
10. Query Loop, şablon, pattern ve tekil yazı bağlamlarında ayrı test yapın.
11. Gizli bilgileri block args içine yazmayın.
12. PHP ve JavaScript tarafında yetki kontrollerini uygulayın.

WordPress’in güncel sürümlerinde Block Bindings kapsamı genişlemeye devam ediyor. Temmuz 2026 geliştirici notları List Item desteği ve iç içe içeriklerin korunması gibi yeni iyileştirmeleri duyurdu. Bu nedenle eski bir blog yazısındaki destek tablosunu kalıcı gerçek kabul etmeyin; uygulama öncesi resmi handbook sayfasını kontrol edin.

WordPress Block Bindings API hakkında sık sorulan sorular

Block Bindings API hangi WordPress sürümünde geldi?

API’nin sunucu tarafındaki ilk sürümü WordPress 6.5 ile geldi. WordPress 6.7, özel kaynakların düzenleyicide değer okuyup yazmasına yönelik istemci API’sini genişletti. Sonraki sürümlerde çekirdek kaynaklar, desteklenen bloklar ve arayüz yetenekleri gelişmeye devam etti.

ACF alanları Block Bindings ile kullanılabilir mi?

Alan gerçek bir post meta olarak kayıtlıysa ve REST erişimi doğru yapılandırılmışsa kullanılabilir. Ancak ACF sürümü, alan tipi ve kayıt biçimi sonucu etkiler. Önce meta anahtarının REST yanıtında göründüğünü doğrulayın; karmaşık repeater veya ilişki alanlarında özel kaynak daha uygun olabilir.

Her blok niteliği bağlanabilir mi?

Hayır. Blok ve nitelik Block Bindings desteği sunmalıdır. Güncel destek listesi sürümlerle değişir. Kendi bloğunuzda ek nitelik desteği için güncel Block Editor Handbook’taki “Extending supported attributes” bölümünü izleyin.

Bağlı özel alan Google tarafından indekslenir mi?

Değer sunucu tarafında nihai HTML’e işlendiği sürece arama motoru çıktıyı normal metin gibi görür. Yalnızca JavaScript sonrasında yüklenen veride indeksleme ve performans davranışı farklı olabilir. Kritik içerik için server-side binding tercih edin.

Block Bindings yerine ne zaman dinamik blok yazmalıyım?

Birden fazla HTML elemanı, karmaşık koşul, veri döngüsü, etkileşimli uygulama durumu veya tamamen özel editör arayüzü gerekiyorsa dinamik blok daha uygundur. Tek bir metin, URL, ALT veya düğme niteliğini bağlamak için Block Bindings genellikle daha hafiftir.

Block Bindings güvenli midir?

API güvenlik mekanizmasının yerine geçmez. Meta kaydında sanitization ve yetki kontrolü; özel REST endpoint’inde nonce ve capability kontrolü; çıktı tarafında doğru escaping yine geliştiricinin sorumluluğundadır. Gizli veriyi bağlı blok üzerinden sunmamalısınız.

Sonuç

WordPress Block Bindings API, dinamik veriyi çekirdek blok tasarım araçlarıyla birleştiren hafif bir katmandır. İlk uygulamada core/post-meta ile başlayın: meta alanını doğru kaydedin, Paragraf veya Görsel niteliğine bağlayın ve ön yüzde doğrulayın. İhtiyaç büyüdüğünde register_block_bindings_source() ile site ayarı, hesaplanan değer veya harici API verisi sağlayın.

En önemli karar şudur: Tek bir blok niteliğine dinamik değer veriyorsanız binding; bütün HTML yapısını koşullu üretmeniz gerekiyorsa dinamik blok kullanın. Bu ayrım, projenin gereksiz JavaScript ve bakım yüküyle büyümesini engeller.

Block Bindings ile bir pattern veya özel kaynak geliştiriyorsanız önce küçük bir Paragraf örneğini çalıştırın, ardından Görsel ve Query Loop senaryolarına geçin. Sorun yaşadığınız blok adını, kaynak adını ve WordPress sürümünü yorumlarda paylaşabilirsiniz.

Kaynaklar

• WordPress Block Editor Handbook: Bindings
• register_block_bindings_source() fonksiyon belgesi
• Block Bindings Bölüm 1: Özel alanları bağlama
• Block Bindings Bölüm 2: Özel kaynaklarla çalışma
• Düzenleyicide bağlı değerleri okuma ve yazma
• ozgurbayram.com WordPress rehberleri
• WordPress Interactivity API rehberi