Lewati ke konten utama

Pendahuluan

Ambil template tampilan yang mengontrol bagaimana halaman, blok, produk, dan gambar dirender di aplikasi Anda.

Informasi lebih lanjut tentang template di panel admin OneEntry: https://doc.oneentry.cloud/docs/category/templates

🎯 Apa yang dilakukan modul ini?​

Modul Templates memungkinkan Anda mengubah struktur dan penampilan proyek Anda tanpa mengubah kode sumbernya. Anda membuat template di panel admin OneEntry (Pengaturan > Template), menandai komponen Anda dengan template tersebut, dan modul ini mengambil konfigurasi tersebut agar aplikasi Anda dapat merender konten dengan gaya yang konsisten.

Pemisahan struktur dari kode ini memungkinkan Anda beralih antara implementasi template untuk mempengaruhi bagaimana entitas dirender, semua tanpa perlu melakukan redeploy. SDK bersifat read-only: Anda tidak dapat membuat template melalui SDK ini.

🚀 Memulai dengan Cepat​

Inisialisasi modul dari defineOneEntry:


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

Ambil template dan baca konfigurasinya:

// Fetch all templates of a given BlockType.
const productTemplates = await Templates.getTemplateByType("product", "en_US");

productTemplates.forEach((tpl) => {
  console.log(tpl.identifier, tpl.title, tpl.generalTypeName);
});

// Or fetch a single template by its marker.
const card = await Templates.getTemplateByMarker("product_thumbnail", "en_US");
console.log(card.attributeValues);

✨ Konsep Kunci​

Apa itu Template?​

Template (ITemplateEntity) adalah konfigurasi tampilan yang mendefinisikan bagaimana konten harus muncul:

  • Tipe Umum (generalTypeName) - Kategori entitas yang diterapkan template, seperti BlockType seperti product, common_page, common_block, form, atau order
  • Judul (title) - Nama template yang ditampilkan di panel admin (tidak unik)
  • Penanda (identifier) - Identifikasi unik untuk referensi kode (gunakan ini, bukan ID)
  • Nilai Atribut (attributeValues) - Peta nilai atribut yang dikunci oleh penanda
  • Set Atribut (attributeSetIdentifier) - Set atribut terkait yang bersifat opsional

Struktur Template (ITemplateEntity):

interface ITemplateEntity {
  id: number;                              // Unique identifier
  title: string;                           // Template name (non-unique)
  identifier: string;                      // Template marker (unique)
  generalTypeId: number;                   // Type ID reference
  version: number;                         // Version number
  generalTypeName: BlockType;              // General type name
  attributeSetIdentifier: string | null;   // Associated attribute set
  attributeValues: IAttributeValues;       // Map of attribute values keyed by marker
  position: number;                        // Sort position
}

Tipe Template (BlockType)​

Tipe template adalah generalTypeName-nya, sebuah nilai BlockType. getTemplateByType(type) menerima BlockType yang sama. Nilai umum:

TipeKategori EntitasContoh Kasus Penggunaan
productProdukDetail produk, tampilan produk
catalog_pageHalaman katalogDaftar kategori, hasil pencarian
common_pageHalaman biasaPostingan blog, halaman landing, halaman tentang
error_pageHalaman kesalahanHalaman 404, halaman 500, tata letak kesalahan kustom
common_blockBlok kontenKartu konten, spanduk, bagian, widget
formFormulirFormulir kontak, formulir pendaftaran, survei
orderPesananKonfirmasi pesanan, riwayat pesanan
serviceEntitas layananKonten terkait layanan

📋 Apa yang Perlu Anda Ketahui​

Template dibuat di panel admin​

Anda tidak dapat membuat template melalui SDK - template dibuat di panel admin OneEntry (Pengaturan > Template). Setiap template memerlukan Nama (tidak unik), Penanda yang unik, dan Tipe (kategori entitas yang diterapkan). SDK digunakan untuk mengambil konfigurasi template, bukan untuk membuatnya.

Gunakan penanda, bukan ID​

Selalu rujuk template dengan penanda (identifier) di kode Anda - penanda stabil di seluruh lingkungan, ID tidak. Gunakan getTemplateByMarker(marker) untuk satu template, getTemplateByType(type) untuk semua template dari satu BlockType, dan getAllTemplates() untuk setiap template yang dikelompokkan berdasarkan tipe.

Template yang hilang​

Metode mengembalikan objek kesalahan (IError) ketika template tidak ditemukan. Selalu verifikasi bahwa penanda ada dan tangani template yang hilang dengan baik.

Cache​

Template jarang berubah - cache mereka (localStorage/sessionStorage di frontend, Redis/memory di backend; ~1 jam TTL adalah titik awal yang wajar).

📊 Tabel Referensi Cepat​

MetodeDeskripsiKasus Penggunaan
getAllTemplates()Ambil semua template yang dikelompokkan berdasarkan tipeDaftar semua template yang tersedia
getTemplateByType()Ambil template berdasarkan tipe entitasAmbil template untuk tipe entitas tertentu
getTemplateByMarker()Ambil template berdasarkan penandaAmbil konfigurasi template tertentu

❓ Pertanyaan Umum (FAQ)​

Apa perbedaan antara Templates dan TemplatePreviews?​

Templates mengonfigurasi tampilan konten umum (halaman, blok, produk), sementara TemplatePreviews secara khusus menangani gambar atribut produk (contoh warna, pratinjau material). Gunakan Templates untuk konten utama, TemplatePreviews untuk gambar atribut.

Bagaimana cara mengambil template tertentu?​

Gunakan getTemplateByMarker(marker) untuk satu template berdasarkan identifikatornya, atau getTemplateByType(type) untuk mengambil semua template dari BlockType tertentu (misalnya product, common_page). Gunakan getAllTemplates() untuk mengambil setiap template yang dikelompokkan berdasarkan tipe.

Apa yang terjadi jika saya merujuk template yang tidak ada?​

Metode mengembalikan objek kesalahan (IError). Selalu verifikasi bahwa penanda template ada dan tangani template yang hilang dengan baik.

Tipe template mana yang harus saya gunakan untuk konten saya?​

Pilih berdasarkan tipe entitas: common_page untuk halaman standar, catalog_page untuk daftar produk, common_block untuk blok konten, product untuk detail produk. Sesuaikan tipe template dengan kategori konten Anda.

🎓 Praktik Terbaik​

  • Gunakan penanda, bukan ID - penanda stabil di seluruh lingkungan.
  • Buat penanda yang semantik - product_card, bukan tpl_1.
  • Cache template - kurangi panggilan API untuk data yang jarang berubah.
  • Tangani template yang hilang - periksa bentuk pengembalian IError.

🔗 Dokumentasi Terkait​