İçerik Kaynakları, etkin bir eklentinin genel işaretlemenin sahibi olmadan mevcut CMS bloklarına türü belirlenmiş alan verileri sunmasını sağlar. Bir katalog, ticaret, etkinlik veya haber eklentisi kayıtları sağlar; CMS sayfaları ise yerleşim, blok bileşimi, çeviri, önizleme ve işleme üzerindeki sahipliğini korur.

Sınır bilinçli olarak belirlenmiştir:

  • bir eklenti kaynağı hangi verilerin kullanılabilir olduğunu yanıtlar;
  • bir CMS bloğu bu verilerin nasıl sunulacağını yanıtlar;
  • sayfa ve slot ağacı nerede görüneceğini yanıtlar.

Eklentiler, yalnızca eklentiye ait kayıtları göstermek için çekirdek Header, Rich Text, Card, Grid, Slider veya Slide işleyicilerini yeniden oluşturmamalıdır.

Varlık kaynağı sözleşmesi

Etkin bir eklenti, tanımında bir varlık kaynağı kaydeder:

PluginDefinition::make('plugin-catalog')
  ->contentSources([
    ContentSourceDefinition::entity('plugin-catalog::plugin')
      ->label('Plugin')
      ->resolver(PluginSource::class)
      ->fields([
        'name' => ['type' => 'text', 'label' => 'Name'],
        'description' => ['type' => 'rich_text', 'label' => 'Description'],
        'download_url' => ['type' => 'url', 'label' => 'Download URL'],
      ]),
  ]);

Çözümleyici ContentSourceResolver arayüzünü uygular. options(), blok editörüne güvenli ve insan tarafından okunabilir önizleme seçenekleri sağlar; resolve() ise istenen kararlı anahtar ve geçerli site, sayfa, dil (locale) ve önizleme bağlamı için tek bir kayıt döndürür.

Eklenti, tablolarının ve alan modellerinin tek sahibi olarak kalır. CMS yalnızca kaynak tanıtıcısını, kararlı kayıt anahtarını, seçilen alanı ve bloğun olağan editoryal yedeğini saklar.

Erişim ve önbelleğe alma

Kısıtlı veri içeren bir kaynak, ContentSourceAccessPolicy ile accessPolicy(...) uygulayan bir sınıf ekler. İlke, herhangi bir çözümleyici çağrılmadan önce siteyi, sayfayı, dili (locale), önizleme durumunu ve kimliği doğrulanmış aktörü alır. Reddedilen bir kaynak, kullanılamayan bir kaynak gibi davranır ve genel blok editoryal yedeğini korur.

Eklentiler cacheFor($seconds) ile sınırlı sonuç önbelleğini etkinleştirebilir. Önbellek anahtarları kaynağı, siteyi, sayfayı, dili (locale), kayıt/sorgu bağımsız değişkenlerini ve kaynak ayarlarını içerir. Önizleme istekleri önbelleği atlar; böylece editörler her zaman güncel verileri inceler. Bir alan yazma işleminden sonra eklentiler, o kaynağın tüm önbelleğe alınmış varyantlarını hemen eskimiş olarak işaretlemek için app(ContentSourceRuntime::class)->invalidate('plugin-handle::source') çağrısını yapabilir. Varsayılan değer olan sıfır süre, önbelleği devre dışı bırakır.

Editör davranışı

Desteklenen mevcut bloklar, Ayarlar sekmelerinde bir İçerik kaynağı denetimi sunar. Editör, Blok Alanları'na girilen değişmez değeri koruyabilir veya bir kaynak kaydı ile tür açısından uyumlu bir alan seçebilir. Hiçbir bağlantı ifadesi elle yazılmaz.

Desteklenen alan bağlantıları şunlardır:

  • Bir title kaynak alanından Header text;
  • Bir content kaynak alanından Plain Text text;
  • Bir content veya text kaynak alanından Rich Text rich_text.
  • Uyumlu alanlardan görsel kaynağı, açıklama, alternatif metin ve bağlantı.
  • Button ve Button Link etiketleri ile URL'leri.
  • Link List Item başlığı, ikincil metni, açıklaması ve URL'si.

Genel işleme sırasında bağlantı boş olmayan bir değere çözümlenirse öncelik kazanır. Eksik kayıtlar, devre dışı eklentiler, kullanılamayan kaynaklar ve boş değerler editoryal blok değerini güvenle korur. Çözümleyici hataları sayfayı devre dışı bırakmadan bildirilir.

Bağlantılar settings.content_bindings altında bulunur; böylece mevcut sayfa çoğaltma, revizyon, dışa aktarma ve içe aktarma davranışı, alana özgü bir veritabanı sütunu olmadan bunları korur.

Koleksiyon kaynakları

Bir eklenti, ContentSourceDefinition::collection(...) uygulayan bir çözümleyiciyle ContentCollectionSourceResolver kaydedebilir. Koleksiyon destekli kapsayıcılar bu koleksiyonu ve mevcut doğrudan alt öğelerden birini yinelenen şablon olarak seçebilir. İşleme sırasında CMS, her kayıt için bu alt ağacı klonlar, kaydı geçerli koleksiyon öğesi olarak sağlar ve alt alan bağlantılarını buna göre çözümler.

Koleksiyon desteği, özel durum blok adlarından oluşan bir CMS listesi değil, bir blok sözleşmesi yeteneğidir. Çekirdek Section, Container, Stack, Cluster, Grid ve Slide, bunun dışında geçerli olan herhangi bir doğrudan alt şablonu kabul eder. Slider, Slide'ı; Columns, Column Item'ı; Feature Grid, Feature Item veya Column Item'ı; Link List ise Link List Item'ı kabul eder. Split ve Card gibi anlamsal kapsayıcılar, yapısal alt öğelerini yinelemek yerleşim sözleşmelerini ihlal edeceği için bu yeteneği sunmaz.

Eklenti blok türleri, herhangi bir geçerli alt tür için ->contentCollectionTemplate() ile etkinleştirilebilir veya izin verilen alt katalog slug'larının bir listesini iletebilir. Yüklü manifestler aynı sözleşmeyi content_collection.enabled ve isteğe bağlı content_collection.child_types olarak ifade eder. Eklentinin genel kapsayıcı görünümü, çözümlenen alt öğeleri çekirdek kapsayıcı görünümleri gibi ContentCollectionRenderer::children($block) aracılığıyla işler.

Diğer alt öğeler olağan editoryal içerik olarak kalır ve konumlarını korur. Seçilen şablon yerinde çözümlenen kayıtlarla değiştirilir; böylece tek bir kapsayıcı, eklentiye ait bir carousel, grid veya card işleyicisi olmadan elle oluşturulan ve dinamik içeriği bilinçli olarak karıştırabilir. Editörler en fazla üç kaynak kaydını önizleyebilir, kayıt sayısını sınırlayabilir, tek bir kaynak alanına ve değerine göre filtreleyebilir, bir kaynak alanına göre iki yönde sıralayabilir ve Grid veya Stack sonuçlarını sayfalayabilir. Çözümleme 50 kayıtla sınırlıdır. Eksik kaynak, devre dışı eklenti, geçersiz şablon veya çözümleyici hatası, olağan saklanan blok ağacını güvenle geri yükler.

Küçük kaynaklar için ContentCollectionSourceResolver yeterlidir ve CMS filtreleme, sıralama ve sayfalamayı yinelenebilir verilerine uygular. Büyük kaynaklar QueryableContentCollectionSourceResolver uygulamalıdır. CMS daha sonra eklentiye türü belirlenmiş bir ContentCollectionQuery iletir ve bir ContentCollectionResult tüketir; böylece tam koleksiyon yüklenmeden veritabanı/API filtreleme, sıralama, sınırlar, toplamlar ve sayfa pencereleri kullanılabilir.

Editörler, geçerli ancak boş bir sonucun ve çözümleyici hatasının yinelenen şablonu gizlemesini mi yoksa editoryal yedeğini göstermesini mi istediklerini ayrı ayrı seçer. Reddedilen veya kaldırılan kaynaklar saklanan içeriği korur. Ayarlar paneli; eklentisi, kaynağı veya bildirilen alanı kaybolmuş bağlantıları bildirir, böylece eklenti yükseltmeleri ve kaldırmaları içeriği sessizce sahipsiz bırakmaz.

Bağlantılar ve koleksiyon yapılandırması, olağan blok settings yükünde bulunur. Sayfa revizyonları ve site dışa/içe aktarma işlemleri bu yükü zaten aynen kopyalar; eklentiye ait hiçbir tablo veya yürütülebilir çözümleyici çıktısı bir CMS revizyonuna ya da aktarım paketine girmez.

Dahili İçerik API’si

API istemcileri yalnızca etkin ve erişilebilir kaynakları GET /webadmin/api/content-sources ile keşfeder. block_id iletildiğinde uyumlu bağlantı hedefleri ve bloğun koleksiyonu barındırıp barındıramayacağı eklenir. Varlık kaynakları güvenli kayıt seçeneklerini içerir; alanlar her zaman eklentinin bildirdiği sözleşmeden gelir.

POST /webadmin/api/content-sources/{source}/preview, içeriği değiştirmeden bir varlık kaydını veya en fazla beş koleksiyon kaydını çözümler. Önizleme yanıtları, kaynağın bildirmediği tüm değerleri atar ve istenen bloğu, dili (locale), kimliği doğrulanmış aktörü ve kaynak erişim ilkesini bağlam olarak kullanır.

Mevcut bir yapılandırılmış blok, content_bindings üst düzeyinde content_collection ve PATCH /webadmin/api/blocks/{block} kabul eder; aynı nesneler settings altında da kabul edilir. Her nesne ilgili yapılandırmasını değiştirir ve null bunu temizler. API yazmadan önce blok hedeflerini, alan türlerini, kaynak erişimini, kayıt seçeneklerini, doğrudan alt öğe sahipliğini ve blok sözleşmesinin izin verdiği koleksiyon şablonu türlerini doğrular. Geçersiz yapılandırma 422 invalid_content_source_configuration döndürür. Bileşik sonucu doğrulamak için yazma işleminden sonra sahibi olan taslak veya güncelleme sayfasını işleyin.