Як додати мета-поля публікації до бічної панелі документа Гутенберга

У цьому дописі ми розглянемо, як додати спеціальні мета-параметри публікації на бічній панелі Gutenberg на вкладці «Документ», а не покладатися на додавання мета-полей традиційним (і, чесно кажучи, набагато більш ручним) способом.

Якщо ви працювали з WordPress деякий час до появи Gutenberg, ви, мабуть, знайомі з додаванням користувацьких мета дописів за допомогою [add_meta_box](https://developer.wordpress.org/reference/functions/add_meta_box/)(). Ця функція дозволяє додавати мета-поле з вашим власним вмістом внизу або збоку під час редагування публікації. Цей метод все ще працює, навіть у редакторі Gutenberg!

Однак це виглядає трохи не так, як решту вмісту бічної панелі Гутенберга. І не кажучи вже про те, що вам потрібно буде вручну написати код введення (прапорець, введення тексту тощо) за допомогою PHP, а також змусити написати додатковий код, щоб зберегти його під час оновлення публікації. І якщо ви хочете, щоб ваші мета-параметри допису були динамічними (скажімо, ви хочете приховати поле, якщо не було ввімкнено якесь інше поле), тоді вам доведеться вручну поставити сценарій у чергу та так, ви вже здогадалися, вручну обробити динамічну логіку приховування і показу. Тепер усе це застаріло та стало простіше завдяки новому редактору Gutenberg на основі Javascript. Ми можемо досить легко зробити щось на зразок цього:

Процес

Процес виглядає наступним чином:

• Ми реєструємо кожен власний мета-ключ публікації, який хочемо додати в PHP, за допомогою [register_post_meta](https://developer.wordpress.org/reference/functions/register_post_meta/)(), і встановлюємо його як доступний в WP REST API. Це необхідний крок, щоб зробити мета публікації доступною в редакторі Gutenberg.
• Ми створюємо файл Javascript і ставимо його в чергу спеціально для редактора (лише).
• У файлі Javascript ми реєструємо плагін, [registerPlugin](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-plugins/#registerPlugin)()вказуючи йому відобразити наш компонент.
• Усередині цього компонента ми можемо вивести все, що нам потрібно. Ми можемо використовувати вбудовані компоненти WordPress для легкого відтворення різних типів налаштувань. А використовуючи пакет даних WordPress, ми можемо отримувати та оновлювати мета-значення публікації одразу після їх зміни.

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

Реєстрація публікації мета

Для кожного мета допису, який ви хочете додати до бічної панелі Gutenberg, вам потрібно буде зареєструватися за допомогою [register_post_meta](https://developer.wordpress.org/reference/functions/register_post_meta/)(). Це необхідно, щоб зробити їх доступними через WP REST API (який використовує Гутенберг) і, таким чином, доступними в нашому Javascript.

У файл вашої теми functions.phpабо будь-який інший активний файл PHP додайте функцію, підключену до хука «init». Усередині функції ви повторюєте a register_post_meta()для кожного спеціального мета допису, який хочете додати. Функція приймає три аргументи; перший параметр — це тип повідомлення, для якого ви хочете зареєструвати мета (встановіть як порожній рядок для всіх типів повідомлення). Другим параметром є ім’я мета-ключа для вашого мета. І третє – це масив налаштувань. Саме тут ми визначаємо, що ця мета має бути доступна в WP REST API, встановивши для «show_in_rest» значення true.

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

Тепер у мене є мета-ключ публікації _my_custom_bool, _my_custom_textготовий і доступний у Gutenberg. Я рекомендую вам перейменувати їх на те, що буде зрозумілим для вас.

Реєстрація нашого плагіна Javascript

Для наступного кроку ми додамо файл Javascript і обов’язково поставимо його в чергу за допомогою PHP.

Майте на увазі, що я пишу код Javascript у синтаксисі ES6. Це означає, що я налаштував конфігурацію webpack/Babel для компіляції мого файлу в окремий читабельний файл Javascript для браузера.

У мене є посібник, як це налаштувати, якщо ви не впевнені, як це працює:

Нам потрібно переконатися, що WordPress завантажує наш сценарій у редакторі. Ми робимо це, підключаючи функцію до enqueue_block_editor_assetsта викликаючи [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)():

add_action( 'enqueue_block_editor_assets', function() {
    wp_enqueue_script(
        'awp-custom-meta-plugin', 
        get_template_directory_uri(). '/assets/js/gutenberg/plugin-awp-custom-postmeta.js', 
        [ 'wp-edit-post' ],
        false,
        false
    );
} );

Я припускаю, що ви знайомі з тим, як поставити сценарії в чергу, і можете замінити значення на власні. Як другий параметр я надаю шлях до файлу збірки (а не вихідного файлу). Щоб переконатися, що наш сценарій не завантажується занадто рано, я встановлюю «wp-edit-post» як залежність. Це пакет, який нам потрібен, щоб обробляти post meta.

Тепер перейдемо до частини Javascript.

Спочатку нам потрібно викликати [registerPlugin](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-plugins/#registerPlugin)()та передати наш компонент для відтворення панелі на бічній панелі документа Гутенберга. Ця функція доступна в wp.pluginsпакеті, тому я деструктурую її вгорі. Мені подобається тримати мої файли в порядку, тому я створюю ще один файл; «awp-custom-postmeta-fields.js», щоб містити відрендерений компонент та імпортувати його.

Написання нашого компонента

Давайте почнемо створювати базовий компонент, який не робить нічого іншого, окрім того, щоб просто сидіти там у правильному місці, тому ми спочатку приберемо це. Щоб відобразити компонент на бічній панелі документа Гутенберга, ми використовуємо [PluginDocumentSettingPanel](https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-document-setting-panel/)компонент. Ми можемо встановити такі атрибути, як title, iconі className. І все, що всередині, буде відображено на бічній панелі документа. Наразі я просто виводжу текст «Hello there».

З наведеним вище кодом (скомпільованим) ми отримуємо наступне:

приголомшливо Однак ми хочемо додати деякі вхідні дані. Але щоб зв’язати ці вхідні дані з нашою спеціальною мета публікації, нам потрібно створити наш компонент із компонентами вищого порядку withSelect(щоб отримати мета-значення публікації) і withDispatch(щоб оновити мета-значення публікації). Це може здатися трохи складним, якщо ви раніше не працювали з компонентами вищого порядку, але як тільки ви подумаєте про це, це досить просто.

Нам спочатку потрібно змінити нашу exportзаяву. Замість того, щоб просто повертати наш компонент окремо, нам потрібно скомпонувати його з withSelectі withDispatch, обидва в wp.dataпакеті.

Всередині withSelect()ми маємо доступ до потужної select()функції. За допомогою select()ми можемо отримати мета-значення поточної публікації. Ми також можемо отримати поточний тип публікації, якщо хочемо. Як я вже згадував раніше, реєструючи мета допису, ми можемо обмежити мета допису певним типом допису. Якщо ми отримуємо тип публікації поточної публікації, ми можемо в нашому компоненті переконатися, що наш код відображається, лише якщо ми маємо правильний тип публікації. Про це пізніше.

У withDispatch()ньому ми можемо визначити функції, які ми можемо запускати в нашому компоненті. Ми створюємо функцію, яка використовуватиметься dispatch()для оновлення мета допису.

Давайте змінимо exportтвердження на таке:

Нам також потрібно деструктурувати їх із наступних пакетів у верхній частині файлу:

const { compose } = wp.compose;
const { withSelect, withDispatch } = wp.data;

Завдяки цьому наш AWP_Custom_Pluginкомпонент має доступ до трьох нових атрибутів; postMetaякий містить усі мета-значення публікації для поточної публікації; postTypeякий містить тип публікації поточної публікації; setPostMeta()і, нарешті, створена нами функція, withDispatch()яка оновить мета допису.

Тож у нашому визначенні компонента ми можемо деструктурувати ці три нові властивості;

І тепер ми можемо додати деякі вхідні дані до нашої візуалізації, переконавшись, що вони відображають поточне значення, і що вони оновлюють мета публікації в події зміни. Я зареєстрував логічне значення та рядок, тому як приклад я додам ToggleControlдля перемикача та простий TextControlдля введення тексту.

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

Ось приклад того, як може виглядати наш компонент:

На лінії #9-10і #16-17знаходимо критичні частини. Ми встановлюємо поточне значення входів postMeta.<your meta key here>і в їхній події onChange запускаємо функцію setPostMeta( { <your meta key here>: ... } )до нового оновленого значення.

Нарешті кілька слів про те, як обмежити ваш компонент певним типом публікації. У нашому withSelect()ми передаємо тип публікації поточної публікації в prop postType. Все, що нам потрібно зробити в нашому компоненті, — це порівняти це значення з типом публікації та повернути null, якщо воно не збігається:

І це все! Тепер наш код має працювати. Кінцевий результат має бути приблизно таким:

Остаточний код

Реєстрація мета публікації та додавання файлу Javascript у чергу:

Два файли Javascript: