Kait Editor Blok

Hooks adalah salah satu fitur fundamental WordPress. Hooks memungkinkan Anda “mengaitkan” kode ke inti WordPress, lalu menjalankan kode Anda sendiri pada titik-titik tertentu dalam siklus hidup WordPress.

Block Editor memiliki kumpulan hook-nya sendiri yang memungkinkan Anda berinteraksi dengan editor dan mengubah perilakunya.

Pelajaran ini akan memperkenalkan beberapa hook berbeda yang tersedia di Block Editor, serta cara menggunakannya untuk memperluas fungsionalitas editor.

Paket @wordpress/hooks

Meskipun hook action dan filter secara historis hanya tersedia di PHP, karena Block Editor dibangun menggunakan JavScript, kini tersedia pula kumpulan hook JavaScript baru.

Hook action dan filter JavaScript ini memungkinkan Anda mengaitkan kode ke berbagai aspek editor, serta mengubah perilaku editor atau blok itu sendiri.

Hook JavaScript didaftarkan menggunakan fungsi addAction dan addFilter dari paket @wordpress/hooks.

Serupa dengan versi PHP, Anda meneruskan nama hook dan fungsi callback ke fungsi-fungsi ini.

Perbedaan pentingnya adalah Anda juga harus meneruskan namespace hook. Namespace adalah pengenal unik untuk fungsi callback, dan membantu mencegah konflik benturan nama.

Mari kita lihat contoh untuk mendemonstrasikan cara menggunakan hook JavaScript.

Filter blocks.registerBlockType

Untuk semua contoh blok yang telah Anda lihat sejauh ini, Anda menggunakan fungsi registerBlockType dari paket @wordpress/blocks untuk mendaftarkan blok dalam JavaScript.

Setiap blok dimulai dengan mendaftarkan definisi tipe blok baru menggunakan fungsi ini.

/**
 * Every block starts by registering a new block type definition.
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
 */
registerBlockType( metadata.name, {
    /**
     * @see ./edit.js
     */
    edit: Edit,

    /**
     * @see ./save.js
     */
    save,
} );

Saat kode yang memproses semua blok yang terdaftar dijalankan, fungsi callback apa pun yang dikaitkan ke hook filter blocks.registerBlockType akan dijalankan dan harus mengembalikan objek pengaturan blok yang telah dimodifikasi.

    const settings = applyFilters(
        'blocks.registerBlockType',
        blockType,
        name,
        null
    );

Hook filter ini memungkinkan Anda memodifikasi objek pengaturan blok sebelum blok didaftarkan.

Untuk mendaftarkan fungsi callback ke filter blocks.registerBlockType, Anda menggunakan fungsi addFilter dari paket @wordpress/hooks.

Mari kita buat plugin untuk memasukkan file JavaScript ke antrean, guna mendaftarkan filter tersebut.

Mulailah dengan membuat direktori di dalam direktori wp-content/plugins untuk menyimpan kode hook blok.

mkdir -p wp-content/plugins/wp-learn-block-hooks

Buat file PHP plugin utama, wp-learn-block-hooks.php, di direktori yang baru dibuat.

Kemudian tambahkan kode berikut untuk menyiapkan header plugin, dan memastikan kode plugin hanya berjalan di lingkungan WordPress:

<?php
/**
 * Plugin Name:       WP Learn Block Hooks
 * Description:       WP Learn Block Hooks
 * Requires at least: 6.6
 * Requires PHP:      7.0
 * Version:           1.0.0
 * Author:            The WordPress Contributors
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       wp-learn-block-hooks
 *
 */
if ( ! defined( 'ABSPATH' ) ) {
    exit; // Exit if accessed directly.
}

Selanjutnya, Anda dapat mengaitkan fungsi callback ke action enqueue_block_editor_assets untuk memasukkan file JavaScript ke antrean.

add_action( 'enqueue_block_editor_assets', 'wp_learn_block_hooks_editor_assets' );
function wp_learn_block_hooks_editor_assets() {
    wp_enqueue_script(
        'wp-learn-block-hooks-editor-script',
        plugin_dir_url( __FILE__ ) . 'block-hooks.js',
        array(
            'wp-hooks',
        ),
    );
}

Perhatikan bahwa Anda perlu menentukan dependensi wp-hooks untuk memastikan kode hook blok hanya dimuat setelah paket @wordpress/hooks tersedia. Ini karena Anda akan menggunakan fungsi addFilter dari paket @wordpress/hooks di file JavaScript.

Sekarang, buat file block-hooks.js di direktori plugin dan awali dengan IIFE (Immediately Invoked Function Expression) untuk mencegah variabel apa pun dari kode ini bocor ke cakupan global:

( function(){

} )()

Selanjutnya, gunakan fungsi addFilter untuk mendaftarkan callback pada hook filter blocks.registerBlockType:

( function(){
    wp.hooks.addFilter(
        'blocks.registerBlockType',
        'wp-learn-block-hooks/list-block-description',
        addListBlockDescription
    );
} )()

Perhatikan bahwa Anda menentukan namespace unik sebelum fungsi callback addListBlockDescription. Namespace ditentukan oleh pengembang dan harus unik untuk plugin Anda.

Sekarang, mari kita buat fungsi callback addListBlockDescription untuk melakukan sesuatu:

    function addListBlockDescription( settings, name ) {
        if ( name === 'core/list' ) {
            settings.description = 'This is a list block';
        }
        return settings;
    }

Di sini, fungsi callback addListBlockDescription menerima objek pengaturan blok dan nama blok sebagai parameter.

Fungsi tersebut kemudian memeriksa apakah blok yang sedang didaftarkan adalah blok daftar, dan jika ya, mengubah properti deskripsi dari objek pengaturan blok.

Terakhir, karena ini adalah filter, fungsi tersebut perlu mengembalikan sesuatu; dalam hal ini, fungsi tersebut perlu mengembalikan objek pengaturan yang telah dimodifikasi.

Untuk mengujinya, jangan aktifkan plugin terlebih dahulu. Sebagai gantinya, edit sebuah pos atau halaman, lalu cari blok daftar dari penyisip blok.

Jika Anda mengarahkan kursor ke blok daftar, Anda akan melihat deskripsi “Create a bulleted or numbered list” ditampilkan.

Sekarang, aktifkan plugin.

Setelah plugin diaktifkan, Anda akan melihat deskripsi blok daftar berubah menjadi “This is a list block”.

Dokumentasi Hook Block Editor

Buku panduan Block Editor memiliki bagian khusus yang didedikasikan untuk Hook Block Editor, yang berisi halaman berbeda untuk berbagai jenis hook yang tersedia.

Halaman Filter Blok berisi daftar semua filter yang tersedia untuk memungkinkan Anda mengubah perilaku blok yang sudah ada, dengan bagian tentang memodifikasi blok selama pendaftaran blok, memodifikasi blok di halaman depan, mengubah perilaku blok di Block Editor, menghapus blok, menyembunyikan blok, serta mengelola kategori blok.

Hook Editor mendokumentasikan semua hook yang memungkinkan Anda mengubah pengalaman editor, termasuk memodifikasi pengaturan editor, menonaktifkan fitur direktori blok dan direktori pola, memperluas fitur Editor, mengontrol data REST API untuk editor, serta mencatat kesalahan Editor.

Halaman Filter i18n berisi daftar filter yang memungkinkan Anda memodifikasi fungsi internasionalisasi yang digunakan di editor.

Filter Parser mendokumentasikan semua filter yang memungkinkan Anda memodifikasi parser blok, yang digunakan untuk mengubah data blok yang tersimpan di memori menjadi markup blok yang disimpan dalam konten pos di basis data.

Autocomplete adalah komponen dalam paket @wordpress/block-editor yang menyediakan cara untuk menambahkan pelengkapan otomatis ke editor.

Jika Anda pernah menggunakan fungsi @username di editor blok, fitur tersebut didukung oleh komponen Autocomplete.

Halaman filter Autocomplete mendokumentasikan cara menambahkan pelengkapan otomatis Anda sendiri ke editor.

Terakhir, halaman Filter Gaya Global mendokumentasikan filter yang ditambahkan ke WordPress pada versi 6.1 yang memungkinkan pengembang memodifikasi pengaturan dan gaya global tema blok sebagaimana ditentukan oleh file theme.json.

Semua halaman ini menyertakan contoh terperinci tentang cara menggunakan hook tersebut dan bagaimana hook tersebut dapat digunakan untuk memperluas fungsionalitas Block Editor.