Custom Gutenberg Block ACF Pro menjadi solusi yang saya bangun saat content creator butuh alat penulisan yang fleksibel, tetapi saya tidak ingin terjebak menulis React maupun JavaScript block yang terlalu rumit. Gutenberg memang sudah jadi fondasi yang kuat, namun blok bawaan sering kurang sesuai dengan struktur konten spesifik di website klien. Artikel ini adalah studi kasus dari pengalaman pribadi saya, bukan tutorial generik. Saya akan memandu Anda lewat proses implementasinya, mulai dari fondasi reusable block, registrasi dinamis, kategori kustom, contoh InnerBlocks, contoh field ACF, hingga PHP rendering. Mari langsung masuk ke studinya.
Tantangan yang Saya Hadapi
Saya membutuhkan custom blocks yang kuat dan ramah untuk content creator, dengan manajemen field yang advanced lewat ACF Pro, tanpa harus membangun ekosistem JavaScript yang berat. Blok default Gutenberg tidak cukup untuk layout konten khusus yang saya pakai berulang kali. Saya juga ingin setiap block baru bisa ditambahkan dengan pola yang konsisten: cukup buat folder di /blocks, tulis block.json, sediakan template PHP, lalu sistem menemukannya sendiri. Tanpa fondasi registrasi yang scalable, menambah block baru akan selalu terasa seperti setup ulang dari nol.
Langkah demi Langkah Implementasi
Membangun Fondasi Reusable Block di Admin
Langkah pertama bukan langsung menulis block visual, melainkan merapikan fondasi reusable block di WordPress admin. Saya membuat file theme-reuseable-blocks.php agar Reusable Blocks mudah diakses dari admin menu, bisa dipanggil lewat shortcode, dan shortcode tersebut tampil sebagai kolom di daftar Patterns/Reusable Blocks. Dengan pendekatan ini, blok yang sudah disusun bisa dipakai ulang di banyak tempat tanpa copy-paste manual. Fondasi ini juga menjadi “rumah” untuk seluruh sistem custom block yang akan saya daftarkan nanti.
Registrasi Dinamis Block dari Folder /blocks
Setelah fondasi admin siap, saya membuat sistem penemuan dan registrasi block secara dinamis. Fungsinya sederhana: scan folder /blocks di theme, lalu daftarkan setiap directory yang punya block.json menggunakan register_block_type(). Saya juga mengecek ketersediaan ACF Pro sebelum registrasi berjalan, agar theme tidak error saat environment belum lengkap. Pendekatan ini membuat sistem Custom Gutenberg Block ACF Pro saya scalable. Setiap kali saya menambah block baru, saya cukup membuat folder baru tanpa mengubah ulang loop utama registrasinya.
Membuat Custom Block Category
Agar block custom tidak berceceran di antara ratusan blok bawaan, saya mendaftarkan kategori sendiri lewat filter block_categories_all. Slug kategorinya rizwanaritonang-block dengan title “RizwanAritonang Blocks”. Semua block.json yang saya buat kemudian merujuk ke kategori ini. Hasilnya, content creator lebih cepat menemukan block yang relevan, sementara saya punya area khusus untuk mengelompokkan tool konten milik proyek.
Auto-Load Field Group ACF per Block
Untuk manajemen field, saya tidak ingin mendaftarkan semua ACF field group di satu file raksasa. Saya membuat loader yang membaca file acf-fields.php di dalam tiap folder block, lalu me-require file tersebut pada hook acf/init. Kalau sebuah block membutuhkan field custom, field group-nya ikut hidup bersama block tersebut. Kalau tidak ada acf-fields.php, block tetap bisa jalan tanpa field ACF. Pola ini menjaga setiap block tetap modular dan mudah dipelihara.
Contoh Block dengan Child Block via InnerBlocks
Salah satu kebutuhan nyata saya adalah layout konten yang mengizinkan blok anak dari Gutenberg core. Saya membuat block content-format-geekfolio dengan block.json pada API version 3, mode preview, dan supports.jsx aktif. Di template content.php, saya membungkus konten dengan wrapper HTML tema, lalu memakai <InnerBlocks> dengan allowedBlocks terbatas pada core/heading, core/paragraph, core/image, dan core/list. Pendekatan ini memberi kontrol layout dari sisi theme, sementara content creator tetap menulis dengan blok Gutenberg yang mereka kenal. Tidak perlu membangun editor React custom hanya untuk menyusun heading, paragraf, gambar, dan list di dalam container yang sudah distyling.
Contoh Block dengan Field ACF dan Preview Placeholder
Kebutuhan kedua lebih “field-driven”: menampilkan paragraf pembuka dengan huruf besar di depan teks. Saya membuat block content-first-paragraph yang mengambil nilai dari get_field('first_character') dan get_field('paragraph'). Di mode preview, jika field masih kosong, saya menyiapkan placeholder agar editor tidak terlihat kosong dan membingungkan. Di frontend, bila kedua field kosong maka block tidak merender apa pun. Ini pola yang sangat membantu untuk block berbasis ACF: content creator mengisi field, PHP merender HTML, dan preview tetap ramah saat data belum lengkap.
PHP Server-Side Rendering untuk Setiap Block
Semua block dalam sistem ini di-render dari sisi server lewat template PHP yang ditunjuk di block.json pada key acf.renderTemplate. Saya konsisten memakai pola yang sama di tiap template: bangun $id dari $block['id'] atau anchor, susun $className, amankan output dengan esc_attr() dan esc_html(), lalu keluarkan markup sesuai field atau InnerBlocks. Keuntungannya jelas: saya tidak perlu menulis JavaScript render yang kompleks, performa frontend tetap ringan, dan markup mengikuti struktur tema yang sudah ada. Untuk proyek custom theme berbasis PHP, pendekatan ini jauh lebih maintainable dibanding stack block React penuh.
Pengujian dan Validasi
Setelah beberapa block aktif, saya menguji alur end-to-end. Saya memastikan registrasi block berjalan, kategori custom muncul di block inserter, field ACF tersedia pada block yang membutuhkannya, InnerBlocks hanya mengizinkan child block yang di-allow, preview placeholder tampil saat field kosong, dan hasil frontend sesuai dengan template PHP. Saya juga menguji reusable block lewat admin menu serta shortcode [reusable_block id="..."] agar pola reuse tetap konsisten. Hasilnya, content creator mendapatkan editor yang lebih powerful, sementara saya tetap punya kontrol penuh atas markup dan performa.
Hasil dan Dampak
Implementasi sistem Custom Gutenberg Block ACF Pro ini memberikan beberapa dampak langsung. Content creation jadi lebih fleksibel karena block disesuaikan dengan kebutuhan website, bukan dipaksa mengikuti blok generik. Integrasi ACF Pro membuat manajemen field terasa familiar bagi siapa pun yang sudah terbiasa dengan ACF. Kategori block kustom merapikan library di editor. Registrasi dinamis dari /blocks mempercepat penambahan block baru. Dan server-side rendering dengan PHP menjaga proyek tetap sederhana tanpa kompleksitas JavaScript yang tidak perlu.
Kesimpulan
Membangun Custom Gutenberg Block ACF Pro adalah proyek yang menantang sekaligus praktis untuk workflow WordPress berbasis PHP. Beberapa takeaway utama dari implementasi ini: fondasi reusable block membantu reuse konten lintas halaman, scan folder /blocks membuat registrasi scalable, kategori kustom merapikan pengalaman editor, acf-fields.php per block menjaga modularitas field, InnerBlocks cocok bila content creator perlu menyusun child block Gutenberg di dalam layout kustom, field ACF cocok untuk konten terstruktur dengan preview placeholder, dan PHP rendering cukup untuk performa serta maintainability tanpa React yang berlebihan. Sistem ini menjadi backbone content creation yang powerful sekaligus user-friendly. Pendekatan yang sama bisa Anda perluas ke block lain selama pola folder, block.json, dan template PHP-nya tetap konsisten.
