Advertisement
  1. Code
  2. WordPress Gutenberg

WordPress Gutenberg Block API: Membuat Blok Khusus

Scroll to top
Read Time: 17 min
This post is part of a series called WordPress Gutenberg Block API.
WordPress Gutenberg Block API: Block Look and Feel
WordPress Gutenberg Block API: Extending Blocks

Indonesian (Bahasa Indonesia) translation by Ilham Saputra (you can also view the original English article)

Editor WordPress baru (nama kode Gutenberg) akan dirilis pada versi 5.0. Sekarang adalah waktu yang tepat untuk mencengkeramnya sebelum masuk ke inti WordPress. Dalam seri ini, saya menunjukkan kepada Anda cara bekerja dengan Block API dan membuat blok konten Anda sendiri yang dapat Anda gunakan untuk membuat posting dan halaman Anda.

Dalam posting sebelumnya, kami melihat bagaimana menggunakan toolkit create-guten-block untuk membuat sebuah plugin yang berisi blok sampel yang siap untuk kami kerjakan. Kami dapat dengan mudah memperpanjang ini sesuai kebutuhan, tetapi itu ide yang baik untuk mengetahui cara membuat blok dari awal untuk sepenuhnya memahami semua aspek pengembangan blok Gutenberg.

Dalam posting ini kita akan membuat blok kedua di plugin my-custom-block kami untuk menampilkan gambar acak dari layanan web PlaceIMG. Anda juga dapat menyesuaikan blok dengan memilih kategori gambar dari kontrol pilih drop-down.

Tapi pertama-tama kita akan belajar bagaimana memblokir skrip dan gaya yang diantisipasi sebelum beralih ke fungsi registerBlockType() yang sangat penting, yang sangat penting untuk membuat blok di Gutenberg.

Enqueueing Block Scripts and Styles

Untuk menambahkan JavaScript dan CSS yang dibutuhkan oleh blok kami, kami dapat menggunakan dua kait WordPress baru yang disediakan oleh Gutenberg:

  • enqueue_block_editor_assets
  • enqueue_block_assets

Ini hanya tersedia jika plugin Gutenberg aktif, dan mereka bekerja dengan cara yang mirip dengan kait WordPress standar untuk skrip yang mengiringi. Namun, mereka dimaksudkan khusus untuk bekerja dengan blok Gutenberg.

Hook enqueue_block_editor_assets menambahkan skrip dan gaya hanya ke editor admin. Ini membuatnya ideal untuk enqueueing JavaScript untuk mendaftarkan blok dan CSS untuk menata elemen antarmuka pengguna untuk pengaturan blok.

Namun, untuk keluaran blok, Anda akan ingin balok Anda dirender sama di editor seperti yang mereka lakukan di bagian depan sebagian besar waktu. Menggunakan enqueue_block_assets menjadikan ini mudah karena gaya ditambahkan secara otomatis ke editor dan front end. Anda juga dapat menggunakan hook ini untuk memuat JavaScript jika diperlukan.

Namun Anda mungkin bertanya-tanya bagaimana cara membuat sketsa dan gaya hanya di bagian depan. Tidak ada hook WordPress yang memungkinkan Anda melakukan ini secara langsung, tetapi Anda bisa menyelesaikannya dengan menambahkan pernyataan kondisional di dalam fungsi callback hook enqueue_block_assets.

Untuk benar-benar mengiringi skrip dan gaya menggunakan dua kait baru ini, Anda dapat menggunakan fungsi wp_enqueue_style() dan wp_enqueue_scripts() seperti biasa.

Namun, Anda perlu memastikan bahwa Anda menggunakan ketergantungan skrip yang benar. Untuk memasukkan skrip pada editor, Anda dapat menggunakan dependensi berikut:

  • scripts: array( 'wp-blocks', 'wp-i18n', 'wp-element', 'wp-components' )
  • styles: array( 'wp-edit-blocks' )

Dan ketika style enqueue untuk editor dan front end, Anda dapat menggunakan ketergantungan ini:

  • array( 'wp-blocks' )

Satu hal yang perlu disebutkan di sini adalah bahwa file aktual yang di-enqueued oleh plugin my-custom-block kami adalah versi compiled dari JavaScript dan CSS dan bukan file yang berisi kode sumber JSX dan Sass.

Ini adalah sesuatu yang harus diingat ketika secara manual melakukan enqueueing file. Jika Anda mencoba memasukkan kode sumber mentah yang mencakup Bereaksi, ES6+, atau Sass, maka Anda akan menemui banyak kesalahan.

Inilah mengapa sangat berguna untuk menggunakan toolkit seperti create-guten-block saat memproses dan mengantre skrip untuk Anda secara otomatis!

Mendaftar Gutenberg Blocks

Untuk membuat blok baru, kita perlu mendaftarkannya dengan Gutenberg dengan memanggil registerBlockType() dan meneruskan nama blok ditambah objek konfigurasi. Objek ini memiliki beberapa properti yang membutuhkan penjelasan yang tepat.

Pertama-tama, mari kita lihat nama blokirnya. Ini adalah parameter pertama dan merupakan string yang terdiri dari dua bagian, namespace dan nama blok itu sendiri, dipisahkan oleh karakter garis miring.

Sebagai contoh:

Jika Anda mendaftarkan beberapa blok dalam sebuah plugin, maka Anda dapat menggunakan namespace yang sama untuk mengatur semua blok Anda. Namespace harus unik untuk plugin Anda, meskipun, yang membantu mencegah konflik penamaan. Ini bisa terjadi jika blok dengan nama yang sama sudah terdaftar melalui plugin lain.

Parameter registerBlockType() yang kedua adalah objek pengaturan dan membutuhkan sejumlah properti yang akan ditentukan:

  • title (string): ditampilkan di editor sebagai label blok yang dapat dicari
  • description (string opsional): menjelaskan tujuan dari sebuah blok
  • icon (opsional Dashicon atau elemen JSX): ikon yang terkait dengan satu blok
  • category (string): di mana blok muncul di dialog Tambahkan blok
  • keywords (array opsional): hingga tiga kata kunci yang digunakan dalam pencarian blok
  • attributes (objek opsional): menangani data blok dinamis
  • edit (fungsi): fungsi yang mengembalikan markup yang akan diberikan di editor
  • save (function): fungsi yang mengembalikan markup yang akan ditampilkan di ujung depan
  • useOnce (boolean opsional): batasi blok agar tidak ditambahkan lebih dari satu kali
  • supports (objek opsional): mendefinisikan fitur yang didukung blok

Dengan asumsi kami menggunakan JSX untuk pengembangan blok, inilah contoh registerBlockType() yang dapat terlihat seperti untuk blok yang sangat sederhana:

Perhatikan bagaimana kami tidak menyertakan entri untuk descriptionattributesuseOnce, and supports properti? Bidang apa pun yang opsional (dan tidak relevan dengan blok Anda) dapat dihilangkan dengan aman. Misalnya, karena blok ini tidak melibatkan data dinamis apa pun, kita tidak perlu khawatir tentang menentukan atribut apa pun.

Sekarang mari kita bahas properti objek konfigurasi registerBlockType() secara lebih detail satu per satu.

Judul dan Deskripsi

Saat memasukkan atau mencari blok di editor, judul akan ditampilkan dalam daftar blok yang tersedia.

Ini juga ditampilkan di jendela blok inspektur, bersama dengan deskripsi blok jika didefinisikan. Jika inspektor blok saat ini tidak terlihat, Anda dapat menggunakan ikon roda gigi di sudut kanan atas editor Gutenberg untuk beralih visibilitas.

Block title and descriptionBlock title and descriptionBlock title and description

Baik bidang judul dan deskripsi idealnya harus dibungkus dalam fungsi i18n untuk memungkinkan terjemahan ke bahasa lain.

Kategori

Ada lima kategori blok yang saat ini tersedia:

  • common
  • formatting
  • layout
  • widgets
  • embed

Ini menentukan bagian kategori di mana blok Anda tercantum di dalam jendela Tambahkan blok.

Block categoriesBlock categoriesBlock categories

Tab Blok berisi kategori Common BlocksFormattingLayout Elements, and Widgets, sedangkan kategori Embeds memiliki tab sendiri.

Kategori saat ini diperbaiki di Gutenberg, tetapi ini dapat berubah di masa depan. Ini akan berguna, misalnya, jika Anda mengembangkan banyak blok dalam satu plugin dan Anda ingin semuanya dicantumkan di bawah kategori umum sehingga pengguna dapat menemukannya dengan lebih mudah.

Icon

Secara default, blok Anda ditetapkan dengan Dashicon perisai, tetapi Anda dapat menimpanya dengan menentukan Dashicon khusus di bidang icon.

DashiconsDashiconsDashicons

Setiap Dashicon diawali dengan dashicons- diikuti oleh string unik. Misalnya, ikon roda gigi memiliki nama dashicons-admin-generic. Untuk menggunakan ini sebagai ikon blokir, cukup hapus dashicons- awalan-awalan untuk itu agar dikenali, mis. icon: 'admin-generic'.

Namun, Anda tidak hanya terbatas menggunakan Dashicons sebagai properti ikon. Fungsi ini juga menerima elemen JSX, yang berarti Anda dapat menggunakan gambar atau elemen SVG sebagai ikon blok Anda.

Pastikan untuk menjaga ukuran ikon konsisten dengan ikon blok lainnya, yaitu 20 x 20 piksel secara default.

Keywords

Pilih hingga tiga kata kunci yang dapat diterjemahkan untuk membantu membuat blok Anda menonjol ketika pengguna mencari sebuah blok. Sebaiknya pilih kata kunci yang terkait erat dengan fungsi blok Anda untuk hasil terbaik.

Anda bahkan dapat menyatakan nama perusahaan dan / atau plugin Anda sebagai kata kunci sehingga jika Anda memiliki beberapa blok, pengguna dapat mulai mengetikkan nama perusahaan Anda dan semua pemblokiran Anda akan muncul dalam hasil pencarian.

Meskipun menambahkan kata kunci sepenuhnya opsional, ini adalah cara yang bagus untuk mempermudah pengguna menemukan blok Anda.

Attributes

Atribut membantu mengelola data dinamis dalam satu blok. Properti ini opsional karena Anda tidak membutuhkannya untuk blok yang sangat sederhana yang menghasilkan konten statis.

Namun, jika blok Anda berhubungan dengan data yang dapat berubah (seperti isi area teks yang dapat diedit) atau Anda perlu menyimpan pengaturan blok, kemudian menggunakan atribut adalah cara untuk pergi.

Atribut bekerja dengan menyimpan data blok dinamis baik di konten posting yang disimpan ke database atau di pos meta. Dalam tutorial ini kita hanya akan menggunakan atribut yang menyimpan data bersama dengan konten posting.

Untuk mengambil data atribut yang disimpan dalam konten posting, kita perlu menentukan di mana letaknya di markup. Kita dapat melakukan ini dengan menentukan pemilih CSS yang mengarah ke data atribut.

Misalnya, jika blok kami berisi tag anchor, kita dapat menggunakan bidang title sebagai atribut kami sebagai berikut:

Di sini, nama atribut adalah linktitle, yang merupakan string acak dan dapat berupa apa pun yang Anda suka.

Sebagai contoh, kita bisa menggunakan atribut ini untuk menyimpan link judul <a title="some title"> yang telah dimasukkan melalui textbox di tataan Blokir. Melakukan begitu tiba-tiba membuat title field dinamis dan memungkinkan Anda untuk mengubah nilai dalam editor.

Ketika posting disimpan, nilai atribut dimasukkan ke dalam bidang title tautan. Demikian pula, ketika editor dimuat, nilai tag title diambil dari konten dan dimasukkan ke dalam atribut linktitle.

Ada banyak cara Anda dapat menggunakan source untuk menentukan bagaimana konten blok disimpan atau diambil melalui atribut. Misalnya, Anda dapat menggunakan sumber 'teks' untuk mengekstrak teks bagian dalam dari elemen paragraf.

Anda juga dapat menggunakan sumber children untuk mengekstrak semua simpul anak dari suatu elemen ke dalam larik dan menyimpannya dalam sebuah atribut.

Ini memilih elemen dengan class .parent dan menyimpan semua node anak di atribut editablecontent.

Jika Anda tidak menentukan sumber, maka nilai atribut disimpan dalam komentar HTML sebagai bagian dari markup pos saat disimpan ke database. Komentar-komentar ini dilucuti sebelum pos diberikan di bagian depan.

Kita akan melihat contoh spesifik dari jenis atribut ini ketika kita masuk ke menerapkan blok gambar acak kami nanti dalam tutorial ini.

Atribut dapat sedikit membiasakan diri, jadi jangan khawatir jika Anda tidak sepenuhnya memahaminya untuk pertama kalinya. Saya akan merekomendasikan untuk melihat bagian attributes buku pegangan Gutenberg untuk rincian dan contoh lebih lanjut.

Edit

Fungsi edit mengontrol bagaimana blok Anda muncul di dalam antarmuka editor. Data dinamis dilewatkan ke setiap blok sebagai props, termasuk atribut khusus apa pun yang telah ditetapkan.

Ini adalah praktik umum untuk menambahkan className={ props.className } ke elemen blok utama untuk menghasilkan kelas CSS khusus untuk blok Anda. WordPress tidak menambahkan ini untuk Anda di dalam editor, jadi itu harus ditambahkan secara manual untuk setiap blok jika Anda ingin memasukkannya.

Menggunakan props.className adalah praktik standar dan disarankan karena menyediakan cara untuk menyesuaikan gaya CSS untuk setiap blok individual. Format kelas CSS yang dihasilkan adalah .wp-block-{namespace}-{name}. Seperti yang Anda lihat, ini didasarkan pada nama ruang blok / nama dan membuatnya ideal untuk digunakan sebagai pengidentifikasi blok yang unik.

Fungsi edit mengharuskan Anda mengembalikan markup yang valid melalui metode render(), yang kemudian digunakan untuk membuat blok Anda di dalam editor.

Save

Serupa dengan fungsi edit, save menampilkan representasi visual dari blok Anda tetapi di ujung depan. Ini juga menerima data blok dinamis (jika didefinisikan) melalui alat peraga.

Satu perbedaan utama adalah bahwa props.className tidak tersedia di dalam save, tetapi ini bukan masalah karena dimasukkan secara otomatis oleh Gutenberg.

Supports

Properti supports menerima objek nilai boolean untuk menentukan apakah blok Anda mendukung fitur inti tertentu.

Properti obyek yang tersedia yang Anda dapat menetapkan adalah sebagai berikut.

  • anchor (default false): memungkinkan Anda untuk menautkan langsung ke blok tertentu
  • customClassName (true): menambahkan bidang di inspektur blok untuk mendefinisikan className kustom untuk blok
  • className (true): menambahkan className blok akar elemen berdasarkan nama blok
  • html (ture): memungkinkan markup blok yang akan diedit secara langsung

useOnce Property

Ini adalah properti yang berguna yang memungkinkan Anda membatasi blok agar tidak ditambahkan lebih dari sekali ke suatu halaman. Contoh dari ini adalah inti More blok, yang tidak dapat ditambahkan ke halaman jika sudah ada.

useOnce propertyuseOnce propertyuseOnce property

Seperti yang Anda lihat, setelah blok More Lainnya ditambahkan, ikon blok menjadi abu-abu dan tidak dapat dipilih. Properti useOnce disetel ke false secara default.

Mari Berkreasi!

Sudah waktunya sekarang untuk menggunakan pengetahuan yang kami peroleh sejauh ini untuk mengimplementasikan contoh kerja yang solid dari sebuah blok yang melakukan sesuatu yang lebih menarik daripada hanya menampilkan konten statis.

Kami akan membuat blok untuk menghasilkan gambar acak yang diperoleh melalui permintaan eksternal ke situs web PlaceIMG, yang mengembalikan gambar acak. Selanjutnya, Anda akan dapat memilih kategori gambar yang dihasilkan melalui kontrol tarik-turun pilihan.

Our random image blockOur random image blockOur random image block

Untuk kenyamanan, kami akan menambahkan blok baru kami ke plugin my-custom-block yang sama, daripada membuat plugin baru. Kode untuk blok default terletak di dalam folder / src/block, jadi tambahkan folder lain di dalam /src yang disebut random-image dan tambahkan tiga file baru:

  • index.js: register blok baru kami
  • editor.scss: untuk style editor
  • style.scss: style untuk editor dan front end

Atau, Anda dapat menyalin folder /src/block dan mengganti namanya jika Anda tidak ingin mengetik semuanya dengan tangan. Pastikan, meskipun, untuk mengganti nama block.js ke index.js di dalam folder blok baru.

Kami menggunakan index.js untuk nama file blok utama karena ini memungkinkan kami menyederhanakan pernyataan impor di dalam blocks.js. Daripada harus memasukkan path dan nama file penuh dari blok, kita bisa menentukan path ke folder block, dan import akan secara otomatis mencari file index.js.

Membuka /src/blocks.js dan menambahkan referensi ke blok baru kami di bagian atas dari file, secara langsung di bawah yang ada impor pernyataan.

Di dalam /src/random-image/index.js, tambahkan kode berikut untuk memulai kami baru blok.

Ini mengatur kerangka blok kami dan sangat mirip dengan kode blok boilerplate yang dihasilkan oleh toolkit create-guten-block.

Kami mulai dengan mengimpor editor dan style sheet front-end, dan kemudian kami akan mengekstrak beberapa fungsi yang biasa digunakan dari wp.i18n dan wp.blocks ke variabel lokal.

Di dalam registerBlockType(), nilai telah dimasukkan untuk properti titleiconcategory, and keywords, sementara fungsi edit dan save saat ini hanya menampilkan konten statis.

Tambahkan blok gambar acak ke halaman baru untuk melihat output yang dihasilkan sejauh ini.

Bare bones block outputBare bones block outputBare bones block output

Pastikan Anda masih menonton file untuk perubahan sehingga setiap kode sumber pemblokiran (JSX, ES6 +, Sass, dll.) Diupload ke JavaScript dan CSS yang valid. Jika Anda saat ini tidak sedang menonton file untuk perubahan, kemudian buka jendela baris perintah di dalam folder root plugin my-custom-block dan masukkan npm start.

Anda mungkin bertanya-tanya mengapa kami tidak perlu menambahkan kode PHP untuk memasukkan skrip blok tambahan. Skrip blok untuk blok my-custom-block di enqueued melalui init.php, tetapi kami tidak perlu memasukkan skrip khusus untuk blok baru kami karena ini diurus untuk kami dengan create-guten-block.

Selama kita mengimpor file blok utama kami ke src/blocks.js (seperti yang kita lakukan di atas) maka kita tidak perlu untuk melakukan pekerjaan tambahan. Semua BEJ, ES6+, dan Sass kode secara otomatis dapat dikompilasi ke dalam file-file berikut:

  • dist/blocks.style.build.css: style untuk editor dan front end
  • dist/blocks.build.js: JavaScript hanya untuk editor
  • dist/blocks.editor.build.css: styles hanya untuk editor

File-file ini berisi JavaScript dan CSS untuk semua blok, jadi hanya satu set file yang perlu di-enqueued, terlepas dari jumlah blok yang dibuat!

Kami sekarang siap untuk menambahkan sedikit interaktivitas ke blok kami, dan kami dapat melakukannya dengan terlebih dahulu menambahkan atribut untuk menyimpan kategori gambar.

Ini membuat category atribut yang disebut, yang menyimpan string dengan nilai default 'nature'. Kami tidak menentukan lokasi di markup untuk menyimpan dan mengambil nilai atribut, sehingga komentar khusus HTML akan digunakan sebagai gantinya. Ini adalah perilaku default jika Anda mengabaikan sebuah sumber atribut.

Kami memerlukan beberapa cara mengubah kategori gambar, yang dapat kami lakukan melalui kontrol drop-down pilih. Perbarui fungsi edit ke yang berikut:

Berikut adalah apa yang akan terlihat seperti:

Adding a block select drop down controlAdding a block select drop down controlAdding a block select drop down control

Ini sangat berbeda dari fungsi edit statis sebelumnya, jadi mari kita jalankan melalui perubahan.

Pertama-tama kami telah menambahkan kontrol drop-down pilihan dengan beberapa pilihan yang cocok dengan kategori gambar yang tersedia di situs PlaceIMG.

PlaceIMG image categoriesPlaceIMG image categoriesPlaceIMG image categories

Ketika nilai drop-down berubah, fungsi setCategory dipanggil, yang menemukan kategori yang sedang dipilih dan kemudian memanggil fungsi setAttributes. Ini adalah fungsi Gutenberg inti dan memperbarui nilai atribut dengan benar. Disarankan agar Anda hanya memperbarui atribut menggunakan fungsi ini.

Sekarang, setiap kali kategori baru dipilih, pembaruan nilai atribut dan diteruskan kembali ke fungsi edit, yang memperbarui pesan output.

Image category updatedImage category updatedImage category updated

Kami harus menyelesaikan satu langkah terakhir untuk mendapatkan gambar acak untuk ditampilkan. Kita perlu membuat komponen sederhana yang akan mengambil kategori saat ini dan mengeluarkan tag <img> dengan gambar acak yang diperoleh dari situs PlaceIMG.

Permintaan yang kami perlukan untuk PlaceIMG adalah formulir: https://placeimg.com/[width]/[height]/[category]

Kami akan menjaga lebar dan tinggi tetap untuk saat ini, jadi kami hanya perlu menambahkan kategori saat ini ke bagian akhir URL permintaan. Misalnya, jika kategori itu 'nature' maka URL permintaan lengkapnya adalah: https://placeimg.com/320/220/nature.

Tambahkan komponen RandomImage di atas registerBlockType():

Untuk menggunakannya, tambahkan saja di dalam fungsi edit dan hapus pesan output statis. Sementara kita melakukannya, lakukan hal yang sama untuk fungsi penyimpanan.

File index.js lengkap seharusnya sekarang terlihat seperti ini:

Akhirnya (untuk sekarang), tambahkan style berikut ke editor.scss untuk menambahkan border berwarna di sekitar gambar.

Anda juga memerlukan beberapa gaya dalam style.css.

Setiap kali halaman disegarkan di editor atau di ujung depan, gambar acak baru akan ditampilkan.

Finished editor viewFinished editor viewFinished editor view
Final front end viewFinal front end viewFinal front end view

Jika Anda melihat gambar yang sama ditampilkan berulang-ulang, Anda dapat melakukan hard refresh untuk mencegah gambar disajikan dari cache browser Anda.

Kesimpulan

Dalam tutorial ini kami telah membahas banyak hal. Jika Anda berhasil melewati semua itu, beri tepukan yang layak di punggung Anda! Pengembangan blok Gutenberg dapat menjadi sangat menyenangkan, tetapi sangat menantang untuk memahami setiap konsep pada paparan pertama.

Di sepanjang jalan, kami telah belajar bagaimana meng-enqueue memblokir skrip dan gaya dan menutupi fungsi registerBlockType() secara mendalam.

Kami mengikutinya dengan menerapkan teori dan membuat blok khusus dari awal untuk menampilkan gambar acak dari kategori tertentu menggunakan layanan web PlaceIMG.

Di bagian berikutnya dan terakhir dari seri tutorial ini, kami akan menambahkan lebih banyak fitur ke blok gambar acak kami melalui panel pengaturan di inspektur blok.

Jika Anda telah mengikuti tutorial ini dan hanya ingin bereksperimen dengan kode tanpa mengetik semuanya, Anda akan dapat mengunduh plugin akhir my-custom-block di tutorial berikutnya.

Advertisement
Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.