Lewati ke konten

Field Kustom

Field kustom memungkinkan Anda menentukan grup field yang dapat digunakan kembali dan dirujuk di beberapa blok. Anggaplah sebagai templat field: tentukan sekali, gunakan di mana saja.

Field kustom berbeda dari jenis field kustom. Gunakan custom/{name} untuk grup field yang sudah ada dan dapat digunakan kembali. Gunakan jenis field kustom bernamespace seperti acme/dimensions saat tema atau plugin mendaftarkan kontrol editor dan bentuk nilai baru.

Pendaftaran Sistem File

Buat file field.json di dalam direktori fields/ pada direktori blockstudio Anda:

Kode
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
JSON
{
  "$schema": "https://blockstudio.dev/schema/field",
  "name": "hero",
  "title": "Hero Section",
  "attributes": [
    {
      "id": "heading",
      "type": "text",
      "label": "Heading",
      "default": "Hello World"
    },
    { "id": "description", "type": "textarea", "label": "Description" },
    { "id": "enabled", "type": "toggle", "label": "Enabled" }
  ]
}

Pendaftaran Filter PHP

Daftarkan field kustom secara terprogram menggunakan filter blockstudio/fields:

PHP
add_filter('blockstudio/fields', function ($fields) {
    $fields['cta'] = [
        'title'      => 'Call to Action',
        'attributes' => [
            ['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
            ['id' => 'url', 'type' => 'text', 'label' => 'URL'],
        ],
    ];
    return $fields;
});

Penggunaan di block.json

Rujuk field kustom menggunakan jenis custom/{name}:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero" }]
  }
}

Ini memperluas field yang ditentukan dalam definisi field kustom secara langsung. Field yang diperluas menggunakan ID aslinya (heading, description, enabled).

Field kustom juga dapat menggunakan kembali definisi grup secara utuh:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/section-header" }]
  }
}

Elemen turunan grup disimpan sebagai section-header_kicker, section-header_title, dan seterusnya. Di templat, gunakan bs_get_group() untuk mengekstraknya menjadi objek grup yang rapi.

Struktur ID

Gunakan idStructure untuk memberi awalan atau mengubah ID field. Placeholder {id} diganti dengan ID field asli:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
  }
}

Ini menghasilkan field dengan ID: hero_heading, hero_description, hero_enabled.

Penggantian

Sesuaikan field satu per satu untuk setiap instans menggunakan overrides. Kuncinya adalah ID field asli dari definisi:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "default": "Welcome", "label": "Title" },
          "enabled": { "id": "active" }
        }
      }
    ]
  }
}

Properti pengganti digabungkan di atas definisi field asli. Pengganti id melewati pola idStructure. Dalam contoh di atas, enabled menjadi active alih-alih hero_enabled.

Penggabungan hanya berlaku satu tingkat: properti yang Anda timpa akan menggantikan seluruh properti asli. Penggantian options adalah daftar opsi lengkap, bukan tambahan untuk daftar tersebut, begitu pula conditions dan attributes milik sebuah grup. Kondisi pada referensi tetap ditambahkan setelahnya.

JSON
{
  "type": "custom/background",
  "overrides": {
    "background": {
      "options": [
        { "value": "white", "label": "White" },
        { "value": "grey", "label": "Grey" }
      ]
    }
  }
}

Blok ini hanya menyediakan White dan Grey, sebanyak apa pun opsi yang tercantum dalam definisi.

Kondisi

Kondisi dalam definisi field kustom otomatis ditulis ulang saat idStructure diterapkan. Field yang bergantung secara kondisional pada field sesama tetap berfungsi setelah diperluas.

JSON
{
  "name": "font-size",
  "attributes": [
    { "id": "enable", "type": "toggle", "label": "Modify font size" },
    {
      "id": "min",
      "type": "number",
      "label": "Min Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    },
    {
      "id": "max",
      "type": "number",
      "label": "Max Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    }
  ]
}
JSON
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }

Blockstudio memperluas ini menjadi title_font_enable, title_font_min, title_font_max dan menulis ulang kondisi agar merujuk ke title_font_enable alih-alih enable. Toggle berfungsi persis seperti jika field tersebut didefinisikan secara langsung.

Kondisi tingkat referensi

Tambahkan conditions pada referensi untuk menerapkannya ke setiap field yang diperluas. Ini berguna untuk menyembunyikan seluruh grup di balik toggle eksternal:

JSON
{
  "type": "custom/font-size",
  "idStructure": "subtitle_font_{id}",
  "conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}

Kondisi ini digabungkan dengan kondisi apa pun yang sudah ditentukan di dalam definisi field. ID kondisi juga ditulis ulang melalui idStructure.

Beberapa Field Kustom

Anda dapat menggunakan beberapa field kustom dalam satu blok, bersama field biasa:

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "intro", "type": "text", "label": "Intro" },
      { "type": "custom/hero", "idStructure": "hero_{id}" },
      { "type": "custom/cta", "idStructure": "cta_{id}" }
    ]
  }
}

Penyarangan

Field kustom dapat digunakan di dalam grup, tab, dan repeater:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "id": "content",
        "title": "Content",
        "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
      }
    ]
  }
}

Jalur Penemuan Tambahan

Gunakan filter blockstudio/fields/paths untuk menambahkan direktori tambahan guna menemukan field:

PHP
add_filter('blockstudio/fields/paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/blockstudio/fields';
    return $paths;
});

Analisis Statis

Paket blockstudio/phpstan memperluas referensi custom/* berbasis file saat memvalidasi PHP, Twig, Blade, tag blok, dan bentuk atribut yang disimpulkan. Ekspansinya mengikuti aturan penyarangan, idStructure, dan overrides yang dijelaskan di atas.

Untuk definisi di luar proyek yang dianalisis, tambahkan direktori pustaka ke blockstudioScanRoots di phpstan.neon. Field yang hanya didaftarkan melalui filter blockstudio/fields PHP tersedia saat runtime dan tidak dapat disimpulkan secara statis.