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:
{
"name": "acf/hero",
"title": "Hero",
"acf": {
"renderTemplate": "template.php"
}
}
add_action( 'init', function () {
register_block_type( __DIR__ . '/blocks/hero' );
} );
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
$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:
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "image", "type": "files", "label": "Background", "multiple": false }
]
}
}
<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.
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:
{
"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:
['name' => 'title', 'type' => 'text', 'label' => 'Title', 'default_value' => 'Hello']
['name' => 'bio', 'type' => 'textarea', 'label' => 'Bio', 'rows' => 4]
['name' => 'content', 'type' => 'wysiwyg', 'label' => 'Content']
Blockstudio:
{ "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:
{ "id": "heading", "type": "richtext" }
<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:
['name' => 'photo', 'type' => 'image', 'return_format' => 'array']
['name' => 'gallery', 'type' => 'gallery', 'return_format' => 'array']
['name' => 'document', 'type' => 'file', 'return_format' => 'array']
Blockstudio:
{ "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:
// 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:
[
'name' => 'color',
'type' => 'select',
'choices' => ['red' => 'Red', 'blue' => 'Blue'],
'return_format' => 'value',
]
Blockstudio:
{
"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:
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:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
Bağlantı alanı
ACF:
['name' => 'cta', 'type' => 'link', 'return_format' => 'array']
// Template
$link = get_field('cta');
echo $link['url'];
echo $link['title'];
echo $link['target'];
Blockstudio:
{ "id": "cta", "type": "link", "label": "CTA", "opensInNewTab": true }
echo $a['cta']['url'];
echo $a['cta']['title'];
echo $a['cta']['target'];
Renk ve gradyan
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "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:
['name' => 'count', 'type' => 'number', 'min' => 1, 'max' => 10]
['name' => 'opacity', 'type' => 'range', 'min' => 0, 'max' => 100, 'step' => 5]
['name' => 'eventDate', 'type' => 'date_picker']
Blockstudio:
{ "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:
['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:
{
"id": "features",
"type": "repeater",
"label": "Features",
"min": 1,
"max": 10,
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "description", "type": "textarea", "label": "Description" }
]
}
<?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:
['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:
{
"id": "author",
"type": "group",
"title": "Author",
"attributes": [
{ "id": "name", "type": "text", "label": "Name" },
{ "id": "role", "type": "text", "label": "Role" }
]
}
<?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:
['name' => 'showSubtitle', 'type' => 'true_false'],
[
'name' => 'subtitle',
'type' => 'text',
'conditional_logic' => [[['field' => 'field_showSubtitle', 'operator' => '==', 'value' => '1']]]
]
Blockstudio:
{ "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:
{
"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:
<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:
{
"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:
{
"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:
{
"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
theme/blockstudio/{block-name}/içindeblock.jsonveindex.phpile blok klasörünü oluşturun.- Alan tanımlarını taşıyın: bloğun alan grubundaki (Local JSON,
acf_add_local_field_group()veya satır içiacf.fieldsdizisindeki) alan tanımlarını,block.jsoniçindekiblockstudio.attributesdizisine taşıyın.namedeğeriniidolarak değiştirin,keyöğesini kaldırın ve tür adlarını gerektiği gibi düzenleyin. - Şablon erişimini güncelleyin:
get_field('name')yerine$a['name']kullanın.have_rows()döngüleriniforeach ($a['repeater'] as $item)ile değiştirin. get_sub_field()yerine doğrudan dizi erişimi kullanın:$item['fieldId'].- Düzenleyiciyle doğru entegrasyon için şablonunuzdaki en dış öğeye
useBlockPropsekleyin. - Koşullu mantığı ACF’ün
conditional_logicözelliğinden Blockstudio’ünconditionsözelliğine taşıyın ve alan anahtarları yerine alan kimliklerine başvurun. - Daha önce
get_post_meta()aracılığıyla sorgulanan veyaWP_Queryiçinde kullanılan alanlar için depolama ekleyin. - ACF kayıt kodunu kaldırın: taşınan blokların
register_block_type()çağrılarını veacfanahtarlarını (veyaacf_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çiacf.fieldsdizisinde ya da yönetim panelinde bulunabilir. - 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.