Dinamik İçerik: Kaynaklar, Döngüler ve Alan Eşlemeleri

Dinamik İçerik, etkin bir sağlayıcının kayıtlarını standart CMS bloklarına bağlar. Verilerin ve çevirilerinin sahibi sağlayıcıdır; sayfa düzenini, tekrarlanan şablonu ve alan eşlemelerini siz yönetirsiniz. Bu rehber, kaynak standardı 1.0 ile CMS 1.104.0 panelindeki akışı açıklar. Örnek olarak yayımlanan eklenti kataloğu kullanılır.

Bu bağlantıları API isteği yazmadan veya blok kimliği girmeden panelde kurabilirsiniz. API erişimi ve kimlik bilgileri kurulu sağlayıcı entegrasyonuna aittir; bu çalışma alanında entegrasyonun önceden tanımladığı kaynaklar seçilir.

Dinamik İçerik → Kaynaklar bölümünü açın. Kaynak ayrıntıları; sağlayıcıyı, bildirilen veri kökenini, koleksiyon veya tek kayıt türünü, desteklenen dilleri, sabit kayıt anahtarını ve kullanılabilir alanları gösterir. Dil bildirimi bir sözleşmeyi tanımlar; başarılı bir canlı bağlantı testi değildir.

Döngüler, Alan bağlantıları ve Sorunlar görünümleri kaynakların nerede kullanıldığını gösterir. Siteye, yayın durumuna veya aramaya göre filtreleyin. Sayılar, üretilen kartları değil kayıtlı blokları ve bağlantıları belirtir. Envanteri açmak uzak içerik istemeden yapılandırmayı okur. Paylaşılan Slot kullanımları mevcut düzenleyiciye bağlanır; aşağıdaki yönlendirmeli hedef akışı sayfaya ait slotları kullanır.

Örnek entegrasyon üç ayrı kaynak sunar:

• Published plugin catalog (webblocks-extensions-live::plugins): tekrarlanan kartlar için koleksiyon.
• Published plugin (webblocks-extensions-live::plugin): sabit kayıt gibi kullanılabilen, seçilmiş tek eklenti.
• Catalog interface (webblocks-extensions-live::ui): ortak çevrilmiş arayüz metinlerini sağlayan labels kaydı.

Panel çevrilmiş olsa da bu sağlayıcı etiketleri İngilizce kalabilir. Kaynak kayıtlarının içeriği istenen dili kullanır.

Kaynak ayrıntılarında Sayfada kullan seçeneğini seçin. Siteyi ve sayfayı seçip Hedefi aç düğmesine basın. Katalog koleksiyonu için döngüyü içeren blok olarak Grid seçin. Bu hedefi açıp doğrudan alt bloğu olan Card bloğunu tekrarlanacak şablon olarak seçin.

Yayındaki sayfada bağlantıları hemen inceleyebilir ve önizleyebilirsiniz. Değişiklikleri kaydetmeden önce Güncelleme taslağı hazırla seçeneğini kullanıp hedefi bu taslakta seçin. Kopyalanan blokların kendilerine ait kimlikleri vardır; görünür seçicileri kullanıp oluşan eşlemeleri inceleyin. Yayımlanan sayfa değişmez.

Taslakta uygun şablon yoksa Başlangıç Grid ve Card oluştur, sayfaya ait slota henüz bağlanmamış bir şablon ekler. Mevcut blokları korur ve sizin yerinize alan eşlemesi seçmez. Sağlayıcı kurulumu, kaynak erişimi ve API kimlik bilgileri bu ekranda değil sağlayıcı entegrasyonunda ayarlanır. Kurulum için Eklenti Sistemi sayfasına bakın.

Döngü Grid bloğuna aittir; Card, eşleşen her kayıt için bir kez tekrarlanan şablondur. Card içindeki Image, Header, Plain Text ve Button Link blokları geçerli kaydı alır. Card ile aynı seviyedeki sabit Header editoryal kalır ve bu döngünün geçerli kaydını kullanamaz.

Blok ağacı döngü sahibini, tekrarlanan şablonu ve bağlı alanları işaretler. Daraltılmış üst bloklar, altında dinamik içerik bulunduğunu gösterir. İlgili döngüye veya eşlemeye gitmek için göstergeyi izleyin. Böylece kayıtlı tek Card, düzenlenebilir on ayrı Card kopyası olmadan on public kart üretebilir.

Başka sayfadaki bloğu veya torun bloğu değil, uyumlu bir doğrudan alt bloğu seçin. Çekirdek Section, Container, Stack, Cluster, Grid ve Slide diğer kurallara uygun alt şablonları kabul eder; Slider için Slide, Columns için Column Item, Feature Grid için Feature Item veya Column Item, Link List için Link List Item gerekir. Card ve Split bu koleksiyon kapsayıcısı yeteneğini sunmaz.

Katalog örneğinde En fazla kayıt değerini 50, Sıralama alanı değerini title, yönünü artan ve Sayfa başına kayıt değerini 12 yapın; Kayıtları sayfalara böl seçeneğini etkinleştirin. Elli, çözümleme üst sınırıdır; elli kayıt bulunduğu anlamına gelmez. On eşleşme ve sayfa başına on iki kayıt varsa önizleme tek sayfadır. Slider bu sayfalama kontrolünü desteklemez.

Yalnızca kaynağın bildirdiği alanlarla filtreleyin. Published plugin catalog, sağlayıcıda zaten yayımlanmış eklentileri seçer; CMS’te bir status alanı uydurmaya veya ikinci bir yayın filtresi tutmaya gerek yoktur. Kayıt bulunamazsa ve Kaynak çalışmazsa durumları için şablonu gizleme veya editoryal sürümünü koruma davranışlarını ayrı seçin. Yayından önce ikisini de inceleyin.

Küçük koleksiyonlarda CMS dönen kayıtları filtreler ve sıralar. Sorgu yeteneği olan sağlayıcılar sorguyu kendileri çalıştırır. Hangi modelin kullanıldığı kaynak ayrıntılarında görünür.

Şablon alan bağlantıları bölümünde her hedef alan için bir değer türü seçin:

• Geçerli döngü kaydı: değerler kart başına değişir. Koleksiyonu ve uyumlu alanı seçin; kayıt, geçerli öğedir.
• Sabit kaynak kaydı: bütün kartlar tek kaydın değerini paylaşabilir. Önce kaynağı, sonra kaydı, ardından uyumlu alanı seçin.
• Editoryal değer / yedek değer: bloğa girilen metni veya görseli kullanın. Bağlı alan kullanılabilir değer döndürmediğinde editoryal değer yedek olarak da kullanılabilir.

Örneğin Header başlığını geçerli döngü kaydının title, Plain Text içeriğini summary, Button Link bağlantısını url alanına bağlayın. Düğme etiketinde sabit Catalog interface kaynağını, labels kaydını ve explore alanını kullanın. Kaynak, kayıt ve alan ayrı seçicilerdir; seçenekleri daraltmak için Kayıt ve alan ara alanını kullanın.

Bağlı bloklarda ayrıca ayrı bir Dinamik İçerik sekmesi bulunur. Normal Blok Alanları değerleri editoryal yedeklerdir. Metin alanı yalnızca URL türündeki alanı seçemez; geçerli kayıt seçenekleri seçilen şablon dalıyla sınırlıdır. Döngüyü değiştirmeden veya kaldırmadan önce etkilenen eşlemeler düzeltilmelidir; doğrulama bağlantısız veya uyumsuz eşlemeleri reddeder.

Kaynak erişilebilir bir görsel URL’si veya bu CMS kurulumuna ait medya referansı sağlar. Uzak uygulamanın sayısal görsel kimliği kendiliğinden CMS medya kimliği olmaz. CMS görseli standart Image bloğuyla gösterir; görseli her Card içine kopyalamazsınız.

Katalogdaki Image bloğunda dört bağımsız bağlantı kullanın:

• Görsel kaynağı → geçerli kaydın image_url alanı.
• Alternatif metin → image_alt.
• İsteğe bağlı görsel açıklaması → image_caption.
• Bağlantı → url.

Dosya diller arasında ortak olabilir; alt metinler ve açıklamalar farklılaşabilir. Alt metin ilgili görsel bilgiyi anlatır; açıklama isteğe bağlı görünür bağlam sağlar. Birini diğerine kopyalamayın. API’de Image subtitle alt metni, Image title ise açıklamayı belirtir. Görselin yüklendiğini ve iki metnin görselin işlevine uygun olduğunu kontrol edin; URL türündeki alan, adresin görsele gittiğini kanıtlamaz.

Standart 1.0, bir sitede daha az dil etkin olsa bile her sağlayıcı kaynağın altı CMS dilini desteklemesini gerektirir: en, tr, de, es, it ve fr. CMS mevcut sitede etkin dili ister; sağlayıcı ilgili kayıt metnini, görsel alt metnini, açıklamayı ve ortak etiketleri sağlar. Üretilen her kartı CMS sayfa düzenleyicisinde çevirmezsiniz.

Örneğin aynı katalog Card bloğu İngilizcede summary alanını, istenen dil tr olduğunda sağlayıcının Türkçe çevirisini kullanır. Düğme etiketi aynı dildeki Catalog interface / labels / explore bağlantısından gelir. Görsel dosyası aynı kalabilir.

Döngünün çevresine yazdığınız sabit bölümler normal sayfa ve blok çevirilerini kullanmaya devam eder. Kaynak doğrulaması dil işaretlerini, sabit anahtarları ve alan türlerini kontrol eder; çeviri kalitesini onaylayamaz. Etkin her dili önizleyip gerçek metinleri inceleyin. Sağlayıcı, değişmeyen İngilizce içeriği başka dil olarak etiketlememelidir.

Önizleme dili seçeneğini belirleyip Kaynağı kontrol et ve önizle düğmesine basın. Yeni sekmedeki özel önizleme, gerçek blok şablonunu kaydedilmemiş güncel eşlemeleriniz, filtre, sıralama, sınır ve sayfalama ayarlarıyla oluşturur. Sayfayı kaydetmez veya yayımlamaz. Yalnızca kaynak ayrıntılarını açmak bu kontrolü çalıştırmaz.

Kayıt sayısını, başlıkları, özetleri, düğme etiketlerini ve hedeflerini doğrulayın. Yüklenen görselleri, çevrilmiş alt metinleri ve açıklamaları kontrol edin. Geçerli boş sonucu; erişim reddinden, kaynak sözleşmesine uymayan yanıttan ve erişilemeyen sağlayıcıdan ayırt edin. Önizleme bu durumları ayrı bildirir. Gerektiğinde sağlayıcı erişimini veya ayarlarını kontrol edin; eksik verinin yerine tahmini çeviriler koymayın.

Ayarları değiştirirseniz yeni önizleme oluşturun. Sayfalama varsa yapılandırılmış sonucu incelemek için sayfalar arasında ilerleyin. Ham API örneği teşhiste yararlıdır; ancak Card bloğunuzun tamamlanmış görsel önizlemesi değildir.

Taslak bağlantılarını kaydet yalnızca taslağı günceller ve revizyon kaydeder. Sayfa siz açtıktan sonra değiştiyse kaydetmeden önce yenileyip inceleyin. Geçersiz yapılandırma önceki ayarları korur. Oluşturulan taslağı etkin tüm dillerde yeniden kontrol edin; yayın veya güncelleme taslağını aktarmak için normal editoryal iş akışını kullanın.

Koleksiyon mevcut sayfa içinde blokları tekrarlar. Kartın detay hedefi önceden var olmalı veya ayrıca yapılandırılan Otomatik Sayfalar kuralı tarafından sağlanmalıdır. Döngü bağlamak bu kuralı oluşturmaz veya etkinleştirmez. Hangi kayıtların kullanılabilir olduğunu yayımlanmış eklenti sağlayıcısı belirler; CMS’te bu kataloğun ikinci bir elle tutulan kopyası yönetilmemelidir.

Etkin eklenti, kaynakları PluginDefinition::contentSources(...) üzerinde tanımlar. Tek kayıt çözümleyicisi ContentSourceResolver uygular: options() sabit kimliğe göre anahtarlanmış, güvenli ve okunabilir kayıt seçenekleri sağlar; resolve() site, sayfa, dil ve önizleme bağlamı için bir kayıt döndürür. Koleksiyon çözümleyicisi ContentCollectionSourceResolver uygular; büyük koleksiyonlar sorgu yürütme, toplamlar ve sayfa aralıkları için ContentCollectionQuery ve ContentCollectionResult ile QueryableContentCollectionSourceResolver uygulayabilir.

Aşağıdaki tanım sayfa düzenleyicisine değil sağlayıcı entegrasyonuna aittir. Çözümlenen her kayıt, istenen dile eşit _locale, recordKey ile bildirilmiş boş olmayan bir metin anahtarı ve bildirilen bütün alanları içermelidir. Kullanılamayan alan değerleri için null kullanın; koleksiyon anahtarları benzersiz olmalıdır. Alan türleri text, rich_text, url veya media olabilir. media değeri pozitif CMS medya kimliğidir; null olmayan diğer değerler metindir. URL değerleri kaynak URL sözleşmesini sağlamalıdır.

Sürümlendirilmemiş kaynaklar Eski kaynak — standart güncellemesi gerekli olarak işaretlenir. Mevcut seçimler değişmeden kalabilir; yeni bağlantılar çok dilli standardı gerektirir. Tabloların ve kayıtların sahibi sağlayıcıdır; düzen ve oluşturma CMS’e aittir. Eklenti kapsayıcıları contentCollectionTemplate() ile katılır ve çözümlenen alt blokları ContentCollectionRenderer::children($block) ile oluşturur; manifest tanımları content_collection.enabled ve isteğe bağlı content_collection.child_types kullanır. Eklentiler Card, Grid ve Image oluşturucularını yeniden yazmak yerine çekirdektekileri kullanmalıdır.

Kısıtlı kayıtlar için accessPolicy(...) ile bir ContentSourceAccessPolicy bağlayın; CMS çözümlemeden önce siteyi, sayfayı, dili, önizleme durumunu ve oturum açmış kullanıcıyı kontrol eder. Tek kayıt hatalarında veya boş değerlerde editoryal alan yedeği korunur. Koleksiyonun boş sonuç ve çözümleyici hata davranışı ayrı seçilir; erişimi reddedilen veya kaldırılan kaynaklar kayıtlı ağacı korur. Sorunlar ve blok kontrolleri, kullanılamayan bağlantıları sessizce silmeden gösterir.

cacheFor($seconds) sınırlı sonuç önbelleğini açar; varsayılan sıfır değeri kapatır. Anahtarlar kaynak, site, sayfa, dil, kayıt/sorgu argümanları ve kaynak ayarlarını içerir. Önizleme bu önbelleği kullanmaz. Alan verisi değiştikten sonra kaynağın önbellek çeşitlerini geçersiz kılmak için app(ContentSourceRuntime::class)->invalidate('plugin-handle::source') çağırın. Sayfa çoğaltma, revizyonlar ve site dışa/içe aktarımı bağlantıları ve koleksiyon yapılandırmasını korur; çalıştırılmış sağlayıcı sonuçları bu paketlere kopyalanmaz.

GET /webadmin/api/content-sources, erişilebilir ve etkin kaynakları bulur. Uyumlu hedefleri ve koleksiyon yeteneğini görmek için block_id ekleyin. POST /webadmin/api/content-sources/{source}/preview, seçilen tek kaydı veya en fazla beş koleksiyon örneğini yalnızca bildirilen alanlarla çözümler. Bu örnek uç noktası yapılandırılmış şablonun tamamını oluşturmaz.

PATCH /webadmin/api/blocks/{block}, content_bindings ve content_collection alanlarını üst düzeyde veya settings altında kabul eder. Her nesne ilgili yapılandırmanın tamamını değiştirir; null temizler. Doğrulama; erişimi, kayıt seçeneklerini, alan türlerini, doğrudan alt blok sahipliğini ve şablon yeteneğini kapsar. Geçersiz istekler 422 invalid_content_source_configuration döndürür. Size ait bir taslak veya güncelleme taslağı kullanıp sonucu sonrasında oluşturun; Dahili İçerik API’si yetkilendirme ve yayın kurallarına uyun. Image subtitle ve title, alt metin ve açıklama için farklı anlamlarını korur.