Lewati ke konten utama

Pendahuluan

Ambil label status produk ("Baru", "Diskon", "Habis") untuk badge dan memfilter item katalog.

Informasi lebih lanjut tentang status produk di panel admin OneEntry: https://doc.oneentry.cloud/docs/category/catalog

🎯 Apa yang dilakukan modul ini?​

Modul ProductStatuses menyediakan kondisi penyaringan tambahan untuk item katalog di samping filter berbasis atribut. Status Produk memungkinkan Anda untuk membuat label kustom - seperti "Kedatangan Baru", "Penjual Terbaik", "Diskon", "Habis" - untuk badge, mengorganisir, dan memfilter produk dalam katalog e-commerce Anda.

Anda mendefinisikan label status di panel admin OneEntry (Katalog > Status Produk), menetapkannya ke produk, dan menggunakan modul ini untuk mengambil status dan memfilter produk berdasarkan status tersebut. SDK bersifat read-only: Anda tidak dapat membuat status melalui SDK ini.

🚀 Memulai dengan Cepat​

Inisialisasi modul dari defineOneEntry:


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

Ambil semua status dan baca field-nya:

// Fetch every product status, localized to English.
const statuses = await ProductStatuses.getProductStatuses("en_US");

statuses.forEach((status) => {
  console.log(status.identifier, status.localizeInfos.title, status.isDefault);
});

// Or fetch a single status by its marker.
const sale = await ProductStatuses.getProductsByStatusMarker("sale", "en_US");
console.log(sale.localizeInfos.title); // "Sale"

✨ Konsep Kunci​

Apa itu Status Produk?​

Status Produk (IProductStatusEntity) adalah label/tag kustom untuk produk:

  • Nama Status (localizeInfos) - Nama tampilan yang dilokalisasi (misalnya, "Kedatangan Baru", "Diskon")
  • Penanda Status (identifier) - Identifikasi unik yang digunakan untuk memfilter
  • Tanda default (isDefault) - Apakah ini adalah status default
  • Posisi (position) - Urutan tampilan

Alur Kerja Status Produk​

1. Create status in admin panel
   (e.g., "New Arrival")
   ↓
2. Assign status to products
   (Select products in admin)
   ↓
3. Fetch statuses via SDK
   (ProductStatuses.getProductStatuses())
   ↓
4. Display status badges on products
   (Render badges in product listings)
   ↓
5. Filter products by status marker
   (Products.getProducts([{ statusMarker }], langCode))

📋 Apa yang Perlu Anda Ketahui​

Status dibuat di panel admin​

Anda tidak dapat membuat status melalui SDK - status dibuat di panel admin OneEntry (Katalog > Status Produk). Setiap status memerlukan Nama (wajib) dan Penanda yang unik (wajib).

Keterbatasan Penanda:

  • Hanya huruf Latin (a-z, A-Z) dan angka (0-9)
  • Garis bawah (_) dan tanda hubung (-) diperbolehkan
  • Tidak ada spasi atau karakter khusus
  • Harus unik di seluruh status

SDK digunakan untuk mengambil status dan memfilter produk, bukan untuk membuat status.

Satu status per produk​

Sebuah produk merujuk paling banyak satu status. Objek produk membawa statusIdentifier (penanda status, atau null):

const product = await Products.getProductById(123);
console.log(product.statusIdentifier); // "in_stock" - status marker, or null

Memfilter berdasarkan status​

Untuk memfilter produk berdasarkan status, gunakan metode getProducts(body, langCode, userQuery) dari modul Produk. Kirim field statusMarker di dalam array body IFilterParams untuk mengambil produk dengan status tertentu.

Memvalidasi penanda​

validateMarker(marker) mengembalikan true jika penanda ada dan false jika tidak. Karena SDK tidak dapat membuat status, gunakan untuk memverifikasi penanda sebelum merujuknya dalam kode Anda.

Status vs atribut​

ProductStatuses berbeda dari atribut produk:

FiturProductStatusesAtribut
TujuanLabel/badge/filterProperti produk
Contoh"Baru", "Diskon", "Unggulan"Warna, Ukuran, Material
Per produkSatu statusBanyak atribut
MemfilterSederhana (berdasarkan penanda status)Kompleks (rentang, nilai)
Kasus penggunaanLabel pemasaranSpesifikasi produk

Praktik terbaik: Gunakan status untuk label pemasaran, atribut untuk properti produk.

📊 Tabel Referensi Cepat​

MetodeDeskripsiKasus Penggunaan
getProductStatuses()Ambil semua status produkDaftar semua status yang tersedia
getProductsByStatusMarker()Ambil status produk berdasarkan penandaAmbil status berdasarkan identifikasi
validateMarker()Periksa apakah penanda adaValidasi penanda sebelum digunakan

❓ Pertanyaan Umum (FAQ)​

Apa perbedaan antara status produk dan atribut produk?​

Status produk adalah label pemasaran (Baru, Diskon, Unggulan) untuk memfilter dan memberi badge, sementara atribut adalah spesifikasi produk (Warna, Ukuran, Material). Gunakan status untuk tag promosi dan atribut untuk properti produk.

Dapatkah sebuah produk memiliki beberapa status sekaligus?​

Tidak. Sebuah produk merujuk paling banyak satu status, yang ditampilkan sebagai statusIdentifier (penanda status) pada objek produk.

Bagaimana cara memfilter produk berdasarkan status?​

Gunakan metode getProducts(body, langCode, userQuery) dari modul Produk. Kirim field statusMarker di dalam array body IFilterParams untuk mengambil produk dengan status tertentu.

Bagaimana cara memeriksa apakah penanda status ada?​

Gunakan validateMarker() - ini mengembalikan true jika penanda ada dan false jika tidak. SDK tidak dapat membuat status; penanda didefinisikan di panel admin mengikuti konvensi penamaan (hanya huruf Latin, angka, garis bawah, tanda hubung).

Dapatkah saya mengubah urutan status yang ditampilkan?​

Ya. Di panel admin, Anda dapat menyeret dan menjatuhkan status untuk mengubah urutannya. Ini mempengaruhi field position, yang menentukan urutan tampilan di aplikasi Anda.

Bagaimana cara menambahkan gaya kustom ke badge status?​

Ambil semua status, lalu peta penanda status ke kelas CSS atau gaya inline dalam kode frontend Anda. Terapkan gaya ini saat merender badge produk berdasarkan statusIdentifier produk.

🎓 Praktik Terbaik​

  • Gunakan penanda yang deskriptif - kedatangan_baru, bukan status1.
  • Validasi sebelum merujuk - panggil validateMarker() sebelum menghardcode penanda.
  • Render badge status - tampilkan badge statusIdentifier produk dalam daftar.
  • Cache status - status jarang berubah, jadi cache untuk kinerja.

🔗 Dokumentasi Terkait​