Lewati ke konten

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.

JSON
{
  "$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:

Kueri Fungsi
posts get_posts
users get_users
terms get_terms

Argumen

Argumen kustom dapat diteruskan menggunakan atribut arguments:

JSON
{
  "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:

JSON
{
  "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:

JSON
{
  "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:

JSON
{
  "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):

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"]
        }
      }
    ]
  }
}

Format Pengembalian

JSON
{
  "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:

JSON
{
  "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:

PHP
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:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "custom",
          "custom": "customData"
        }
      }
    ]
  }
}

Data Eksternal

Ambil data dari sumber eksternal:

JSON
{
  "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.

JSON
{
  "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.