У цій частині ми напишемо Javascript для реєстрації та налаштування нашого спеціального блоку. Наприкінці ми зареєструємо скрипт у PHP і створимо необхідний код PHP, щоб WordPress розпізнав його як новий блок.
Спочатку коротко про те, як отримати доступ до функцій і компонентів WordPress Gutenberg.
Глобальний wpпакет і деструктуризація
Коли ми знаходимося у файлі Javascript, поставленому в чергу в редакторі Гутенберга, ми маємо доступ до глобального об’єкта/пакета: wp. Це дуже великий об’єкт Javascript, який містить цілу купу корисних компонентів і функцій, які ми будемо використовувати для створення блоків. Під час написання Javascript для спеціальних блоків ви будете посилатися на wpдосить багато.
Тому як у сучасному Javascript, так і в React прийнято деструктурувати те, що ми хочемо використовувати. По суті, це просто означає, що ми визначаємо локальні змінні з частин більшої структури. Наприклад, перша функція, яку ми будемо використовувати registerBlockType(), існує в wp.blocks. Ми могли б викликати функцію так:
wp.blocks.registerBlockType();Але деструктурувати його простіше так:
const { registerBlockType } = wp.blocks;
registerBlockType();Тепер ви можете звертатися до функції безпосередньо без префікса її структури. Це стає набагато кориснішим, коли ми посилаємося на функції чи компоненти, які часто повторюємо.
Ми зробимо реструктуризацію в цій серії, і, просуваючись у підручнику, ми побачимо, наскільки читабельнішим і коротшим стане наш код.
Реєстрація нового блоку
У пакеті registerBlockType()доступна функція реєстрації нового власного блоку. wp.blocksВін приймає два параметри; по-перше, рядок із простором імен та ім’ям блоку, а по-друге, об’єкт із повною конфігурацією блоку.
Гутенберг очікує, що всі блоки мають простір імен і ім’я, визначене косою рискою між ними. Простір імен призначений для того, щоб назва вашого блоку не конфліктувала з будь-якими іншими блоками, які можуть використовувати те саме ім’я. Усі блоки в WordPress використовують простір імен core. Наприклад, стандартний блок абзаців у WordPress має назву core/paragraph. Якщо ви виберете інший простір імен, ви також можете створити блок під назвою абзац без проблем.
Виберіть унікальний простір імен slug-версії. У цій серії я буду використовувати простір імен awp(коротку версію A White Pixel).
Відкрийте вихідний файл, який ми створили на останньому кроці; src/block-awhitepixel-myfirstblock.js, в редакторі. Спочатку ми зателефонуємо registerBlockTypeз destructured wp.blocksпід назвою awp/firstblock. Налаштуйте своє ім’я та простір імен по ходу роботи.
const { registerBlockType } = wp.blocks;
registerBlockType('awp/firstblock', {
// Your block configuration and code here
});У другому параметрі, об’єкті конфігурації блоку, нам потрібно визначити кілька властивостей, щоб його було успішно зареєстровано. Пам’ятайте, що конфігурація блоку є об’єктом, а це означає, що вам потрібно записати все як пари ключ + значення, розділені комами. Існує чимало можливих властивостей конфігурації, тому давайте переглянемо їх, і ми побачимо остаточний код у кінці.
Обов’язково: назва
Першою необхідною властивістю є title. Це ім’я, яке відображатиметься під час вибору між блоками. Встановіть цю властивість як будь-яке ім’я в рядку.
Ми додамо наступне як назву:
title: 'My first block',PS: ми переглянемо, як ми пишемо всі рядки в нашому блоці, щоб переконатися, що вони можуть бути перекладені в частині 8. Але поки що ми збережемо це просто і просто будемо писати рядки.
Необхідно: категорія
Властивість categoryвизначає, де в якій категорії блоку з’являтиметься ваш блок, коли ви виберете блоки для вставлення в редакторі. Можливі значення: common, formatting, layout, widgets, embed.
Давайте помістимо його в commonпершу категорію блоку.
category: 'common',Додатково: значок
Якщо ви користувалися Gutenberg, то, мабуть, помітили, що всі блоки мають піктограми. Ви можете додати піктограму до свого блоку за допомогою рядка, який посилається на будь-який із Dashicons WordPress, або ви можете надати спеціальний svgелемент.
Я просто виберу один із значків WordPress, смайлик, але ви можете вибрати будь-який, який хочете. Зауважте, що ви пропускаєте включення «dashicons-» у назву класу значка.
icon: 'smiley',Додатково: опис
Ви можете надати опис, який відображатиметься на бічній панелі налаштувань (праворуч), коли блок активний.
Я просто додам короткий текст як приклад:
description: 'Learning in progress',Додатково: ключові слова
Gutenberg підтримує функцію пошуку під час вибору типів блоків. Ви можете надати масив можливих збігів у властивості keywords. Без keywordsнього ви б знайшли свій блок лише за його назвою.
Я додам exampleі test, щоб ми могли легко знайти наш спеціальний блок, починаючи вводити одне з цих ключових слів.
keywords: ['example', 'test'],Необов’язково: атрибути
Властивість attributes— це дуже важлива властивість, яку ми будемо часто повертати в цій серії посібників. Тут ви зберігаєте свої структуровані дані та інформацію, введену користувачем для вашого блоку. Ви можете уявити це як змінні. Наразі ми не додамо його, але незабаром обов’язково повернемося до цього.
(Начебто) потрібно: редагувати та необов’язково: зберегти
Всередині editта saveвластивості фактично куди ви додасте весь свій код як для виводу редактора, так і для візуалізації інтерфейсу. Обидві ці властивості очікують функції, яка має повернути певний результат.
Властивість editописує структуру вашого блоку в редакторі. Власність в saveосновному обробляє дві речі; вихід вашого блоку у інтерфейсі, а також структуру того, як ваш блок зберігається в базі даних. Ви здебільшого працюватимете edit, оскільки саме тут ви додаєте вхідні дані для введення або вибору речей і оновлення даних блоку. Функція saveне повинна оновлювати чи редагувати дані жодним чином, вона має лише виводити.
Гутенбергу потрібно мати можливість реконструювати ваш блок із усіма його налаштуваннями в редакторі з того, що виводиться у saveфункції (та атрибутах). Якщо Гутенберг коли-небудь відкриє публікацію, у якій попередньо збережений вихід блоку відрізняється (навіть незначно) від того, що визначено під час збереження, ваш блок стане недійсним.
Я можу гарантувати вам, що ви часто стикатиметеся з цим під час розробки спеціальних блоків. Коли це станеться, вам потрібно видалити блок (з крапок на панелі інструментів) і додати його знову. Рекомендую також оновити браузер (F5 або CTRL+R).
У WordPress є спеціальна сторінка документації для функцій редагування та збереження блоку, якщо ви хочете дізнатися більше.
Що стосується нашого першого блоку, давайте виведемо щось базове. Ми повернемо те саме для обох editі save; «:)», загорнутий у <div>. Піктограма блоку все-таки є смайликом.
Інші властивості
Є додаткові властивості для registerBlockType; parent, supports, transforms, example, і styles. Наразі ми пропустимо їх, оскільки більшість призначено для більш просунутого або індивідуального блокового будівництва. Якщо вам цікаво прочитати більше про це, перегляньте документацію WordPress.
Кінцевий блоковий код регістру
Зараз наш код виглядає приблизно так.
Таким чином, у нас достатньо, щоб наш блок був успішно зареєстрований як власний блок. Побачимо це на практиці в редакторі Gutenberg.
Ви не забули скомпілювати свій Javascript? У попередньому кроці ми дізналися, що ми не можемо завантажити цей файл Javascript у Gutenberg; нам потрібна скомпільована версія. Зазвичай ви розвиваєтеся, npm run startпрацюючи у фоновому режимі, або можете просто запустити npm run buildодин раз. Це повинно скомпілювати наш вихідний Javascript і розмістити його там, де ви визначили його для розміщення та імені у вашому webpack.config.js.
PHP частина реєстрації блоку
Для кожного блоку вам потрібно зареєструвати файл Javascript, і це так само, як ви реєструєте будь-які інші сценарії в WordPress – за допомогою [wp_register_script](https://developer.wordpress.org/reference/functions/wp_register_script/)(). Зауважте, що ми реєструємо сценарій, а не ставимо його в чергу. Це пояснюється тим, що нам також потрібно викликати функцію PHP для реєстрації кожного спеціального блоку, і ця функція відповідає за додавання сценарію в чергу, коли це необхідно.
Я вважаю за краще зберігати код, пов’язаний з Гутенбергом, в окремому файлі в моїх темах. Але ви можете, і ми це зробимо в цьому підручнику, просто написати весь код PHP безпосередньо всередині теми functions.phpзаради простоти.
Я рекомендую використовувати initхук для вашої функції, а не enqueue_block_assets. Ми можемо поєднати як реєстрацію сценарію, так і реєстрацію блоку.
Функція PHP, яку ми будемо використовувати для реєстрації нового блоку, це [register_block_type](https://developer.wordpress.org/reference/functions/register_block_type/)(). Подібно до Javascript, registerBlockType()він приймає два параметри; простір імен і ім’я блоку, а також масив з аргументами. Переконайтеся, що ви надали той самий простір імен і назву в PHP, що й у Javascript.
У другому аргументі є кілька можливих аргументів (до деяких із них ми повернемося пізніше в цій серії). Але найважливішим є те, editor_scriptде ви надаєте дескриптор (перший параметр wp_register_script()) зареєстрованого сценарію.
І це все!
Наш блок у редакторі Gutenberg
Тепер, коли ви оновлюєте редактор у якійсь публікації, ви маєте знайти наш блок – або відкривши загальну категорію, або здійснивши пошук за будь-яким із наданих вами ключових слів чи імені.
Наш блок відтворює простий «:)» як у редакторі, так і в інтерфейсі. Наразі ви не можете нічого редагувати в блоці, але це те, що ми дізнаємось у наступних кроках!