Додайте спеціальну бічну панель інспектора в WordPress Gutenberg за допомогою Post Meta

У цьому посібнику ми розглянемо, як додати спеціальну бічну панель до інспектора (права бічна панель) у WordPress Gutenberg. Усередині ми реалізуємо поле, пов’язане з мета допису. Усе реалізовано за допомогою Javascript у редакторі Gutenberg і є альтернативою традиційному додаванню метабоксів.

Голови вгору!

Це підручник зі створення власної бічної панелі. Але якщо ви хочете просто додати мета/налаштування до стандартної бічної панелі інспектора (вкладка «Документ»), у мене є підручник саме для цього:

Що ми створимо

WordPress Gutenberg дозволяє розробникам створювати власні бічні панелі за допомогою створення так званого плагіна Javascript. (Не плутати з традиційними плагінами WordPress). Використовуючи плагін Javascript, ми можемо створити нову бічну панель, а також підключити її до меню «Інструменти та параметри».

Ми додамо новий пункт меню в «Інструменти», який відкриє нашу спеціальну бічну панель. Вміст бічної панелі залежить виключно від вас, але я наведу кілька прикладів, зокрема те, як підключити мета-поле допису всередині неї.

Налаштування вашого Javascript

Для цього підручника я напишу ES6/ESNext Javascript з JSX, що означає, що нам потрібно налаштувати компілятор. Якщо ви хочете продовжувати, а не писати ES5 Javascript, вам потрібно буде налаштувати середовище розробки, яке компілює ваш Javascript під час роботи. Якщо ви не знайомі з цим, перегляньте мій допис із поясненнями, як це налаштувати, а потім поверніться сюди.

Я налаштував webpack.config.jsкомпіляцію вихідного файлу Javascript у папку теми /assets/js/sidebar-plugin.js. Цей скомпільований файл – це те, що нам потрібно поставити в чергу до редактора Gutenberg. Поки я пишу цей код, я запускаю компілятор під час виконання, який перекомпілює Javascript щоразу, коли я зберігаю зміни у вихідному коді (npm run start). Усе це докладно пояснюється у згаданому вище посібнику.

Я пишу це в темі, але це так само працює в плагіні. Тільки не забудьте налаштувати шляхи під час додавання сценарію до редактора.

Додавання скрипта в редактор

Щоб додати наш скрипт до редактора Gutenberg, нам потрібно написати трохи PHP. Якщо ви перебуваєте в темі, functions.phpце гарне місце для початку або десь у ваших файлах плагінів. Зауважте, що нам потрібно додати остаточний скомпільований сценарій, а не вихідний код. У моєму прикладі скомпільований Javascript знаходиться в моїй папці теми /assets/js/sidebar-plugin.js.

Ми створюємо функцію, підключену до enqueue_block_editor_assets. Всередині робимо звичайне [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)(). Як залежності до сценарію ми додаємо дві; wp-plugins, і wp-edit-post. Ці два пакунки мають бути завантажені перед нашим скриптом, оскільки ми використовуємо функції з них.

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-sidebar-plugin', get_stylesheet_directory_uri(). '/assets/js/sidebar-plugin.js', ['wp-plugins', 'wp-edit-post']);
});

Оскільки ми ставимо сценарій у чергу, enqueue_block_editor_assetsнаш сценарій буде завантажено лише тоді, коли редактор Gutenberg активний. Чудово! Тепер усе готово для написання нашого плагіна Javascript.

Зареєструйте плагін Javascript

Першим кроком є ​​реєстрація плагіна. Ми робимо це за допомогою [registerPlugin](https://github.com/WordPress/gutenberg/tree/master/packages/plugins#registerPlugin)функції wp.plugins зсередини wp.pluginsпакета.

Як параметр для registerPlugin ми надаємо назву (переконайтеся, що вона унікальна) і об’єкт із налаштуваннями. Як мінімум вам потрібно надати компонент для властивості render. Ви також можете додатково додати піктограму з дашіконів WordPress. Майте на увазі, що якщо ви не вкажете значок, він повернеться до значка плагіна. Для демонстрації я використовую 'carrot'значок.

Що стосується компонента, ми починаємо з визначення базового компонента, який повертає простий div з довільним текстом у ньому. І перед усім кодом ми деструктуруємо функції з пакетів, які ми хочемо використовувати.

Якщо нічого не відбувається (навіть помилки), коли ви оновлюєте Gutenberg, усе готово. Ми не бачимо наш компонент, тому що не вказали WordPress, де його рендерити. Наступним кроком є ​​підключення до користувацького меню бічної панелі та компонентів меню інструментів для відтворення нашого матеріалу.

Зареєструйте спеціальну бічну панель

Але спочатку пояснення того, як Гутенберг обробляє спеціальні бічні панелі та чому ми повинні робити те, що ми будемо робити. Коли ми успішно зареєструємо спеціальну бічну панель, спочатку автоматично відбудеться одна річ. Гутенберг додасть ярлик до нашої бічної панелі на верхній панелі інструментів поруч із меню «Інструменти». Це відбувається тому, що наша бічна панель автоматично «закріплюється».

Проблема простого додавання спеціальної бічної панелі полягає в тому, що будь-який користувач може «відкріпити» цей ярлик. Коли вони це роблять, немає точки доступу, щоб знову відкрити бічну панель! Ось чому нам також потрібно додати пункт меню до меню Інструменти.

Реєстрація спеціальної бічної панелі виконується за допомогою компонента PluginSidebarз wp.editPostпакета. Додавання пункту меню до меню «Інструменти» здійснюється за допомогою компонента з влучною назвою PluginSidebarMoreMenuItem(також у wp.editPostпакеті).

Для PluginSidebarкомпонента нам потрібно надати деякі властивості. Ви повинні надати як мінімум nameі title. Проп titleне потребує пояснень, це ім’я, яке з’явиться у верхній частині бічної панелі. У пропілі nameнадайте унікального слимака. Коли ви додаєте пункт меню, вам потрібно посилатися на цей слаг.

Для додавання PluginSidebarMoreMenuItemкомпонента (меню інструментів) потрібен як мінімум один проп; target. Тут ви вказуєте те саме ім’я, яке ви вказали в атрибуті бічної панелі name. Як вміст компонента ви пишете текст, який відображатиметься як пункт меню. Зазвичай це те саме, що на бічній панелі title.

Оскільки для React потрібен єдиний вузол обертання навколо повернення компонента, ми обертаємо все всередині Fragmentкомпонента (з wp.elementпакету). Я також загортаю рядки __()з wp.i18nпакета, щоб забезпечити переклад.

За допомогою наведеного вище коду ми отримаємо наступні дві (швидше за все, три) речі. Ви отримаєте ярлик значка моркви на панелі інструментів (якщо ви ще не відкріпили його). Натиснувши на це, відкриється бічна панель. Ви також отримаєте новий пункт меню на бічній панелі в меню «Інструменти» під заголовком «Плагіни».

Додавання вмісту на бічну панель

Фактичний вміст бічної панелі залежить виключно від вас. Вам просто потрібно додати HTML або компоненти всередину PluginSidebarкомпонента з тим, що завгодно (замість тексту «Привіт!»).

Ви можете помітити, що у вмісті бічної панелі відсутні відступи. Це зроблено навмисно, оскільки ідея полягає в тому, що ви створите панелі всередині цієї бічної панелі. Панелі — це складні секції звичайної бічної панелі Гутенберга. Це компоненти, які ви можете дуже легко додати до своєї спеціальної бічної панелі. Ви можете додати скільки завгодно панелей, і вони чудово підходять для групування різних речей.

Додаємо панелі в нашу сайдбар

Давайте швидко розглянемо, як ми можемо додати панелі до нашої бічної панелі. Якщо ви створили власні власні типи блоків, ви можете бути знайомі з цими компонентами. Використовуємо PanelBodyі за бажанням PanelRowз wp.componentsупаковки.

Для PanelBodyкомпонента ви надаєте як мінімум prop title. Додатково можна вказати значення true або false, initialOpenщоб вирішити, чи слід розгортати панель за замовчуванням чи ні. Оскільки вміст усередині компонента – це все, що знаходиться всередині панелі.

Всередині PanelBodyви можете додатково використовувати PanelRowкомпоненти. Вони насправді не є необхідними, але можуть допомогти вам створити гарний стиль для вмісту панелі.

Для прикладу, давайте додамо дві панелі до нашої спеціальної бічної панелі.

З цим кодом наша спеціальна бічна панель починає справді виглядати так, ніби їй належить Гутенберг!

Додавання мета-полів публікації на спеціальну бічну панель

Тепер ми дійсно приступаємо до суті корисних речей для спеціальної бічної панелі; додавання параметрів і збереження їх значень. Але спочатку нам потрібно зрозуміти, як.

Додавати поля налаштувань (введення, прапорці, поля перемикання тощо) на бічній панелі дуже легко за допомогою готових до використання компонентів у пакетах WordPress. Однак нам потрібно розглянути, як зберігати значення. Очевидним варіантом є збереження їх як мета публікації. Але підключення налаштування до мета-поля публікації потребує додаткового коду. Точніше, нам потрібно використовувати так звані компоненти вищого порядку, щоб отримати та оновити мета повідомлення всередині Javascript. Нам також потрібно зареєструвати кожну мета публікацію за допомогою PHP і зробити їх доступними для REST API.

На завершення цього уроку я покажу, як додати мета допису з ключем awp_my_custom_meta, який має зберігатися як true або false. На бічній панелі воно відображатиметься як поле перемикання (компонент true/false).

Зареєструйте мета публікації для REST API

Першим кроком до додавання мета публікацій у наш файл Javascript є їх реєстрація та визначення як доступних у REST API. Для цього ми знову повертаємося до PHP.

Усередині функції, підключеної до initдії, ми використовуємо [register_meta](https://developer.wordpress.org/reference/functions/register_meta/)()функцію. Як параметр нам потрібно визначити тип об’єкта як «post», оскільки ми використовуємо його як мета публікації (це не виключає, наприклад, тип публікації сторінки). Ми надаємо мета-ключ, а потім масив аргументів. Найважливіша річ, яку потрібно додати до масиву аргументів, — це встановити для «show_in_rest» значення true. Мета повідомлення зазвичай використовується як «single» (подумайте, як ви використовуєте get_post_meta()). Ми також визначаємо type. У нашому випадку ми встановили значення «boolean».

За допомогою цього коду awp_my_custom_metaмета-поле " post" доступне з Gutenberg. Вам потрібно повторити register_meta()для кожного мета допису, який ви хочете додати на бічну панель.

Тепер повернемося до нашого Javascript.

Додавання налаштувань на нашу бічну панель

Давайте почнемо з легкої частини: додавання вхідних даних до нашої бічної панелі. Пізніше ми додамо більше коду, щоб фактично підключити поле налаштувань до мета публікації. Оскільки нам потрібно це зробити, ми визначаємо окремий новий компонент для нашого налаштування. Отже, всередині панелі, до якої ви хочете додати свої налаштування, просто викличте цей новий компонент.

Давайте назвемо компонент CustomSidebarMetaComponent(ви можете назвати це чимось, що стосується вашого проекту). Усередині цього компонента ми хочемо відобразити поле перемикання. Для цього використовуємо ToggleControlкомпонент з wp.componentsпакету. Як атрибут ToggleControl ми надаємо відповідну мітку в атрибуті title. ToggleControl також потребує реквізитів onChangeдля оновлення значення та checkedдля поточного значення. Наразі ми опустимо ці два до наступного кроку.

За допомогою коду вище ви повинні отримати поле перемикання на бічній панелі. Це знято, і нічого не відбувається, коли ви натискаєте на нього. Це наступний крок: підключити його до нашої мета публікації.

Доступ до мета публікації за допомогою withSelect і withDispatch

Щоб отримати доступ, а також оновити мета-значення публікації, нам потрібно використовувати компоненти вищого порядку (HOC) для доступу до версії магазинів WordPress (подібної до Redux). WordPress надає нам кілька корисних HOC із функціями, які ми можемо використовувати в wp.dataпакеті.

Компонент вищого порядку [withSelect](https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect)надає нашому компоненту реквізити, які, у нашому випадку, витягуються з post meta. Ми використовуємо це, щоб отримати значення мета нашої публікації. Всередині withSelectми можемо використовувати select('core/editor').getEditedPostAttribute('meta')для отримання мета поточної публікації.

З іншого боку, [withDispatch](https://developer.wordpress.org/block-editor/packages/packages-data/#withDispatch)це компонент вищого порядку, який може виконувати дії. У нашому випадку ми хочемо оновити мета публікації, коли відповідне налаштування поля змінено на бічній панелі. Усередині цього компонента ми використовуємо dispatch('core/editor').editPost(), щоб повідомити WordPress про виконання дії. Усередині наданого нами об’єкта ми повідомляємо WordPress, що це мета, яку ми хочемо оновити.

Нарешті, нам потрібно поєднати withSelectі withDispatchз нашим компонентом, який обробляє мета-поле post (CustomSidebarMetaComponent). Для цього ми використовуємо WordPress’ composeз wp.composeпакета. Ідея полягає в тому, що withSelectі withDispatchзабезпечує наш CustomSidebarMetaComponentкомпонент реквізитом. withSelectнадає значення мета публікації як проп і withDispatchнадає функцію, яку ми можемо викликати, щоб оновити значення як проп. Ми встановлюємо ці властивості для нашого ToggleField checkedі onChange, відповідно.

Це багато чого пояснює. Давайте подивимося на фактичний код:

Почнемо спочатку. Який внизу. На рядку #36ми змінюємо компонент, який ми візуалізуємо на бічній панелі, на компонент, за допомогою якого ми створили compose(на рядку #15). Компонент CustomSidebarMetaпоєднає компоненти withSelectі withDispatchта поверне CustomSidebarMetaComponent.

Матиме CustomSidebarMetaComponentдоступ до customPostMetaValueреквізиту з withSelect, а setCustomPostMetaреквізиту з withDispatchЦі два ми використовуємо для checkedі onChangeреквізити в ToggleField.

Зверніть увагу, що в рядку #5ми додаємо propsпараметри до компонентів, щоб зробити властивості доступними в компоненті.

Висновок і заключні слова

Я сподіваюся, що цей посібник був для вас корисним. Це те, що мені вдалося збагнути по темі під час багатьох проб і помилок. Документації на цю тему ще майже немає. Я все ще борюся з цим, особливо коли справа доходить до ефективної обробки кількох мета-повідомлень. Якщо мені вдасться навчитися хороших прийомів, я обов’язково оновлю цей посібник!

Сподіваюся, дотримуючись цього підручника, ви матимете код, який успішно додає нову спеціальну бічну панель до редактора WordPress Gutenberg, і, сподіваюся, з деяким значущим вмістом і налаштуваннями. Ось остаточний код для спеціальної бічної панелі з мета-полем публікації.