Nilai Atribut

Atribut adalah cara OneEntry menggambarkan konten: sebuah halaman, produk, blok, pengguna, pesanan, atau kolom formulir membawa peta nilai atribut yang dikunci oleh penanda. SDK menormalkan setiap atribut dari setiap respons ke bentuk yang sama, sehingga kolom yang sama terlihat sama tidak peduli modul mana yang mengembalikannya.

const page = await Pages.getPageByUrl('catalog');

page.attributeValues.title.value;   // "Catalog"        — string
page.attributeValues.amount.value;  // 5                — number
page.attributeValues.cover.value;   // { downloadLink } — the file object itself
page.attributeValues.notes.value;   // null             — no value set

Bentuk yang dinormalisasi

Nilai atribut adalah IAttributeValue: { type, value, position?, additionalFields? }. Apa yang dipegang oleh value tergantung pada type:

Tipe atribut	value
string, text	string
integer, float, real	number — dikonversi dari bentuk string API
image, file dengan satu file	objek file itu sendiri
image, file dengan beberapa file	array objek file
groupOfImages	selalu array — ini adalah koleksi berdasarkan definisi
list	array
timeInterval	array grup — lihat Time Intervals
tidak ada nilai yang ditetapkan	selalu null

Atribut file tunggal tidak dibongkar

Ketika atribut image atau file memegang tepat satu file, value-nya adalah objek file itu sendiri. Hanya nilai dengan dua atau lebih file yang tetap sebagai array.

const block = await Blocks.getBlockByMarker('promo');

// before: block.attributeValues.img.value[0].downloadLink
// now:    block.attributeValues.img.value.downloadLink

Ini berlaku di setiap modul. Sebelumnya, pembongkaran hanya terjadi di produk, menu, formulir, data-formulir, set atribut, koleksi integrasi, dan Pages.searchPage, dan hanya pada kunci attributeValues — di tempat lain (blok, semua metode halaman lainnya, Products.getProductsEmptyPage, Products.getProductBlockById, admins, diskon, template, pesanan, pengguna) atribut yang sama tiba sebagai array dengan satu elemen, sehingga konsumen harus bercabang berdasarkan bentuk. Atribut attributes, kolom data formulir, dan additionalFields bersarang tidak pernah dibongkar sama sekali.

⚠️ Migrasi: kode yang membaca value[0] dari produk atau menu tidak terpengaruh — modul-modul tersebut sudah mengembalikan objek. Kode yang membaca value[0] dari blok, halaman, pengguna, atau pesanan harus menghapus indeks.

groupOfImages adalah koleksi berdasarkan definisi dan selalu tetap sebagai array. Di sisi permintaan, IBodyTypeFile.value diketik IFileValue | IFileValue[] sesuai.

Angka adalah angka

Nilai integer, float, dan real dikonversi menjadi angka. real dulunya dibiarkan sebagai string, sehingga kolom numerik yang sama mencapai konsumen sebagai 10 atau sebagai "10" tergantung pada tipe mana dari ketiga tipe yang dinyatakan:

const page = await Pages.getPageByUrl('catalog');

// before: page.attributeValues.amount.value // "5"
// now:    page.attributeValues.amount.value // 5

Normalisasi numerik juga berjalan pada atribut formulir dan kolom data-formulir, yang sepenuhnya dilewati — kolom rating dari atribut formulir integer adalah number, bukan string.

Saat mengirim data, kirim sebagai string: IBodyTypeStringNumberFloat.value adalah string | number | null, dan respons kembali dinormalisasi.

Nilai kosong selalu null

API mengembalikan peta lokalisasi kosong untuk nilai yang tidak diatur. SDK dulunya meneruskannya untuk tipe seperti teks sementara tipe numerik menjadi null — keadaan "tidak ada nilai" yang sama memiliki tiga representasi. Sekarang selalu null.

if (page.attributeValues.notes.value === null) {
  // nothing configured for this attribute
}

⚠️ Migrasi: integer/float yang tidak diatur tidak lagi 0. Number(null) adalah 0, jadi null eksplisit dari API dulunya dilaporkan sebagai nol yang nyata — nilai yang tidak dapat dibedakan dari 0 yang dikonfigurasi.

Segalanya diurutkan berdasarkan posisi

attributeValues selalu dikembalikan dalam urutan position, dan atribut formulir sekarang juga demikian. API mengembalikan kolom formulir tanpa urutan — kolom dengan position: 10 bisa tiba setelah position: 14 — sehingga merender formulir dalam urutan CMS memerlukan pengurutan di sisi konsumen.

Sebuah formulir tanpa atribut mengembalikan attributes: []. API mengirim objek kosong dalam kasus itu, dan SDK menormalkannya menjadi array kosong, sehingga attributes selalu IFormAttribute[] dan form.attributes.map(...) aman pada setiap formulir.

Kolom bersarang: additionalFields

Nilai atribut bersarang tiba di bawah additionalFields. Secara default, SDK mengonversi array yang dikembalikan API menjadi objek yang dikunci oleh marker; atur rawData: true dalam konfigurasi untuk mempertahankan array asli — lihat Format Kolom Tambahan.

// default (rawData: false)
attribute.additionalFields['my_field'].value;

// rawData: true
attribute.additionalFields.find((f) => f.marker === 'my_field').value;

additionalFields bersarang melalui normalisasi yang sama seperti atribut tingkat atas — file tunggal dibongkar dan angka juga dikonversi di sana.

Mengetik nilai atribut

IAttributeValue.value diketik unknown, karena bentuknya tergantung pada type. Persempit sebelum digunakan — untuk atribut timeInterval, SDK menyediakan penjaga tipe:

import { isTimeIntervalAttribute } from 'oneentry';
import type { IAttributeValues } from 'oneentry';

function readText(values: IAttributeValues, marker: string): string {
  const value = values[marker]?.value;
  return typeof value === 'string' ? value : '';
}

---

🔗 Dokumentasi Terkait

• Time Intervals - memperluas atribut timeInterval menjadi slot
• Importing Types - IAttributeValue, IAttributeValues, dan yang lainnya
• AttributesSets Module - bagaimana atribut dikonfigurasi

---