Menu dan fragment

Apa itu menu dan fragment

Menu adalah pohon tautan, seperti navigasi utama atau tautan footer. Fragment adalah pohon block yang dipakai banyak halaman, seperti header, footer, atau banner atas. Keduanya disimpan per bahasa, jadi header dalam id dan header dalam en adalah dua record.

Keduanya berlaku untuk seluruh situs. Perubahannya tidak terikat pada satu halaman dan tidak pada satu revisi, sehingga tidak ada langkah draf. Menyimpan menu atau fragment langsung mengubah output yang tayang. Karena itu menulis butuh publisher (atau admin). Siapa pun yang menjadi anggota brand boleh membacanya.

Menu

Menampilkan semua menu brand, diurutkan menurut key dan bahasa.

Mengganti seluruh pohon sebuah menu, atau membuatnya. locale harus bahasa milik brand, jika tidak jawabannya 404. key adalah nama bebas, dan tema bisa mendeklarasikan key yang direndernya di menuLocations.

{
  "items": [
    {
      "label": "Products",
      "url": "/products",
      "eyebrow": "Catalogue",
      "key": "products",
      "children": [
        {
          "label": "Spare parts",
          "description": "Screens, batteries and chargers",
          "children": [
            { "label": "Screens", "url": "/products/screens" }
          ]
        }
      ]
    },
    { "label": "Contact", "url": "/contact" }
  ]
}

Field item

Setiap item, di kedalaman mana pun, menerima field berikut. Key lain dibuang.

Teks biasa berarti tanpa HTML. Satu pohon memuat paling banyak 500 item, termasuk anak-anaknya.

Kedalaman dan tautan tidak aman

Menu bersarang paling dalam tiga tingkat (item atas, tab, tier). Jika tema aktif mendeklarasikan maxDepth yang lebih kecil untuk key menu itu di menuLocations, angka yang lebih kecil yang berlaku. Pohon yang lebih dalam dijawab 422 pada items.

Tautan harus berupa alamat web, tautan email atau telepon, atau path di situs. Selain itu, seperti alamat javascript:, ditolak dan galatnya menyebut item yang tepat sehingga editor bisa menampilkannya pada field:

{ "errors": { "items.0.children.1.url": ["Must be a web address, an email or phone link, or a path on this site."] } }

Membaca menu di situs Anda

curl -s "https://api.atlascms.id/v1/public/menus/header?locale=en" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Jika menu belum ada pada bahasa yang diminta, API mengembalikan menu bahasa default. Jika keduanya tidak ada, jawabannya 404. Item dengan media_id kembali bersama image: { url, alt, width, height }, dengan teks alt dalam bahasa menu lalu bahasa default. Jika file sudah hilang, image bernilai null.

DELETE /v1/manage/menus/{menu} menghapus menu (publisher). File media yang dipakai sebuah menu tidak bisa dihapus sampai menu itu berhenti memakainya.

Fragment

{
  "blocks": [
    { "id": "h1", "type": "acme-header", "v": 1, "props": {} }
  ],
  "published": true
}

Key yang umum adalah header, footer, dan banner. blocks adalah pohon block yang diperiksa seperti pohon lain (tiga tingkat, tautan aman, prop terhadap definisi block). Fragment tidak pernah memuat block atlas-post-content, karena ia tampil di banyak halaman dan tidak punya isi entri tunggal. published: false menyimpan block tanpa membuatnya tayang. Part tanpa override tayang akan kembali ke bawaan yang dibawa paket tema.

Situs Anda tidak memanggil endpoint fragment. Payload halaman dari GET /v1/public/page membawa fragments, dengan key area (header, footer, banner). Jika sebuah bahasa tidak punya fragment, bahasa default mengisi kekosongannya.

DELETE /v1/manage/fragments/{fragment} menghapus satu fragment (publisher).

Fragment adalah part template

Fragment adalah alias dari part template milik tema aktif. Endpoint di atas menulis override yang sama seperti sebuah part, dan menyimpan record fragment lama sebagai cermin, sehingga situs yang membaca fragments tetap berjalan. Alias ini bertahan selama dua versi minor. Pekerjaan baru sebaiknya memakai endpoint part, yang juga memberi draf sebelum diterbitkan:

Sisi tema dijelaskan di Pengembangan tema.

Bagaimana perubahan sampai ke situs yang tayang

Setiap penyimpanan menu atau fragment menjalankan langkah yang sama:

1. Perubahan disimpan dan baris audit ditulis (menu.updated, menu.deleted, fragment.updated, fragment.deleted).
2. Versi konten brand naik. API publik membangun ETag dari versi itu, sehingga klien dan cache langsung melihat jawaban baru.
3. Webhook purge bertanda tangan diantrekan ke setiap webhook aktif milik brand. paths-nya ["*"], karena menu atau fragment bisa muncul di setiap halaman.

Situs Anda memeriksa tanda tangan, membuang halaman dari cache-nya, dan pengunjung berikutnya mendapat header baru. Lihat Webhook dan purge untuk header dan contoh verifikasi.

Menu tidak punya draf

Menu tidak punya draf atau jadwal. Jika perlu menyiapkan navigasi baru lebih dulu, bangun di bawah key lain, lalu alihkan situs Anda untuk membaca key itu.

Menyimpan berarti mengganti pohon

PUT mengirim seluruh menu. Baca dulu dengan GET /v1/manage/menus, ubah item yang perlu, lalu kirim kembali seluruh pohonnya.