Lewati ke konten utama

Pendahuluan

Ambil menu navigasi situs multi-level yang dibangun dari halaman yang dikonfigurasi di OneEntry.

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

🎯 Apa yang dilakukan modul ini?​

Modul Menus memungkinkan Anda mengambil struktur navigasi situs - menu header, menu footer, navigasi sidebar, menu mobile - dengan membangun navigasi multi-level secara dinamis dari halaman yang dikonfigurasi di OneEntry.

Anda membuat menu di panel admin OneEntry (menghubungkan halaman bersama) dan modul ini mengambil pohon menu lengkap, sehingga Anda dapat merender navigasi secara dinamis tanpa mengkodekan tautan secara langsung. SDK ini bersifat hanya-baca untuk menu - Anda mengambilnya, Anda tidak membuatnya melalui kode.

🚀 Memulai dengan Cepat​

Inisialisasi modul dari defineOneEntry:


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

Ambil menu berdasarkan penandanya dan telusuri halamannya:

// Fetch the "main_menu" structure in English.
const menu = await Menus.getMenusByMarker("main_menu", "en_US");

console.log(menu.identifier, menu.localizeInfos.title);

// Top-level items; nested items live in each item's children[].
menu.pages.forEach((item) => {
  console.log(item.pageUrl, item.localizeInfos.title, item.children);
});

✨ Konsep Kunci​

Apa itu Menu?​

Menu (IMenusEntity) adalah struktur navigasi yang menghubungkan halaman-halaman bersama:

  • identifier - penanda menu (misalnya, "main_menu")
  • localizeInfos - judul menu yang dilokalisasi
  • pages - array item menu (setiap item adalah sebuah halaman)

Struktur Item Menu​

Setiap item dalam pages adalah objek IMenusPages:

{
  id: 123,                       // Page ID
  pageUrl: "home",               // Page URL (marker)
  localizeInfos: { title: "Home" },
  attributeValues: {},           // Custom attribute values
  parentId: null,                // null for top-level items
  parentType: null,              // "page" | "custom" | null - kind of the parent
  itemType: "page",              // "page" | "custom" - kind of this item
  position: 1,                   // Display order
  children: []                   // Nested menu items
}

Hierarki Menu​

Menu mendukung struktur bersarang. Penyusunan bersarang dinyatakan melalui array children[] dari setiap item bersama dengan parentId-nya (item tingkat atas memiliki parentId: null). Tidak ada field kedalaman terpisah - Anda menentukan kedalaman dengan menelusuri children[].

📂 Header Menu
├─ Home (parentId: null)
├─ About (parentId: null)
│  ├─ Team (parentId: 2)
│  └─ History (parentId: 2)
├─ Products (parentId: null)
│  └─ Electronics (parentId: 4)
│     ├─ Phones (parentId: 5)
│     └─ Laptops (parentId: 5)
└─ Contact (parentId: null)

Dua jenis item menu: itemType dan parentType​

Sebuah menu memiliki dua jenis item - halaman menu dan item kustom - dan id mereka berasal dari urutan yang berbeda, sehingga mereka tumpang tindih: parentId: 5 saja tidak mengatakan apakah orang tua adalah halaman dengan id 5 atau item kustom dengan id 5.

Dua field menyelesaikan itu:

  • itemType ('page' | 'custom') - apa item ini sendiri.
  • parentType ('page' | 'custom' | null) - apa orang tuanya. null bersama dengan parentId: null berarti item tersebut adalah tingkat atas.

Anak-anak dari sebuah item membawa itemType-nya sebagai parentType mereka, jadi cocokkan pada pasangan saat Anda membangun kembali pohon itu sendiri:

const childrenOf = (items, parent) =>
  items.filter(
    (item) => item.parentId === parent.id && item.parentType === parent.itemType,
  );

📋 Apa yang Perlu Anda Ketahui​

Anda tidak dapat membuat menu melalui SDK - mereka dibuat di panel admin OneEntry (Menus → Create Menu → Add Pages → Save) atau melalui Admin API. SDK ini digunakan untuk mengambil struktur menu.

Item menu adalah halaman​

Setiap item menu adalah sebuah halaman yang dikonfigurasi di OneEntry - Anda tidak dapat menambahkan tautan sembarangan. Untuk menambahkan tautan eksternal, buat halaman dengan URL eksternal di modul Halaman dan tambahkan ke menu.

Urutkan berdasarkan posisi​

Item membawa field position - urutkan berdasarkan itu untuk menghormati urutan tampilan yang dikonfigurasi di panel admin.

Multi-bahasa​

Menu dilokalisasi berdasarkan langCode yang diteruskan ke getMenusByMarker() (kembali ke bahasa yang diatur di defineOneEntry()). Ambil menu dalam bahasa yang disukai pengguna.

📊 Tabel Referensi Cepat​

MetodeDeskripsiKasus Penggunaan
getMenusByMarker()Ambil menu berdasarkan penandaAmbil struktur menu tertentu

❓ Pertanyaan Umum (FAQ)​

Bagaimana cara membuat menu multi-level (dropdown)?​

Bangun pohon menu di panel admin dengan menyusun halaman. Penyusunan dikembalikan melalui array children[] dari setiap item - render secara rekursif.

Bisakah saya menambahkan tautan eksternal ke menu?​

Item menu harus merupakan halaman yang dikonfigurasi di OneEntry. Untuk menambahkan tautan eksternal, buat halaman dengan URL eksternal di modul Halaman, lalu tambahkan ke menu Anda.

Bagaimana cara menangani status item menu aktif?​

Bandingkan URL halaman saat ini dengan pageUrl dari setiap item dan terapkan kelas aktif saat mereka cocok.

Bagaimana cara membangun breadcrumbs?​

Lacak dari halaman saat ini melalui hubungan parentId (Beranda > Kategori > Subkategori > Halaman Saat Ini).

Bisakah saya memiliki menu yang berbeda untuk bagian yang berbeda?​

Ya - buat beberapa menu dengan penanda yang berbeda (misalnya, header_menu, footer_menu, sidebar_menu) dan ambil masing-masing dengan getMenusByMarker().

🎓 Praktik Terbaik​

  • Gunakan penanda, bukan ID - penanda stabil di seluruh lingkungan.
  • Render children[] secara rekursif - itulah cara penyusunan diwakili.
  • Urutkan berdasarkan position - hormati urutan tampilan yang dikonfigurasi.
  • Cache menu - mereka jarang berubah.
  • Terapkan langCode - ambil menu dalam bahasa pengguna.
  • Tangani menu yang hilang dengan baik - sediakan fallback saat penanda tidak ditemukan.

🔗 Dokumentasi Terkait​