Pendahuluan

Tentukan bidang kustom untuk konten Anda tanpa menyentuh kode.

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

---

🎯 Apa yang dilakukan modul ini?

Modul AttributesSets memungkinkan Anda membaca definisi bidang kustom (set atribut) yang digunakan oleh konten Anda - produk, halaman, formulir, blok, dan lainnya. Set atribut adalah skema yang menggambarkan bidang apa yang dimiliki suatu entitas dan jenis apa masing-masing bidang; Anda mendefinisikannya di panel admin OneEntry dan mengambil strukturnya dengan modul ini.

Catatan: set atribut menggambarkan skema, bukan nilai. Nilai aktual berada pada entitas itu sendiri (halaman, produk, dll.) di bawah attributeValues. Satu pengecualian adalah tipe timeInterval, yang dapat membawa nilai - lihat contoh di bawah.

🚀 Memulai dengan Cepat

Inisialisasi modul dari defineOneEntry:

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

Ambil atribut yang didefinisikan dalam satu set dan baca penanda serta jenisnya:

// Get every attribute in the "productAttributes" set.
const attributes = await AttributesSets.getAttributesByMarker(
  "productAttributes",
  "en_US",
);

attributes.forEach((attr) => {
  console.log(attr.marker, attr.type, attr.localizeInfos.title);
});

✨ Konsep Kunci

Atribut, Set Atribut, Nilai

Istilah	Apa Itu	Contoh
Atribut	Definisi bidang tunggal (penanda + jenis)	price (float)
Set Atribut	Kumpulan atribut - skema entitas	Set "Produk"
Nilai	Data yang disimpan entitas untuk atribut	19.99 pada produk tertentu

Set atribut mengelompokkan atribut menjadi skema yang dapat digunakan kembali. Set yang sama dapat dilampirkan ke beberapa entitas, sehingga mengubah set mengubah bidang yang tersedia di mana pun ia digunakan.

Penanda

Penanda adalah pengidentifikasi teknis yang Anda gunakan dalam kode (misalnya, product_name). Ini dipetakan ke judul yang dapat dibaca manusia yang ditampilkan di panel admin.

product.attributeValues.product_name; // "product_name" is the marker

Aturan penanda:

• Harus unik
• Tidak boleh ada spasi (gunakan _)
• Tidak boleh dimulai dengan angka
• Gunakan huruf kecil untuk konsistensi

✅ Baik: product_name, price_usd, main_image — ❌ Buruk: product name, 2nd_price, Product Name

📋 Apa yang Perlu Anda Ketahui

Set atribut bersama

Jika set atribut digunakan oleh beberapa entitas, perubahan akan menyebar ke semuanya:

• Menambahkan atribut - akan muncul di setiap entitas yang menggunakan set; konten yang ada mempertahankan nilainya dan bidang baru dimulai kosong.
• Menghapus atribut - akan dihapus dari setiap entitas yang menggunakan set, dan nilai yang ada akan dihapus secara permanen.

Anda tidak dapat menghapus atribut saat masih digunakan dalam set atribut.

Validator

Atribut dapat membawa validator untuk menegakkan kualitas data - bidang yang diperlukan, panjang min/maks, batas ukuran file, dimensi piksel gambar, rentang tanggal, dan nilai default. Konfigurasi validator dikembalikan pada setiap atribut di bawah validators.

Klik untuk melihat contoh validator

• requiredValidator: mengharuskan nilai untuk dimasukkan.

{
  "type": "string",
  "value": {},
  "marker": "string",
  "position": 1,
  "listTitles": [],
  "validators": {
    "requiredValidator": {
      "strict": true
    }
  },
  "localizeInfos": {
    "title": "Currency"
  },
  "additionalFields": {
    "extra": {
      "type": "integer",
      "value": "10",
      "marker": "extra"
    }
  }
}

---

• defaultValueValidator: menyediakan nilai default untuk bidang.

{
  "type": "string",
  "value": {},
  "marker": "string",
  "position": 1,
  "listTitles": [],
  "validators": {
    "defaultValueValidator": {
      "customErrorText": "Custom error",
      "fieldDefaultValue": "usd",
      "fieldDefaultValue2": ""
    }
  },
  "localizeInfos": {
    "title": "String"
  },
  "additionalFields": {
    "extra": {
      "type": "integer",
      "value": "10",
      "marker": "extra"
    }
  }
}

---

Pelajari lebih lanjut: Lihat Validators untuk konfigurasi yang lebih rinci.

Atribut bersarang

Anda dapat melampirkan bidang tambahan ke atribut melalui Additional Fields (dikembalikan di bawah additionalFields).

---

📊 Tabel Referensi Cepat - Metode Umum

Metode	Apa yang Dilakukan
getAttributes()	Mendapatkan semua objek set atribut.
getAttributesByMarker()	Mendapatkan semua atribut dari satu set, dengan data dari set atribut.
getAttributeSetByMarker()	Mendapatkan satu objek set atribut berdasarkan penanda.
getSingleAttributeByMarkerSet()	Mendapatkan satu atribut (dengan data set) berdasarkan penanda set dan penanda atribut.

---

📚 Tipe Data yang Tersedia

Setiap atribut memiliki type. Pilih tipe yang tepat untuk setiap bidang.

Tipe	Terbaik Untuk	Contoh Penggunaan
string	Teks pendek (< 255 karakter)	Nama produk, email
text	Teks panjang yang diformat	Postingan blog, deskripsi
textWithHeader	Teks dengan judul	Bagian artikel
integer	Angka bulat	Kuantitas, usia
real	Desimal presisi tinggi	Data ilmiah
float	Angka desimal	Harga, penilaian
date	Hanya tanggal	Tanggal lahir, tenggat waktu
dateTime	Tanggal + waktu	Waktu mulai, diterbitkan pada
time	Hanya waktu	Jam buka
file	File apa pun	PDF, dokumen
image	Gambar tunggal	Avatar, logo
groupOfImages	Beberapa gambar	Galeri foto
radioButton	Pilihan tunggal	Ukuran (S/M/L)
list	Pilihan dropdown	Negara, kategori
button	Tindakan interaktif	Kirim formulir, CTA
spam	Perlindungan spam formulir	Bidang honeypot anti-bot
entity	Tautan ke konten lain	Produk terkait
timeInterval	Rentang tanggal/waktu	Jadwal, periode promosi

Memilih tipe

• Teks: string (satu baris), text (paragraf terformat), textWithHeader (teks dengan judul).
• Angka: integer (tanpa desimal), float (desimal standar), real (presisi ekstra).
• Tanggal/waktu: date, time, dateTime, atau timeInterval (rentang/jadwal).
• File/gambar: file (dokumen apa pun), image (satu gambar), groupOfImages (galeri).
• Pilihan: radioButton (pilih satu), list (dropdown).
• Lanjutan: entity (tautan ke halaman/produk lain), button (tindakan interaktif), spam (perlindungan bot).

---

📖 Contoh Tipe Data

Berikut adalah contoh teknis dari struktur setiap tipe data yang dikembalikan oleh API.

💡 Data yang dikembalikan dalam set atribut tidak mencakup nilai atribut aktual - nilai tersebut berada pada entitas tertentu (halaman, produk, dll.). Satu-satunya pengecualian adalah timeInterval, yang dapat membawa nilai ketika kotak yang sesuai dicentang di panel admin.

Klik untuk melihat semua contoh tipe data

Referensi Tipe Data

• String: Teks sederhana, misalnya, "Halo, dunia!".

{
  "type": "string",
  "value": {},
  "marker": "string",
  "position": 1,
  "listTitles": [],
  "validators": {
    "requiredValidator": {
      "strict": true
    }
  },
  "localizeInfos": {
    "title": "String"
  },
  "additionalFields": {
    "Extra": {
      "type": "integer",
      "value": "10",
      "marker": "Extra"
    }
  }
}

---

• Text: Teks yang lebih panjang, sering diformat, misalnya, artikel atau surat.

{
  "type": "text",
  "value": {},
  "marker": "text",
  "position": 2,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Text"
  },
  "additionalFields": {}
}

---

• Text dengan Header: Teks dengan header yang dapat digunakan untuk menunjukkan topik atau kategori.

{
  "type": "textWithHeader",
  "value": {},
  "marker": "text_with_header",
  "position": 3,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Text With Header"
  },
  "additionalFields": {}
}

---

• Integer: Sebuah integer, misalnya, 5, 100, -2.

{
  "type": "integer",
  "value": {},
  "marker": "integer",
  "position": 4,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Integer"
  },
  "additionalFields": {}
}

---

• Real: Sama dengan Float, tetapi dengan presisi lebih tinggi.

{
  "type": "real",
  "value": {},
  "marker": "real_number",
  "position": 5,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Real Number"
  },
  "additionalFields": {}
}

---

• Float: Angka floating-point yang dapat memiliki bagian desimal, misalnya, 3.14, 1.5, -0.25.

{
  "type": "float",
  "value": {},
  "marker": "float",
  "position": 6,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Float"
  },
  "additionalFields": {}
}

---

• Tanggal dan Waktu: Kombinasi tanggal dan waktu, misalnya, 2023-10-27 10:00:00.

{
  "type": "dateTime",
  "value": {},
  "marker": "date_time",
  "position": 7,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "DateTime"
  },
  "additionalFields": {}
}

---

• Tanggal: Sebuah tanggal, misalnya, 2023-10-27.

{
  "type": "date",
  "value": {},
  "marker": "date",
  "position": 8,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Date"
  },
  "additionalFields": {}
}

---

• Waktu: Sebuah waktu, misalnya, 10:00:00.

{
  "type": "time",
  "value": {},
  "marker": "time",
  "position": 9,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Time"
  },
  "additionalFields": {}
}

---

• File: File apa pun, misalnya, dokumen, gambar, musik.

{
  "type": "file",
  "value": {},
  "marker": "file",
  "position": 10,
  "listTitles": [],
  "validators": {
    "checkingFilesValidator": {
      "maxUnits": "kb",
      "maxValue": "2000",
      "minUnits": "kb",
      "minValue": 0,
      "extensions": []
    }
  },
  "localizeInfos": {
    "title": "File"
  },
  "additionalFields": {}
}

---

• Gambar: Sebuah gambar, misalnya, foto atau gambar.

{
  "type": "image",
  "value": {},
  "marker": "image",
  "position": 11,
  "listTitles": [],
  "validators": {
    "sizeInPixelsValidator": {
      "maxX": "500",
      "maxY": "500"
    }
  },
  "localizeInfos": {
    "title": "Image"
  },
  "additionalFields": {}
}

---

• Kumpulan Gambar: Kumpulan gambar, misalnya, album foto.

{
  "type": "groupOfImages",
  "value": {},
  "marker": "image_group",
  "position": 12,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Image Group"
  },
  "additionalFields": {}
}

---

• Radio Button: Sebuah pilihan dari mana hanya satu opsi yang dapat dipilih.

{
  "type": "radioButton",
  "value": {},
  "marker": "radio",
  "position": 13,
  "listTitles": [
    {
      "title": "A",
      "value": "a",
      "extended": {
        "type": null,
        "value": null
      },
      "position": 1
    },
    {
      "title": "B",
      "value": "b",
      "extended": {
        "type": null,
        "value": null
      },
      "position": 2
    }
  ],
  "validators": {},
  "localizeInfos": {
    "title": "Radio"
  },
  "additionalFields": {}
}

---

• List: Daftar item yang dapat dipilih, misalnya, dropdown.

{
  "type": "list",
  "value": {},
  "marker": "list",
  "position": 14,
  "listTitles": [
    {
      "title": "A",
      "value": "a",
      "extended": {
        "type": null,
        "value": null
      },
      "position": 1
    },
    {
      "title": "B",
      "value": "b",
      "extended": {
        "type": null,
        "value": null
      },
      "position": 2
    },
    {
      "title": "C",
      "value": "c",
      "extended": {
        "type": "string",
        "value": "Additional Value"
      },
      "position": 3
    }
  ],
  "validators": {},
  "localizeInfos": {
    "title": "List"
  },
  "additionalFields": {}
}

---

• Entity: Tautan ke objek lain (halaman, produk, …).

{
  "type": "entity",
  "value": {},
  "marker": "entity",
  "position": 15,
  "listTitles": [
    {
      "title": "Products",
      "value": {
        "id": 1,
        "depth": 0,
        "parentId": null,
        "isPinned": false,
        "position": 1,
        "selected": true
      }
    },
    {
      "title": "Normal Page",
      "value": {
        "id": 4,
        "depth": 0,
        "parentId": null,
        "isPinned": false,
        "position": 2,
        "selected": true
      }
    },
    {
      "title": "Error",
      "value": {
        "id": 2,
        "depth": 0,
        "parentId": null,
        "isPinned": false,
        "position": 3,
        "selected": true
      }
    }
  ],
  "validators": {},
  "localizeInfos": {
    "title": "Entity"
  },
  "additionalFields": {
    "test_field": {
      "type": "string",
      "value": "Test Field",
      "marker": "test_field"
    }
  }
}

---

• Interval waktu: Kalender fleksibel dengan antarmuka yang ramah pengguna untuk mengelola data interval waktu.

{
  "time_interval": {
    "id": 4,
    "type": "timeInterval",
    "value": [
      // Array of value groups, each linked to a specific interval (via intervalId). This array is formed when Receive values is enabled in CMS
      {
        // Specific time records applicable to the specified dates
        "values": [
          {
            // Unique record identifier
            "id": "1dc1787d-acc3-4315-a45d-52166c72e577",
            // Date range (inclusive) to which this record applies
            "dates": ["2025-11-27T00:00:00.000Z", "2025-11-27T00:00:00.000Z"],
            // Array of time slots in format [[start, end], ...]
            "times": [
              [
                // Start of time slot (hours and minutes)
                {
                  "hours": 19,
                  "minutes": 18
                },
                // End of time slot
                {
                  "hours": 21,
                  "minutes": 19
                }
              ]
            ],
            // Reserved (not used in current implementation)
            "intervals": [],
            // Exceptions — time segments excluded from the schedule on the specified date
            "exceptions": [
              {
                // Exception date
                "date": "2025-12-17T17:00:00.000Z",
                // Array of excluded time segments
                "externalTimes": [
                  ["2025-12-17T17:25:00.000Z", "2025-12-17T17:27:00.000Z"]
                ]
              }
            ],
            // Reference to interval from the `intervals` array
            "intervalId": "0da61a19-49cb-40b1-88e6-1fa3c93a1fa6",
            // Flag for weekly recurrence (on the corresponding day of the week)
            "inEveryWeek": true
          },
          {
            "id": "cfa187d3-0284-4e0d-8206-7b353cf47110",
            "dates": ["2025-12-18T00:00:00.000Z", "2025-12-18T00:00:00.000Z"],
            // Array of time slots in format [[start, end], ...]
            "times": [
              [
                {
                  "hours": 0,
                  "minutes": 25
                },
                {
                  "hours": 0,
                  "minutes": 27
                }
              ],
              [
                {
                  "hours": 19,
                  "minutes": 18
                },
                {
                  "hours": 21,
                  "minutes": 19
                }
              ]
            ],
            "intervals": [],
            "exceptions": [
              {
                "date": "2025-12-17T17:00:00.000Z",
                "externalTimes": [
                  ["2025-12-17T17:25:00.000Z", "2025-12-17T17:27:00.000Z"]
                ]
              }
            ],
            "intervalId": "0da61a19-49cb-40b1-88e6-1fa3c93a1fa6"
          },
          {
            "id": "474de0f7-595f-49a5-aaa7-65617203ae69",
            "dates": ["2025-12-25T00:00:00.000Z", "2025-12-25T00:00:00.000Z"],
            // No time slots
            "times": [],
            // Dynamic rules for schedule expansion
            "external": [
              {
                // Base date for calculating recurring event
                "date": "2026-01-15T00:00:00.000Z",
                // Event repeats every month on this day
                "inEveryMonth": true
              }
            ],
            "intervals": [],
            "exceptions": [
              {
                "date": "2025-12-17T17:00:00.000Z",
                "externalTimes": [
                  ["2025-12-17T17:25:00.000Z", "2025-12-17T17:27:00.000Z"]
                ]
              }
            ],
            "intervalId": "0da61a19-49cb-40b1-88e6-1fa3c93a1fa6",
            // Flag for weekly recurrence
            "inEveryWeek": true,
            // Flag for monthly recurrence
            "inEveryMonth": true,
            // Flag for yearly recurrence
            "inEveryYears": true
          }
        ],
        // Reference to interval from the `intervals` array
        "intervalId": "0da61a19-49cb-40b1-88e6-1fa3c93a1fa6"
      },
      {
        "values": [
          {
            "id": "2f80dc18-16da-45cb-82c6-e41e1f6ee084",
            "dates": ["2025-12-22T00:00:00.000Z", "2025-12-23T00:00:00.000Z"],
            "times": [],
            "intervals": [],
            "exceptions": [],
            "intervalId": "918175fd-cc18-4ca5-9bee-c78c61c9415a",
            "inEveryWeek": true,
            "inEveryMonth": true
          }
        ],
        "intervalId": "918175fd-cc18-4ca5-9bee-c78c61c9415a"
      }
    ],
    "isPrice": false,
    "original": true,
    "intervals": [
      // Array of time interval templates
      {
        // Unique identifier of interval template
        "id": "0da61a19-49cb-40b1-88e6-1fa3c93a1fa6",
        "range": [
          // Main range of interval applicability
          "2025-11-26T17:00:00.000Z",
          "2025-11-26T17:00:00.000Z"
        ],
        // Exceptions at the entire interval level
        "external": [
          {
            "date": "2025-12-17T17:00:00.000Z",
            "externalTimes": [
              ["2025-12-17T17:25:00.000Z", "2025-12-17T17:27:00.000Z"]
            ]
          }
        ],
        // Internal time slots (working/active periods)
        "intervals": [
          {
            "id": "01fea594-9933-47ac-af0a-ec0e0884f618",
            // End of time slot
            "end": {
              "hours": 21,
              "minutes": 19
            },
            // Start of time slot
            "start": {
              "hours": 19,
              "minutes": 18
            },
            // Duration of repeating block (in minutes); null — no periodicity
            "period": null
          },
          {
            "id": "22ba24af-1fae-4422-8c92-0635b684a306",
            "end": {
              "hours": 0,
              "minutes": 29
            },
            "start": {
              "hours": 0,
              "minutes": 25
            },
            // Periodicity: time slots repeat with 2-minute step
            "period": 2,
            // Exception inside periodic slot
            "external": {
              // Flag for displaying exception in the interface
              "show": false,
              // Duration of excluded fragment (in minutes)
              "value": 2
            }
          }
        ],
        "inEveryWeek": true,
        "inEveryMonth": true,
        "inEveryYears": true
      },
      {
        "id": "918175fd-cc18-4ca5-9bee-c78c61c9415a",
        "range": ["2026-01-18T17:00:00.000Z", "2026-01-20T17:00:00.000Z"],
        // No exceptions
        "external": [],
        // No internal time slots
        "intervals": [],
        "inEveryWeek": true,
        "inEveryMonth": true,
        "inEveryYears": true
      }
    ],
    // Flag for attribute visibility in the interface
    "isVisible": true,
    "identifier": "time_interval",
    "localizeInfos": {
      "title": "Time interval"
    },
    "receiveValues": true
  }
}

---

Antarmuka pengisian konten di panel admin sesuai dengan tipe data yang dipilih untuk setiap bidang atribut.

---

❓ Pertanyaan Umum (FAQ)

Apa perbedaan antara string dan text?

• string - teks pendek, satu baris (maks ~255 karakter). Gunakan untuk nama, judul, email.
• text - teks panjang, beberapa paragraf, mendukung pemformatan dan HTML. Gunakan untuk deskripsi, artikel.

---

Kapan saya harus menggunakan integer, float, atau real?

• integer - hanya angka bulat (1, 2, 100, -5). Gunakan untuk kuantitas, hitungan, usia.
• float - angka desimal (19.99, 4.5). Gunakan untuk harga, penilaian, pengukuran.
• real - seperti float tetapi dengan presisi lebih tinggi. Gunakan untuk perhitungan ilmiah.

---

Bisakah saya menggunakan atribut yang sama di set atribut yang berbeda?

Atribut didefinisikan dalam skema set atribut (berdasarkan penanda). Untuk menggunakan kembali bidang di tempat lain, buat atribut serupa dengan penanda yang berbeda, atau gunakan kembali seluruh set atribut di beberapa entitas.

---

Apa itu "penanda" dan mengapa itu penting?

Penanda adalah pengidentifikasi teknis yang Anda gunakan dalam kode (misalnya, product.attributeValues.product_name), berbeda dengan judul yang dapat dibaca manusia yang ditampilkan di panel admin. Penanda harus unik, tidak mengandung spasi (gunakan _), tidak boleh dimulai dengan angka, dan secara konvensional menggunakan huruf kecil.

---

Bisakah saya memiliki atribut bersarang?

Ya - gunakan Additional Fields (dikembalikan di bawah additionalFields).

---

Bagaimana cara menambahkan aturan validasi?

Di panel admin OneEntry: buka set atribut Anda, klik atribut, tambahkan validator (diperlukan, min/maks, dll.), dan simpan. Pelajari lebih lanjut: Validators.

---

🎓 Praktik Terbaik

• Gunakan penanda yang deskriptif (product_price, bukan pp).
• Rencanakan tipe atribut sebelum menambahkan konten.
• Gunakan kembali set atribut di seluruh entitas jika memungkinkan.
• Tambahkan validator untuk menegakkan kualitas data.
• Ingat bahwa set bersama menyebarkan perubahan ke setiap entitas yang menggunakannya.

---

🔗 Dokumentasi Terkait

• Modul Produk - Menggunakan set atribut untuk data produk
• Modul Halaman - Menggunakan set atribut untuk konten halaman
• Modul Blok - Menggunakan set atribut untuk blok yang dapat digunakan kembali
• Modul Formulir - Membuat formulir dengan bidang kustom

---