İçeriğe geç

Programlı Oluşturma

Gutenberg, istemciler için kolayca düzenlenebilir web siteleri oluştururken başlıca araç hâline geldiğinden, web sitesinin gerekli tüm bölümlerini bloklar olarak oluşturmak mantıklıdır. Bu yaklaşım çoğu ihtiyacı karşılasa da ileri düzey kullanıcılar ve özel kullanım durumları, mevcut blokları düzenleyici dışında kullanmayı gerektirebilir.

Blockstudio, blokları programlı olarak oluşturmak için iki yaklaşım sunar:

  • PHP işlevleri: PHP kodundan oluşturmak için bs_render_block ve bs_block
  • HTML etiketleri: sayfanın herhangi bir yerinde blok çıktısıyla değiştirilen <bs:block-name> etiketleri

Satır içi stiller, betikler ve kapsamlı stiller gibi Blockstudio özelliklerinin tümü desteklenir.

Adalar da bu oluşturma yollarıyla çalışır. bs_render_block(), bs_block() veya blok etiketiyle oluşturulan dinamik bir ada, yazı içeriğinden oluşturulan blokla aynı yer tutucu işaretleyiciyi döndürür ve yanıt bu işaretleyiciyi içerdiğinde ön uç çalışma zamanı eklenir.

Yapılandırılmış Bileşimler ve Tam Belgeler

Uzun süre kullanılacak araçlar, ön izlemeler, dışa aktarımlar ve bileşen galerileri için sürümlendirilmiş Blockstudio\Render API kullanın. Tek bir bildirim veya sıralı bir liste kabul eder ve çıktı yankılamadan oluşturur:

PHP
use Blockstudio\Render;

$composition = [
  'root' => 'theme/card',
  'example' => [
    'data' => [
      'heading' => 'Example card',
    ],
    'layers' => [
      [
        'name' => 'theme/button',
        'data' => [
          'label' => 'Continue',
        ],
      ],
    ],
  ],
];

$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
  'title' => 'Component preview',
  'contentElement' => 'main',
  'contentClasses' => ['component-preview'],
]);

Standart normalleştirilmiş bildirimin dört anahtarı vardır:

PHP
[
  'name' => 'theme/card',
  'attributes' => [],
  'content' => '',
  'children' => [],
]

data, inner, innerBlocks, root, layers ve example girdi kolaylıklarıdır ve normalleştirme sırasında kaldırılır. İç içe bildirimler aynı Blockstudio işlem hattından özyinelemeli olarak oluşturulur.

Render::document(); schemaVersion, html, body, blocks, assets, warnings ve errors değerlerini döndürür. assets değeri; head, footer, styles, scripts, modules, interactivity, ui ve tailwind öğelerini birbirinden ayırır. Blok listesi ve varlıklar, seçili şablonların başvurduğu bağımlılıkları içerir; ancak ilgisiz ve yalnızca düzenleyiciye ait varlıkları dışarıda bırakır.

Tam belgeler bodyClasses/bodyAttributes ayarlarını yapabilir ve oluşturulan gövdeyi isteğe bağlı olarak contentElement, contentClasses ve contentAttributes ile sarabilir. Sarmalayıcı, güvenli bir öğe adıyla sınırlandırılır; döndürülen body ise sarılmamış oluşturulan içerik olarak kalır. head ve footer seçenekleri, güvenilir belge işaretlemesini ilgili konumlarına ekler ve döndürülen varlık bağımlılık kümesine dâhil edilir.

Daha önce oluşturulmuş HTML çevresinde bir belge oluşturmak için bilinen kök blok adlarını sağlayın:

PHP
$document = Render::document_from_html(
  $rendered_html,
  ['theme/hero', 'theme/button'],
  ['title' => 'Homepage preview']
);

Serileştirilmiş WordPress blok içeriği için Render::content() kullanın. Tek bir istekte birden fazla bağımsız belgeyi işleyen tüketiciler, belgeler arasında Blockstudio\Batch_Render::reset() çağırmalıdır; Canvas::documents() bunu otomatik olarak yapar.

Sayfa Dışında Oluşturma

Blockstudio, oluşturduğu her bloğun önüne bir <!--blockstudio/namespace/slug--> yorumu ekler. Ön yüz sayfasında arabellek bu yorumları okuyarak hangi blokların bulunduğunu belirler, ilgili varlıkları yükler ve yanıt gönderilmeden önce yorumları kaldırır.

Bu arabellekten geçmeyen çıktılarda yorumlar kalır. Buna REST yanıtları, akışlar, AJAX işleyicileri ve do_blocks(), Render::content() veya bs_render_block() sonrasında başka bir yere kaydettiğiniz ya da gönderdiğiniz HTML dahildir. Bunları kaldırmak için bs_strip_render_markers() kullanın:

PHP
$html = bs_strip_render_markers(do_blocks($post->post_content));

İşlev, kayıtlı Blockstudio bloklarının yorumlarını kaldırır ve diğer HTML yorumları dahil her şeyi olduğu gibi bırakır. Sayfa arabelleğinin kaldırdığı işaretleyicilerin aynısını eşleştirir. Blok kaydından sonra (init veya daha sonra) çağırın.

Arabellekli bir ön yüz sayfasında yazdırılmaya devam eden işaretlemeyi kaldırmayın. Sayfanın hangi blok varlıklarını yükleyeceğini belirlemek için yorumlara ihtiyacı vardır ve Blockstudio bunları sonunda kendisi kaldırır.

Yorumları kaldırmak varlık eklemez. Blok CSS ve JavaScript dosyaları yalnızca sayfa arabelleği tarafından eklenir. Tüketicinin bunlara da ihtiyacı varsa bs_block_assets() veya Render::document() kullanın.

Blokları İnceleme

Dahili kayıt defterlerini okumadan çözümlenmiş alan tanımlarını almak için blok kaydından sonra (init veya daha sonra) bs_block_fields() kullanın:

PHP
$fields = bs_block_fields('theme/card');

if ($fields === null) {
  // Unknown block, or not a Blockstudio block.
}

Döndürülen değer; öznitelik filtreleri, genişletilmiş özel alanlar, geçersiz kılmalar ve iç içe gruplar, sekmeler ve yineleyiciler dahil olmak üzere kayıtlı alan tanımı dizisidir. Alanı olmayan bir Blockstudio bloğu [] döndürür. Sonuç bir kopyadır; üzerinde değişiklik yapmak kayıtlı bloğu değiştirmez.

Bunlar kaydedilmiş değerler değil, tanımlardır. Kaydedilmiş işaretlemeyi doğrulamak için ayrı bir alan gezgini tutmak yerine bs_validate_block() kullanın. Bir bloğun kabul ettiği değerleri açıklamak için bs_block_schema() kullanın. WordPress tarafından yönetilen öznitelikler ayrı kalır.

uzantılar tarafından eklenen alanlar bs_block_fields() kapsamında değildir. Bunları almak için bs_block_extension_fields() kullanın. Uzantıları blok adına göre eşleştirdiğinden çekirdek ve üçüncü taraf bloklarda da çalışır:

PHP
$fields = array_merge(
  bs_block_fields('core/paragraph') ?? [],
  bs_block_extension_fields('core/paragraph')
);

Döndürülen değer, eşleşen her uzantının alan tanımlarını uzantıların kaydedilme sırasına göre listeler ve bs_block_fields() ile aynı yapıyı kullanır. Hiçbir uzantının eşleşmediği bir blok [] döndürür. Uzantı değerleri, bloğun kendi alan değerleriyle aynı attrs.blockstudio.attributes nesnesinde kaydedilir; bu nedenle tüm kimlikler aynı ad alanını paylaşır. İki uzantı aynı kimliği tanımlarsa her iki tanım da döndürülür ve aynı değeri düzenler; oluşturma sırasında daha sonra kaydedilen uzantının tanımı geçerli olur.

Kaydedilmiş bir bloğun şablonuna ulaştığı şekliyle değerlerini okumak için bs_block_values() kullanın.

Bloğun keşfedilen CSS ve JavaScript bilgilerini incelemek için bs_block_assets() kullanın. İç içe bloklar ve paylaşılan çalışma zamanı bağımlılıkları dahil eksiksiz bir önizleme belgesi için yukarıda açıklandığı gibi Render::document() kullanın.

Kaydedilmiş değerleri doğrulama

Programlı olarak oluşturulan veya içe aktarılan blok özniteliklerini kaydetmeden önce denetlemek için blok kaydından sonra (init veya daha sonra) bs_validate_block() kullanın:

PHP
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);

if ($findings === null) {
  // No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
  // No stored-value problems were found.
} else {
  // Review the findings before saving.
}

Yalnızca blockstudio.attributes değil, eksiksiz attrs dizisini iletin. Blockstudio oluşturma işlemi, en üst düzeyde tanımlı alanları da kabul eder; her ikisi de sağlanırsa iç içe değerler önceliklidir. Çekirdek ve üçüncü taraf blokların uzantıları yalnızca blockstudio.attributes okur. Boş bir Blockstudio bloğu yönetilir ve [] döndürür; null döndürmez.

Doğrulama açıkça çağrılır ve salt okunurdur. Şablonları oluşturmaz, değerleri değiştirmez, yazıları kaydetmez, medyayı sorgulamaz veya doldurma geri çağrımlarını çalıştırmaz. Kaydetme, sayfa eşitleme veya oluşturma sırasında otomatik olarak çalışmaz. Bir temizleyici, yetkilendirme denetimi veya bir ekin var olup olmadığını denetleyen bir kontrol değildir.

Her bulgu şu kararlı anahtarları içerir:

PHP
[
  'code' => 'unknown_option',
  'path' => 'steps/1/style',
  'source' => 'block',
  'message' => 'This value is not among the field options.',
  'value' => 'c',
  'expected' => ['a', 'b'],
]

Araçlarda çevrilmiş message yerine code kullanın. source, block veya extension biçimindedir. Yollar, başında eğik çizgi olmadan depolama anahtarlarını ve sıfır tabanlı yineleyici satırı ya da seçim indekslerini kullanır. Anahtardaki ~ ve / karakterleri ~0 ve ~1 olarak kaçışlanır. Üst düzey bir grup, alt öğelerine önek ekler (cta_title); anonim gruplar ve sekmeler düzey eklemez. Başka bir grubun veya yineleyicinin içinde kimliği olan gruplar oluşturucu tarafından desteklenmez; bu nedenle anahtarları kabul edilmez. Mesaj alanlarının saklanan bir değeri yoktur. Dosya alanında <id>__size eşlikçisi bulunabilir. Bir Blockstudio bloğunun kökünde, kayıt tutma anahtarları ve işlenen öğeye iletilen genel HTML öznitelikleri bilinmeyen alan sayılmaz. Bu, yineleyici satırlarında rastgele anahtarların kullanılmasına veya çekirdek blokların genişletilmesine izin vermez.

Kod Anlamı expected
unknown_field Tutulan hiçbir alan bu depolama anahtarını bildirmiyor. Bilinen depolama anahtarları.
unknown_option Seçim, bilinen seçenekler arasında değil. İzin verilen seçenek değerleri.
wrong_type Saklanan biçim, alan tarafından desteklenmiyor. Beklenen depolama ailesi veya türü.
too_few_rows, too_many_rows Mevcut bir yineleyici, min veya max sınırlarının dışında. Satır sınırı.
definition_conflict Bir anahtar için geçerli tanımlar farklı depolama biçimleri gerektiriyor. Her tanımın kaynağı ve alan türü.
shadowed_value İç içe bir değer, farklı bir üst düzey alan değerini geçersiz kılıyor. Kazanan iç içe değer.
extension_top_level Şablon üst düzey bir değeri okuyabiliyor ancak uzantı bağlamaları okuyamıyor. blockstudio/attributes altındaki gerekli yolu.
unknown_attribute Blockstudio bloğunun üst düzey anahtarı işleme yolu tarafından okunmuyor ve siliniyor. Kayıtlı öznitelik adları, uzantı alanları ve blockstudio.
missing_container attributes, disabled, name veya editor üst düzeyde saklanmış ve blockstudio eksik. blockstudio altındaki gerekli yolu.
invalid_container blockstudio veya blockstudio.attributes bir nesne değil. object.

Bir unknown_field bulgusunun iletisi, üç düzenleme içinde bulunuyorsa aynı düzeydeki en yakın depolama anahtarını belirtir; kuralın bilinmeyen ayarlarda kullandığı yöntem budur: This storage key is not declared by the block or its extensions. Did you mean "title"? expected yine de bilinen tüm anahtarları listeler. Eşleştirme büyük/küçük harf duyarlılığını yok sayar ve yalnızca o kapsayıcıdaki depolama anahtarlarını dikkate alır. İletiler çevrilir; entegrasyonlar ileti metnini ayrıştırmak yerine code, path ve expected kullanmalıdır.

Kayıtlı bir öznitelik (alanları, WordPress’in supports, lock ve metadata için eklediği öznitelikler), eşleşen bir uzantının alanı, blockstudio, kayıt tutma anahtarı veya iletilen HTML özniteliği olmayan bir Blockstudio bloğunun üst düzey anahtarı, şablon çalışmadan önce silinir. Örneğin yanlış yazılmış bir alan kimliği veya blockstudio sarmalayıcısı olmadan saklanan bir values nesnesi gibi bir anahtar, blok bu değer olmadan işlendiği için bir bulguya yol açar. Yalnızca uzantı alanları taşıyan bloklarda üst düzey anahtarlar denetlenmez.

Kabul edilen biçimler işleme davranışını izler: çoklu seçimler ve onay kutuları bir liste, tek bir seçenek nesnesi veya sayısal sıfır dahil içe aktarılan bir skaler içerebilir. Sayı dizeleri kabul edilir. Dosyalar ek kimlikleri, kimlik nesneleri, listeler veya dize başvuruları içerebilir. Bağlantı ve simge değerleri nesne olmalıdır; özel alan türleri kayıtlı öznitelik türlerini kullanır. Bir attributes alanı, boş olmayan bir attribute adına ve skaler bir value değerine sahip çiftlerden oluşan bir liste tutar; data.media gibi isteğe bağlı meta veriler korunur.

WordPress, işleme öncesinde kayıtlı üst düzey öznitelikleri doğrular; bu nedenle blockstudio.attributes içinde kabul edilen bir biçimi reddedebilir. Örneğin, "a" radyo değeri iç içe nesnede çalışır ancak kayıtlı türünün object olduğu üst düzeyde silinir. Böyle bir değer wrong_type oluşturur. Düzenleyicinin yazdığı depolama biçimini kullanmak için iç içe nesneyi kullanın.

Eksik alanlar zorunlu değildir. Boş iç içe değerler (null, false, '', []) ve devre dışı alanlar değer hatalarına yol açmaz. Açıkça boş bırakılmış bir yineleyici yine de min sınırlarına göre denetlenir; bulunmayan veya devre dışı yineleyici denetlenmez. Üst düzeydeki boş bir değer, WordPress bu değeri silip yerine boş olmayan varsayılanı koyarsa raporlanır. İç içe nesnedeki aynı değer onu temizleyebilir. Anahtarın kayıtlı bir değeri olmasa bile tanım çakışmaları raporlanır.

Kayıt sırasında çözümlenmiş statik seçenekler ve seçenekleri doldur seçenekleri, doldurma işlevi yeniden çağrılmadan denetlenir. Uzak fetch seçenekleri ve {attributes.*} içeren seçenekleri doldur bağımsız değişkenleri atlanır. disableCustomColors veya disableCustomGradients ayarlanmadığı sürece renk ve gradyan değerleri özel olabilir. Bu denetim, default, fallback veya düzenleyici doğrulama kurallarını değil, saklanan değerleri kapsar.

Eşleşen uzantı alanları, hedefledikleri her bloğa dahil edilir. İşleme sırasında olduğu gibi, blok veya uzantıları içinde sonraki tanımlar öncekilerin yerini alır. Bloğun kendi alanı ve bir uzantı alanı aynı anahtarın ayrı tanımları olarak kalır ve ikisi de geçerlidir. Yineleyici satırlarında işleyici, her kaynakta eşleşen kimliğe sahip ilk alanı okur; seçenekleri ve sınırları geçerlidir. Çakışma tanılaması için yinelenen tanımlar korunur: uyumsuz depolama biçimleri, sonraki yinelenen tanım işleme sırasında okunmasa bile definition_conflict üretir.

İşlev tek bir bloğu denetler. Bir belgeyi doğrularken innerBlocks üzerinde gezin; eşitlenmiş kalıplar ve diğer başvurular otomatik olarak genişletilmez. wp bs blocks validate komutu, bir veya daha fazla yazıdaki bloklarda gezinir ve blok yollarını raporlar.

Özel bir işleme zamanı çözümleyicisi kullanan siteler, saklanan verileri değiştirmeden bulguları uyarlayabilir:

PHP
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
  if ($name !== 'my-theme/card') {
    return $findings;
  }

  return array_values(array_filter($findings, function($finding) {
    return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
  }));
}, 10, 3);

Her zaman bulguların listesini döndürün; [] döndürmek bloğun kabul edilmesini sağlar. Bu filtre yalnızca yönetilen bloklarda çalışır, null sonucu için çalışmaz.

Kaydedilmiş değerleri açıklama

Bir bloğun sakladığı değerleri açıklamak için, örneğin bir araçta veya bir AI entegrasyonunda blok işaretlemesi oluşturmak ya da bir REST rotasındaki girdiyi denetlemek üzere, blok kaydından sonra (init veya daha sonra) bs_block_schema() kullanın:

PHP
$schema = bs_block_schema('theme/card');

if ($schema === null) {
  // No Blockstudio fields or matching extensions apply.
}

Sonuç, attrs.blockstudio.attributes içinde kaydedilen nesnenin JSON Şemasıdır. Bloğun alanlarını ve eşleşen uzantıların alanlarını, doğrulamanın kullandığı depolama anahtarlarıyla birlikte kapsar: üst düzey bir grup, alt öğelerine önek ekler; anonim gruplar ve sekmeler düzey eklemez; dosya alanı ise <id>__size eşlikçi alanını ekler. Tekrarlayıcılar, min ve max kaynaklarından gelen minItems ve maxItems değerlerine sahip satır nesnelerinin listeleridir. additionalProperties, alan depolama kökünde ve tekrarlayıcı satırlarında false şeklindedir. Bağlantılar ve özel nesneler gibi nesne değerli alanlar kendi meta verilerini taşıyabilir. Alanı olmayan bir blokta properties bulunmadığından yalnızca boş bir nesne eşleşir.

Her alan, bs_validate_block() tarafından kabul edilen standart biçimde açıklanır:

Alan Şema
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block Bir dize.
number, range min ve max kaynaklarından gelen minimum ve maximum değerlerine sahip bir sayı.
toggle Bir boole değeri.
select, radio, checkbox Bir seçenek değeri veya checkbox ve multiple için enum içeren seçenek değerleri listesi.
color, gradient disableCustomColors veya disableCustomGradients ayarlanmışsa enum içeren bir dize.
token Dizeler listesi.
files Negatif olmayan bir tam sayı ek ID’si veya multiple ile birlikte bir ID listesi.
link url, title ve opensInNewTab içeren bir nesne; url gereklidir.
icon set, subSet ve icon içeren bir nesne; set ve icon gereklidir.
attributes Boş olmayan bir attribute ve skaler bir value içeren nesneler listesi.
repeater Satır nesneleri listesi.
Özel alan türleri Bunların kayıtlı öznitelik türü.

enum, doğrulamanın denetlediği seçenekleri listeler: kayıt sırasında çözümlenmiş statik seçenekler ve doldurma seçenekleri. Uzak fetch seçeneklerinde ve {attributes.*} içeren doldurma bağımsız değişkenlerinde enum bulunmaz. Depolama biçimleri farklı tanımlara sahip bir anahtar dışarıda bırakılır; çünkü doğrulama, o anahtar altında saklanan her değeri raporlar. Bir blok alanı ile uzantı alanı aynı anahtarı paylaştığında enum, ikisinin de kabul ettiği değerleri listeler. Paylaşılan tekrarlayıcılar alt alanlarını birleştirir ve her iki tanımdaki daha katı satır sınırlarını uygular. Tekrarlayıcı satırlarında, render sırasında olduğu gibi, her kaynakta eşleşen ID’ye sahip ilk alan geçerlidir. Açıkça tanımlanmış <id>__size adlı bir alan, otomatik eklenen dosya boyutu eşlikçi alanına öncelik verir.

Kapalı bir alanın kullanılabilir seçeneği olmadığında veya uygulanabilir iki seçenek kümesinin kesişimi boş olduğunda, tekli seçim için standart değeri null, çoklu seçim içinse boş listedir. Boş bir seçenek listesi alanı sınırsız hâle getirmez. Uzak ve özniteliklere bağlı seçenekler açık kalır.

Bir alanın label değeri title olur, help değeri description olur ve default açıklama olarak korunur. Şemanın kendi title değeri blok başlığıdır. Alanlar hiçbir zaman zorunlu değildir ve koşullu mantık şemanın parçası değildir.

Kısıtlar yalnızca rest_validate_value_from_schema() tarafından denetlenen anahtar sözcükleri kullanır; böylece şema, bir REST rotasının veya bir yeteneğin girdi şeması olarak olduğu gibi çalışır:

PHP
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
  $result = rest_validate_value_from_schema($values, $schema);
}

Şema, her alan için bir form tanımlar; doğrulama, seçenek nesneleri, sayısal dizeler ve kimlik nesneleri gibi içe aktarılan biçimleri de kabul eder. bs_validate_block() öğesinin yerini almaz: tanım çakışmaları yapılandırma sorunlarıdır ve çakışan anahtar çıkarılsa bile bulgulara yol açabilir. Doğrulama filtreleri siteye özgü kurallar da uygulayabilir. Saklanan içeriği denetlemek için bs_validate_block() kullanın. Özel bir işleme zamanı çözümleyicisi olan siteler, şemayı blockstudio/blocks/attributes/schema filtresiyle uyarlayabilir.

PHP İşlevleri

Veri Olmadan

En basit biçiminde işlev, sayfada oluşturulması gereken bloğun kimliği olan tek bir değer alır.

PHP
bs_render_block('blockstudio/cta');

Veriyle

Bloğu özel verilerle oluşturmak için ilk parametrede tek bir değer yerine bir dizi kullanılmalıdır. data anahtarındaki değer, blok şablonunuzdaki $attributes ve $a değişkenlerine aktarılır.

PHP
bs_render_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
]);

İç İçe Bloklar

Blok şablonlarınızın içindeki güçlü $content değişkeniyle birlikte bs_block işlevini kullanarak blokları birbirinin içine yerleştirebilirsiniz.

PHP
<div>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => bs_block([
    'id' => 'blockstudio/button',
    'data' => [
      'text' => 'Button Text',
    ]
  ])
]);

Düğme bloğu, blok şablonundaki $content değişkeninin yerine oluşturulur.

bs_render_block() veya bs_block() ile oluşturulan gömülü bloklar, üst blok o anda düzenleyici önizlemesi oluşturuyor olsa bile her zaman ön uçta çözümlenmiş HTML çıktısını verir. <RichText /> ve <InnerBlocks /> gibi şablon sözde bileşenleri, gömülü blok döndürülmeden önce çözümlenir.

Birden Fazla Yuva

$content değişkenini ilişkisel dizi hâline getirip bs_block işlevinde uygun anahtarlarını çağırarak birden fazla içerik yuvası oluşturabilirsiniz.

PHP
<div>
  <?php echo $content['beforeContent']; ?>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content['afterContent']; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => [
    'beforeContent' => bs_block([
      'id' => 'blockstudio/badge',
      'data' => ['text' => 'Before Content']
    ]),
    'afterContent' => bs_block([
      'id' => 'blockstudio/button',
      'data' => ['text' => 'Button Text']
    ])
  ]
]);

Blok Etiketleri

HTML etiket söz dizimini kullanarak istediğiniz bloğu gömün. İki biçim desteklenir:

HTML
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />

İki biçim de aynı bloğu oluşturur. <bs:> söz dizimi, kısa çizgiyi ad alanı ayırıcısına dönüştürür (acme-hero, acme/hero olur). Kısa çizgiler soldan sağa denenir ve kaydı yapılmış ilk aday kullanılır; bu sayede kısa çizgi içeren ad alanları da çözümlenir: <bs:acme-ui-button>, önce acme/ui-button ardından acme-ui/button değerini dener. <block> söz diziminde tam blok adı, name özniteliği olarak verilir.

Hem Blockstudio blokları hem de çekirdek WordPress blokları çalışır. Blockstudio blokları tam işlem hattından (şablonlar, Tailwind, varlıklar) geçerek oluşturulur. Çekirdek bloklar, yerleşik blok oluşturucular kullanılarak WordPress’nın blok oluşturma sistemi üzerinden oluşturulur.

Nasıl çalışır

Blok etiketleri, bulundukları yere göre farklı davranır:

Blok şablonlarında ve yazı içeriğinde, etiketler çalışma zamanında oluşturulmuş HTML ile değiştirilir. Çıktı, başvurulan bloğun son işaretlemesidir ve doğrudan sayfaya gömülür. Bu bloklar için düzenleyicide WordPress bloğu bulunmaz. Bunlar yalnızca oluşturma mekanizmasıdır.

Sayfalar, Desenler ve Site Şablonları içinde, dosya kaynağı eşitlenmeden veya WordPress ile kaydedilmeden önce etiketler yerel WordPress bloklarına dönüştürülür. Böylece bloklar düzenleyicide görünür, hedef düzenleme desteği sunuyorsa düzenlenebilir ve WordPress’nın tam blok yaşam döngüsünden geçer. Etiket söz dizimi, şablon dosyalarında blok içeriği tanımlamanın kısa yoludur.

Bu ayrım önemlidir: şablonlardaki blok etiketleri çıktı üretirken sayfalardaki, desenlerdeki ve Site Şablonlarındaki blok etiketleri yerel bloklar üretir.

Blok şablonlarında

Blok etiketleri Twig ve PHP şablonlarının içinde otomatik olarak oluşturulur. Ayar yapmanız gerekmez. Buna <bs:> ve <block> sözdizimleri ile kayıtlı tüm ön ek ve takma ad etiketleri dahildir; böylece şablon bunları bs_render_block() çağırmak yerine doğrudan üretebilir. Çıktı, bloğun şablon çıktısına doğrudan gömülü şekilde oluşturulur: HTML

Twig
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
  <block name="core/heading" level="2">Also WordPress</block>
  <theme-card title="Prefix shorthand" />
</div>

Yazı içeriğinde

Sayfa düzeyinde oluşturma (yazı içeriği, bileşen alanları) isteğe bağlıdır:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

Veya filtre aracılığıyla:

PHP
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');

Söz dizimi

Kendiliğinden kapanan etiketler:

HTML
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />

İçeriği olan eşleşen etiketler:

HTML
<bs:mytheme-section layout="wide">
  <p>Content inside the block.</p>
</bs:mytheme-section>

<block name="core/group">
  <block name="core/paragraph">Inside a group.</block>
</block>

İki biçimi de istediğiniz gibi karıştırıp kullanın. Her iki söz dizimi de iç içe kullanılabilir:

HTML
<bs:mytheme-section>
  <block name="core/heading" level="2">Title</block>
  <bs:mytheme-card title="Features" />
  <block name="core/paragraph">Description text.</block>
</bs:mytheme-section>

Önek kısaltmaları

Blok etiketlerinde projeye özel önek kısaltmaları da kullanılabilir. Bir veya daha fazla ad alanı için önek kaydedin; Blockstudio, <prefix-slug> değerini ad alanı sırasına göre ilk kaydedilmiş blok olarak çözümler:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
HTML
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />

Yukarıdaki örnekte <theme-card>, theme-components/card olarak çözümlenir; theme-components/button kayıtlı değilse <theme-button>, bsui/button olarak değerlendirilir; <theme-ui-feature-matrix> ise theme-components/ui-feature-matrix olarak çözümlenir.

Önekler birleştirilerek de kullanılabilir. Önekli bir etiket doğrudan çözümlenmez ve kalan kısa adın kendisi kayıtlı bir önek etiketi olursa çözümleme yinelenir; böylece marka öneki, ad alanı önekinin üzerine eklenebilir:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components'];
  $prefixes['ui'] = ['bsui'];

  return $prefixes;
});
HTML
<theme-ui-input />

<theme-ui-input> için bir theme-components/ui-input bloğu bulunmadığından ui önekine geçilir ve bsui/input çözümlenir. Doğrudan eşleşmeler, iç içe çözümlemeden her zaman önceliklidir; izin ve engelleme kuralları da son aşamada çözümlenen bloğa uygulanır.

Önekleri blockstudio.json içinde de yapılandırabilirsiniz:

JSON
{
  "blockTags": {
    "prefixes": {
      "theme": ["theme-components", "bsui"]
    }
  }
}

Önekler küçük harflerden veya rakamlardan oluşmalı, bir harfle başlamalı ve kısa çizgi içermemelidir. blockstudio/block_tags/tag_aliases içindeki açık diğer adlar, önek çözümlemesinden önceliklidir. Bilinmeyen önekli etiketler değiştirilmeden bırakılır.

Önek ve diğer ad etiketleri, yazarlara kolaylık sağlamaya devam eder. Proje filtrelerine bağlı olmadan gerçek blok adını kaydettiği için standart ve taşınabilir yazım her zaman <bs:namespace-slug> olur:

HTML
<bs:theme-components-card />
<bs:bsui-input />

Blockstudio örnekleri, oluşturulan tanılama çıktıları ve programatik çıktılar bu standart yazımı kullanır. Eski bir kısaltmayı kaldırmak isteyen projeler, WordPress başlatmadan bağımsız ve önce deneme çalıştırması yapan standart etiket geçişini kullanabilir.

Çekirdek bloklar

Kaydedilmiş bir oluşturucu içeren tüm bloklar kullanılabilir:

HTML
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
  <bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>

Veya <block> söz dizimiyle:

HTML
<block name="core/group">
  <block name="core/columns">
    <block name="core/column">
      <block name="core/paragraph">Left column</block>
    </block>
    <block name="core/column">
      <block name="core/paragraph">Right column</block>
    </block>
  </block>
</block>

İzin verilenler ve engellenenler listeleri

Etiketler aracılığıyla hangi blokların oluşturulabileceğini denetleyin:

JSON
{
  "blockTags": {
    "enabled": true,
    "allow": ["mytheme/*", "core/*"],
    "deny": ["mytheme/internal-*"]
  }
}

allow yalnızca eşleşen kalıplara izin verir. deny eşleşen kalıpları engeller ve önceliklidir. Her ikisi de * joker karakterlerini fnmatch() aracılığıyla destekler. Bunlar her iki söz dizimine, hem şablon hem de sayfa düzeyindeki oluşturmaya uygulanır.

Filtreler: blockstudio/block_tags/allow ve blockstudio/block_tags/deny.

HTML aktarımı

data- önekiyle başlayan öznitelikler, oluşturulan bloğun kök öğesine aktarılır. html- önekiyle başlayan öznitelikler de aktarılır ve önekleri kaldırılır. Her iki söz dizimiyle çalışır. Aktarılan bir öznitelik, kök öğenin mevcut değerini birleştirmek yerine onun yerine geçer; bu nedenle html-class bloğun kendi sınıflarının yerini alır.

Bir Blockstudio bloğu, bildiriminde yer almayan genel öznitelikleri de kök öğesine ekler: id, style, role, title, lang, dir, hidden, tabindex ve tüm aria-* öznitelikleri. Bildirilmiş bir alan her zaman önceliklidir; bu nedenle title alanı olan bir blok, bunun yerine $a['title'] içindeki değeri alır. Aktarılan stiller safecss_filter_attr() üzerinden geçer; WordPress filtresi, yazı içeriğindeki stil özniteliklerine uygulanır ve şablonda önceden ayarlanmış bir stile eklenir.

Öznitelik değerleri HTML olduğundan etiket ayrıştırılırken varlık kodları bir kez çözülür: title="Tom &amp; Jerry" şablona Tom & Jerry olarak ulaşır ve çıktı verilirken yeniden kaçışlanır. Tırnak içine alınan değerler, kendiliğinden kapanan ve eşleşen etiketlerde > içerebilir; örneğin Tailwind varyantları ve animasyon seçicileri.

Bir bloğun bildirmediği class dahil diğer öznitelikler HTML öğesine hiçbir zaman ulaşmaz. WP_DEBUG etkinse Blockstudio, her istek için bu özniteliklerin her birini bir kez _doing_it_wrong() aracılığıyla bildirir. Öznitelik için bir alan bildirin veya onu data-, aria- ya da html- özniteliği olarak yazın.

HTML
<bs:mytheme-card
  title="My Card"
  html-class="featured-card"
  html-id="main-card"
  data-analytics="card-click"
/>

<block name="core/paragraph" html-class="highlight" data-section="intro">
  Highlighted paragraph.
</block>

Özel oluşturucular

Ek blok türleri için özel blok oluşturucular kaydedin. Oluşturucular bir öznitelik dizisi ve iç içerik dizesi alır, ardından WordPress blok dizisi döndürür:

PHP
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
    $builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
        $html = '<div class="my-block">' . $inner_content . '</div>';
        return [
            'blockName'    => 'myplugin/custom-block',
            'attrs'        => $attrs,
            'innerBlocks'  => [],
            'innerHTML'    => $html,
            'innerContent' => [$html],
        ];
    };
    return $builders;
}, 10, 2);

İç içeriği alt bloklara ayrıştırması gereken kapsayıcı bloklar için aynı filtreye ikinci bir girdi ekleyin:

PHP
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
    $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
    $content = ['<div class="my-wrapper">'];
    foreach ($inner_blocks as $block) {
        $content[] = null;
    }
    $content[] = '</div>';
    return [
        'blockName'    => 'myplugin/wrapper',
        'attrs'        => $attrs,
        'innerBlocks'  => $inner_blocks,
        'innerHTML'    => '<div class="my-wrapper"></div>',
        'innerContent' => $content,
    ];
};

blockstudio/block_tags/builders hem blok etiketlerine hem de blockstudio/parser/element_mapping aracılığıyla seçilen özel bloklara uygulanır. Öğe eşlemeli bir proje bloğunda iç metni Blockstudio alanına taşımak veya özel bir blok dizisi oluşturmak gerekiyorsa uygun kanca budur.

blockstudio/block_tags/renderers ve blockstudio/parser/renderers aynı kayıt defterini ve geri çağrı biçimini alır. Geriye dönük uyumluluk ve ayrıştırıcının son aşamasındaki geçersiz kılmalar için kullanılmaya devam ederler. Filtreler şu sırayla çalışır:

  1. blockstudio/block_tags/builders
  2. blockstudio/block_tags/renderers
  3. blockstudio/parser/renderers

Daha sonraki bir filtre, önceki bir filtre tarafından kaydedilmiş oluşturucuyu değiştirebilir.

Programatik kullanım

Etiket oluşturmayı PHP içindeki istediğiniz dizeye uygulayın:

PHP
$html = apply_filters('blockstudio/block_tags/render', $content);

Bileşenler

Blok etiketleri, Bileşenlerle iyi çalışır. Bileşenler yalnızca programatik olarak oluşturulan ve düzenleyicide hiçbir zaman görünmeyen bloklardır.

HTML
<bs:mytheme-card title="My Card" description="Card content." />

Ayrıştırıcı

Blok etiketleri, DOMDocument’in yerini alan hafif bir dize tarayıcısıyla işlenir. Ayrıştırıcı hem <bs:> hem de <block> söz dizimini, derinlik takibiyle aynı adlı iç içe etiketleri, tırnak içindeki öznitelik değerlerini ve özyinelemeli kapsayıcı blokları işler. Bu özel kullanım için tasarlanmıştır, hem DOMDocument’den hem de WordPress’nın WP_HTML_Tag_Processor aracından daha hızlıdır ve DOMDocument’in ad alanı öneki kaldırma ve öznitelik adlarını küçük harfe dönüştürme gibi bilinen sorunlarını önler.

Sayfalar, Desenler ve Site Şablonları için aynı ayrıştırıcı, ham HTML öğelerini de (<p>, <div>, <h1> vb.) işler ve bunları karşılık gelen WordPress çekirdek bloklarına eşler.

Bir öğe eşlemesi <p> değerini, content richtext özniteliği bildiren, çekirdek olmayan kayıtlı bir Blockstudio bloğuna yönlendirdiğinde, iç HTML otomatik olarak bu content özniteliğine aktarılır. Buna blok düzeyinde öğe eşlemesi yapılan code ve img gibi satır içi etiketler de dahildir. Tek alt öğesi bir görsel olan paragraf, <img> değerinin eşlediği bloğa dönüşür. İç içe blok etiketleri veya blok düzeyindeki HTML ise normal iç blok ayrıştırmasına geri döner. <block name="core/shortcode"> kısa kod metnini blok içeriği olarak korur.