Genel (Public) Varlıklar

CMS Çekirdeği Genel Varlıkları

WebBlocks CMS çekirdeğinin genel varlıkları şu dizinlerde bulunur:

  • public/cms/css/
  • public/cms/js/
  • public/cms/brand/

Bu yollar, ürünün kendisiyle birlikte gelmesi gereken, CMS'e ait çalışma zamanı davranışı ve stilleri içindir.

CMS çekirdek varlıkları statik paket/çalışma zamanı varlıklarıdır. CMS çalışma zamanı ve sürüm paketi Vite, Laravel Vite eklentisi, Tailwind, npm, Node, public/build, public/hot, paket kilit dosyaları veya @vite Blade yönergeleri gerektirmemelidir. CMS'e ait CSS veya JavaScript değiştiğinde, public/cms altındaki izlenen dosyaları ve packages/webblocks-cms/public/cms paketini doğrudan güncelleyin.

/cms/... URL ad alanı bu statik CMS varlıkları için ayrılmıştır. CMS yönetim rotası öneki, takma adı veya yönlendirmesi olarak yeniden kullanılmamalıdır. Kanonik CMS yönetim ad alanı, pakete ait CMS kimlik doğrulama rotaları etkinken /webadmin/login dahil olmak üzere /webadmin/... yoludur.

Genel sayfa yolları, /contact veya /docs/internal-content-api gibi kanonik Sayfa Çevirisi yollarıdır. Bunlar /cms/... yolunu sahiplenmemelidir; bu ad alanı yalnızca statik varlıklara ayrılmıştır. Eski /p/... genel sayfa biçimi, eski bir yönlendirme/takma addır ve yeni kanonik URL'ler için kullanılmaz.

Bu ayrım, yaygın Nginx try_files dağıtımlarını korur. /cms/ yoluna gelen bir istek, Laravel isteği almadan önce fiziksel public/cms/ diziniyle eşleşebilir; bu yüzden CMS yönetim yönlendirmesi /cms yoluna bağlı olmamalıdır. Nihai yönetim öneki tasarımı bu çakışmayı tamamen ortadan kaldırır ve public/cms/index.php ön denetleyici devri kullanmaz; bu dosya hem kurulum kökündeki public/cms/ dizininde hem de paketteki packages/webblocks-cms/public/cms/ varlıklarında bulunmamalıdır.

Site Tanıtıcısı (Handle) Kuralı

Site tanıtıcıları, site kapsamlı genel varlık klasörleri için kullanılan, dosya sistemi açısından güvenli tanımlayıcılardır.

  • Tanıtıcılar küçük harflidir.
  • Tanıtıcılar mümkün olduğunca ASCII açısından güvenlidir.
  • Boşluklar, noktalar, eğik çizgiler, alt çizgiler ve tekrarlanan noktalama işaretleri tek bir tireye normalize edilir.
  • Yalnızca a-z, 0-9 ve - karakterleri kalır.
  • Tekrarlanan tireler teke indirilir; baştaki ve sondaki tireler kırpılır.
  • Örnek normalizasyonlar:
  • ui.webblocksui.com -> ui-webblocksui-com
  • WebBlocks UI -> webblocks-ui
  • Docs Site -> docs-site

Tire, site tanıtıcıları ve public/site/{site_handle}/... klasörleri için kanonik ayırıcıdır.

Kurulum Düzeyi ve Site Geçersiz Kılma Varlıkları

Kuruluma özgü veya siteye özgü genel geçersiz kılmalar, çözümlenen site tanıtıcısı altında bulunur:

  • public/site/{site_handle}/css/site.css
  • public/site/{site_handle}/js/site.js

Bu dosyalar mevcut kurulum için geçersiz kılma alanıdır ve CMS çekirdek davranışı için kullanılmamalıdır.

Mevcut olduğunda, public/site/{site_handle}/css/site.css dosyası o an çözümlenen genel site için genel <head> içinde işlenir.

Mevcut olduğunda, public/site/{site_handle}/js/site.js dosyası o an çözümlenen genel site için genel <head> içinde defer ile işlenir.

Site Dışa / İçe Aktarma dosya dahil etme etkin olarak çalıştığında, bu iki kanonik site düzeyi geçersiz kılma dosyası mevcutsa paketlenir ve nihai içe aktarılan site tanıtıcısı altında geri yüklenir. Eksik site.css veya site.js dosyaları sorunsuzca atlanır. Dışa / İçe Aktarma, bu site düzeyi yol üzerinden rastgele public/site/{site_handle}/... ağaçlarını paketlemez.

public/storage, public/site/... yolundan ayrıdır. storage/app/public altındaki dosyalar için storage:link tarafından oluşturulan Laravel genel depolama sembolik bağlantısıdır ve CMS varlık alanı ya da site geçersiz kılma varlık alanı olarak değerlendirilmemelidir.

Kanonik geçersiz kılma kuralı bir site tanıtıcısı segmenti gerektirir. Tanıtıcısız site geçersiz kılma yolları kanonik değildir ve yeni çalışma zamanı davranışı için kullanılmamalıdır.

CMS'e ait konuk ve e-posta destek stilleri artık public/cms/css/guest.css ve public/cms/css/email.css altında bulunur.

Varsayılan CMS favicon'ları ve uyumluluk işareti dosyaları gibi CMS'e ait ürün marka varlıkları, paketteki public/cms/brand/ dizininden gelir ve kurulum kökündeki public/cms/brand/ dizinine kurulur, yayımlanır veya eşitlenir. Bunlar CMS kabuğu için ürün kimliği varlıklarıdır; siteye özgü Medya Kitaplığı markalaması ya da public/site/... geçersiz kılmaları değildir. Kanonik ürün marka seti logo-mark.svg, logo-mark-dark.svg, logo-mark-on-accent.svg, favicon.svg, favicon-32x32.png, favicon-16x16.png ve apple-touch-icon.png dosyalarından oluşur. Pakete ait CMS kimlik doğrulama ekranları ve yönetim kenar çubuğu, işareti currentColor değerini devralan satır içi bir SVG bileşeniyle işler.

Sayfa Varlıkları

Sayfa kapsamlı CSS ve JS dosyaları artık page_assets üzerinden ilişkisel olarak referans gösterilebilir.

  • V1 yalnızca /site/webblocks-ui/pages/playground/page.css veya /site/webblocks-ui/pages/playground/page.js gibi yerel /site/... yollarını kabul eder
  • Kanonik sayfa varlığı yolları şunlardır:
  • public/site/{site_handle}/pages/{page_slug}/page.css
  • public/site/{site_handle}/pages/{page_slug}/page.js
  • CSS sayfa varlıkları genel <head> içinde işlenir
  • JS sayfa varlıkları genel <head> içinde defer ile işlenir
  • Yapılandırılmış sayfa varlıklarını yalnızca sahibi olan genel sayfa işler
  • Sayfa Varlıkları yönetim yerleşimlerinde işlenmez
  • Sayfa Varlıkları pages.settings içinde değil, page_assets içinde saklanır
  • Site Dışa / İçe Aktarma medya dosyalarını dahil ettiğinde, referans verilen /site/... fiziksel dosyaları da paketlenir ve geri yüklenir

Eklenti Genel Varlıkları

Etkin eklentiler, PluginPublicAsset kayıt nesneleri aracılığıyla genel varlık katkıları bildirebilir. Bu kancalar açık ve kaynağı belirlenebilir eklenti varlıkları içindir; CMS çekirdek varlıklarından, site geçersiz kılma varlıklarından ve sayfa kapsamlı varlıklardan ayrıdır.

  • eklenti varlık tanıtıcıları, analytics-tools.public-css gibi eklenti tanıtıcısıyla nokta ad alanlı olmalıdır
  • eklenti CSS'i genel <head> içine katkı olarak eklenebilir
  • eklenti JS'i, bildirildiği yerde defer, async veya type="module" ile genel <head> içine katkı olarak eklenebilir
  • geç yükleme uygun olduğunda eklenti JS'i genel body sonuna katkı olarak eklenebilir
  • devre dışı ve uyumsuz eklenti varlıkları toplanmaz ve işlenmez
  • eklenti varlıkları yine de eklenti tarafından, eklentiye ait statik bir ad alanı altında yayımlanmalıdır

Bu kanca eklenti paketleri kurmaz, dosya yayımlamaz, varlıkları Laravel üzerinden akışla sunmaz, uzak keşif oluşturmaz veya pazar yeri davranışı oluşturmaz.

Dahili/operatör WebBlocks UI Manager eklentisi, genel sayfa varlığı kancası yerine ayrı bir CDN artefakt kuralı kullanır. Sıradan CMS kurulumlarında paketlenmiş olarak gelmez ve yalnızca elle ZIP yükleme ve açıkça etkinleştirme sonrasında kullanılabilir:

  • sürüm artefakt hedefleri public/cdn/webblocks-ui/{version}/... altında sürümlendirilir
  • sürüm manifestleri, hazırlanan artefaktlar için yerel meta verilerdir ve SHA-256 sağlama toplamlarını içerir
  • dry-run yayımlama; kaynak yolları, beklenen dist dosyalarını, sağlama toplamlarını, manifest tutarlılığını, hedef yol güvenliğini ve idempotentliği dosya yazmadan doğrular
  • apply yayımlama, doğrulama geçtikten sonra yalnızca yapılandırılmış yerel/projeye ait statik hedefe yazar
  • sağlama toplamı eşleşen mevcut dosyalar atlanır; sağlama toplamı uyuşmazlıkları yayımlamayı engeller
  • bu iş akışı harici bir üretim CDN'ine dağıtım yapmaz ve CMS çekirdeğinin WebBlocks UI tüketim URL'lerini değiştirmez

Genel Varlık Kuralı

  • CSS genel <head> içinde kalır
  • Adlandırılmış genel JS, genel <head> içinde defer ile kalır
  • body_end ile saklanmış eski adlandırılmış JS satırları hâlâ kabul edilir, ancak genel adlandırılmış JS <head defer> çıktısına normalize edilir
  • Genel blok işleyicileri satır içi betikler üretmemelidir
  • CMS'e ait genel JS public/cms/js/ altında olmalıdır
  • CMS'e ait genel CSS public/cms/css/ altında olmalıdır
  • eklentiye ait genel varlıklar eklentiye ait tanıtıcılar ve statik yollar kullanmalı ve CMS genel yerleşimini doğrudan değiştirmek yerine eklenti varlık katkı kancaları üzerinden kaydedilmelidir
  • Site düzeyi geçersiz kılma JS'i public/site/{site_handle}/js/site.js altında olmalıdır
  • Site düzeyi geçersiz kılma CSS'i public/site/{site_handle}/css/site.css altında olmalıdır
  • Genel sayfa kabuğu, galeri görüntüleyicileri ve genel arama modali gibi ürünle gelen WebBlocks UI modal tabanlı davranışlar için tek ortak #wb-overlay-root.wb-overlay-root bağlama noktasının sahibidir
  • Genel parçalar ve güvenilen HTML içeriği, #wb-public-overlay-root, #public-overlay-root veya #overlay-root gibi rakip kökler işlemek yerine kaplama alt öğelerini bu kanonik köke katkı olarak eklemelidir
  • Ortak genel diyalog katmanı hidden ile işlenmemelidir; WebBlocks UI v2.7.12 bu katmanı modal, galeri görüntüleyici ve toast hedefleri için yeniden kullanır ve görünürlüğü yeniden kullanılan katman sarmalayıcısında değil, yalnızca etkin arka plan/modal veya toast durumunda değiştirir
  • CMS çekirdeği yalnızca WebBlocks UI davranışı zaten kapsamıyorsa genel JS gönderir; public-search-modal.js CMS'e ait kalır, Header Actions modu, ön ayar, vurgu ve açılır menü davranışı ise artık ek bir CMS çalışma zamanı olmadan ürünle gelen WebBlocks UI data-wb-* davranışına dayanır

Site Marka Varlıkları

Genel favicon ve sosyal paylaşım görselleri artık her Site üzerinde ortak Medya kitaplığından seçilir.

  • favicon çıktısı, ilgili medya öğesinin genel bir URL'si olduğunda, o an çözümlenen sitenin favicon_media_id değerini kullanır
  • Open Graph yedek görselleri, mevcut olduğunda o an çözümlenen sitenin social_image_media_id değerini kullanır
  • bunlar site kapsamlı meta veri varlıklarıdır, CMS ürün marka varlıkları değildir
  • sayfa çevirisindeki og_image_media_id, ilgili medya öğesinin genel bir URL'si olduğunda tek bir dil (locale) için site sosyal görselini geçersiz kılabilir
  • sayfa düzeyi SEO varlıkları yalnızca genel meta verileri etkiler ve CMS yönetim markalamasını değiştirmez
  • kurulum düzeyi Proje Kimliği; genel favicon'u, genel meta verileri veya site kapsamlı sosyal paylaşım varlıklarını etkilemez

WebBlocks UI Varlıkları

WebBlocks UI varlıkları CMS genel yerleşiminde CDN'den yüklenmeye devam eder.

CMS'e ait varsayılan CDN referansları; genel ve yönetim çalışma zamanı CSS'i, ikon CSS'i, çalışma zamanı JS'i ve varsayılan ikon manifesti eşitleme kaynağı için WebBlocks UI v2.7.12 sürümüne sabitlenmiştir. Üretim yerleşim çıktısı, standart dist artefaktları webblocks-ui.css, webblocks-icons.css ve webblocks-ui.js ile kanonik jsDelivr etiket URL biçimini kullanır; küçültme (minification) sıkılaştırması ertelenmiştir. Tarayıcıya dönük CSS ve JavaScript, Chrome bu yanıtları ORB veya MIME işleme yoluyla engelleyebileceği için raw.githubusercontent.com yedeklerini kullanmamalıdır.

Bu CDN varlıkları UI projesinin parçasıdır ve CMS deposu içinde düzenlenmemeli veya derlenmemelidir. Bir operatör sitesine kurulduğunda WebBlocks UI Manager; sürüm, artefakt, manifest, sağlama toplamı ve yayımlama çalıştırması meta verilerini eklentiye ait davranış olarak kaydeder ve doğrulanmış dosyaları yapılandırılmış yerel/projeye ait statik bir CDN hedefine yayımlayabilir. Ayrı ve açık bir geçiş bu davranışı değiştirene kadar CMS çekirdeği mevcut sabitlenmiş CDN URL'lerini kullanmaya devam eder.

Yönetim JavaScript Kapsamı

Paket yönetim yerleşimi, genel JavaScript'i bilinçli olarak küçük tutar: sabitlenmiş WebBlocks UI webblocks-ui.js ile public/cms/js/admin/core.js yolundaki ortak CMS yönetim çekirdek varlığı. Özelliğe özgü yönetim davranışı, eşleşen DOM kancalarını işleyen görünüm veya parça tarafından admin-scripts yığını üzerinden yüklenmelidir.

Sayfa kapsamlı özellik varlıklarına örnek olarak varlık seçici panelleri, medya kopyalama düğmeleri, sıralanabilir oluşturucu satırları, satır içi ve yapılandırılmış oluşturucu editörleri, sayfa oluşturucu modalleri, slot blok silme modalleri, sayfa slot kaynağı modalleri, Sayfa Düzenleme varlık denetimleri, Galeri öğesi düzenleme, Zengin Metin düzenleme ve yönetici parola görünürlüğü anahtarları verilebilir. Bunlar public/cms/js/admin/ altında CMS'e ait statik dosyalar olarak kalır ve uygun olduğunda packages/webblocks-cms/public/cms/js/admin/ altında eşleşen paket kaynak kopyaları bulunur. CMS yönetim varlıkları Vite, npm, Tailwind, public/build, hot dosyaları veya herhangi bir frontend derleme zinciri kullanmaz.