CSS, JS ve varlıklar

Tema varlıklarında tek kural vardır: CPalius tema varlıklarını derlemez. Tailwind, Sass, Vite, esbuild ya da düz CSS; hangisini isterseniz kullanırsınız. Çıktıyı Resources/dist/ altına koyar ve theme.json'da bildirirsiniz. Sistem yalnızca derlenmiş dosyayı sunar.

tema/
  src/              kendi kaynağınız (pakete girmesi gerekmez)
  package.json      kendi derleme araçlarınız (isteğe bağlı, yalnız sizin makinenizde)
  Resources/
    dist/
      style.css     ← derlenmiş çıktı
      main.js
      fonts/  img/  CSS'in url() ile çağırdığı dosyalar

Dosyaları sunmak: cp_theme_url#

<link rel="stylesheet" href="{{ cp_theme_url('dist/style.css') }}">
<script{{ csp_nonce_attr() }} src="{{ cp_theme_url('dist/main.js') }}"></script>

cp_theme_url şunları yapar:

1. Yolu doğrular. Yalnızca dist/ ya da assets/ altındaki, [A-Za-z0-9._/-] karakterli yollar kabul edilir; .. reddedilir. Bunların dışı boş döner.
2. Dosyayı bulur. Önce etkin temada, yoksa diğer kurulu temalarda arar. Kısmi temada dosya sizde yoksa varsayılan temadan gelir.
3. Kopyalar. public/themes/<tema>/dist/... altına ilk kullanımda kopyalar; kaynak daha yeniyse yeniler. Web sunucusu dosyayı bundan sonra doğrudan sunar.
4. Sürüm ekler. Adres ?v=<değişiklik zamanı> ile döner: dosya değişince tarayıcı önbelleği kendiliğinden kırılır.

Bu yüzden CSS/JS'i elle public/themes/ altına kopyalamayın; tema klasöründe (Resources/dist) tutun.

CSS içindeki yazı tipi ve görseller#

CSS'in url() ile çağırdığı yazı tipi ve görseller cp_theme_url'den geçmez. Bu yüzden CSS dosyası kopyalanırken içindeki url() bağımlılıkları da aynı anda kopyalanır. Bir .deps işaret dosyası bunu, her istekte dosya sistemini taramadan, istek başına tek stat() maliyetine indirir. Bağımlılıklar tema klasöründe mevcut olmalıdır; olmayan bir yolu çağıran url() kırık görsel olur.

Dış çağrı yok#

Temalar yazı tipi, simge ve betikleri dışarıdan (CDN) çağırmaz. Sebepler:

• Gizlilik: üçüncü taraftan yazı tipi çeken sayfa, her okuyucuyu o üçüncü tarafa bildirir.
• CSP: dış alan adları içerik güvenlik politikasıyla engellenir.
• Dayanıklılık: dış servis çökünce siteniz bozulmasın.

Yazı tiplerini ve simge kütüphanelerini temanın kendi dist/ klasörüne koyun ya da yöneticinin AACP'den kurduğu yazı tiplerini kullanın (Menü, widget ve görünüm).

CSP ve betikler#

• Satır içi betik/stil csp_nonce_attr() taşımalıdır.
• eval, satır içi olay işleyicileri (onclick="...") engellenebilir; olay dinleyicilerini JS dosyasında bağlayın.
• Üçüncü taraf betik gerekiyorsa yöneticinin CSP ayarlarına (security.csp_script_src) eklemesi gerekir; bu bir tema kararı olmamalıdır.

Çekirdek paneli ile tema aynı şey değildir#

Yerel geliştirme döngüsü#

1. src/ içinde değiştir
2. kendi araçlarınla derle         (npm run build, sass, …)
3. tarayıcıyı yenile              (cp_theme_url sürümü değişiklik zamanından alır)

Sürümlü adres sayesinde elle önbellek temizlemeniz gerekmez. Şablon (Twig) değiştirdiğinizde geliştirme ortamında Twig önbelleği kendiliğinden yenilenir; canlıda cache:clear gerekir.

Koyu / açık tema#

CSS değişkenleriyle ve data-theme özniteliğiyle anahtarlayın:

:root, [data-theme="light"] { --bg: #fff; --fg: #1f2328; }
[data-theme="dark"]         { --bg: #0d1117; --fg: #e6edf3; }

Sistem tercihini de dinleyin (prefers-color-scheme) ve seçimi localStorage'a try/catch ile yazın (gizli sekme ve çerez engelinde localStorage hata verir). Githeme teması bu kalıbı tek bir küçük githeme.js ile uygular ve ?gh-theme=dark|light ile geçici zorlama sunar.

Üretilmiş dosyalar#

Bir CSS dosyanız başka bir CSS'ten üretiliyorsa (Githeme'in githeme-recolor.css dosyası gibi) bunu açık işaretleyin ve üreticiyi (tools/recolor.php) temayla birlikte saklayın; üretilmiş dosyayı elle düzenlemek bir sonraki derlemede kaybolur.