Lewati ke konten utama

Pengantar

Blok konten yang dapat digunakan kembali yang dapat digunakan di berbagai halaman.

Informasi lebih lanjut tentang antarmuka pengguna modul https://doc.oneentry.cloud/docs/category/blocks

🎯 Apa yang dilakukan modul ini?​

Modul Blocks memungkinkan Anda mengambil komponen konten yang dapat digunakan kembali (blok) — sekumpulan atribut yang Anda buat sekali di panel admin dan gunakan kembali di halaman dan halaman produk: header, footer, spanduk, testimoni, slider, dan widget produk/rekomendasi. Perbarui sebuah blok sekali dan itu akan berubah di mana pun ia digunakan.

SDK bersifat hanya-baca: Anda mengambil blok di sini dan membuat atau mengeditnya di panel admin OneEntry.

🚀 Memulai dengan Cepat​

Inisialisasi modul dari defineOneEntry:


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

Ambil satu blok berdasarkan penandanya dan baca atributnya:

// Fetch the "footer" block.
const block = await Blocks.getBlockByMarker("footer", "en_US");

console.log(block.identifier, block.type, block.isVisible);
// "footer" "common_block" true

// Custom fields live in attributeValues.
console.log(block.attributeValues);

✨ Konsep Kunci​

Apa itu Blok?​

Sebuah blok adalah komponen konten yang dapat digunakan kembali yang berisi:

  • identifier — penanda unik yang digunakan untuk merujuknya dalam kode (selalu gunakan penanda; itu tidak pernah berubah)
  • localizeInfos — data yang dilokalisasi (misalnya title), konten yang berbeda per bahasa
  • type — BlockType yang menentukan apa yang dirender oleh blok
  • isVisible — bendera visibilitas
  • attributeValues — bidang kustom yang Anda definisikan melalui AttributesSets

Struktur Blok​

{
  id: 3, // unique ID
  localizeInfos: { // block localized data
    title: 'Block', // block localized title
  },
  version: 0, // block version
  position: 1, // block position in array of blocks
  identifier: 'block', // block identifier (marker)
  type: 'common_block', // block type
  templateIdentifier: null, // template identifier
  isVisible: true, // visibility
  attributeValues: {}, // block attributes
}

📋 Apa yang Perlu Anda Ketahui​

  • Rujuk blok berdasarkan penanda (identifier) dalam kode — penanda tidak pernah berubah.
  • Blok dibuat di panel admin. SDK bersifat hanya-baca.
  • Bidang kustom berasal dari AttributesSets. Contoh: blok footer (hak cipta, tautan sosial, informasi kontak), spanduk hero (judul, CTA, gambar latar), testimoni (penulis, foto, kutipan, penilaian).
  • Blok vs. Halaman. Sebuah halaman adalah dokumen mandiri dengan URL (misalnya /about) yang dibuat di modul Halaman; sebuah blok adalah komponen yang dapat digunakan kembali yang Anda masukkan ke dalam halaman.

📊 Tabel Referensi Cepat - Metode Umum​

MetodeApa yang DilakukanKapan Digunakan
getBlocks()Mendapatkan semua blok (terpaginated, terfilter)Daftar semua blok yang tersedia
getBlockByMarker()Mendapatkan blok berdasarkan penandaAmbil blok tertentu dalam kode
searchBlock()Mencari blokAmbil blok
getFrequentlyOrderedProducts()Produk yang sering dipesan"Sering dipesan bersama"
getCartComplement()"Lengkapi keranjang Anda" berdasarkan konteks keranjangPenjualan silang dari keranjang
getCartComplementByProductIds()"Lengkapi keranjang Anda" berdasarkan productIdsPenjualan silang untuk produk tertentu
getCartSimilar()"Mirip dengan keranjang" berdasarkan konteks keranjangAlternatif untuk item keranjang
getCartSimilarByProductIds()"Mirip dengan keranjang" berdasarkan productIdsAlternatif untuk produk tertentu
getWishlistSimilar()"Mirip dengan wishlist" berdasarkan wishlistAlternatif untuk item wishlist
getWishlistSimilarByProductIds()"Mirip dengan wishlist" berdasarkan productIdsAlternatif untuk produk tertentu
getPersonalRecommendations()Rekomendasi pribadiUmpan produk yang dipersonalisasi
getRecentlyViewed()Produk yang baru saja dilihatWidget "Baru saja dilihat"
getRepeatPurchase()Produk untuk pembelian ulangWidget "Beli lagi"
getTrending()Produk yang sedang trenWidget "Sedang tren sekarang"
getSlides()Pohon slide blok sliderRender slider/karusel

🧩 Jenis Blok​

type blok ( BlockType) menentukan apa yang dirender. Selain jenis dasar (common_block, product_block, similar_products_block, form, dan lainnya), jenis blok produk & personalisasi berikut tersedia:

Jenis blokMetode
frequently_ordered_blockgetFrequentlyOrderedProducts()
trending_blockgetTrending()
recently_viewed_blockgetRecentlyViewed()
repeat_purchase_blockgetRepeatPurchase()
slider_blockgetSlides()
personal_recommendations_blockgetPersonalRecommendations()
cart_complement_blockgetCartComplement() / getCartComplementByProductIds()
cart_similar_blockgetCartSimilar() / getCartSimilarByProductIds()
wishlist_similar_blockgetWishlistSimilar() / getWishlistSimilarByProductIds()

Blok personalisasi (baru saja dilihat, pembelian ulang, rekomendasi pribadi, keranjang/wishlist) didorong oleh aktivitas pengguna yang dilacak dan bekerja untuk pengguna yang terotorisasi maupun tamu (lihat Mode Tamu).

Memperbaiki harga (signPrice)​

Metode blok produk & rekomendasi (getCartSimilar, getRecentlyViewed, getTrending, getPersonalRecommendations, getRepeatPurchase, getCartComplement, getFrequentlyOrderedProducts, …) menerima argumen signPrice opsional. Ini mengambil penanda penyimpanan pesanan dan meminta server untuk mengunci harga produk yang dikembalikan untuk waktu terbatas, sehingga harga yang dilihat pelanggan dalam widget rekomendasi adalah harga yang mereka bayar saat checkout.

signPrice — tipe string

Penanda penyimpanan pesanan untuk memperbaiki harga. Jika parameter diatur, harga akan tetap untuk waktu tertentu.

  • Pada metode rekomendasi signPrice adalah argumen posisi terakhir (setelah langCode).
  • Pada varian …ByProductIds (getCartSimilarByProductIds, getCartComplementByProductIds, …) itu adalah bidang dari body permintaan (body.signPrice).

Setiap produk yang dikembalikan kemudian membawa token signedPrice yang mengenkripsi harga yang terkunci:


const products = await Blocks.getCartSimilar("cart_similar_block", "en_US", "orders");

const signedPrice = products[0].signedPrice;

➡️ Gunakan kembali token itu saat membuat pesanan — lihat bagian Harga produk tetap (signedPrice) dari modul Pesanan. Parameter perbaikan harga yang sama juga ada di modul Produk (dalam userQuery.signPrice).

❓ Pertanyaan Umum (FAQ)​

Apa perbedaan antara Blocks dan Pages?​

  • Halaman/Halaman Produk — halaman mandiri dengan URL (misalnya /about) yang dibuat di modul Halaman, di mana Anda menambahkan blok dan komponen lainnya.
  • Blok — komponen yang dapat digunakan kembali yang dimasukkan ke dalam halaman (misalnya footer).

Anggaplah sebuah halaman sebagai dokumen penuh dan sebuah blok sebagai paragraf yang Anda gunakan kembali di berbagai dokumen.

Bagaimana cara memperbarui konten blok?​

Edit di panel admin OneEntry (bagian Blocks). Semua halaman yang menggunakan blok itu akan diperbarui secara otomatis.

Haruskah saya membuat banyak blok kecil atau sedikit blok besar?​

Lebih baik banyak blok kecil yang terfokus (misalnya header_logo, footer_social_links) daripada satu blok besar entire_page_layout — blok kecil lebih mudah digunakan kembali dan dipelihara.

Bagaimana cara menampilkan/menyembunyikan blok secara kondisional?​

Periksa bidang isVisible pada blok yang diambil.

Bagaimana cara menangani blok yang hilang dengan baik?​

Bungkus pengambilan dalam try/catch dan render fallback ketika blok tidak ditemukan.

🎓 Praktik Terbaik​

  • Buat blok kecil yang terfokus (tanggung jawab tunggal).
  • Gunakan penanda deskriptif (global_footer, bukan block1); huruf kecil dengan garis bawah.
  • Rujuk blok berdasarkan penanda dalam kode — penanda tidak pernah berubah.
  • Cache blok — mereka jarang berubah.
  • Tangani blok yang hilang dengan baik (try/catch).

🔗 Dokumentasi Terkait​