Wordpress Gutenberg Blocks Block Editor Block JSON Dynamic Blocks Rendering Strategies
WordPress1 September 20269 menit baca
Selesai membaca dokumentasi ini?
Kembali ke rujukan utama WordPress untuk melanjutkan topik lainnya.
Wordpress Gutenberg Blocks Block Editor Block JSON Dynamic Blocks Rendering Strategies
Definisi
Gutenberg adalah sistem block editor di WordPress. Isinya bukan cuma editor visual, tapi juga model konten berbasis blok, API registration untuk block, metadata block.json, serta strategi rendering yang bisa dilakukan di client, server, atau gabungan keduanya.
Kalau dulu WordPress dipakai terutama sebagai halaman dengan editor berbasis HTML klasik, Gutenberg memindahkan cara kerja konten ke unit kecil yang bisa disusun ulang: paragraph, heading, image, query loop, custom block, dan seterusnya. Untuk developer, yang penting bukan sekadar “bisa bikin blok”, tapi memahami kapan block editor memang cocok, bagaimana block didaftarkan, dan kapan output harus dirender ulang di server.
Kapan memakai block editor
Pakai block editor kalau konten yang dibangun:
- terdiri dari elemen modular yang bisa diurutkan ulang
- butuh preview yang dekat dengan hasil akhir
- perlu dipakai ulang lintas halaman atau lintas editor
- punya variasi struktur, seperti hero, card, CTA, testimonial, grid konten, atau listing dinamis
- ingin dikelola editor non-teknis tanpa menyentuh HTML mentah
Block editor kurang cocok kalau:
- struktur kontennya sangat tetap dan sederhana, misalnya satu halaman statis pendek
- layout sangat custom dan tiap bagian saling bergantung ketat pada markup yang sulit diprediksi
- tim belum siap menjaga kompatibilitas markup, atribut, dan style block saat versi plugin berubah
- Anda hanya butuh input data struktural; dalam kasus ini, custom meta box atau form admin kadang lebih tepat
Aturan praktisnya: kalau konten akan disusun seperti komponen, block editor biasanya menang. Kalau yang dibutuhkan hanya satu bentuk output yang sangat kaku, jangan memaksa semua hal masuk ke block.
Cara kerja block registration
Registrasi block adalah proses memberi tahu WordPress bahwa sebuah block ada, metadata apa yang dimilikinya, skrip apa yang dipakai, dan bagaimana block itu diperlakukan di editor maupun di front end.
Urutannya biasanya seperti ini:
- Plugin atau theme memanggil
register_block_type(). - WordPress membaca metadata dari
block.jsonatau argumen manual PHP. - Script editor, script view, style, dan atribut block dihubungkan ke registry.
- Editor menampilkan block tersebut di inserter.
- Saat post disimpan, atribut block ikut tersimpan di konten atau diproses server-side.
- Saat halaman dirender, WordPress memutuskan apakah output berasal dari markup tersimpan atau hasil render callback.
Yang sering terlupakan adalah bahwa block registration bukan cuma “daftar nama block”. Ia juga menentukan:
- atribut apa yang valid
- script mana yang aktif di editor
- style mana yang dimuat di editor dan di front end
- apakah block statis atau dinamis
- dukungan fitur seperti align, color, spacing, typography, anchor, dan lain-lain
Peran block.json
block.json adalah sumber metadata utama untuk block modern WordPress. File ini membuat registration lebih deklaratif, lebih konsisten, dan lebih mudah di-scan oleh WordPress tooling.
Biasanya block.json berisi:
name: nama block, misalnyamy-plugin/cta-boxtitle: label yang tampil di inserterdescription: deskripsi singkatcategory: kategori insertericon: ikon blockattributes: schema atribut blockeditorScript: script khusus editorscript: script bersama untuk editor dan front endviewScript: script front end sajastyle: style bersamaeditorStyle: style editor sajarender: path template render server-side, pada setup tertentusupports: fitur block yang diaktifkan
Keuntungan utama block.json:
- metadata block lebih terpusat
- registration lebih sedikit boilerplate
- WordPress bisa memetakan asset block secara konsisten
- easier maintenance untuk block yang jumlahnya banyak
- lebih cocok untuk tooling modern dan build pipeline
Kalau menggunakan block.json, PHP biasanya tinggal memanggil:
phpregister_block_type( __DIR__ . '/build' );Artinya WordPress akan membaca block.json di folder itu dan mendaftarkan block beserta asset yang dirujuk.
Static block vs dynamic block
Static block
Static block menyimpan markup hasil save() ke dalam konten post. Saat front end dibuka, WordPress merender markup yang sudah tersimpan di database, lalu cocokkan atribut dan wrapper yang diperlukan.
Cocok untuk:
- paragraph, heading, button, image, callout
- layout yang output HTML-nya stabil
- block yang tidak tergantung data runtime
Kelebihan:
- cepat
- mudah dipahami
- hasil render relatif konsisten
Risiko:
- jika markup
save()berubah, block lama bisa jadi invalid - refactor HTML perlu hati-hati karena bisa memicu block validation warning
Dynamic block
Dynamic block tidak mengandalkan markup final dari save() sebagai output utama. Biasanya save() mengembalikan null atau placeholder minimal, lalu front end dirender oleh PHP via render_callback atau template render.
Cocok untuk:
- query listing
- latest posts
- related content
- data yang berubah setelah post disimpan
- output yang tergantung user, tanggal, peran, locale, atau konfigurasi server
Kelebihan:
- output selalu mengikuti data terbaru
- lebih aman untuk konten yang sering berubah
- markup server-side lebih mudah dikontrol
Risiko:
- lebih banyak kerja di server
- butuh perhatian pada caching
- preview editor bisa berbeda dari front end kalau data fetch tidak disamakan
Rendering strategies
Ada tiga strategi utama yang perlu dipahami:
1. Save-side rendering
Markup final disimpan di konten saat post disimpan.
Dipakai untuk block statis yang output-nya stabil.
2. Server-side rendering
PHP menghasilkan output saat request dibuka.
Dipakai untuk dynamic block dan block yang bergantung pada data runtime.
3. Hybrid rendering
Editor menampilkan preview dari data client-side atau server-side, sementara front end tetap dirender oleh server.
Dipakai ketika editor butuh pengalaman visual yang baik, tapi front end tetap harus akurat terhadap data terbaru.
Pilihan strateginya biasanya begini:
- kalau konten statis dan sederhana, gunakan static block
- kalau output tergantung query atau kondisi runtime, gunakan dynamic block
- kalau editor perlu preview kaya fitur, gunakan hybrid dengan hati-hati
Jangan memilih strategi hanya karena “lebih modern”. Pilih berdasarkan sifat data dan biaya maintenance.
Alur register → edit → save → render
Loading diagram...
Intinya:
- registration membuat block dikenal WordPress
- editor memakai metadata itu untuk menampilkan UI block
save()menentukan apa yang disimpan di konten untuk block statis- dynamic block menyerahkan output akhir ke server saat request
Contoh struktur block modern
Contoh struktur plugin block modern biasanya seperti ini:
textmy-plugin/
├── build/
│ ├── block.json
│ ├── index.js
│ ├── style-index.css
│ └── index.asset.php
├── src/
│ ├── edit.js
│ ├── save.js
│ └── style.scss
└── my-plugin.phpAlur build-nya umumnya:
- file di
src/ditulis saat development - bundler menghasilkan file di
build/ block.jsonmenunjuk ke asset hasil build- PHP mendaftarkan block dari folder
build/
Jebakan umum saat membangun block/plugin
1. Mengubah markup save() tanpa rencana migrasi
Ini jebakan paling umum di static block. Begitu markup output berubah, block lama bisa dianggap invalid.
Solusi:
- jaga stabilitas markup
- gunakan deprecated versions bila perlu
- pikirkan migration path sebelum refactor besar
2. Memakai dynamic block untuk semua hal
Tidak semua block perlu render server-side. Kalau output statis, dynamic block hanya menambah kompleksitas.
Solusi:
- pakai dynamic block hanya saat data benar-benar runtime-based
- jangan memindahkan semua rendering ke PHP tanpa alasan
3. Menaruh logic terlalu banyak di edit()
Komponen editor bisa membengkak kalau bisnis logic, fetch, formatting, dan UI digabung semua.
Solusi:
- pisahkan komponen preview, controls, dan data fetching
- pertahankan
edit()sebagai layer UI, bukan dump seluruh logic
4. Abaikan atribut schema
Atribut block yang tidak jelas tipe dan sumbernya sering bikin parsing konten rapuh.
Solusi:
- definisikan atribut secara eksplisit di
block.json - validasi bentuk data yang masuk
- jangan bergantung pada asumsi string/boolean yang tidak konsisten
5. Preview editor tidak sama dengan front end
Ini sering terjadi pada dynamic block atau block yang bergantung pada style global.
Solusi:
- samakan sumber data
- gunakan server preview bila perlu
- uji block di editor dan front end sebelum dianggap selesai
6. Style dimuat di tempat yang salah
Block bisa terlihat benar di editor tetapi rusak di front end, atau sebaliknya.
Solusi:
- bedakan
style,editorStyle,script, daneditorScript - pastikan dependensi dan enqueue path benar
7. Tidak memperhatikan caching
Dynamic block yang bergantung pada query bisa bentrok dengan page cache atau object cache.
Solusi:
- pahami layer cache di WordPress dan server
- jika data sangat dinamis, pertimbangkan invalidation atau fragment strategy
8. Mengandalkan HTML mentah yang sulit dipelihara
Kalau block terlalu banyak menyimpan HTML custom di string, maintenance jadi susah.
Solusi:
- gunakan komponen dan template yang jelas
- jaga struktur render tetap sederhana
- hindari markup yang rapuh terhadap perubahan kecil
Catatan implementasi
- Untuk block baru, mulai dari
block.jsondulu agar metadata, asset, dan dukungan fitur tersusun rapi. - Untuk content block yang sifatnya editorial, static block biasanya lebih ringan dan lebih cepat.
- Untuk block yang tampilannya bergantung pada query atau data hidup, dynamic block lebih aman.
- Untuk plugin besar, konsistensi struktur folder lebih penting daripada sekadar “bloknya jalan”.
- Uji tiga tempat: inserter/editor, saved content, dan front end.
Referensi cepat
register_block_type()untuk mendaftarkan blockblock.jsonuntuk metadata block modernsave()untuk output static blockrender_callbackuntuk dynamic blocksupportsuntuk fitur editor dan style support
Ringkasan
Kalau mau merangkum satu kalimat: Gutenberg block adalah unit konten yang didaftarkan ke WordPress, diedit lewat block editor, disimpan sebagai markup atau data terstruktur, lalu dirender dengan strategi yang cocok untuk sifat kontennya.
Kalau Anda memahami kapan block editor dipakai, bagaimana registration bekerja, apa fungsi block.json, dan kapan harus pindah ke dynamic rendering, biasanya setengah masalah plugin/block WordPress sudah selesai sebelum coding dimulai.