Ana içeriğe geç

Giriş

🎯 Bu modül ne yapar?​

Templates modülü, projenizin kaynak kodunu değiştirmeden yapısını ve görünümünü değiştirmenizi sağlar. Templates, esnek tasarım ve davranış seçeneklerini korurken bileşenleri OneEntry Platformu aracılığıyla yönetmenizi sağlar.

Templates, projeniz kodundaki bileşenleri tanımlamanıza ve ardından bunları platform tarafından oluşturulan şablonlarla etiketlemenize olanak tanır. Bu ayrım, varlıkların nasıl işlediğini etkilemek için farklı şablon uygulamaları arasında geçiş yapmayı mümkün kılar.

Bunu tasarım sistemi yapılandırıcınız olarak düşünün - OneEntry yönetim panelinde (Ayarlar > Templates) şablonlar oluşturursunuz, bileşenlerinizi bu şablonlarla etiketlersiniz ve bu modül, uygulamanızın tutarlı bir stil ile dinamik olarak içerik oluşturabilmesi için bu yapılandırmaları alır.

📖 Basit Açıklama​

Her uygulamanın tutarlı bir içerik sunumuna ihtiyacı vardır:

  • 🖼️ Görüntü Şablonları - Önceden tanımlanmış boyutlar ve kesimler (küçük resim, kahraman, galeri)
  • 📄 Sayfa Şablonları - Sayfa düzeni yapılandırmaları (blog yazısı, açılış sayfası)
  • 🧱 Blok Şablonları - İçerik bloklarının görünümleri (kart, afiş, bölüm)
  • 🛍️ Ürün Şablonları - Ürün görüntüleme formatları (ızgara, liste, detay)
  • 🎨 Duyarlı Tasarım - Mobil, tablet, masaüstü için farklı boyutlar
  • ♻️ Yeniden Kullanılabilir Yapılandırmalar - Bir kez tanımlayın, her yerde kullanın

Sabit kodlanmış görüntüleme mantığı ile ilgili sorunlar:

Sorunlar:

  • 🔒 Tutarsız - Farklı yerlerde farklı boyutlar
  • 🎨 Bakımı zor - Değişiklik, birden fazla dosyanın düzenlenmesini gerektirir
  • 📱 Duyarlı değil - Sabit boyutlar uyum sağlamaz
  • ♻️ Yeniden kullanılabilirlik yok - Her yerde tekrar eden kod

Templates çözümü:

Faydalar:

  • 🔒 Tutarlı - Her yerde aynı şablon kullanılır
  • 🎨 Kolay bakım - Yönetim panelinde yapılan değişiklik, her yere uygulanır
  • 📱 Duyarlı - Farklı ekranlar için farklı şablonlar
  • ♻️ Yeniden kullanılabilir - Bir kez tanımlayın, uygulama genelinde kullanın

✨ Temel Kavramlar​

Şablon Nedir?​

Şablon, içeriğin nasıl görünmesi gerektiğini tanımlayan bir görüntüleme yapılandırmasıdır:

  • Şablon Türü - Görüntü, sayfa, blok, ürün şablonu
  • Boyutlar - Genişlik, yükseklik, en-boy oranı
  • Kesim Ayarları - Görüntülerin nasıl kesileceği (merkez, üst, alt)
  • Format - Görüntü formatı (JPEG, PNG, WebP)
  • Kalite - Sıkıştırma kalitesi
  • İşaretçi - Kod referansı için benzersiz tanımlayıcı

Şablon Yapısı​

Her şablon bu yapıya sahiptir:

{
  id: 1,                                    // Benzersiz tanımlayıcı
  title: "Ürün Küçük Resmi",                // Şablon adı (benzersiz değil)
  identifier: "product_thumbnail",          // Şablon işaretçisi (benzersiz)
  generalTypeId: 1,                         // Tür ID referansı
  version: 0,                               // Sürüm numarası
  attributeSetIdentifier: null,             // İlişkili özellik seti
  localizeInfos: {                          // Yerelleştirilmiş bilgi
    en_US: {
      title: "Ürün Küçük Resmi",
      description: "Küçük ürün resmi"
    }
  },
  attributeValues: {},                      // Ek özellik verileri
  isActive: true,                           // Aktif durum
  createdAt: "2024-01-15T10:00:00Z",
  updatedAt: "2024-01-15T10:00:00Z"
}

Ana Alanlar:

  • identifier - Şablon referansı için benzersiz işaretçi (bunu kullanın, ID değil)
  • title - Yönetim panelinde görüntülenen şablon adı
  • generalTypeId - Şablonun uygulandığı varlık kategorisi
  • attributeSetIdentifier - İsteğe bağlı ilişkili özellik seti

Şablon Türleri​

Şablonlar, varlık türüne göre organize edilir ve aşağıdaki kategorileri destekler:

Şablon TürüVarlık KategorisiÖrnek Kullanım Durumları
Ürün BloklarıforCatalogProductsÜrün ızgarası, ürün listesi, öne çıkan ürünler
Normal BloklarforOneBlockİçerik kartları, afişler, bölümler, widget'lar
Hata SayfalarıforErrorPages404 sayfası, 500 sayfası, özel hata düzenleri
Normal SayfalarforOnePageBlog yazısı, açılış sayfası, hakkında sayfası
Ürün SayfalarıforOneProductÜrün detayı, ürün karşılaştırması
Katalog SayfalarıforCatalogPageKategori listesi, arama sonuçları
FormlarforFormİletişim formu, kayıt formu, anket
SiparişlerforOrderSipariş onayı, sipariş geçmişi

Yaygın Görüntü Şablonları​

ŞablonBoyutKesimKullanım Durumu
Küçük Resim150×150MerkezKüçük önizleme resimleri
Kart Görüntüsü300×200MerkezÜrün kartları, blog kartları
Kahraman Görüntüsü1920×1080MerkezTam genişlikte afişler
Galeri Görüntüsü800×600MerkezGörüntü galerileri
Avatar100×100MerkezKullanıcı profil resimleri
Mobil Kahraman768×432MerkezMobil uyumlu afişler

Şablon Yapılandırma İş Akışı​

1. Yönetim panelinde şablonlar oluşturun
   (Boyutları, kesimleri, formatları tanımlayın)
   ↓
2. SDK aracılığıyla şablonları alın
   (Templates.getTemplates())
   ↓
3. Şablon yapılandırmalarını uygulayın
   (Görüntü oluşturma sırasında boyutları kullanın)
   ↓
4. Görüntüler otomatik olarak optimize edilir
   (OneEntry CDN doğru boyutu sunar)
   ↓
5. Her yerde tutarlı görüntüleme
   (Aynı şablon = aynı görünüm)

Neden Templates Modülünü Kullanmalısınız?​

FaydasıAçıklama
Tutarlı TasarımUygulama genelinde aynı şablonlar kullanılır
Kolay BakımYönetimde şablonu değiştirin, her yerde güncellenir
Görüntü OptimizasyonuOtomatik yeniden boyutlandırma ve sıkıştırma
Duyarlı TasarımFarklı ekranlar için farklı şablonlar
CDN EntegrasyonuOptimize edilmiş görüntü teslimi
Yeniden Kullanılabilir YapılandırmalarBir kez tanımlayın, her yerde kullanın

📋 Bilmeniz Gerekenler​

Şablonlar Yönetim Panelinde Oluşturulur​

SDK aracılığıyla şablon oluşturamazsınız - bunlar OneEntry yönetim panelinde oluşturulur:

OneEntry Yönetim Paneli → Ayarlar → Şablonlar → Şablon Oluştur → Ad/İşaretçi/Tür Belirle → Kaydet

Oluşturma Süreci:

  • Ad sağlayın (benzersiz olmayan tanımlayıcı)
  • İşaretçi sağlayın (benzersiz tanımlayıcı)
  • Tür seçin (şablonun uygulandığı varlık kategorisi)
  • Tamamlamak için "Oluştur" butonuna tıklayın

Yönetim İşlemleri:

  • Yapılandırma - Adı, işaretçiyi veya türü düzenlemek için dişli simgesine tıklayın
  • Silme - Şablonu seçin ve silme simgesine tıklayın, ardından kaldırmayı onaylayın

SDK, şablon yapılandırmalarını almak için kullanılır, oluşturmak için değil.

Şablon Tanımlaması​

Şablonları tanımlamanın üç yolu:

YöntemNe Zaman KullanılırÖrnek
Türüne GöreKodda referans (en iyi uygulama)product_thumbnail, hero_banner
İşaretçiye GöreKodda referans (en iyi uygulama)product_thumbnail, hero_banner
Tümünü ListeleMevcut şablonları göstergetTemplates()

En iyi uygulama: Kodunuzda her zaman işaretçileri kullanın (asla değişmezler).

Görüntü Şablonu CDN Entegrasyonu​

OneEntry, şablonlara dayalı olarak görüntüleri otomatik olarak optimize eder.

Şablonlarla Duyarlı Tasarım​

Farklı ekran boyutları için farklı şablonlar oluşturun.

Şablon Yapısı:

interface ITemplateEntity {
  id: number;                        // Benzersiz tanımlayıcı
  title: string;                     // Şablon adı (benzersiz değil)
  identifier: string;                // Şablon işaretçisi (benzersiz)
  generalTypeId: number;             // Tür ID referansı
  version: number;                   // Sürüm numarası
  attributeSetIdentifier: string | null;  // İlişkili özellik seti
  localizeInfos: {                   // Yerelleştirilmiş bilgi
    [langCode: string]: {
      title: string;
      description?: string;
    };
  };
  attributeValues: any;              // Ek özellik verileri
  isActive: boolean;                 // Aktif durum
}

Mevcut Şablon Türleri:

  • forCatalogProducts - Ürün blokları
  • forOneBlock - Normal bloklar
  • forErrorPages - Hata sayfaları
  • forOnePage - Normal sayfalar
  • forOneProduct - Ürün sayfaları
  • forCatalogPage - Katalog sayfaları
  • forForm - Formlar
  • forOrder - Siparişler

💡 Önemli Notlar​

Şablonlar Yönetim Panelinde Oluşturulur​

Unutmayın: SDK, şablon yapılandırmalarını almak için kullanılır, şablon oluşturmak için değil.

Şablon oluşturmak/düzenlemek için: OneEntry Yönetim Panelini kullanın.

Şablonların Çalışma Şekli​

Şablonlar, yapıyı koddan ayırarak esnek bileşen yönetimini sağlar:

  1. Proje kodunuzda bileşenleri tanımlayın
  2. Bileşenleri platform tarafından oluşturulan şablonlarla etiketleyin
  3. Varlıkların işleyişini değiştirmek için şablonları değiştirin
  4. Kaynak kodunu değiştirmeden görünümü güncelleyin

Bu ayrım, kod değişiklikleri olmadan birden fazla tasarım ve işlevsel varyasyon sağlar.

Görüntü Optimizasyonu​

OneEntry CDN, şablon ayarlarına dayalı olarak görüntüleri otomatik olarak optimize eder:

  • Otomatik yeniden boyutlandırma
  • Format dönüştürme (JPEG, PNG, WebP)
  • Sıkıştırma
  • Kesme
  • Önbellekleme

Sadece şablon işaretçisini referans alırsınız:

<img src={`${image.url}?template=thumbnail`} />

Duyarlı Şablonlar​

Farklı cihazlar için ayrı şablonlar oluşturun:

  • Mobil şablonlar (768px genişliğinde veya daha az)
  • Tablet şablonları (1024px genişliğinde)
  • Masaüstü şablonları (1920px genişliğinde)

Duyarlı görüntüler için <picture> öğesi ile kullanın.

Şablon Önbellekleme​

Şablonlar nadiren değişir - önbellekleme uygulayın:

  • Ön uç: localStorage, sessionStorage
  • Arka uç: Redis, bellek önbelleği
  • TTL: 1 saat önerilir

📊 Hızlı Referans Tablosu​

YöntemAçıklamaKullanım Durumu
getAllTemplates()Tüm şablonları türlerine göre gruplandırınMevcut tüm şablonları listeleyin
getTemplateByType()Varlık türüne göre şablonları alınBelirli varlık türü için şablonları alın
getTemplateByMarker()İşaretçiye göre şablonu alınBelirli şablon yapılandırmasını alın

❓ Sıkça Sorulan Sorular (SSS)​

Şablonlar ile TemplatePreviews arasındaki fark nedir?​

Şablonlar genel içerik görüntülemesini yapılandırırken (sayfalar, bloklar, ürünler), TemplatePreviews özellikle ürün özellik görüntülerini (renk örnekleri, malzeme önizlemeleri) işler. Ana içerik için Şablonları, özellik görüntüleri için TemplatePreviews'i kullanın.

Bir şablonu bir görüntü URL'sine nasıl uygularım?​

Görüntü URL'sine ?template=marker ekleyin, burada marker şablon tanımlayıcısıdır. OneEntry CDN, şablon yapılandırmasına (boyut, kesim, format) dayalı olarak optimize edilmiş görüntüyü otomatik olarak sunar.

Mobil ve masaüstü için farklı şablonlar oluşturabilir miyim?​

Evet! Her cihaz için uygun boyutlarla ayrı şablonlar oluşturun (örneğin, hero_mobile, hero_desktop). Ekran boyutuna göre doğru şablonu yüklemek için duyarlı tasarım tekniklerini veya <picture> öğelerini kullanın.

Var olmayan bir şablonu referans alırsam ne olur?​

Görüntü, şablon optimizasyonu olmadan orijinal boyutunda yüklenir. Her zaman şablon işaretçilerinin mevcut olduğunu doğrulayın ve eksik şablonları yedek boyutlarla düzgün bir şekilde yönetin.

Üretimi etkilemeden bir şablonu nasıl güncelleyebilirim?​

Şablonlar yapılandırmadır, kod değildir. Yönetim panelindeki değişiklikler hemen uygulanır. Şablon değişikliklerini önce bir test ortamında test edin, ardından doğrulandıktan sonra üretim şablonlarını güncelleyin.

İçeriğim için hangi şablon türlerini kullanmalıyım?​

Varlık türüne göre seçin: standart sayfalar için forOnePage, ürün listeleri için forCatalogProducts, içerik blokları için forOneBlock, ürün detayları için forOneProduct. Şablon türünü içerik kategorinize eşleştirin.

🎓 En İyi Uygulamalar​

  • ID'ler yerine işaretçileri kullanın - İşaretçiler, ortamlar arasında kararlıdır
  • Şablonları önbelleğe alın - Nadir değişen veriler için API çağrılarını azaltın
  • Duyarlı şablonlar oluşturun - Farklı ekranlar için farklı boyutlar
  • WebP formatını kullanın - JPEG/PNG'den daha iyi sıkıştırma
  • Kalite ayarlarını tanımlayın - Kalite ile dosya boyutu arasında denge kurun
  • CDN şablon parametrelerini kullanın - Optimizasyon için ?template=marker
  • Anlamlı işaretçiler oluşturun - product_thumbnail, img_1 değil
  • Şablon kullanımını belgeleyin - Her şablonun ne için olduğunu açıklayın

OneEntry yönetim panelinde şablonlar hakkında daha fazla bilgi: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/templates/content_templates/

Templates modülünün tanımı​

Templates modülü, uygulamanız içindeki içeriğin görüntülenmesini yapılandırır.

Bazı şablonlar OneEntry'de depolanan görüntüleri etkilerken, diğerleri bloklar, sayfalar ve ürünler gibi varlıkların görünümünü tanımlar.


const { Templates } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 İlgili Belgeler​