Membangun Blok Gutenberg Kustom: Tutorial Pengembangan Blok Definitif

Banyak orang mengeluh tentang rintangan untuk memulai membangun blok dan aplikasi Gutenberg. Kurva pembelajarannya curam, terutama karena kesulitan menginstal dan mengonfigurasi lingkungan pengembangan. Selain itu, pengetahuan yang kuat tentang JavaScript, Node.js, React, dan Redux adalah bahan yang harus dimiliki untuk resep yang cukup rumit ini.

Buku Pegangan Editor Blok WordPress resmi memberi pengembang sejumlah besar informasi, tetapi Anda mungkin tersesat dalam lautan detail itu.

Dan perlu disebutkan apa yang Matias Ventura, arsitek utama proyek Gutenberg, laporkan dalam wawancaranya dengan WP Tavern:

Meskipun ada orang yang dapat mempelajarinya dengan cepat, itu masih menjadi penghalang besar bagi orang-orang. Saya pikir ada beberapa lapisan untuk ini; dokumentasi bisa menjadi urutan besarnya lebih baik di kedua organisasi dan presentasi. Saya harap kami bisa melakukan lebih banyak di sana.

Dengan mengingat hal itu, kami memutuskan untuk memberikan tutorial langkah demi langkah yang bertujuan membantu pembaca kami memulai pengembangan blok Gutenberg.

Terdengar menarik? Mari selami!

Prasyarat Pengembangan Blok Gutenberg

Untuk tutorial ini, satu-satunya keterampilan yang diperlukan adalah pengetahuan yang baik tentang pengembangan plugin WordPress dan setidaknya pemahaman dasar tentang HTML, CSS, JavaScript, dan React.

Apakah ini akan menjadi proyek yang ambisius? Anda yakin itu akan terjadi!

Tidak mudah menemukan kompromi yang tepat antara kelengkapan dan kesederhanaan atau memutuskan topik mana yang akan disertakan dan mana yang tidak.

Mudah-mudahan, pembaca tingkat menengah dan lanjutan akan memaafkan kami karena tidak mempelajari secara mendalam konsep-konsep tertentu seperti status React, toko Redux, komponen tingkat tinggi, dan sebagainya. Topik-topik ini membutuhkan ruang dan perhatian tambahan dan mungkin terlalu canggih untuk memulai pengembangan blok (kecuali jika Anda seorang pengembang Bereaksi).

Untuk alasan yang sama, kami tidak akan membahas beberapa topik lanjutan yang terkait dengan pengembangan blok Gutenberg, seperti blok dinamis dan kotak meta.

Dengan pengetahuan yang akan Anda peroleh di akhir artikel ini, Anda akan dapat langsung mulai bersenang-senang dan menjadi produktif.

Setelah Anda mulai membangun blok, Anda akan siap untuk meningkatkan keterampilan Anda lebih jauh dan membangun blok Gutenberg yang lebih maju sendiri.

Apa itu Blok Gutenberg?

Sejak pertama kali dirilis pada Desember 2018, editor blok telah sangat ditingkatkan dalam semua aspek: API yang lebih kuat, antarmuka pengguna yang lebih canggih, kegunaan yang ditingkatkan, banyak blok baru, implementasi pertama Pengeditan Situs Lengkap, dan banyak lagi. .

Singkatnya, bahkan jika Gutenberg masih dalam pengembangan yang berat, itu telah berjalan jauh — dan hari ini, editor blok adalah kandidat penuh sebagai pembuat halaman dan situs yang andal dan fungsional.

Dari sudut pandang pengembang, Gutenberg adalah Aplikasi Halaman Tunggal (SPA) berbasis React yang memungkinkan pengguna WordPress untuk membuat, mengedit, dan menghapus konten di WordPress. Namun, ini seharusnya tidak membuat Anda memikirkan versi yang disempurnakan dari editor konten tradisional.

Kami ingin memperjelas ini:

Di Gutenberg, konten dibagi menjadi blok, yang merupakan "batu bata" yang dapat digunakan pengguna untuk membuat posting dan halaman atau seluruh situs web mereka.

Tapi apa itu blok secara teknis?

Kami menyukai definisi WordPress:

"Blokir" adalah istilah abstrak yang digunakan untuk menggambarkan unit markup yang, disusun bersama, membentuk konten atau tata letak halaman web. Idenya menggabungkan konsep dari apa yang di WordPress hari ini kami capai dengan kode pendek, HTML khusus, dan penemuan yang disematkan ke dalam satu API dan pengalaman pengguna yang konsisten.

Judul, paragraf, kolom, gambar, galeri, dan semua elemen yang membentuk antarmuka editor, dari panel bilah sisi hingga kontrol bilah alat, adalah komponen Bereaksi.

Jadi, apa itu komponen React? W3Schools memberikan definisi berikut:

Komponen adalah bit kode yang independen dan dapat digunakan kembali. Mereka melayani tujuan yang sama seperti fungsi JavaScript, tetapi bekerja secara terpisah dan mengembalikan HTML melalui fungsi render() .

Meskipun pengalaman pengeditan yang diberikan oleh Gutenberg tergolong baru dibandingkan dengan editor WordPress klasik, cara WordPress menyimpan konten Anda di database tidak berubah sama sekali. Itu karena Gutenberg adalah aplikasi yang bekerja di dalam WordPress tetapi tidak mengubah cara kerja CMS pada intinya.

Postingan (dan ini termasuk posting, halaman, dan jenis posting khusus) yang dibuat dengan Gutenberg masih disimpan di tabel wp_posts , persis seperti dengan editor klasik.

Namun dalam postingan yang dibuat dengan Gutenberg, Anda akan menemukan informasi tambahan dalam tabel yang menunjukkan perbedaan mendasar antara postingan yang dibuat melalui Editor Klasik vs Gutenberg.

Potongan informasi ini terlihat seperti komentar HTML, dan memiliki fungsi khusus: membatasi blok:

Pembatas blok memberi tahu WordPress blok apa yang akan ditampilkan di layar. Mereka juga memberikan nilai untuk properti blok di objek JSON. Alat peraga tersebut menentukan cara blok harus ditampilkan di layar:

Menyiapkan Lingkungan Pengembangan WordPress Anda

Menyiapkan lingkungan pengembangan JavaScript modern membutuhkan pengetahuan yang kuat tentang teknologi canggih seperti Webpack, React dan JSX, Babel, ESLint, dll.

terintimidasi? Jangan! Komunitas WordPress telah datang untuk menyelamatkan dengan menyediakan alat canggih yang memungkinkan Anda menghindari proses konfigurasi manual yang berantakan.

Untuk mempermudah, kami tidak akan membahas transpiling dalam artikel ini (yang kami sarankan untuk membiasakan diri Anda setelah Anda mempelajari dasar-dasar pengembangan blok). Sebagai gantinya, kami akan memperkenalkan dua alat alternatif yang dapat Anda gunakan untuk menyiapkan lingkungan pengembangan JavaScript modern dengan cepat dan mudah dalam beberapa menit. Terserah Anda untuk memilih yang menurut Anda paling nyaman untuk proyek Anda.

Menyiapkan lingkungan pengembangan JavaScript untuk membangun blok Gutenberg adalah proses tiga langkah:

1. Instal Node.js dan npm
2. Siapkan lingkungan pengembangan
3. Siapkan plugin blok

Mari kita mulai.

1. Instal Node.js dan npm

Sebelum menginstal lingkungan pengembangan Anda dan mendaftarkan blok pertama Anda, Anda harus menginstal Node.js dan manajer paket Node (npm).

Anda dapat menginstal Node.js dan npm dengan beberapa cara berbeda. Tetapi pertama-tama, Anda mungkin ingin memeriksa apakah perangkat lunak tersebut sudah diinstal pada mesin Anda.

Untuk melakukan ini, luncurkan terminal dan jalankan perintah berikut:

 node -v

Jika hasilnya command not found , berarti Node.js belum terinstal di komputer Anda, dan Anda dapat melanjutkan instalasi.

Untuk artikel ini, kami telah memilih opsi instalasi termudah, yaitu Node Installer. Yang perlu Anda lakukan adalah mengunduh versi yang sesuai dengan sistem operasi Anda dan meluncurkan wizard penginstalan:

Setelah Anda menginstal Node.js, jalankan kembali perintah node -v di terminal Anda. Anda juga dapat menjalankan perintah npm -v untuk mengonfirmasi bahwa Anda memiliki paket npm yang tersedia.

Anda sekarang dilengkapi dengan alat-alat berikut:

• Paket runner npx Node.js (lihat dokumen). Ini memungkinkan Anda untuk menjalankan perintah npm tanpa menginstalnya terlebih dahulu.
• Manajer paket npm Node.js (lihat dokumen). Ini digunakan untuk menginstal dependensi dan menjalankan skrip.

Langkah selanjutnya adalah menginstal lingkungan pengembangan.

2. Siapkan Lingkungan Pengembangan Anda

Setelah Anda memiliki versi terbaru Node.js dan npm di mesin lokal Anda, Anda akan memerlukan lingkungan pengembangan untuk WordPress.

Anda dapat menggunakan lingkungan pengembangan lokal seperti DevKinsta atau menggunakan alat WordPress resmi. Mari kita intip kedua opsi tersebut.

Opsi 1: Lingkungan Pengembangan Lokal (DevKinsta)

Hanya dengan beberapa klik, Anda dapat menginstal WordPress secara lokal menggunakan DevKinsta, alat pengembangan WordPress lokal modern kami. Atau Anda dapat memilih alat pengembangan lokal yang berbeda, seperti MAMP atau XAMPP:

Opsi 2: wp-env

Anda juga dapat memilih alat wp-env resmi, yang menyediakan lingkungan pengembang WordPress lokal yang dapat Anda luncurkan langsung dari baris perintah. Nuh Alen mendefinisikannya sebagai berikut:

Lingkungan WordPress lokal sekarang sesederhana menjalankan satu perintah. wp-env adalah alat konfigurasi nol untuk lingkungan WordPress lokal yang tidak menyakitkan. Ini memberikan keputusan atas opsi sehingga pengguna dapat dengan cepat memutar WordPress tanpa membuang waktu. Memang, tujuannya adalah untuk membuat lingkungan ini mudah diakses oleh semua — apakah Anda seorang pengembang, desainer, manajer, atau siapa pun.

Jika Anda memutuskan untuk mencobanya, menginstal wp-env membutuhkan sedikit usaha. Ikuti saja langkah-langkah ini:

Langkah 1: Konfirmasi Instalasi Docker dan Node.js

Untuk memenuhi persyaratan teknis, pertama-tama Anda harus menginstal Docker dan Node.js di komputer Anda. Itu karena wp-env membuat instance Docker yang menjalankan situs WordPress. Setiap perubahan yang dibuat pada kode segera tercermin dalam instance WordPress.

Langkah 2: Instal @wordpress/env dari Command Line

Dengan Docker dan Node.js yang berjalan di komputer Anda, Anda dapat melanjutkan dan menginstal lingkungan pengembangan WordPress.

Anda dapat menginstal wp-env baik secara global maupun lokal. Untuk melakukannya secara global, Anda harus menjalankan perintah berikut dari dalam direktori plugins (lebih lanjut tentang ini di kotak pemberitahuan “Penting” di bawah):

 npm install -g @wordpress/env

Mari kita uraikan:

• npm install menginstal paket.
• -g ditambahkan ke perintah menginstal paket yang ditentukan secara global.
• @wordpress/env adalah paket yang akan Anda instal.

Untuk mengonfirmasi bahwa wp-env telah berhasil diinstal, jalankan perintah berikut:

 wp-env --version

Anda akan melihat versi wp-env saat ini, yang berarti Anda sekarang dapat meluncurkan lingkungan menggunakan perintah berikut dari folder plugin Anda:

 wp-env start

Anda dapat mengakses dashboard WordPress menggunakan alamat berikut:

• http://localhost:8888/wp-admin/

Kredensial default adalah sebagai berikut:

• Nama pengguna: admin
• Kata sandi: password

Siapkan Plugin Blok Anda

Sekarang Anda memerlukan plugin blok starter untuk dibangun. Tetapi alih-alih membuat plugin blok pengembangan secara manual dengan semua file dan folder yang diperlukan, Anda cukup menjalankan alat dev yang menyediakan semua file dan konfigurasi yang Anda butuhkan untuk memulai pengembangan blok.

Sekali lagi, Anda memiliki beberapa opsi untuk dipilih. Mari kita lihat masing-masing.

Opsi 1: Menyiapkan Plugin Blokir Dengan @wordpress/create-block

@wordpress/create-block adalah alat konfigurasi nol resmi untuk membuat blok Gutenberg:

Create Block adalah cara yang didukung secara resmi untuk membuat blok untuk mendaftarkan blok untuk plugin WordPress. Ini menawarkan pengaturan build modern tanpa konfigurasi. Ini menghasilkan PHP, JS, kode CSS, dan semua yang Anda butuhkan untuk memulai proyek.

Ini sebagian besar terinspirasi oleh create-react-app. Pujian besar untuk @gaearon, seluruh tim Facebook, dan komunitas React.

Setelah lingkungan lokal Anda aktif dan berjalan, Anda dapat mengatur blok starter hanya dengan menjalankan perintah npx @wordpress/create-block , dan itu akan menyediakan semua file dan folder yang Anda butuhkan untuk membuat perancah plugin dan mendaftarkan blok baru .

Mari kita jalankan tes untuk melihat cara kerjanya.

Dari alat Baris Perintah Anda, navigasikan ke direktori /wp-content/plugins/ dan jalankan perintah berikut:

 npx @wordpress/create-block my-first-block

Saat diminta untuk mengonfirmasi, masukkan y untuk melanjutkan:

Prosesnya memakan waktu beberapa saat. Setelah selesai, Anda akan mendapatkan respons berikut:

Dan itu saja!

Sekarang luncurkan lingkungan pengembangan WordPress Anda dan buka layar Plugin di dasbor WordPress. Plugin baru bernama "Blok Pertama Saya" seharusnya telah ditambahkan ke daftar plugin Anda:

Aktifkan plugin jika diperlukan, buat posting blog baru, gulir ke bawah penyisipan blok ke bagian Widget , dan pilih blok baru Anda:

Sekarang kembali ke terminal dan ubah direktori saat ini menjadi my-first-block :

 cd my-first-block

Kemudian jalankan perintah berikut:

 npm start

Ini memungkinkan Anda untuk menjalankan plugin dalam mode pengembangan. Untuk membuat kode produksi, Anda harus menggunakan perintah berikut:

 npm run build

Opsi 2: Menyiapkan Plugin Blok Dengan create-guten-block

create-guten-block adalah alat pengembangan pihak ketiga untuk membangun blok Gutenberg:

create-guten-block adalah dev-toolkit konfigurasi nol (#0CJS) untuk mengembangkan blok WordPress Gutenberg dalam hitungan menit tanpa mengonfigurasi React, webpack, ES6/7/8/Next, ESLint, Babel, dll.

Sama seperti alat create-block resmi, create-guten-block didasarkan pada create-react-app dan dapat membantu Anda menghasilkan plugin blok pertama Anda tanpa kerumitan.

Toolkit ini menyediakan semua yang Anda butuhkan untuk membuat plugin WordPress modern, termasuk yang berikut:

• Dukungan sintaks React, JSX, dan ES6.
• proses pembuatan webpack dev/production di belakang layar.
• Ekstra bahasa di luar ES6 seperti operator penyebaran objek.
• CSS dengan awalan otomatis, jadi Anda tidak memerlukan -webkit atau awalan lainnya.
• Skrip build untuk menggabungkan JS, CSS, dan gambar untuk produksi dengan peta sumber.
• Pembaruan tanpa kerumitan untuk alat di atas dengan skrip cgb ketergantungan tunggal.

Perhatikan peringatan berikut:

Imbalannya adalah bahwa alat-alat ini telah dikonfigurasikan sebelumnya untuk bekerja dengan cara tertentu. Jika proyek Anda membutuhkan lebih banyak penyesuaian, Anda dapat "mengeluarkan" dan menyesuaikannya, tetapi Anda perlu mempertahankan konfigurasi ini.

Setelah Anda memiliki situs web WordPress lokal, luncurkan alat Baris Perintah Anda, navigasikan ke folder /wp-content/plugins instalasi Anda, dan jalankan perintah berikut:

 npx create-guten-block my-first-block

Anda harus menunggu satu atau dua menit saat struktur proyek dibuat dan dependensi diunduh:

Ketika proses selesai, Anda akan melihat layar berikut:

Gambar berikut ini menunjukkan struktur proyek dengan terminal yang berjalan di Visual Studio Code:

Sekarang kembali ke dashboard WordPress Anda. Item baru harus terdaftar di layar Plugin — ini adalah plugin blok pertama saya :

Aktifkan plugin dan kembali ke terminal. Ubah direktori saat ini menjadi my-first-block , lalu jalankan npm start :

 cd my-first-block npm start

Anda harus mendapatkan respons berikut:

Sekali lagi, ini memungkinkan Anda untuk menjalankan plugin dalam mode pengembangan. Untuk membuat kode produksi, Anda harus menggunakan:

 npm run build

Aktifkan plugin dan buat posting atau halaman baru, lalu jelajahi blok Anda dan pilih blok Gutenberg baru Anda:

Untuk gambaran yang lebih mendalam atau jika terjadi kesalahan, lihat dokumentasi yang disediakan oleh Ahmad Awais.

Panduan Perancah Blok Pemula

Mana pun dari dua dev-tools — create-block atau create-guten-block — yang Anda pilih, Anda sekarang memiliki perancah blok yang dapat Anda gunakan sebagai titik awal untuk membangun plugin blok.

Tapi apa sebenarnya perancah blok itu?

Perancah blok adalah istilah singkat yang menjelaskan struktur direktori pendukung yang Anda perlukan agar WordPress mengenali blok. Biasanya direktori itu menyertakan file seperti index.php , index.js , style.css , dan lainnya — yang pada gilirannya menahan panggilan seperti register_block_type .

Kami memilih alat pengembang Create Block resmi, seperti yang digunakan dalam Buku Pegangan Block Editor. Tetapi bahkan jika Anda memutuskan untuk menggunakan alat pihak ketiga seperti create-guten-block , pengalaman Anda tidak akan terlalu berbeda.

Dengan itu, mari selami lebih dalam alat create-block .

Melihat Lebih Dekat pada Buat Blok Dev-Tool

Seperti yang kami sebutkan di atas, Create Block adalah alat baris perintah resmi untuk membuat blok Gutenberg. Menjalankan @wordpress/create-block di terminal Anda menghasilkan file dan kode PHP, JS, dan SCSS yang diperlukan untuk mendaftarkan jenis blok baru:

 npx @wordpress/create-block [options] [slug]

• [slug] (opsional) — digunakan untuk menetapkan blok slug dan menginstal plugin
• [options] (opsional) — opsi yang tersedia

Secara default, template ESNext ditetapkan. Ini berarti Anda akan mendapatkan versi JavaScript berikutnya, dengan tambahan sintaks JSX.

Jika Anda menghilangkan nama blok, perintah berjalan dalam mode interaktif, memungkinkan Anda untuk menyesuaikan beberapa opsi sebelum membuat file:

 npx @wordpress/create-block

Gambar di bawah ini menunjukkan struktur file plugin blok yang dibuat dengan alat Create Block resmi:

Dengan itu, mari kita lihat file dan folder utama dari plugin blok baru kita.

File Plugin

Dengan file plugin utama Anda mendaftarkan blok di server:

 /** * Plugin Name: My First Block * Description: Example block written with ESNext standard and JSX support – build step required. * Requires at least: 5.8 * Requires PHP: 7.0 * Version: 0.1.0 * Author: The WordPress Contributors * License: GPL-2.0-or-later * License URI: https://www.gnu.org/licenses/gpl-2.0.html * Text Domain: my-first-block * * @package create-block */ /** * Registers the block using the metadata loaded from the `block.json` file. * Behind the scenes, it registers also all assets so they can be enqueued * through the block editor in the corresponding context. * * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/ */ function create_block_my_first_block_block_init() { register_block_type( __DIR__ ); } add_action( 'init', 'create_block_my_first_block_block_init' );

Fungsi register_block_type mendaftarkan tipe blok di server menggunakan metadata yang disimpan dalam file block.json .

Fungsi ini mengambil dua parameter:

• Nama tipe blok termasuk namespace, atau jalur ke folder tempat file block.json berada, atau objek WP_Block_Type lengkap
• Array argumen tipe blok

Dalam kode di atas, argumen tipe blok disediakan oleh konstanta ajaib __DIR__ . Itu berarti file block.json berada di folder yang sama dengan file plugin.

File package.json

File package.json mendefinisikan properti JavaScript dan skrip untuk proyek Anda. Di sinilah Anda dapat menginstal dependensi proyek Anda.

Untuk lebih memahami untuk apa file ini, buka dengan editor kode favorit Anda:

 { "name": "my-first-block", "version": "0.1.0", "description": "Example block written with ESNext standard and JSX support – build step required.", "author": "The WordPress Contributors", "license": "GPL-2.0-or-later", "main": "build/index.js", "scripts": { "build": "wp-scripts build", "format": "wp-scripts format", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "start": "wp-scripts start", "packages-update": "wp-scripts packages-update" }, "dependencies": { "@wordpress/block-editor": "^7.0.1", "@wordpress/blocks": "^11.0.1", "@wordpress/i18n": "^4.2.1" }, "devDependencies": { "@wordpress/scripts": "^18.0.0" } }

Properti scripts adalah kamus yang berisi perintah yang dijalankan pada berbagai waktu dalam siklus hidup paket menggunakan npm run [cmd] .

Pada artikel ini, kita akan menggunakan perintah berikut:

• npm run build — buat build produksi (terkompresi)
• npm run start — buat build pengembangan (tidak terkompresi)

dependencies dan devDependencies adalah dua objek yang memetakan nama paket ke versi. dependencies diperlukan dalam produksi, sedangkan devDependences hanya diperlukan untuk pengembangan lokal (baca selengkapnya).

Satu-satunya ketergantungan dev default adalah paket @wordpress/scripts , yang didefinisikan sebagai "kumpulan skrip yang dapat digunakan kembali yang disesuaikan untuk pengembangan WordPress."

File block.json

Dimulai dengan WordPress 5.8, file metadata block.json adalah cara kanonik untuk mendaftarkan jenis blok.

Memiliki file block.json memberikan beberapa manfaat, termasuk peningkatan kinerja dan visibilitas yang lebih baik di Direktori Plugin WordPress:

Dari perspektif kinerja, ketika tema mendukung aset pemuatan lambat, blok yang terdaftar di block.json akan memiliki aset yang diantrekan dioptimalkan di luar kotak. Aset CSS dan JavaScript frontend yang tercantum dalam properti style atau script hanya akan diantrekan saat blok ada di halaman, sehingga ukuran halaman berkurang.

Menjalankan perintah @wordpress/create-block menghasilkan file block.json berikut:

 { "apiVersion": 2, "name": "create-block/my-first-block", "version": "0.1.0", "title": "My First Block", "category": "widgets", "icon": "smiley", "description": "Example block written with ESNext standard and JSX support – build step required.", "supports": { "html": false }, "textdomain": "my-first-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Berikut daftar lengkap properti default:

• apiVersion — versi API yang digunakan oleh blok (versi saat ini adalah 2)
• name — pengidentifikasi unik untuk blok termasuk namespace
• version — versi blok saat ini
• title — judul tampilan untuk sebuah blok
• category — kategori blok
• icon — siput Dashicon atau ikon SVG khusus
• description — deskripsi singkat yang terlihat di inspektur blok
• supports — satu set opsi untuk mengontrol fitur yang digunakan dalam editor
• textdomain — plugin domain teks
• editorScript — definisi skrip editor
• editorStyle — definisi gaya editor
• style — menyediakan gaya alternatif untuk sebuah blok

Selain properti yang tercantum di atas, Anda dapat (dan mungkin akan) mendefinisikan objek attributes yang menyediakan informasi tentang data yang disimpan oleh blok Anda. Di block.json Anda, Anda dapat mengatur sejumlah atribut dalam pasangan kunci/nilai , di mana kuncinya adalah nama atribut dan nilainya adalah definisi atribut.

Perhatikan contoh definisi atribut berikut ini:

 "attributes": { "content": { "type": "array", "source": "children", "selector": "p" }, "align": { "type": "string", "default": "none" }, "link": { "type": "string", "default": "https://kinsta.com" } },

Kami akan menyelam lebih dalam ke file block.json nanti di artikel, tetapi Anda mungkin juga ingin memeriksa Buku Pegangan Editor Blok untuk informasi lebih rinci tentang metadata dan atribut block.json .

Folder src

Folder src adalah tempat pengembangan terjadi. Di folder itu, Anda akan menemukan file-file berikut:

• index.js
• edit.js
• simpan.js
• editor.scss
• style.scss

index.js

File index.js adalah titik awal Anda. Di sini Anda akan mengimpor dependensi dan mendaftarkan jenis blok pada klien:

 import { registerBlockType } from '@wordpress/blocks'; import './style.scss'; import Edit from './edit'; import save from './save'; registerBlockType('create-block/my-first-block', { edit: Edit, save, });

Pernyataan pertama mengimpor fungsi registerBlockType dari paket @wordpress/blocks . Pernyataan impor berikut mengimpor stylesheet bersama dengan fungsi Edit dan save .

Fungsi registerBlockType mendaftarkan komponen pada klien. Fungsi ini mengambil dua parameter: nama blok namespace/block-name (sama dengan yang terdaftar di server) dan objek konfigurasi blok.

Fungsi Edit menyediakan antarmuka blok seperti yang dirender di editor blok, sedangkan fungsi save menyediakan struktur yang akan diserialisasikan dan disimpan ke dalam database (baca selengkapnya).

edit.js

edit.js adalah tempat Anda akan membangun antarmuka admin blok:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Pertama, mengimpor fungsi __ dari paket @wordpress/i18n (paket ini berisi versi JavaScript dari fungsi terjemahan), hook useBlockProps React, dan file editor.scss .

Setelah itu, ia mengekspor komponen React (baca lebih lanjut tentang pernyataan impor dan ekspor).

simpan.js

File save.js adalah tempat kita membangun struktur blok untuk disimpan ke dalam database:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; export default function save() { return ( <p {...useBlockProps.save()}> {__( 'My First Block – hello from the saved content!', 'my-first-block' )} </p> ); }

editor.scss dan style.scss

Terlepas dari skrip, dua file SASS berada di folder src . File editor.scss berisi gaya yang diterapkan ke blok dalam konteks editor, sedangkan file style.scss berisi gaya blok untuk ditampilkan di frontend. Kami akan menyelam lebih dalam ke file-file ini di bagian kedua dari panduan ini.

Node_modules dan bangun Folder

Folder node_modules berisi modul node dan dependensinya. Kami tidak akan membahas lebih dalam paket node karena berada di luar cakupan artikel ini, tetapi Anda dapat membaca lebih lanjut di artikel ini tentang tempat npm menginstal paket.

Folder build berisi file JS dan CSS yang dihasilkan dari proses build. Anda dapat menyelami lebih dalam proses pembuatan di sintaks ESNext dan panduan Penyiapan Pembuatan JavaScript.

Proyek: Membangun Blok Gutenberg Pertama Anda

Saatnya mengotori tangan kita. Bagian ini akan mengajarkan Anda cara membuat plugin yang menyediakan blok CTA bernama Affiliate Block.

Blok akan terdiri dari dua kolom, dengan gambar di sebelah kiri dan paragraf teks di sebelah kanan. Tombol dengan tautan yang dapat disesuaikan akan ditempatkan di bawah teks:

Ini hanyalah contoh sederhana, tetapi ini memungkinkan kita untuk membahas dasar-dasar pengembangan blok Gutenberg. Setelah Anda mendapatkan pemahaman yang jelas tentang dasar-dasarnya, Anda dapat melanjutkan dan membuat blok Gutenberg yang semakin kompleks dengan bantuan Buku Pegangan Editor Blok dan sumber daya besar lainnya yang tersedia di luar sana.

Dengan asumsi bahwa Anda memiliki versi terbaru WordPress yang berjalan di lingkungan pengembangan lokal Anda, inilah yang akan Anda pelajari dari sini:

• Cara Mengatur Plugin Blok Pemula
• block.json di Tempat Kerja
• Menggunakan Komponen Bawaan: Komponen RichText
• Menambahkan Kontrol ke Bilah Alat Blok
• Menyesuaikan Bilah Sisi Pengaturan Blok
• Menambahkan dan Menyesuaikan Tautan Eksternal
• Menambahkan Beberapa Gaya Blok
• Blok Bersarang Dengan Komponen InnerBlocks
• Peningkatan Tambahan

Siap… siap… berangkat!

Cara Mengatur Plugin Blok Pemula

Luncurkan alat baris perintah Anda dan navigasikan ke folder /wp-content/plugins :

Sekarang, jalankan perintah berikut:

 npx @wordpress/create-block

Perintah ini menghasilkan file PHP, SCSS, dan JS untuk mendaftarkan blok dalam mode interaktif, memungkinkan Anda untuk menambahkan data yang diperlukan untuk blok Anda dengan mudah. Untuk contoh kami, kami akan menggunakan detail berikut:

• Blok slug : blok-afiliasi-saya
• Ruang nama internal : plugin-afiliasi saya
• Judul tampilan blok : Blok afiliasi
• Deskripsi blok pendek : Contoh blok untuk pembaca Kinsta
• Dashicon : uang
• Nama kategori : desain
• Penulis plugin : nama Anda
• Lisensi : –
• Tautan ke teks lisensi : –
• Versi plugin saat ini : 0.1.0

Menginstal plugin dan semua dependensi membutuhkan waktu beberapa menit. Saat proses selesai, Anda akan melihat respons berikut:

Sekarang, jalankan perintah berikut dari folder /wp-content/plugins :

 cd my-affiliate-block

Terakhir, dari dalam folder plugin Anda ( my-affiliate-block dalam contoh kami), Anda dapat memulai pengembangan dengan:

 npm start

Sekarang buka layar Plugin untuk menemukan dan mengaktifkan plugin Blok Afiliasi :

Buat posting baru, buka penyisip blok, dan gulir ke bawah ke kategori Desain . Klik untuk menambahkan Blok Afiliasi:

block.json di Tempat Kerja

Seperti yang kami sebutkan sebelumnya, pendaftaran blok sisi server dilakukan di file .php utama. Namun, kami tidak akan menentukan pengaturan dalam file .php . Sebagai gantinya, kita akan menggunakan file block.json .

Jadi, buka block.json lagi dan lihat lebih dekat pengaturan default:

 { "apiVersion": 2, "name": "my-affiliate-plugin/my-affiliate-block", "version": "0.1.0", "title": "Affiliate Block", "category": "design", "icon": "money", "description": "An example block for Kinsta readers", "supports": { "html": false }, "textdomain": "my-affiliate-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Skrip dan Gaya

editorScript , editorStyle , dan properti style menyediakan jalur relatif ke skrip dan gaya frontend dan backend.

Anda tidak perlu secara manual mendaftarkan skrip dan gaya yang ditentukan di sini karena ini secara otomatis terdaftar dan diantrekan oleh WordPress. Untuk membuktikannya, luncurkan inspektur browser dan buka tab Jaringan :

Seperti yang Anda lihat dari gambar di atas, skrip index.js kami yang berada di folder build telah di-enqueued secara teratur tanpa harus menambahkan kode PHP apa pun .

Mendaftar Untuk Buletin

Ingin tahu bagaimana kami meningkatkan lalu lintas kami lebih dari 1000%?

Bergabunglah dengan 20.000+ orang lain yang mendapatkan buletin mingguan kami dengan kiat-kiat WordPress orang dalam!

Berlangganan sekarang

Label UI

Properti title dan description menyediakan label yang diperlukan untuk mengidentifikasi blok di editor:

Kata kunci

Seperti yang kami sebutkan sebelumnya, Anda dapat secara akurat mengonfigurasi pengaturan blok Anda menggunakan properti dan atribut. Misalnya, Anda dapat menambahkan satu atau beberapa keywords untuk membantu pengguna menelusuri blok:

 { "keywords": [ "kinsta", "affiliate", "money" ] }

If you now input “kinsta”, “affiliate” or “money” in the quick inserter, the editor will suggest you the Affiliate block:

Lokalisasi

If you are wondering how the localization of the strings in the JSON file happens, here is the answer:

In JavaScript, you can use now registerBlockTypeFromMetadata method from @wordpress/blocks package to register a block type using the metadata loaded from block.json file. All localized properties get automatically wrapped in _x (from @wordpress/i18n package) function calls similar to how it works in PHP with register_block_type_from_metadata . The only requirement is to set the textdomain property in the block.json file.

Here we are using the registerBlockType function instead of registerBlockTypeFromMetadata , as the latter has been deprecated since Gutenberg 10.7, but the mechanism is the same.

Using Built-In Components: The RichText Component

The elements that make up a Gutenberg block are React components, and you can access these components via the wp global variable. For example, try to type wp.editor into your browser's console. This will give you the full list of the components included in the wp.editor module.

Scroll through the list and guess what components are meant for by their names.

Similarly, you can check the list of components included in the wp.components module:

Now go back to the edit.js file and take a closer look at the script:

import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Kode ini menghasilkan blok statis dengan teks sederhana yang tidak dapat diedit. Tapi kita bisa mengubah banyak hal dengan mudah:

Untuk membuat teks dapat diedit, Anda harus mengganti tag <p> saat ini dengan komponen yang membuat konten input dapat diedit. Untuk itu, Gutenberg menyediakan komponen RichText bawaan.

Menambahkan komponen bawaan ke blok Anda adalah proses 5 langkah:

1. Impor komponen yang diperlukan dari paket WordPress
2. Sertakan elemen yang sesuai ke dalam kode JSX Anda
3. Tentukan atribut yang diperlukan dalam file block.json
4. Tentukan pengendali acara
5. Simpan data

Langkah 1: Impor Komponen yang Diperlukan dari Paket WordPress

Sekarang buka file edit.js dan ubah pernyataan import berikut:

 import { useBlockProps } from '@wordpress/block-editor';

…ke:

 import { useBlockProps, RichText } from '@wordpress/block-editor';

Dengan cara ini, Anda mengimpor fungsi useBlockProps dan komponen RichText dari paket @wordpress/block-editor .

gunakanBlockProps

useBlockProps React menandai elemen pembungkus blok:

Saat menggunakan API versi 2, Anda harus menggunakan kait useBlockProps baru di fungsi edit blok untuk menandai elemen pembungkus blok. Hook akan memasukkan atribut dan event handler yang diperlukan untuk mengaktifkan perilaku blok. Atribut apa pun yang ingin Anda teruskan ke elemen blok harus melewati useBlockProps dan nilai yang dikembalikan disebarkan ke elemen.

Sederhananya, useBlockProps secara otomatis menetapkan atribut dan kelas ke elemen pembungkus (elemen p dalam contoh kita):

Jika Anda menghapus useBlockProps dari elemen pembungkus, Anda akan memiliki string teks sederhana tanpa akses untuk memblokir fungsionalitas dan gaya:

Seperti yang akan kami jelaskan nanti, Anda juga dapat meneruskan ke useBlockProps sebuah objek properti untuk menyesuaikan output.

Teks yang kaya

Komponen RichText menyediakan input yang dapat diedit, memungkinkan pengguna untuk mengedit dan memformat konten.

Anda akan menemukan komponen yang didokumentasikan di GitHub di gutenberg/packages/block-editor/src/components/rich-text/README.md.

Langkah 2: Sertakan Elemen yang Sesuai Ke dalam Kode BEJ Anda

 ... const blockProps = useBlockProps(); return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> );

Mari mengomentari kode baris demi baris:

• tagName — nama tag dari elemen HTML yang dapat diedit
• onChange — fungsi dipanggil saat konten elemen berubah
• allowedFormats — larik format yang diizinkan. Secara default, semua format diperbolehkan
• value — string HTML yang dapat diedit
• placeholder — teks placeholder untuk ditampilkan saat elemen kosong

Langkah 3: Tentukan Atribut yang Diperlukan di File block.json

Atribut memberikan informasi tentang data yang disimpan oleh blok, seperti konten yang kaya, warna latar belakang, URL, dll.

Anda dapat mengatur jumlah atribut yang berubah-ubah dalam objek attributes dalam pasangan kunci/nilai, di mana kuncinya adalah nama atribut dan nilainya adalah definisi atribut.

Sekarang buka file block.json dan tambahkan prop attributes berikut:

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" } },

Atribut content memungkinkan untuk menyimpan teks yang diketik oleh pengguna di bidang yang dapat diedit:

• type menunjukkan tipe data yang disimpan oleh atribut. Jenis ini diperlukan kecuali jika Anda mendefinisikan properti enum .
• source mendefinisikan bagaimana nilai atribut diekstraksi dari konten posting. Dalam contoh kita, ini adalah konten HTML. Perhatikan bahwa jika Anda tidak menyediakan properti sumber, data disimpan di pembatas blok (baca selengkapnya).
• selector adalah tag HTML atau pemilih lainnya, seperti nama kelas atau atribut id.

Kami akan melewati fungsi Edit objek properti. Jadi, kembali ke file edit.js dan buat perubahan berikut:

 export default function Edit( { attributes, setAttributes } ) { ... }

Langkah 4: Tentukan Penangan Acara

Elemen RichText memiliki atribut onChange , menyediakan fungsi untuk dipanggil saat konten elemen berubah.

Mari kita definisikan fungsi itu dan lihat seluruh skrip edit.js :

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> ); }

Sekarang simpan file dan jalankan npm run start di jendela terminal Anda. Kemudian, kembali ke dasbor WordPress Anda, buat posting atau halaman baru dan tambahkan blok Afiliasi Anda:

Tambahkan beberapa teks dan alihkan ke tampilan Kode. Berikut adalah tampilan kode Anda:

 <!-- wp:my-affiliate-plugin/my-affiliate-block --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable Gutenberg block </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

Jika sekarang Anda menyimpan halaman dan memeriksa hasil frontend, Anda mungkin akan sedikit kecewa karena perubahan Anda tidak memengaruhi situs. Itu karena Anda harus memodifikasi file save.js untuk menyimpan input pengguna di database saat posting disimpan.

Langkah 5: Simpan Data

Sekarang buka file save.js dan ubah skrip sebagai berikut:

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } /> ); }

Itulah yang kami lakukan di sini:

• Impor komponen RichText dari paket block-editor .
• Lewati beberapa properti melalui argumen objek ke fungsi save (dalam contoh ini, kami hanya meneruskan properti attributes )
• Kembalikan konten komponen RichText

Anda dapat membaca lebih lanjut tentang komponen RichText di Buku Pegangan Block Editor dan menemukan daftar lengkap alat peraga di Github.

Sekarang mari kita selangkah lebih maju. Di bagian berikutnya, Anda akan mempelajari cara menambahkan kontrol ke bilah alat blok.

Menambahkan Kontrol ke Bilah Alat Blok

Bilah alat blok berisi satu set kontrol yang memungkinkan pengguna untuk memanipulasi bagian dari konten blok. Untuk setiap kontrol toolbar, Anda akan menemukan komponen:

Misalnya, Anda dapat menambahkan kontrol perataan teks untuk blok Anda. Yang perlu Anda lakukan adalah mengimpor dua komponen dari paket @wordpress/block-editor .

Kita akan melalui langkah-langkah yang sama seperti contoh sebelumnya:

1. Impor Komponen yang Diperlukan Dari Paket WordPress
2. Sertakan Elemen yang Sesuai Ke dalam Kode BEJ Anda
3. Tentukan Atribut yang Diperlukan di File block.json
4. Tentukan Penangan Acara
5. Simpan Data

Langkah 1: Impor Komponen BlockControls dan AlignmentControl dari @wordpress/block-editor

Untuk menambahkan kontrol perataan ke bilah alat blok, Anda memerlukan dua komponen:

• BlockControls membuat bilah alat kontrol dinamis (tidak didokumentasikan).
• AlignmentControl membuat menu tarik-turun yang menampilkan opsi perataan untuk blok yang dipilih (baca selengkapnya)

Buka file edit.js dan edit pernyataan import seperti yang ditunjukkan di bawah ini:

 import { useBlockProps, RichText, AlignmentControl, BlockControls } from '@wordpress/block-editor';

Langkah 2: Tambahkan Elemen BlockControls dan AlignmentControl

Buka fungsi Edit dan masukkan elemen <BlockControls /> pada level yang sama dengan <RichText /> . Kemudian tambahkan dan <AlignmentControl /> di dalam <BlockControls /> :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

Dalam kode di atas, <> dan </> adalah sintaks singkat untuk mendeklarasikan fragmen React, yang merupakan cara kami mengembalikan beberapa elemen di React.

Dalam contoh ini, AlignmentControl memiliki dua atribut:

• value memberikan nilai saat ini untuk elemen
• onChange menyediakan event handler untuk dijalankan ketika nilainya berubah

Kami juga telah mendefinisikan atribut tambahan untuk elemen RichText (periksa daftar lengkap atribut dengan contoh)

Langkah 3: Tentukan Atribut align di block.json

Sekarang buka file block.json dan tambahkan atribut align :

 "align": { "type": "string", "default": "none" }

Kembali ke terminal, hentikan proses saat ini dengan ^C dan mulai skrip lagi dengan npm run start . Kemudian kembali ke editor blok, segarkan halaman dan pilih blok. Anda akan melihat bilah alat blok dengan kontrol perataan:

Sekarang, jika Anda mencoba memformat konten blokir menggunakan kontrol perataan baru, Anda akan melihat bahwa tidak ada yang terjadi. Itu karena kita belum mendefinisikan event handler.

Langkah 4: Tentukan Penangan Acara

Sekarang tentukan onChangeAlign :

 const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) }

Jika newAlign tidak undefined , maka kami menyetel newAlign menjadi none . Jika tidak, kami menggunakan newAlign .

Skrip edit.js kami harus lengkap (untuk saat ini):

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

Sekarang Anda dapat kembali ke editor dan menyelaraskan konten blok.

Kita perlu memodifikasi fungsi simpan untuk menyimpan konten blok dan atribut dalam database.

Langkah 5: Simpan Data

Buka save.js dan ubah fungsi save sebagai berikut:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } style={ { textAlign: attributes.align } } /> ); }

Terakhir, untuk membuat kode lebih mudah dibaca, Anda dapat mengekstrak properti individual dari objek attribute menggunakan sintaks penugasan destrukturisasi:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align } } /> ); }

Simpan file, mulai ulang proses dan kembali ke editor dalam mode Editor kode. Kodenya akan terlihat seperti ini:

 <!-- wp:my-affiliate-plugin/my-affiliate-block {"align":"right"} --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable <strong><em>Gutenberg</em></strong> <em>block</em> </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

Dan itu saja! Anda baru saja menambahkan kontrol perataan ke bilah alat blok

Anda dapat membaca lebih lanjut tentang kontrol bilah alat blok di Buku Pegangan Editor Blok.

Menyesuaikan Bilah Sisi Pengaturan Blok

Anda juga dapat menambahkan kontrol ke blok Pengaturan Sidebar (atau bahkan membuat sidebar baru untuk aplikasi Anda).

API menyediakan komponen InspectorControls untuk itu.

Buku Pegangan Editor Blok menjelaskan cara menggunakan Bilah Sisi Pengaturan:

Bilah Sisi Pengaturan digunakan untuk menampilkan pengaturan yang jarang digunakan atau pengaturan yang membutuhkan lebih banyak ruang layar. Bilah Sisi Pengaturan harus digunakan hanya untuk pengaturan tingkat blok .

Jika Anda memiliki pengaturan yang hanya memengaruhi konten yang dipilih di dalam blok (contoh: pengaturan "tebal" untuk teks yang dipilih di dalam paragraf): jangan letakkan di dalam Bilah Sisi Pengaturan. Bilah Sisi Pengaturan ditampilkan bahkan saat mengedit blok dalam mode HTML, jadi seharusnya hanya berisi pengaturan tingkat blok.

Lagi:

1. Impor Komponen yang Diperlukan Dari Paket WordPress
2. Sertakan Elemen yang Sesuai Ke dalam Kode BEJ Anda
3. Tentukan Atribut yang Diperlukan di File block.json
4. Tentukan Penangan Acara
5. Simpan Data

Langkah 1. Impor Komponen InspectorControls dan PanelColorSettings dari @wordpress/block-editor

Anda dapat menambahkan beberapa kontrol untuk memungkinkan pengguna menyesuaikan aspek tertentu dari blok. Misalnya, Anda dapat menyediakan panel kontrol warna. Untuk melakukannya, Anda perlu mengimpor komponen InspectorControls dan PanelColorSettings dari modul block-editor :

 import { useBlockProps, RichText, AlignmentControl, BlockControls, InspectorControls, PanelColorSettings } from '@wordpress/block-editor';

Langkah 2: Sertakan Elemen yang Sesuai Ke dalam kode JSX Anda

Sekarang Anda dapat menambahkan elemen terkait ke BEJ yang dikembalikan oleh fungsi Edit :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <InspectorControls> <PanelColorSettings title={ __( 'Color settings', 'my-affiliate-block' ) } initialOpen={ false } colorSettings={ [ { value: textColor, onChange: onChangeTextColor, label: __( 'Text color', 'my-affiliate-block' ), }, { value: backgroundColor, onChange: onChangeBackgroundColor, label: __( 'Background color', 'my-affiliate-block' ), } ] } /> </InspectorControls> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> </> ); }

Perhatikan bahwa kami juga telah memperbarui atribut style dari elemen RichText :

 <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } />

Langkah 3: Tentukan Atribut yang Diperlukan di block.json

Sekarang tentukan atribut backgroundColor dan textColor di file block.json :

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" }, "align": { "type": "string", "default": "none" }, "backgroundColor": { "type": "string" }, "textColor": { "type": "string" } },

Langkah 4: Tentukan Penangan Acara

Sekarang Anda perlu mendefinisikan dua fungsi untuk memperbarui backgroundColor dan textColor pada input pengguna:

 const onChangeBackgroundColor = ( newBackgroundColor ) => { setAttributes( { backgroundColor: newBackgroundColor } ) } const onChangeTextColor = ( newTextColor ) => { setAttributes( { textColor: newTextColor } ) }

Langkah 5: Simpan Data

Satu langkah terakhir: Buka file save.js dan ubah skrip sebagai berikut:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align, backgroundColor, textColor } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> ); }

Sekarang hentikan proses (^C) dan jalankan npm run start lagi. Segarkan halaman, hapus setiap instance dari blok Anda dan tambahkan lagi ke posting Anda:

Buat perubahan Anda, simpan pos, dan lihat di frontend. Perubahan yang Anda buat di editor blok harus tercermin di situs depan.

Menambahkan dan Menyesuaikan Tautan Eksternal

Di bagian ini, Anda akan menambahkan komponen baru ke jenis blok Anda:

• Komponen ExternalLink yang memungkinkan pengguna untuk menambahkan tautan yang dapat disesuaikan ke blok Afiliasi
• Beberapa kontrol bilah sisi memungkinkan pengguna untuk menyesuaikan pengaturan tautan

Langkah 1. Impor Komponen dari @wordpress/components

Sekarang Anda perlu mengimpor beberapa komponen dari @wordpress/components . Buka file edit.js Anda dan tambahkan pernyataan import berikut:

 import { TextControl, PanelBody, PanelRow, ToggleControl, ExternalLink } from '@wordpress/components';

• PanelBody menambahkan wadah yang dapat dilipat ke Bilah Sisi Pengaturan.
• PaneRow menghasilkan wadah umum untuk kontrol bilah sisi.
• TextControl menyediakan kontrol input teks.
• ToggleControl menyediakan sakelar yang memungkinkan pengguna untuk mengaktifkan/menonaktifkan opsi tertentu
• ExternalLink adalah komponen sederhana untuk menambahkan tautan eksternal.

Langkah 2. Sertakan Elemen yang Sesuai Ke dalam Kode BEJ Anda

Anda pertama-tama akan menambahkan elemen ExternalLink pada tingkat RichText yang sama dalam wadah div :

 <div { ...blockProps }> <RichText ... /> <ExternalLink href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "" } > { linkLabel } </ExternalLink> </div>

Komponen ExternalLink tidak didokumentasikan, jadi kami merujuk ke komponen itu sendiri untuk mendapatkan daftar atribut yang tersedia. Di sini kita menggunakan atribut href , className , dan rel .

Secara default, nilai atribut rel diatur ke noopener noreferrer . Kode kami akan menambahkan kata kunci nofollow ke atribut rel dari tag a dihasilkan saat kontrol sakelar aktif .

Sekarang Anda dapat menambahkan pengaturan tautan ke bilah sisi blok.

Pertama, Anda akan menambahkan elemen PanelBody di dalam InspectorControls pada level yang sama dengan PanelColorSettings :

 <InspectorControls> <PanelColorSettings ... /> <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > ... </PanelBody> </InspectorControls>

Inilah yang kami lakukan dengan ini:

1. Atribut title memberikan judul panel.
2. initialOpen menyetel apakah panel awalnya terbuka atau tidak.

Selanjutnya, kita akan menambahkan dua elemen PanelRow di dalam PanelBody , dan sebuah elemen TextControl di dalam setiap PanelRow :

 <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > <PanelRow> <fieldset> <TextControl label={__( 'Affiliate link', 'my-affiliate-block' )} value={ affiliateLink } onChange={ onChangeAffiliateLink } help={ __( 'Add your affiliate link', 'my-affiliate-block' )} /> </fieldset> </PanelRow> <PanelRow> <fieldset> <TextControl label={__( 'Link label', 'my-affiliate-block' )} value={ linkLabel } onChange={ onChangeLinkLabel } help={ __( 'Add link label', 'my-affiliate-block' )} /> </fieldset> </PanelRow> </PanelBody>

Kode di atas sekarang akan terlihat cukup mudah. Dua kontrol teks memungkinkan pengguna untuk mengatur label tautan dan URL.

Kami juga akan menambahkan PanelRow tambahan dengan ToggleControl untuk mengaktifkan/menonaktifkan opsi tertentu, seperti apakah akan menyertakan atribut atau tidak:

 <PanelRow> <fieldset> <ToggleControl label="Add rel = nofollow" help={ hasLinkNofollow ? 'Has rel nofollow.' : 'No rel nofollow.' } checked={ hasLinkNofollow } onChange={ toggleNofollow } /> </fieldset> </PanelRow>

Langkah 3: Tentukan Atribut yang Diperlukan di block.json

Sekarang tentukan atribut affiliateLink , linkLabel , dan hasLinkNofollow di file block.json :

 "affiliateLink": { "type": "string", "default": "" }, "linkLabel": { "type": "string", "default": "Check it out!" }, "hasLinkNofollow": { "type": "boolean", "default": false }

Tidak ada lagi yang perlu ditambahkan di sini! Mari kita beralih ke mendefinisikan fungsi penanganan acara.

Langkah 4: Tentukan Penangan Acara

Kembali ke file edit.js dan tambahkan fungsi berikut:

 const onChangeAffiliateLink = ( newAffiliateLink ) => { setAttributes( { affiliateLink: newAffiliateLink === undefined ? '' : newAffiliateLink } ) } const onChangeLinkLabel = ( newLinkLabel ) => { setAttributes( { linkLabel: newLinkLabel === undefined ? '' : newLinkLabel } ) } const toggleNofollow = () => { setAttributes( { hasLinkNofollow: ! hasLinkNofollow } ) }

Fungsi-fungsi ini memperbarui nilai atribut yang sesuai pada input pengguna.

Langkah 5: Simpan Data

Terakhir, kita harus memperbarui fungsi save di save.js :

 export default function save( { attributes } ) { const { align, content, backgroundColor, textColor, affiliateLink, linkLabel, hasLinkNofollow } = attributes; const blockProps = useBlockProps.save(); return ( <div { ...blockProps }> <RichText.Content tagName="p" value={ content } style={ { backgroundColor: backgroundColor, color: textColor } } /> <p> <a href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "noopener noreferrer" } > { linkLabel } </a> </p> </div> ); }

Perhatikan bahwa di sini kami telah menggunakan elemen a reguler alih-alih ExternalLink :

Sekarang simpan data dan mulai ulang lingkungan Anda.

Menambahkan Beberapa Gaya Blok

Di bagian sebelumnya, Anda telah mempelajari cara menambahkan kontrol bilah alat blok yang memungkinkan pengguna menyelaraskan input pengguna. Kami dapat menambahkan lebih banyak kontrol gaya ke bilah alat blok, tetapi kami juga dapat menyediakan satu set gaya blok yang telah ditentukan yang dapat dipilih pengguna dengan satu klik.

Untuk tujuan ini, kita akan menggunakan fitur yang berguna dari Block API: Block Styles.

Yang perlu Anda lakukan adalah mendefinisikan properti styles block.json dan mendeklarasikan gaya yang sesuai di lembar gaya Anda.

Misalnya, Anda dapat menambahkan larik gaya berikut:

 "styles": [ { "name": "default", "label": "Default", "isDefault": true }, { "name": "border", "label": "Border" } ],

Dengan ini, Anda baru saja menambahkan gaya default dan gaya tambahan yang disebut border . Sekarang kembali ke editor blok:

Gaya akan tersedia bagi pengguna dengan mengklik pengalih blok dan kemudian mencari panel Gaya di Bilah Sisi Pengaturan Blok .

Pilih gaya dan periksa kelas yang diterapkan ke elemen p . Klik kanan pada blok dan Inspect . Kelas baru telah ditambahkan dengan nama terstruktur sebagai berikut:

 is-style-{style-name}

Jika Anda mencentang gaya "Border", maka kelas is-style-border akan ditambahkan ke elemen p . Jika Anda mencentang gaya "Default", maka kelas is-style-default akan ditambahkan sebagai gantinya.

Sekarang Anda hanya perlu mendeklarasikan properti CSS. Buka file editor.scss dan ganti gaya saat ini dengan yang berikut:

 .wp-block-my-affiliate-plugin-my-affiliate-block { padding: 2px; &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Sekarang Anda dapat melakukan hal yang sama dengan style.scss :

 .wp-block-my-affiliate-plugin-my-affiliate-block { &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Hentikan proses (^C) dan jalankan npm run start lagi.

Dan itu saja! Segarkan halaman, dan bersenang-senanglah dengan gaya blok baru Anda:

Blok Gutenberg Bersarang Dengan Komponen InnerBlocks

Meskipun berfungsi penuh, Blok Afiliasi kami masih belum terlalu menarik. Untuk membuatnya lebih menarik bagi penonton, kita bisa menambahkan gambar.

Ini mungkin menambah lapisan kerumitan pada blok kita, tetapi untungnya, Anda tidak perlu menemukan kembali roda karena Gutenberg menyediakan komponen khusus yang dapat Anda gunakan untuk membuat struktur blok bersarang.

Komponen InnerBlocks didefinisikan sebagai berikut:

InnerBlocks mengekspor sepasang komponen yang dapat digunakan dalam implementasi blok untuk mengaktifkan konten blok bersarang.

Pertama, Anda harus membuat file .js baru di folder src . Dalam contoh kita, kita akan memanggil file ini container.js .

Sekarang Anda harus mengimpor sumber daya baru ke dalam file index.js :

 import './container';

Kembali ke container.js dan impor komponen yang diperlukan:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor";

Langkah selanjutnya adalah mendefinisikan template yang menyediakan struktur di mana blok akan ditempatkan. Dalam contoh berikut, kami mendefinisikan template yang terdiri dari dua kolom yang berisi blok Gambar inti dan blok Afiliasi kustom kami:

 const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ];

Template disusun sebagai larik blockTypes (nama blok dan atribut opsional).

Dalam kode di atas, kami menggunakan beberapa atribut untuk mengkonfigurasi blok Kolom dan Kolom. Secara khusus, atribut templateLock: 'all' mengunci blok Kolom sehingga pengguna tidak akan menambah, menyusun ulang, atau menghapus blok yang ada. templateLock dapat mengambil salah satu dari nilai berikut:

• all — InnerBlocks terkunci, dan tidak ada blok yang dapat ditambahkan, disusun ulang, atau dihapus.
• insert — Blok hanya dapat disusun ulang atau dihapus.
• false — Template tidak dikunci.

Template kemudian ditetapkan ke elemen InnerBlocks :

 <InnerBlocks template={ TEMPLATE } templateLock="all" />

Untuk mencegah masalah kompatibilitas, kami juga menambahkan atribut templateLock ke komponen InnerBlocks (lihat juga masalah #17262 dan tarik #26128).

Ini adalah file container.js terakhir kami:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor"; const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ]; registerBlockType('my-affiliate-plugin/my-affiliate-container-block', { title: __( 'Container', 'my-affiliate-block' ), category: 'design', edit( { className } ) { return( <div className={ className }> <InnerBlocks template={ TEMPLATE } templateLock="all" /> </div> ) }, save() { const blockProps = useBlockProps.save(); return( <div { ...blockProps }> <InnerBlocks.Content /> </div> ) }, });

Peningkatan Tambahan

Blok kami berfungsi penuh, tetapi kami dapat memperbaikinya sedikit dengan beberapa perubahan kecil.

Kami menetapkan atribut backgroundColor ke paragraf yang dihasilkan oleh komponen RichText . Namun, kami mungkin lebih suka menetapkan warna latar belakang ke wadah div :

Jadi, ubah file edit.js dan save.js div s sebagai berikut:

 <div { ...blockProps } style={ { backgroundColor: backgroundColor } } > ... </div>

Ini akan memungkinkan pengguna untuk mengubah latar belakang seluruh blok.

Di sisi lain, perubahan yang lebih relevan melibatkan metode useBlockProps . Dalam kode asli, kami mendefinisikan blockProps konstan sebagai berikut:

 const blockProps = useBlockProps();

Tetapi kita dapat menggunakan useBlockProps dengan lebih efektif dengan melewatkan sekumpulan properti. Misalnya, kita dapat mengimpor nama classnames dari classnames nama kelas dan mengatur nama kelas pembungkus yang sesuai.

Dalam contoh berikut, kami menetapkan nama kelas berdasarkan nilai atribut align ( edit.js ):

 import classnames from 'classnames'; ... export default function Edit( { attributes, setAttributes } ) { ... const blockProps = useBlockProps( { className: classnames( { [ `has-text-align-${ align }` ]: align, } ) } ); ... }

Kami akan melakukan perubahan yang sama pada file save.js :

 import classnames from 'classnames'; ... export default function save( { attributes } ) { ... const blockProps = useBlockProps.save({ className: classnames( { [ `has-text-align-${ align }` ]: align, } ) }); ... }

Dan itu bungkus! Anda sekarang dapat menjalankan build untuk produksi.

Ringkasan

Dan di sinilah kita, di akhir perjalanan yang luar biasa ini! Kami mulai dengan konfigurasi lingkungan pengembangan dan akhirnya membuat tipe blok lengkap.

Seperti yang kami sebutkan di pendahuluan, pengetahuan yang kuat tentang Node.js, Webpack, Babel, dan React sangat penting untuk membuat blok Gutenberg tingkat lanjut dan memposisikan diri Anda di pasar sebagai pengembang Gutenberg profesional.

Tetapi Anda tidak perlu memiliki pengalaman React yang mapan untuk mulai bersenang-senang dengan pengembangan blok. Pengembangan blok dapat memberi Anda motivasi dan tujuan untuk mendapatkan keterampilan yang semakin luas dalam teknologi di balik blok Gutenberg.

Oleh karena itu, panduan ini masih jauh dari kesempurnaan. Ini hanyalah pengantar untuk berbagai topik yang akan membantu Anda mulai membangun blok Gutenberg pertama Anda.

Untuk alasan ini, kami sarankan Anda memperdalam pengetahuan Anda dengan membaca dokumentasi dan panduan online dengan cermat. Di antara banyak sumber daya yang tersedia di luar sana, kami merekomendasikan hal berikut:

• Resmi Buat Tutorial Blok untuk pemula
• Tutorial Blok Resmi untuk pengembang menengah
• Blok Dinamis
• Kotak Meta
• Membuat Bilah Sisi untuk Plugin Anda

Jika Anda baru memulai pengembangan WordPress, Anda mungkin ingin memahami konsep dasar pengembangan frontend. Berikut adalah daftar cepat sumber daya yang dapat membantu Anda memulai:

• Cara Install WordPress Lokal (ebook gratis)
• Nilai Nyata Managed WordPress Hosting (ebook gratis)
• Apa itu JavaScript?
• HTML vs HTML5
• Cara Mengedit CSS di WordPress
• Apa Itu PHP?
• Bootcamp WordPress Hooks: Cara Menggunakan Actions, Filters, dan Custom Hooks

Dan ingat bahwa kode lengkap dari contoh panduan ini tersedia di Gist.

Sekarang giliran Anda: Sudahkah Anda mengembangkan blok Gutenberg? Apa kesulitan utama yang Anda alami sejauh ini? Beri tahu kami tentang pengalaman Anda di komentar!