İçeriğe geç

ACF Blocks’dan Geçiş

WordPress (Advanced Custom Fields) ile özel ACF bloklar oluşturuyorsanız Blockstudio’e geçiş kolaydır. Kavramlar benzerdir: alanları tanımlar, bir şablon yazar ve blok düzenleyicide görünür. Farklar şunlardır: Blockstudio blok klasörlerini kendi bulur, alanları block.json içinde kendi şemasında tanımlar ve her şablona alan değerlerini tek bir $a dizisi olarak iletir.

Bu kılavuz, ACF ve Blockstudio kalıplarını yan yana karşılaştırarak geçişi adım adım ele alır.

Temel fark

ACF 6.0’dan itibaren bir ACF bloğu, oluşturma şablonunun adını belirten bir acf anahtarına sahip bir block.json öğesidir ve her blok klasörü kendi register_block_type() çağrısıyla kaydedilir. Alanlar, bloğa Blok konum kuralıyla eklenmiş bir alan grubundan (yönetim panelinde oluşturulan, Local JSON üzerinden eşitlenen veya acf_add_local_field_group() ile kaydedilen) ya da ACF PRO 6.8.1 sürümünden itibaren aynı block.json içindeki satır içi bir acf.fields dizisinden gelir. Blockstudio, kayıt çağrısının yerine dosya tabanlı otomatik keşfi koyar: block.json ve bir index.php içeren bir klasör oluşturduğunuzda blok otomatik kaydedilir.

ACF:

JSON
{
  "name": "acf/hero",
  "title": "Hero",
  "acf": {
    "renderTemplate": "template.php"
  }
}
PHP
add_action( 'init', function () {
  register_block_type( __DIR__ . '/blocks/hero' );
} );
PHP
acf_add_local_field_group([
  'key'      => 'group_hero',
  'title'    => 'Hero Fields',
  'fields'   => [
    ['key' => 'field_title', 'name' => 'title', 'type' => 'text', 'label' => 'Title'],
    ['key' => 'field_image', 'name' => 'image', 'type' => 'image', 'label' => 'Background', 'return_format' => 'array'],
  ],
  'location' => [[['param' => 'block', 'operator' => '==', 'value' => 'acf/hero']]],
]);
PHP
<?php
$title = get_field('title');
$image = get_field('image');
?>
<div class="hero" <?php if ($image) : ?>style="background-image: url(<?php echo esc_url($image['url']); ?>)"<?php endif; ?>>
  <h1><?php echo esc_html($title); ?></h1>
</div>

Blockstudio:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "title", "type": "text", "label": "Title" },
      { "id": "image", "type": "files", "label": "Background", "multiple": false }
    ]
  }
}
PHP
<div useBlockProps class="hero" <?php if ($a['image']) : ?>style="background-image: url(<?php echo esc_url($a['image']['url']); ?>)"<?php endif; ?>>
  <h1><?php echo esc_html($a['title']); ?></h1>
</div>

Kayıt çağrısı veya oluşturma geri çağrımı gerekmez: klasör yapısı kaydın kendisidir ve alanlar şablonun yanındaki block.json içinde bulunur. Şablon, get_field() çağırmak yerine $a değerini okur.

Blok kaydı

ACF

Mevcut ACF blokları, renderTemplate veya renderCallback ve blockVersion gibi seçenekleri içeren acf anahtarlı bir block.json üzerinden kaydedilir; her blok klasörü için açık bir register_block_type() çağrısıyla yüklenir. Bu işlem genellikle functions.php içindeki init dosyasında veya bir eklenti dosyasında yapılır. Eski bloklarda hâlâ acf_register_block_type() kullanılabilir; ACF bunu ACF 6.0’dan beri kullanımdan kaldırılmış olarak belgelemiştir. Çalışmaya devam ettiği için bu blokları da aynı şekilde taşıyın.

Blockstudio

Temanızın blockstudio/ dizininde (isterseniz blocks/ içinde) bir klasör oluşturun. Standart WordPress blok meta verilerine ve bir blockstudio anahtarına sahip bir block.json ekleyin. Hepsi bu.

Kod
theme/
└── blockstudio/
    └── hero/
        ├── block.json
        └── index.php

block.json, alanlar ve yapılandırma için blockstudio anahtarını kullanan standart WordPress block.json biçimini kullanır:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "category": "theme",
  "icon": "cover-image",
  "description": "Full-width hero section with background image.",
  "blockstudio": {
    "attributes": []
  }
}

Alan değerlerine erişme

Geçiş sırasında yapacağınız en yaygın değişiklik budur.

ACF Blockstudio
get_field('title') $a['title']
get_field('title', $post_id) $a['title'] (her zaman kullanılabilir)
the_field('title') <?php echo $a['title']; ?>
have_rows('items') / the_row() foreach ($a['items'] as $item)
get_sub_field('name') $item['name']

$a değişkeni, $attributes için kısa yazımdır ve geçerli bloğun tüm alan değerlerini içerir. Hem düzenleyicide hem de ön yüzde şablonda her zaman kullanılabilir.

Şablon değişkenleri

Blockstudio her şablonda çeşitli değişkenler sağlar:

Değişken Kısa yazım Açıklama
$attributes $a Tüm alan değerleri
$block $b Blok meta verileri (name, title, dir, url, postId)
$context $c Üst blok bağlamı
$content InnerBlocks içeriği
$post_id Geçerli yazı kimliği (düzenleyicide ve ön yüzde çalışır; Twig içinde post_id veya postId)

Alan türü eşlemesi

Çoğu ACF alan türünün Blockstudio içinde doğrudan karşılığı vardır. JSON sözdizimi farklıdır, ancak kavramlar kolayca eşleşir.

Metin ve içerik alanları

ACF:

PHP
['name' => 'title', 'type' => 'text', 'label' => 'Title', 'default_value' => 'Hello']
['name' => 'bio', 'type' => 'textarea', 'label' => 'Bio', 'rows' => 4]
['name' => 'content', 'type' => 'wysiwyg', 'label' => 'Content']

Blockstudio:

JSON
{ "id": "title", "type": "text", "label": "Title", "default": "Hello" }
{ "id": "bio", "type": "textarea", "label": "Bio", "rows": 4 }
{ "id": "content", "type": "wysiwyg", "label": "Content" }

Blok düzenleyicide düzenlenebilir metin (yalnızca metin girişi değil) için, <RichText /> bileşeniyle birlikte richtext türünü kullanın:

JSON
{ "id": "heading", "type": "richtext" }
PHP
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />

Görsel ve dosya alanları

ACF’in image ve file alanları, Blockstudio’in files türüne karşılık gelir:

ACF:

PHP
['name' => 'photo', 'type' => 'image', 'return_format' => 'array']
['name' => 'gallery', 'type' => 'gallery', 'return_format' => 'array']
['name' => 'document', 'type' => 'file', 'return_format' => 'array']

Blockstudio:

JSON
{ "id": "photo", "type": "files", "label": "Photo", "multiple": false }
{ "id": "gallery", "type": "files", "label": "Gallery", "multiple": true }
{ "id": "document", "type": "files", "label": "Document", "multiple": false, "allowedTypes": ["application/pdf"] }

Döndürülen nesnenin yapısı benzerdir:

PHP
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];

// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];

Kullanılabilir özellikler: ID, title, alt, caption, description, href, url, sizes. Boyutlar sizes cinsindendir; örneğin $a['photo']['sizes']['full-width'].

Seçim, radyo ve onay kutusu

ACF:

PHP
[
  'name' => 'color',
  'type' => 'select',
  'choices' => ['red' => 'Red', 'blue' => 'Blue'],
  'return_format' => 'value',
]

Blockstudio:

JSON
{
  "id": "color",
  "type": "select",
  "label": "Color",
  "options": [
    { "value": "red", "label": "Red" },
    { "value": "blue", "label": "Blue" }
  ]
}

Hem değeri hem de etiketi almak için "returnFormat": "both" kullanın:

PHP
echo $a['color']['value'];  // "red"
echo $a['color']['label'];  // "Red"

Aynı kalıp radio ve checkbox türleri için de geçerlidir.

Açma/kapatma ve doğru/yanlış

ACF:

PHP
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']

Blockstudio:

JSON
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }

ACF:

PHP
['name' => 'cta', 'type' => 'link', 'return_format' => 'array']

// Template
$link = get_field('cta');
echo $link['url'];
echo $link['title'];
echo $link['target'];

Blockstudio:

JSON
{ "id": "cta", "type": "link", "label": "CTA", "opensInNewTab": true }
PHP
echo $a['cta']['url'];
echo $a['cta']['title'];
echo $a['cta']['target'];

Renk ve gradyan

ACF:

PHP
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']

Blockstudio:

JSON
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }

color türü, WordPress renk paletiyle bütünleşir. gradient türü gradyan seçici sunar.

Sayı, aralık ve tarih

ACF:

PHP
['name' => 'count', 'type' => 'number', 'min' => 1, 'max' => 10]
['name' => 'opacity', 'type' => 'range', 'min' => 0, 'max' => 100, 'step' => 5]
['name' => 'eventDate', 'type' => 'date_picker']

Blockstudio:

JSON
{ "id": "count", "type": "number", "label": "Count", "min": 1, "max": 10 }
{ "id": "opacity", "type": "range", "label": "Opacity", "min": 0, "max": 100, "step": 5 }
{ "id": "eventDate", "type": "date", "label": "Event Date" }

Yineleyiciler

ACF’in yineleyici alanı, Blockstudio’in repeater türüyle doğrudan eşleşir. ACF şablonları genellikle have_rows() / the_row() / get_sub_field() ile döngü kurar (yineleyicide get_field() de satırlardan oluşan bir dizi döndürür); Blockstudio ise yalnızca $a biçiminde, zaten düz olan PHP dizisine sahiptir.

ACF:

PHP
['name' => 'features', 'type' => 'repeater', 'sub_fields' => [
  ['name' => 'title', 'type' => 'text'],
  ['name' => 'description', 'type' => 'textarea'],
]]

// Template
if (have_rows('features')) :
  while (have_rows('features')) : the_row();
    echo get_sub_field('title');
    echo get_sub_field('description');
  endwhile;
endif;

Blockstudio:

JSON
{
  "id": "features",
  "type": "repeater",
  "label": "Features",
  "min": 1,
  "max": 10,
  "attributes": [
    { "id": "title", "type": "text", "label": "Title" },
    { "id": "description", "type": "textarea", "label": "Description" }
  ]
}
PHP
<?php foreach ($a['features'] as $feature) : ?>
  <h3><?php echo esc_html($feature['title']); ?></h3>
  <p><?php echo esc_html($feature['description']); ?></p>
<?php endforeach; ?>

Blockstudio yineleyicileri 3 düzeye kadar iç içe yerleştirmeyi destekler.

Gruplar

ACF’in grup alanı, Blockstudio’in group türüyle eşleşir. Grupların içindeki alan kimliklerinin başına grup kimliği eklenir.

ACF:

PHP
['name' => 'author', 'type' => 'group', 'sub_fields' => [
  ['name' => 'name', 'type' => 'text'],
  ['name' => 'role', 'type' => 'text'],
]]

// Template
$author = get_field('author');
echo $author['name'];
echo $author['role'];

Blockstudio:

JSON
{
  "id": "author",
  "type": "group",
  "title": "Author",
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" }
  ]
}
PHP
<?php $author = bs_get_group($a, 'author'); ?>
<p><?php echo esc_html($author['name']); ?></p>
<p><?php echo esc_html($author['role']); ?></p>

bs_get_group() yardımcı işlevi, alan kimliklerinden grup önekini kaldırarak alanlara kolayca erişmenizi sağlar. Bu olmadan alanlara $a['author_name'] ve $a['author_role'] olarak erişirsiniz.

Koşullu mantık

Hem ACF hem de Blockstudio, diğer alanların değerlerine göre alanları gösterip gizlemek için koşullu mantığı destekler.

ACF:

PHP
['name' => 'showSubtitle', 'type' => 'true_false'],
[
  'name' => 'subtitle',
  'type' => 'text',
  'conditional_logic' => [[['field' => 'field_showSubtitle', 'operator' => '==', 'value' => '1']]]
]

Blockstudio:

JSON
{ "id": "showSubtitle", "type": "toggle", "label": "Show Subtitle" },
{
  "id": "subtitle",
  "type": "text",
  "label": "Subtitle",
  "conditions": [[{ "id": "showSubtitle", "operator": "==", "value": true }]]
}

Blockstudio koşulları alan anahtarlarına değil, doğrudan alan kimliklerine başvurur. Kullanılabilir işleçler: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.

Blockstudio ayrıca yazı türü, yazı kimliği, kullanıcı rolü ve kullanıcı kimliğine dayalı genel koşulları destekler:

JSON
{
  "conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}

InnerBlocks

Hem ACF hem de Blockstudio, özel bloğunuzun içine başka bloklar yerleştirmek için InnerBlocks’u aynı <InnerBlocks /> etiketi ve aynı allowedBlocks, template ve templateLock nitelikleriyle destekler; bu nedenle şablonun bu bölümü genellikle değişmeden taşınır.

Blockstudio:

PHP
<div useBlockProps class="my-wrapper">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr(wp_json_encode(["core/heading", "core/paragraph", "core/image"])); ?>'
    template='<?php echo esc_attr(wp_json_encode([
      ["core/heading", ["placeholder" => "Section title"]],
      ["core/paragraph", ["placeholder" => "Section content"]]
    ])); ?>'
    templateLock="insert"
  />
</div>

<InnerBlocks /> etiketi, düzenleyicide React bileşeniyle, ön yüzde ise görüntülenen blok içeriğiyle değiştirilir.

Yazı meta verilerinin depolanması

Hem ACF Blocks hem de Blockstudio, alan değerlerini varsayılan olarak yazı meta verilerinde değil, yazı içeriğinde blok öznitelikleri olarak saklar. Bu nedenle meta veri depolamayı etkinleştirmediğiniz sürece alan değerleri WP_Query ile sorgulanamaz.

ACF, ACF PRO 6.3 sürümünde bloklar için usePostMeta: true aracılığıyla, sayfa başına bir üst düzey blok için isteğe bağlı yazı meta verisi depolama özelliğini ekledi. Blockstudio, storage özelliğini kullanarak alan başına isteğe bağlı bir mekanizma sunar:

JSON
{
  "id": "featured",
  "type": "toggle",
  "label": "Featured",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "is_featured"
  }
}

Meta anahtarı show_in_rest ile otomatik olarak kaydedilir. get_post_meta($post_id, 'is_featured', true) ile her yerden erişin.

Site genelindeki değerler (ACF seçenek sayfaları gibi) için seçenek depolamayı kullanın:

JSON
{
  "storage": {
    "type": "option",
    "optionKey": "site_company_name"
  }
}

Mevcut blokları genişletme

ACF’ün Blok konum kuralı, alan gruplarını yalnızca ACF bloklarına bağlar; çekirdek veya üçüncü taraf bloklara alan eklemez. Başlık, Paragraf, Görsel ve Düğme gibi çekirdek bloklara ulaşmak için ACF’ün sunduğu yol, mevcut blok özniteliklerini ACF alan değerlerine bağlayan WordPress Blok Bağlamaları API özelliğidir. Blockstudio, uzantı dosyaları aracılığıyla kayıtlı herhangi bir bloğa yeni alanlar ve kontroller ekleyebilir.

blockstudio dizininizde bir uzantı dosyası oluşturun:

JSON
{
  "name": "core/heading",
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "accentColor",
        "type": "color",
        "label": "Accent Color",
        "set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
      }
    ]
  }
}

set özelliği, alan değerini bloğun HTML özelliğine otomatik olarak uygular. Birden fazla bloğu aynı anda genişletmek için joker karakterleri kullanın: "name": "core/*".

Geçiş kontrol listesi

  1. theme/blockstudio/{block-name}/ içinde block.json ve index.php ile blok klasörünü oluşturun.
  2. Alan tanımlarını taşıyın: bloğun alan grubundaki (Local JSON, acf_add_local_field_group() veya satır içi acf.fields dizisindeki) alan tanımlarını, block.json içindeki blockstudio.attributes dizisine taşıyın. name değerini id olarak değiştirin, key öğesini kaldırın ve tür adlarını gerektiği gibi düzenleyin.
  3. Şablon erişimini güncelleyin: get_field('name') yerine $a['name'] kullanın. have_rows() döngülerini foreach ($a['repeater'] as $item) ile değiştirin.
  4. get_sub_field() yerine doğrudan dizi erişimi kullanın: $item['fieldId'].
  5. Düzenleyiciyle doğru entegrasyon için şablonunuzdaki en dış öğeye useBlockProps ekleyin.
  6. Koşullu mantığı ACF’ün conditional_logic özelliğinden Blockstudio’ün conditions özelliğine taşıyın ve alan anahtarları yerine alan kimliklerine başvurun.
  7. Daha önce get_post_meta() aracılığıyla sorgulanan veya WP_Query içinde kullanılan alanlar için depolama ekleyin.
  8. ACF kayıt kodunu kaldırın: taşınan blokların register_block_type() çağrılarını ve acf anahtarlarını (veya acf_register_block_type() çağrılarını) ve alan gruplarını kaldırın. Bunlar Local JSON içinde, acf_add_local_field_group() olarak, satır içi acf.fields dizisinde ya da yönetim panelinde bulunabilir.
  9. Alanların doğru göründüğünü doğrulamak için düzenleyicide test edin, ardından ön yüz çıktısını kontrol edin.