Lewati ke konten utama

Pendahuluan

Ambil template pratinjau yang menstandarkan ukuran dan format gambar untuk gambar atribut produk.

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

🎯 Apa yang dilakukan modul ini?​

Modul TemplatePreviews memungkinkan Anda untuk menstandarkan parameter gambar di seluruh proyek Anda. Dengan menerapkan template pratinjau pada atribut "Gambar" atau "Grup Gambar", Anda menyajikan gambar yang ukurannya dan pemotongannya konsisten sesuai dengan konfigurasi template - di seluruh gambar produk, gambar varian, dan gambar berbasis atribut.

Anda membuat template pratinjau di panel admin OneEntry (Pengaturan > Template Pratinjau), dan modul ini mengambil konfigurasi tersebut sehingga atribut produk dengan gambar ditampilkan secara konsisten. SDK bersifat hanya-baca: Anda tidak dapat membuat template pratinjau melalui SDK ini.

🚀 Memulai dengan Cepat​

Inisialisasi modul dari defineOneEntry:


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

Ambil template pratinjau dan baca proporsinya:

// Fetch all preview templates, localized to English.
const previews = await TemplatePreviews.getTemplatePreviews("en_US");

previews.forEach((tpl) => {
  console.log(tpl.identifier, tpl.title, tpl.proportions.default.square);
});

// Or fetch a single preview template by its marker.
const swatch = await TemplatePreviews.getTemplatePreviewByMarker("color_swatch", "en_US");
console.log(swatch.proportions.default.horizontal);

✨ Konsep Kunci​

Apa itu Template Pratinjau?​

Template Pratinjau (ITemplatesPreviewEntity) adalah konfigurasi gambar untuk atribut produk:

  • Marker (identifier) - Pengidentifikasi unik untuk referensi template (gunakan ini, bukan ID)
  • Judul (title) - Nama template yang ditampilkan di panel admin (tidak unik)
  • Proporsi (proportions) - Set parameter gambar per orientasi (horizontal, vertikal, persegi)
  • Penyelarasan (alignmentType) - Cara gambar dipotong/dipusatkan

Struktur Template Pratinjau​

interface ITemplatesPreviewEntity {
  id: number;
  title: string;
  proportions: {
    default: {
      horizontal: IProportion | null;   // { width, height, alignmentType }
      vertical: IProportion | null;     // { width, height, alignmentType }
      square: ISquare;                  // { side, alignmentType }
    };
  };
  identifier: string;
  version: number;
  attributeValues: IAttributeValues;
  position: number;
  isUsed: boolean;
  attributeSetIdentifier?: string | null;
}

Contoh nilai proporsi:

{
  default: {
    horizontal: { width: 234, height: 324, alignmentType: "middleBottom" },
    vertical:   { width: 2,   height: 3,   alignmentType: "leftTop" },
    square:     { side: 3,    alignmentType: "leftTop" },
  },
}

Alur Kerja Template Pratinjau​

1. Create preview template in admin panel
   (Define proportions for attribute images)
   ↓
2. Assign template to an attribute type
   (e.g., "Color" attribute uses "color_swatch")
   ↓
3. Fetch templates via SDK
   (TemplatePreviews.getTemplatePreviews())
   ↓
4. Apply proportions to attribute images
   (Render images with consistent sizing)
   ↓
5. Consistent attribute image display
   (All color swatches same size)

📋 Apa yang Perlu Anda Ketahui​

Template pratinjau dibuat di panel admin​

Anda tidak dapat membuat template pratinjau melalui SDK - mereka dibuat di panel admin OneEntry (Pengaturan > Template Pratinjau). Setiap template memerlukan Nama (tidak unik) dan Marker yang unik, ditambah set proporsi untuk tiga orientasi gambar:

  • Horizontal - lebar, tinggi, jenis penyelarasan
  • Vertikal - lebar, tinggi, jenis penyelarasan
  • Persegi - panjang sisi, jenis penyelarasan

SDK digunakan untuk mengambil konfigurasi template pratinjau, bukan untuk membuatnya.

Gunakan marker, bukan ID​

Referensikan template pratinjau dengan marker (identifier) di kode Anda - marker stabil di seluruh lingkungan. Gunakan getTemplatePreviewByMarker(marker) untuk satu template dan getTemplatePreviews() untuk semuanya.

TemplatePreviews vs Templates​

TemplatePreviews khusus untuk gambar atribut produk:

FiturTemplatePreviewsTemplates
TujuanPratinjau gambar atributTampilan konten umum
Kasus PenggunaanSwatch warna, pratinjau materialGambar hero, tata letak produk
LingkupHanya atribut produkHalaman, blok, produk

Praktik terbaik: Gunakan TemplatePreviews untuk gambar atribut, Templates untuk konten umum.

Caching​

Template pratinjau 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
getTemplatePreviews()Ambil semua template pratinjauDaftar semua template atribut yang tersedia
getTemplatePreviewByMarker()Ambil template pratinjau berdasarkan markerAmbil konfigurasi template tertentu

❓ Pertanyaan Umum (FAQ)​

Apa perbedaan antara TemplatePreviews dan Templates?​

TemplatePreviews khusus untuk gambar atribut produk (swatch warna, pratinjau material), sementara Templates menangani tampilan konten umum (halaman, blok, produk). Gunakan TemplatePreviews hanya untuk gambar yang spesifik untuk atribut.

Bagaimana cara mengonfigurasi ukuran yang berbeda untuk gambar horizontal, vertikal, dan persegi?​

Di panel admin, konfigurasikan ketiga orientasi untuk setiap template pratinjau. Sistem mendeteksi orientasi gambar dan menerapkan set proporsi yang sesuai (horizontal, vertical, atau square).

Dapatkah saya menetapkan template pratinjau yang berbeda untuk jenis atribut yang berbeda?​

Ya. Buat beberapa template pratinjau dengan marker yang berbeda (misalnya, color_swatch, material_preview, pattern_thumbnail) dan tetapkan masing-masing ke jenis atribut yang sesuai untuk rendering yang konsisten.

Bagaimana cara menerapkan template pratinjau ke gambar atribut?​

Ambil template melalui getTemplatePreviewByMarker() dan gunakan proportions-nya untuk merender gambar atribut dengan ukuran yang konsisten. Penetapan template ke jenis atribut dilakukan di panel admin.

🎓 Praktik Terbaik​

  • Gunakan marker, bukan ID - marker stabil di seluruh lingkungan.
  • Gunakan marker yang semantik - color_swatch, bukan preview_1.
  • Peta atribut ke template - simpan satu template per jenis atribut untuk konsistensi.
  • Cache template pratinjau - kurangi panggilan API untuk data yang jarang berubah.

🔗 Dokumentasi Terkait​