Mengisi Opsi
Alih-alih menyediakan tipe field berbeda seperti Posts, Users, atau Terms, Blockstudio memungkinkan pengisian data secara modular langsung dari block.json. Fitur ini berfungsi untuk tipe field select, radio, checkbox, color, dan gradient.
Data dapat diisi dengan empat cara:
- Kueri – Mengembalikan hasil dari kueri post, user, atau term
- Fetch – Mengembalikan hasil dari sumber eksternal
- Fungsi – Mengembalikan hasil dari fungsi kustom
- Kustom – Mengembalikan hasil dari kumpulan data kustom
Kueri
Saat memilih mode kueri, Posts, Users, atau Terms dapat diisi.
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "blockstudio/native",
"title": "Native Block",
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts"
}
}
]
}
}
Tipe kueri yang tersedia menggunakan fungsi WordPress ini secara internal:
Argumen
Argumen kustom dapat diteruskan menggunakan atribut arguments:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "jobs",
"numberposts": "20"
}
}
}
]
}
}
Format Pengembalian
Secara default, Blockstudio mengembalikan:
| Kueri | Nilai | Label |
|---|---|---|
posts |
objek post | post_title |
users |
objek user | display_name |
terms |
objek term | name |
Sesuaikan respons dengan returnFormat:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "posts",
"numberposts": "20"
},
"returnFormat": {
"value": "id",
"label": "post_name"
}
}
}
]
}
}
Mode Fetch
Aktifkan pencarian dinamis dengan opsi fetch:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"fetch": true,
"arguments": {
"post_type": "posts",
"numberposts": "20"
}
}
}
]
}
}
Fitur ini mengaktifkan stylisedUi dan mengambil 20 post pertama saat awal. Mengetik di field pilihan akan mencari post menggunakan argumen s.
Fungsi
Gunakan fungsi kustom untuk mengisi opsi:
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types"
}
}
]
}
}
Argumen
Teruskan argumen sebagai array (menggunakan call_user_func_array secara internal):
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"]
}
}
]
}
}
Format Pengembalian
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"],
"returnFormat": {
"value": "name",
"label": "label"
}
}
}
]
}
}
Menggabungkan Opsi
Gabungkan opsi statis dengan data yang diisi:
{
"blockstudio": {
"attributes": [
{
"id": "users",
"type": "radio",
"label": "Users",
"options": [
{
"value": "administrators",
"label": "Administrators"
},
{
"value": "editors",
"label": "Editors"
}
],
"populate": {
"type": "query",
"query": "users",
"position": "before"
}
}
]
}
}
Opsi position (before atau after) mengontrol posisi opsi yang diisi relatif terhadap opsi statis.
Peringatan
Penggabungan opsi dengan data yang diisi tidak didukung saat menggunakan mode fetch.
Data Kustom
Buat kumpulan data yang dapat digunakan kembali dengan filter blockstudio/blocks/attributes/populate. Filter menerima satu argumen, yaitu array semua kumpulan data kustom yang diberi nama sebagai key. Tambahkan kumpulan data Anda dengan sebuah key, lalu kembalikan array:
add_filter('blockstudio/blocks/attributes/populate', function($options) {
$options['customData'] = [
['value' => '1', 'label' => 'Option 1'],
['value' => '2', 'label' => 'Option 2'],
];
return $options;
});
Lalu, rujuk key tersebut di blok Anda:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "custom",
"custom": "customData"
}
}
]
}
}
Data Eksternal
Ambil data dari sumber eksternal:
{
"blockstudio": {
"attributes": [
{
"id": "select",
"type": "select",
"label": "Select",
"multiple": true,
"populate": {
"type": "fetch",
"arguments": {
"urlSearch": "https://example.com/wp-json/wp/v2/posts?search="
},
"returnFormat": {
"value": "id",
"label": "title.rendered"
}
}
}
]
}
}
Istilah pencarian ditambahkan ke urlSearch.
Argumen Dinamis
Argumen pengisian dapat merujuk atribut blok lain menggunakan sintaks {attributes.*}. Saat atribut yang dirujuk berubah, field akan mengambil ulang opsinya secara otomatis.
{
"blockstudio": {
"attributes": [
{
"id": "post_type",
"type": "select",
"label": "Post Type",
"options": [
{ "label": "Pages", "value": "page" },
{ "label": "Posts", "value": "post" }
]
},
{
"id": "selected_post",
"type": "select",
"label": "Select Post",
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "{attributes.post_type.value}",
"numberposts": 10
}
}
}
]
}
}
Ini berfungsi dengan semua tipe pengisian (query, function, custom). Nilai apa pun dalam konfigurasi pengisian yang berisi {attributes.*} akan diselesaikan di sisi klien dengan nilai atribut terkini sebelum kueri dijalankan.
Referensi menggunakan nilai yang tersimpan di editor. Untuk opsi pilihan, gunakan {attributes.post_type.value} untuk nilainya atau {attributes.post_type.label} untuk labelnya; returnFormat mengontrol nilai templat, bukan bentuk nilai yang tersimpan di editor ini.
Argumen bertingkat diselesaikan tanpa menyerialisasikannya menjadi string templat.
Argumen yang terdiri dari satu placeholder mempertahankan tipe yang dirujuk, termasuk angka, boolean, larik, dan objek. Placeholder yang disisipkan ke dalam teks lain menghasilkan string. Referensi yang tidak ditemukan dibiarkan apa adanya, dan nilai yang dikutip atau terdiri dari beberapa baris dikirim secara utuh.
Callback fungsi mempertahankan daftar argumen posisionalnya. Editor hanya menambahkan argumen pencarian WordPress pada query populate, bukan pada pemanggilan fungsi.
Merender Pilihan yang Bergantung pada Pilihan Lain
Opsi bergantung tidak dimuat saat blok didaftarkan, karena setiap instans blok dapat memiliki argumen yang berbeda. Perenderan menggunakan pilihan yang tersimpan alih-alih membuangnya karena daftar opsi kosong. Callback populate tidak dijalankan lagi di frontend.
returnFormat kolom tetap berlaku:
returnFormat |
Pilihan tunggal | Pilihan ganda |
|---|---|---|
value (default) |
Nilai yang disimpan, misalnya "a" |
Array nilai yang disimpan, misalnya ["a", "b"] |
label |
Label yang disimpan | Array label yang disimpan |
both |
Opsi {value, label} yang disimpan |
Array opsi yang disimpan |
Untuk pilihan yang diisi melalui kueri, nilainya tetap mengarah ke objek postingan, pengguna, atau istilah WordPress yang sesuai, kecuali jika populate.returnFormat.value adalah "id". Label diambil dari pilihan yang disimpan. Jika pilihan yang diimpor tidak memiliki label, nilainya digunakan sebagai label. Opsi statis yang cocok dan dideklarasikan di options lebih diutamakan daripada opsi tersimpan, sehingga label terkininya yang digunakan.
Pilihan kosong tetap berupa false (atau fallback yang dikonfigurasi untuk field). Hal ini tidak mengubah validasi opsi statis biasa: nilai tersimpan yang tidak lagi ada dalam daftar opsi statis tetap menghasilkan false.
Pilihan dinamis juga mempertahankan pilihan default dan fallback saat opsinya ditangguhkan. Gunakan nilai skalar, opsi {value, label}, atau array yang berisi salah satunya untuk pilihan ganda. Skalar menggunakan nilainya sebagai label, kecuali jika cocok dengan opsi statis yang dideklarasikan. Objek opsi mempertahankan label yang diberikan; opsi statis yang cocok lebih diutamakan. Callback populate tidak dijalankan di server untuk mencari nilai default ini.