Blok Türü Sözleşmeleri

Bu belge, WebBlocks CMS'te hâlihazırda dağıtılan yayındaki çekirdek blok türlerinin Faz 1 envanteri olarak başladı; artık Faz 2 salt okunur yönetim sözleşmesi görünümünü de belgeliyor ve bugüne kadar tamamlanan Faz 3 boşluk standartlaştırma düzeltmelerini kaydediyor. Bunlara section, container, grid, cluster, card ve content_header için Yerleşim + Kart temizliği; hero, columns, column_item, cta, feature-grid ve feature-item için Pazarlama / Yapılandırılmış İçerik temizliği; ve eski uyumluluk slug'larını yayındaki çekirdek kataloğa terfi ettirmeden dürüstçe belgelenmiş tutan Eski / Geçiş temizliği dahildir.

Faz 1 yalnızca salt okunur dokümantasyondur.

• Blok formlarını yeniden tasarlamaz.
• Veritabanı güdümlü bir form oluşturucu eklemez.
• Blok içeriğini taşımaz.
• Herkese açık render sürecini değiştirmez.
• Admin -> System -> Block Types düzenlemelerinin bugün nasıl çalıştığını değiştirmez.

Mevcut Blok Türleri yönetim ekranı bir katalog ve meta veri ekranı olmaya devam ediyor. Faz 2'de artık listelenen her satır için salt okunur bir Sözleşme kipi (modal) açabiliyor, ancak yine de dinamik bir form oluşturucu veya şema editörü değildir.

Eklenti Faz 3, PluginBlockTypeDefinition, PluginBlockPackDefinition ve PluginBlockRegistry aracılığıyla yalnızca bildirime dayalı eklenti blok kancaları ekler. Etkin eklentiler, keşif için analytics-tools::score-card gibi eklentiye ait tanıtıcıları sunabilir; ancak bu bildirimler dağıtılan çekirdek blok sözleşmelerinin, çekirdek blok görünümlerinin, çekirdek seeder'ların veya blok düzenleme hizmetlerinin yerini almaz. hero gibi nitelenmemiş çekirdek tarzı tanıtıcılar çekirdeğe ait kalır ve eklenti bildirimleri için reddedilir.

Bir Blok Türü Sözleşmesi, bir blok türünün CMS katmanları arasında nasıl davrandığına ilişkin güncel teknik anlaşmadır:

• katalog kimliği: slug, etiket, kategori, durum ve sistem ya da kapsayıcı meta verileri
• yönetim formu kaynağı: bloku şu anda hangi Blade parçasının düzenlediği ve hangi alanları sunduğu
• doğrulama ve istek işleme: App\Http\Requests\Admin\BlockRequest sınıfının blok yüklerini şu anda nasıl normalleştirip doğruladığı
• depolama sahipliği: hangi değerlerin blocks tablosunda, özel çeviri satırlarında, block_media tablosunda veya ilişkili kayıtlarda yaşadığı
• çeviri sahipliği: kullanıcıya görünen hangi alanların dile (locale) ait olduğu
• ortak sahiplik: hangi ayarların veya ilişkilerin diller arasında ortak kaldığı
• medya veya ilişki sahipliği: doğrudan media_id, sıralı block_media, gezinme aramaları veya aynı sayfa ilişkileri
• alt öğe desteği: blokun bir kapsayıcı olup olmadığı ve alt türlerin kısıtlanıp kısıtlanmadığı
• herkese açık renderer kaynağı: bloku bugün hangi herkese açık Blade parçasının render ettiği
• renderer kök sözleşmesi: blokun herkese açık kök işaretlemesine sahip olup olmadığı veya genel sarmalayıcı yoluna mı dayandığı
• taşınabilirlik ve revizyonlar: mevcut depolama biçiminin revizyonlar, klonlama, dışa/içe aktarma ve terfi süreçlerinde dolaşmaya devam edip etmeyeceği
• testler ve boşluklar: bilinen odaklı kapsam, belirsiz davranış veya uyumluluk borcu

Aşağıda kullanılan durum terimleri:

• clear: yönetim formu, istek işleme, depolama ve renderer çoğunlukla örtüşüyor
• mostly clear: güncel sözleşme anlaşılabilir ama kayda değer bir çekincesi var
• transitional: güncel sözleşme bilinçli olarak bir uyumluluk yolu veya karma sahiplik deseni taşıyor
• needs review: güncel kod yolları uyuşmuyor veya davranış, Faz 2'nin daha net göstermesini gerektirecek kadar az belgelenmiş
• legacy/fallback: yayındaki davranış bir yedek (fallback) veya uyumluluk yoluna dayanıyor

Güncel ve gelecekteki sözleşme çalışmaları bu sahiplik kurallarını açık tutmalıdır:

• blok dile (locale) aitse kullanıcıya görünen metinler çeviri satırlarına aittir
• ortak operasyonel veya ayar verileri ortak blok ayarlarına veya açık ilişkilere aittir
• medya, uygun olduğunda media_id veya block_media sahiplik yollarını kullanmalıdır
• kullanıcıya görünen içeriği rastgele ayar JSON'ına taşımaktan kaçının
• uyumluluk depolama yolları herkese açık çıktıyı veya içe aktarmaları hâlâ etkiliyorsa belgelenmiş tutun

Bu Faz 1 envanteri tahminlere değil, dağıtılan kaynak koduna dayanır.

• katalog kaynağı: app/Support/Blocks/CoreBlockTypeCatalogSyncer.php
• blok düzenleme isteği normalleştirmesi: app/Http/Requests/Admin/BlockRequest.php
• kalıcılık yardımcıları: app/Support/Blocks/BlockPayloadWriter.php, app/Support/Blocks/BlockTranslationWriter.php, app/Support/Blocks/BlockTranslationResolver.php
• çeviri kayıt defteri: app/Support/Blocks/BlockTranslationRegistry.php
• yönetim formları: resources/views/admin/blocks/types/*.blade.php
• herkese açık renderer'lar: resources/views/pages/partials/blocks/*.blade.php
• kapsam referansları: tests/Feature/ altındaki blok kataloğu, render, çeviri ve slug'a özgü testler

Şu anda burada belgelenen yayındaki çekirdek blok türleri: 42.

Faz 1, güvenli bir geliştirici denetim komutu ekler:

Komut salt okunurdur.

• veritabanını değiştirmez
• kurulu site içeriğine bağımlı değildir
• dağıtılan çekirdek katalog tanımlarını okur
• dağıtılan yönetim formu ve herkese açık renderer dosyalarının varlığını doğrular
• çeviri ailesi meta verilerini ve temel kapsayıcı desteğini raporlar

Komut, katalog ve dosya varlığı sapmaları için bir güncellik yardımcısıdır. Bu belgedeki daha kapsamlı sözleşme notlarının yerini tutmaz.

Faz 2, sözleşme ayrıntılarını Admin -> System -> Block Types içinde salt okunur olarak sunar.

• her satır bir Block Type Contract kipi (modal) açabilir
• kip yalnızca bilgilendirme amaçlıdır ve güncelleme göndermez
• dağıtılan koddan katalog, yönetim formu, depolama, çeviri, medya veya ilişki, alt öğe, renderer ve boşluk ayrıntılarını gösterir
• Blok Türleri yönetimini bir şema editörüne veya form oluşturucuya dönüştürmez
• özel veya taslak blok türleri kipi yine açabilir, ancak tanımlı bir çekirdek sözleşme yoksa No shipped contract is documented for this block type yet. mesajını gösterebilir

Yayında olan blok tipleri bugün her biri için ayrılmış kendi istek (request) sınıfına sahip değildir.

• App\Http\Requests\Admin\BlockRequest ortak düzenleme isteği yoludur
• bu istek içindeki slug'a özgü dallar, alanları mevcut kanonik depolamaya normalleştirir
• App\Support\Blocks\BlockPayloadWriter normalleştirilmiş blok yükünü kalıcı hale getirir
• App\Support\Blocks\BlockTranslationWriter dile (locale) ait alanları kayıtlı aileler için çeviri satırlarına taşır
• App\Support\Blocks\BlockTranslationResolver çevrilmiş veya geri dönüş değerlerini render edilebilir bir blok örneğine geri çözümler

Bu ortak istek yolu, 1. Fazın herhangi bir şema güdümlü düzenleme çalışmasından önce ilk olarak sözleşmeleri belgelemesinin nedenlerinden biridir.

Mevcut 3. Faz düzeltmelerinden sonra kalan yüksek önemdeki eksikler:

• gallery, kanonik sıralı block_media satırları eksik olduğunda hâlâ ayarlara dayalı eski bir geri dönüş öğe yolunu koruyor
• table renderer'ı, çekirdek yönetim formu çevrilmiş satır metnini yazsa da hâlâ eski bir settings.rows geri dönüş yolunu destekliyor
• hero, kanonik çevrilmiş giriş alanları boş olduğunda hâlâ eski alan geri dönüşlerini koruyor
• feature-grid ve feature-item kaynak destekli oldukları için artık yayında, ancak ortak Columns veya Column Item sunum yolları üzerinde bilinçli olarak geçici temsilci (delegate) sözleşmeleri olarak kalıyorlar
• tabs, slider, menu ve faq-list, uyumluluk formları veya renderer'larıyla hâlâ eski taslak katalog satırları olarak duruyor; ancak yayında olan çekirdek sözleşmeler değiller ve sözleşme kipinde (modal) ve denetim çıktısında güvenli biçimde başarısız olmaya devam etmeliler
• showcase-list ve contact-info hâlâ yalnızca genel render uyumluluk yolları olarak var; yayınlanmış çekirdek katalog blokları değiller; ayar güdümlü bağlantıları artık diğer blok renderer'larıyla aynı güvenli genel URL kurallarını izliyor
• yayında ve taslak kataloglar bir arada bulunuyor; bu nedenle gelecekteki yönetim arayüzü, yayında olan çekirdek sözleşmeler ile taslak veya kuruluma özgü satırlar arasındaki ayrımı açıkça korumalı

Blok grupları için önerilen sonraki standartlaştırma çalışması:

• yerleşim, içerik, gezinme, desen ve gelişmiş gibi kararlı, ürün sahipliğindeki blok gruplarını tek bir doğruluk kaynağında tanımlayın
• seçici gruplandırmalarını, dokümantasyon gruplandırmalarını ve Block Types yönetim gruplandırmalarını aynı kaynağa hizalayın
• şu anda taslak veya geçiş aşamasında olan blokların hangilerinin desteklenen, arşivlenen veya açıkça eski (legacy) olacağına karar verin
• herhangi bir şema güdümlü form çalışması başlamadan önce hangi sözleşmelerin çeviri destekli, hangilerinin bilinçli olarak yalnızca ortak olduğunu standartlaştırın

1. Faz, blok düzenleme davranışını, blok depolamayı veya genel render işlemini değiştirmeden mevcut yayında sözleşme envanterini oluşturur.

1. Faz sürümü için amaçlanan durma noktası buydu.

2. Faz, blok düzenleme davranışını, depolamayı, renderer'ları ve seçici davranışını değiştirmeden, belgelenen sözleşmeyi Block Types yönetiminde salt okunur bilgi olarak görünür kılar.

3. Faz, bir şema editörü, dinamik form oluşturucu veya veritabanı güdümlü blok form sistemi eklemeden, belgelenmiş düşük riskli sözleşme eksiklerini çözmeye başlar.

• code artık başlık, etiket ve kod parçası gövdesi için mevcut metin çevirisi yolunu izliyor; sözdizimi dili ortak kalıyor
• table artık başlık ve satır metni için mevcut metin çevirisi yolunu izliyor; tablo stili ortak kalıyor
• breadcrumb artık kaydetme sırasında sunulan ortak ayarları koruyor
• stat-card artık genel renderer'da mevcut isteğe bağlı URL'yi basit ve güvenli bir bağlantıyla kullanıyor
• link-list artık mevcut çevrilmiş giriş metnini alt öğe listesinin üzerinde gösteriyor
• sticky-navbar artık kalıcı Navbar kök sahipliğini Block::ownsPublicRoot() ile hizalıyor; böylece genel kabuk fazladan genel bir sarmalayıcı eklemiyor
• image artık altyazı ve alternatif metin için mevcut görsel çevirisi yolunu izliyor; seçilen medya ve isteğe bağlı bağlantı URL'si ortak kalıyor
• gallery artık öğe başına alternatif metin, altyazı, kaplama başlığı ve kaplama metni için dile (locale) ait block_gallery_item_translations kullanıyor; sıralı galeri medyası ve sunum ayarları ortak kalıyor, eski içerik için eski geri dönüş öğeleri korunuyor ve eski galeri başlığı/açıklaması normal düzenlemenin ve genel çıktının dışında tutuluyor
• download artık görünür etiket ve yardım metni için mevcut metin çevirisi yolunu izliyor; seçilen medya ve düğme varyantı ortak kalıyor
• file, video ve audio artık birinci sınıf yönetim formlarına ve istek normalleştirmesine sahip; böylece çevrilmiş görünür metin ile ortak medya veya URL kaynakları, zaten genel tarafta render ettikleri aynı sözleşme üzerinden gidip geliyor
• image, gallery, download, file, video ve audio artık yeni rastgele alt öğe yerleşimini kabul etmiyor ve rastgele geçmiş alt ağaçları genel tarafta render etmiyor; mevcut alt satırlar yönetim blok ağaçlarında korunmaya devam ediyor
• code, table, quote, toc ve html artık yeni normal alt öğe yerleşimini kabul etmiyor ve rastgele geçmiş alt ağaçları genel tarafta render etmiyor; mevcut alt satırlar yönetim blok ağaçlarında korunmaya devam ediyor
• navbar-brand ve sidebar-brand artık temkinli bir kayıtlı URL veya site ana sayfası geri dönüş sözleşmesini paylaşıyor ve her ikisi de görünür metin zorlamadan yalnızca-logo çıktısı için güvenli erişilebilir adlandırmayı koruyor
• sidebar-nav-group artık iç içe alt bağlantılar için sidebar-nav-item ile aynı manuel kenar çubuğu öğesi çıktı semantiğini yeniden kullanıyor; mevcut WebBlocks UI nav-group sarmalayıcı sözleşmesi korunuyor
• section, container, grid, cluster, card ve content_header artık kayıt (registry), salt okunur yönetim sözleşme kipi, denetim çıktısı, dokümantasyon ve odaklı regresyon kapsamı genelinde aynı yayınlanan sözleşme kaynağını kullanıyor
• hero, columns, column_item, cta, feature-grid ve feature-item artık yayınlanan çekirdek katalogda yayında, ortak sözleşme kaydında belgelenmiş durumda ve yalnızca taslak veya yetersiz belgelenmiş kalmak yerine kaynak destekli pazarlama veya yapılandırılmış içerik sözleşmeleri olarak kapsanıyor
• yönetilen CTA düğmeleri ve yapılandırılmış alt öğeler için yalnızca-dil düzenlemeleri artık çevrilmiş etiketleri veya metni güncellerken ortak URL'leri koruyor
• yerleşim temel öğeleri, ortak yerleşim ayarlarını ve alt yapıyı çeviri satırları veya rastgele metin alanları yerine kanonik blok depolamada tutuyor
• card artık bileşebilir bir kabuk sözleşmesi kullanıyor: üst Card wb-card köküne sahip, Card bölgeleri wb-card-header, wb-card-body ve wb-card-footer'a sahip, bölge blokları yalnızca Card altında geçerli ve eski kaydedilmiş Card metni yalnızca minimal, bölgesiz bir geri dönüş renderer yolu üzerinden korunuyor
• content_header çevrilmiş başlık, giriş ve meta metnini koruyor, başlığını her zaman H1 olarak render ediyor, eski kaydedilmiş başlık düzeyi değerlerini güvenle yok sayıyor ve semantik <header class="wb-content-header"> kökünü genel bir sarmalayıcı olmadan renderer sahipliğinde tutuyor
• testimonial ve stats, bağımsız yayınlanmış çekirdek sözleşmeler olarak değil, mevcut Quote veya Columns render yollarına devreden yalnızca-takma-ad davranışı olarak dürüstçe belgelenmeye devam ediyor
• tabs, slider, menu ve faq-list, yayınlanmış çekirdek sözleşmeler değil, taslak veya takma ad dönemi uyumluluk slug'ları olarak kalıyor; showcase-list ve contact-info ise yayınlanan çekirdek sözleşme girdisi olmayan, yalnızca genel tarafta çalışan uyumluluk renderer'ları olarak kalıyor