Ekstensi
Ekstensi memungkinkan Anda memperluas blok terdaftar apa pun di instalasi
WordPress menggunakan API berbasis .json yang sederhana, serupa dengan konfigurasi block.json. Ini mencakup blok inti, pihak ketiga, dan blok yang dibuat dengan Blockstudio.
Semua jenis bidang dapat ditambahkan ke blok apa pun, dan datanya disimpan ke atribut blok. Seluruh fitur atribut seperti pemfilteran, penonaktifan, logika kondisional, dan pengisian opsi tersedia untuk ekstensi.
Jenis Ekstensi
Nilai yang diperluas dapat dimanfaatkan dengan berbagai cara:
- class: Tambahkan class ke blok menggunakan nilai atribut
- style: Tambahkan gaya sebaris ke blok menggunakan nilai atribut
- attributes: Tetapkan nilai atribut apa pun langsung pada blok
- data attributes: Gunakan nilai ekstensi untuk menetapkan atribut data tertentu
Penyiapan
Bayangkan skenario berikut: Anda ingin menambahkan field kelas kustom select ke setiap blok inti. Anda hanya perlu menambahkan file .json ini di mana saja dalam folder blok, dan file tersebut akan otomatis didaftarkan sebagai ekstensi.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"priority": 10,
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Custom color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
Ini akan menambahkan field customColor ke setiap blok inti, sehingga Anda dapat mengatur warna teks blok.
Nama File
Karena tidak ada templat perenderan, ekstensi tidak memerlukan file index yang cocok, sehingga namanya juga tidak harus block.json. Dengan begitu, semua ekstensi dapat disimpan dengan mudah dalam satu folder. Beberapa file dapat memperluas blok yang sama, misalnya dua file dengan "name": "core/*"; masing-masing mendaftarkan field-nya sendiri.
Skema
Blockstudio menyediakan skema JSON kustom untuk konfigurasi ekstensi:
Nama
Properti name pada objek konfigurasi menentukan blok mana yang akan diperluas. Ada tiga opsi sesuai kebutuhan Anda:
- blockName: Satu nama blok, e.g.
core/paragraph - [blockNameA, blockNameB]: Array nama blok, e.g.
["core/paragraph", "core/heading"] - core/*: Karakter pengganti untuk memperluas semua blok dari jenis tertentu
Nama apa pun yang diakhiri tanda bintang adalah wildcard prefiks, bukan hanya core/*. Ekstensi berikut berlaku untuk setiap blok yang namanya diawali my-plugin/, termasuk blok yang dibuat dengan Blockstudio:
{
"name": "my-plugin/*",
"blockstudio": {
"extend": true,
"attributes": []
}
}
Mengecualikan Blok
Gunakan larik tingkat teratas exclude untuk melewati blok yang jika tidak akan cocok dengan name:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"exclude": ["core/button", "core/image"],
"blockstudio": {
"extend": true,
"attributes": []
}
}
Pengecualian menggunakan pencocokan nama persis dan prefiks dengan akhiran * yang sama seperti name. Pengecualian diprioritaskan daripada nama tunggal, daftar nama, dan wildcard. Blok yang dikecualikan tidak menerima kolom editor ekstensi maupun atribut atau aset frontend-nya. Ekstensi lain yang cocok tidak terpengaruh. Hilangkan exclude atau gunakan larik kosong untuk mempertahankan perilaku yang ada.
Kunci Blockstudio
Sama seperti saat menggunakan block.json untuk blok kustom, properti blockstudio harus ada di objek konfigurasi dengan extend bernilai true.
Posisi
Secara default, ekstensi ditampilkan di tab tersendiri pada pemeriksa blok. Jika ingin memindahkan ekstensi ke posisi lain, Anda dapat menggunakan properti group:
- settings: Posisi default
- styles: Tab gaya
- advanced: Tab lanjutan
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"group": "styles",
"attributes": []
}
}
Prioritas
Properti priority memungkinkan Anda menentukan urutan ekstensi ditampilkan. Ekstensi dengan prioritas lebih tinggi akan ditampilkan belakangan. Atur properti ini di tingkat teratas file, seperti pada contoh penyiapan, atau di dalam extend:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": { "priority": 10 },
"attributes": []
}
}
Jika keduanya diatur, blockstudio.extend.priority yang berlaku.
Atribut
Untuk informasi selengkapnya tentang cara kerja atribut, silakan lihat bagian atribut.
Satu-satunya hal yang perlu Anda ketahui tentang atribut dalam ekstensi adalah properti set. Properti ini digunakan untuk menerapkan nilai atribut ke salah satu jenis ekstensi.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
Mendapatkan Nilai
Notasi titik di dalam kurung kurawal digunakan untuk mendapatkan nilai atribut.
Anda juga dapat mengambil nilai bertingkat saat atribut tidak mengembalikan satu nilai, misalnya saat format pengembalian diatur ke both pada jenis field yang memiliki opsi.
{
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"returnFormat": "both",
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor.value}"
},
{
"attribute": "data-color",
"value": "{attributes.customColor.label}"
}
]
}
]
}
Contoh di atas akan mengatur atribut style ke color: #f00 atau color: #00f dan atribut data-color ke Red atau Blue, bergantung pada nilainya.
Untuk saat ini, hanya nilai dari atribut saat ini yang dapat digunakan dalam definisi set. Kemampuan menggunakan nilai dari atribut lain mungkin akan ditambahkan nanti.
Array
Saat menggunakan array, properti set akan diterapkan ke setiap item dalam array.
Setiap item menambahkan kelas atau deklarasi gaya masing-masing. Atribut lainnya hanya menampung satu nilai, jadi setiap item menimpanya dan item terakhir yang berlaku. Atur join ke true agar hasil semua item ditulis sekaligus, dipisahkan spasi tanpa nilai kosong atau berulang, sehingga pemilih seperti [data-langs~="en"] cocok dengan setiap item yang dipilih. join tidak berpengaruh pada class dan style, maupun pada kolom yang mengembalikan satu nilai.
{
"id": "langs",
"type": "checkbox",
"label": "Languages",
"options": [
{
"value": "en",
"label": "English"
},
{
"value": "de",
"label": "German"
}
],
"set": [
{
"attribute": "data-langs",
"value": "{attributes.langs}",
"join": true
}
]
}
Memilih kedua opsi akan menghasilkan data-langs="en de". Tanpa join, hasilnya data-langs="de".
Field Atribut
Saat menggunakan field attributes, properti set tidak diperlukan karena field tersebut otomatis memetakan nilai ke nama dan nilai atribut.
Memeriksa Kolom Ekstensi
bs_block_extension_fields('core/paragraph') mengembalikan definisi kolom dari setiap ekstensi yang cocok dengan sebuah blok. Lihat Memeriksa Blok untuk mengetahui nilai yang dikembalikan dan kaitannya dengan bs_block_fields().