Ви коли-небудь потрапляли в ситуацію, коли хочете додати власні налаштування до блоків Гутенберга WordPress? У цій публікації ми детально розповімо, як це зробити. Ви знайдете два приклади коду реальних випадків використання додавання власних налаштувань до блоків WordPress.

Майте на увазі, що оскільки блоки Гутенберга є Javascript, для їх модифікації потрібно писати код у Javascript. Подібно до того, як PHP-код WordPress має хуки та фільтри, які дозволяють розробникам тем або плагінів змінювати код, у коді Javascript WordPress також є фільтри. Подібно до [add_filter](https://developer.wordpress.org/reference/functions/add_filter/)()функції PHP, у нас є функція Javascript [addFilter](https://developer.wordpress.org/block-editor/packages/packages-hooks/#api-usage)().

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

Що можна фільтрувати на блоках Гутенберга

Доступних хуків і фільтрів Gutenberg не так багато документації. Але з метою додавання власних налаштувань і якимось чином їх застосування до існуючих блоків; це те, що я наразі знайшов. Я зосередився на додаванні простих налаштувань, а не на операціях, які вимагають різких змін компонентів або складної поведінки.

Є три кроки, щоб додати спеціальні налаштування до існуючих блоків:

Ми додаємо фільтр до існуючого [registerBlockType](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/#registerblocktype)масиву налаштувань блоку. Це дозволяє нам додавати нові атрибути до attributesмасиву, таким чином дозволяючи нам зберігати додаткову інформацію в блоці. Нам потрібно десь зберегти наше власне налаштування.
Підключіться до editкомпонента блоку (компонента, який відповідає за рендеринг блоку в редакторі). У цьому хуку ми можемо підключитися до Inspector (бічна панель) і додати власні компоненти. Ми можемо або додати новий розділ/панель, або підключитися до розділу «Додатково», який завжди присутній у всіх блоках. Тоді ми повинні відтворити вхідні параметри, такі як введення тексту, прапорці тощо.
saveФільтруйте реквізити блоку. Ми можемо налаштувати параметри збереження, які відповідають як за збереження блоку, так і за його рендеринг у інтерфейсі (поза редактором). У нашому випадку ми хочемо додати клас або вбудований стиль.

Ми можемо націлюватися на конкретні блоки або на всі. У нас завжди є доступ до того, який тип блоку ми знаходимо.

Іншими словами: ми додаємо деякі спеціальні налаштування в Inspector і зберігаємо їх у спеціальних атрибутах, які ми додали до блоку. Потім ми можемо впливати на назву класу блоку або вбудований стиль (у деяких випадках), залежно від збережених атрибутів. За допомогою користувацьких імен класів ми можемо легко додати власний CSS, який візуально надасть нашим налаштуванням ефект.

Що ми не можемо зробити (наразі?)

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

Немає доступу до вбудованого стилю блоку всередині редактора

У деяких випадках налаштувань, які впливають на дизайн блоку, нам потрібно додати вбудований стиль у вузол упаковки блоку. Просто назва класу не підійде. Наприклад, якщо ви додаєте настроюваний колір, і користувач вибирає настроюваний колір (з вибору кольорів), ви не можете вирішити це, додавши клас – вам потрібен вбудований стиль.

На жаль, здається, що блоки WordPress за замовчуванням обробляють вбудований стиль у редакторі абсолютно незалежно, без можливості фільтрації чи «підключення». Я покажу спосіб обійти це в останньому прикладі нижче, але він не ідеальний у всіх випадках.

Ви можете запитати, навіщо дбати про те, що блок виглядає по-різному в редакторі та в інтерфейсі? Вся суть Gutenberg полягає в тому, щоб реалізувати візуальний спосіб редагування вмісту, де те, що ми бачимо, насправді є тим, що ми отримуємо. Ми хочемо досягти однакового візуального вигляду як у редакторі, так і в інтерфейсі.

Деякі блоки не включають назву класу в редакторі

Як згадувалося вище, ми можемо відфільтрувати назву класу упаковки блоку, оскільки це проп, який передається всім блокам Gutenberg. Але, на жаль, є деякі блоки, які взагалі не застосовують клас блоку в edit. Одним із прикладів є блок Cover. Я багато бавився, використовуючи блоки Cover як «розділи» для перших сторінок, і постійно стикався з проблемами, оскільки блок Cover будує власний клас усередині edit. Він повністю пропускає «глобальний» клас блоку (той, до якого ми маємо доступ через фільтри).

Але принаймні ми можемо бути впевнені, що відфільтровані імена класів завжди застосовуються в save(інтерфейсі). Це відбувається автоматично за межами конкретного коду кожного блоку.

Якщо я помиляюся в будь-якому з вищесказаного, БУДЬ ЛАСКА, дайте мені знати в коментарях нижче! Я постійно вивчаю Гутенберга, і водночас Гутенберг також розвивається. Я сподіваюся, що в якийсь момент це стане можливим або що це можливо, але мені просто бракує важливої інформації!

Покінчивши з цим, почнемо вивчати код.

Приклад 1: додайте поле перемикання, щоб приховати блок обкладинки на мобільному пристрої

Припустімо, що ми розробляємо тему, де блоки обкладинки використовуватимуться для «розділів» на головній сторінці. І ми хочемо надати користувачеві можливість приховати певний розділ від мобільного. Щоб вирішити цю проблему, ми можемо додати поле перемикання в розділ «Додатково» в інспекторі блоку покриття. Якщо це поле ввімкнено, блок Cover отримає додатковий спеціальний клас, на який ми можемо націлити CSS і медіа-запити.

До речі: це той випадок, коли блок Cover не застосовує наші власні імена класів у редакторі насправді є перевагою! Уявіть, якби це було; тоді користувачеві буде неможливо редагувати блок у редакторі, якщо він або вона має маленький екран!

Як згадувалося раніше, є три кроки, які нам потрібно закодувати. Нам також потрібно додати трохи PHP, щоб поставити наш файл Javascript у чергу до редактора. Давайте зробимо це спочатку.

Додаємо наш скрипт в редактор

Ми підключаємо функцію до дії [enqueue_block_editor_assets](https://developer.wordpress.org/reference/hooks/enqueue_block_editor_assets/). Усередині нашої функції ми ставимо сценарій у чергу, як зазвичай робимо в wp_enqueue_scriptshook.


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

Не забудьте налаштувати шлях до місця, де знаходиться ваш сценарій! Примітка: якщо ви пишете в ES6 з webpack, компілюючи свій Javascript, пам’ятайте, що потрібно вказати шлях до збірки вашого сценарію, а не джерело.

Мені подобається додавати «wp-edit-post» як залежність до сценарію, щоб він завантажувався досить пізно.

Це все PHP, що нам потрібно зробити. Решта записано в нашому файлі Javascript.

Додайте спеціальний атрибут

Перший фільтр, який ми використаємо, це об’єкт налаштувань blocks.registerBlockTypeфільтрів registerBlockType.

Але спочатку трохи про додавання фільтрів у Javascript. Оскільки я не знайшов жодної хорошої документації для цього, я трохи поясню це тут. Функція addFilterзнаходиться в wp.hooksпросторі імен і приймає чотири аргументи.

addFilter('hookName', 'namespace', 'functionName', 'priority');

Перший параметр, ‘hookName’, це ім’я фільтра, який ми хочемо підключити. Це еквівалент першого параметра при використанні PHP add_filter(). Другий параметр, ‘простір імен’, — це настроюване ім’я простору імен для вашого коду. Це лише для того, щоб уникнути зіткнення імен. Ви можете встановити тут все, що завгодно, тільки не використовуйте простір імен WordPress (‘wp’). Використовуйте коротку форму свого імені або назви проекту. Третій параметр, ‘functionName’, є підключеною функцією, яка збігається add_filter()з другим аргументом PHP. І, нарешті, четвертий параметр, «пріоритет», є необов’язковим. Знову ж таки, це те саме, add_filter()що й третій аргумент PHP.

Процес для фільтрів у Javascript такий самий, як і в PHP. Ми визначаємо функцію, яка повинна повертати відфільтровану змінну. Іноді змінна є рядком, об’єктом або компонентом. Усередині функції ми змінюємо змінну, як вважаємо за потрібне.

У нашому випадку ми хочемо додати новий атрибут до attributeоб’єкта блоку. Ми викличемо новий атрибут hideOnMobileі встановимо його тип boolean. Це робиться так:


function addCoverAttribute(settings, name) {
    if (typeof settings.attributes !== 'undefined') {
        if (name == 'core/cover') {
            settings.attributes = Object.assign(settings.attributes, {
                hideOnMobile: {
                    type: 'boolean',
                }
            });
        }
    }
    return settings;
}
 
wp.hooks.addFilter(
    'blocks.registerBlockType',
    'awp/cover-custom-attribute',
    addCoverAttribute
);

У рядку #3ми переконаємося, що націлені лише блоки типу " core/cover". Другим аргументом для blocks.registerBlockTypeфільтрації досить зручно є назва блоку. Потім ми додаємо до об’єкта новий елемент settings.attributesоб’єкта. Нарешті ми повертаємо відфільтровану змінну, settings.

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

Додати налаштування до інспектора (розширена панель)

Викликається другий фільтр, який фільтрує компонент editor.BlockEditблоку. editЦей фільтр отримує BlockEditкомпонент вихідного блоку та повертає новий упакований компонент. Нам потрібно використовувати wp.compose.createHigherOrderComponent, щоб повернути загорнутий компонент.

Усередині нашого компонента ми обов’язково відтворюємо загорнутий компонент BlockEdit, незважаючи на це. Але якщо блок має тип Cover, ми також підключаємося до компонента InspectorAdvancedControls(яким є панель «Додатково» в Inspector) і додаємо ToggleControl. Ми пишемо, ToggleControlщоб показати значення та оновити спеціальний атрибут, який ми додали раніше, hideOnMobile.

Не забувайте завжди повертати оригінал BlockEdit, що ми робимо на лінії #9. У рядку №10 ми перевіряємо, чи є тип блоку Cover, і виконуємо рендеринг InspectorAdvancedControlsкомпонента. Сюди всередину ми додаємо ToggleControl, який є елементом керування введенням, який відображається як перемикач між true або false. Ми встановлюємо мітку і зв’язуємо її значення з hideOnMobileатрибутом. Якщо ви раніше додавали налаштування до Inspector, це має бути досить простим для вас.

За допомогою наведеного вище коду ми маємо отримати це всередині панелі «Додатково» в блоках «Інспектор на обкладинці»:

Тепер введені дані оновлять наш спеціальний атрибут hideOnMobile. Останній крок – зробити щось залежно від значення цього атрибута. Наразі атрибут збережено, але фактично ні на що не впливає.

Додайте спеціальний клас

Останнім кроком є додавання спеціального класу до класу блоку. Робимо це за допомогою фільтра blocks.getSaveContent.extraProps. Цей фільтр впливає на властивості saveкомпонента блоку. Одним із них є prop className, який завжди застосовуватиметься до інтерфейсу. Ми просто додаємо свій власний клас після нього, якщо атрибут був true, а потім повертаємо його. Я вирішив додати клас " hide-on-mobile", але ви можете називати його як завгодно.

Цей код досить зрозумілий. У рядку #4ми перевіряємо, чи атрибут hideOnMobileіснує і чи є true. Якщо так, ми додаємо власний клас до classNameрядка.

З усіма вищезазначеними трьома фільтрами ми тепер маємо отримати спеціальний клас «hide-on-mobile», застосований до нашого блоку Cover щоразу, коли це налаштування вмикається.

Все, що залишилося, це додати CSS до таблиці стилів інтерфейсу вашої теми. Щось на зразок цього;


.wp-block-cover.hide-on-mobile { display: none; }
@media (min-width: 480px) {
    .wp-block-cover.hide-on-mobile { display: block; }
}

Приклад 2: додайте панель інспектора з власним налаштуванням кольору фону для блоку Spacer

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

Примітка. Робота з кольорами дещо складніша, оскільки нам потрібно використовувати компонент вищого порядку withColors. Оскільки нам уже потрібно реалізувати компонент вищого порядку, editor.BlockEditнам потрібно composeкілька компонентів. Крім того, нам потрібно додати два атрибути для кожного параметра кольору. Один міститиме слаг палітри кольорів, а інший міститиме шістнадцятковий код кольору – лише якщо користувач вибрав настроюваний колір (використав інструмент вибору кольорів). Це типова поведінка під час роботи з withColors. У мене є <a href="https://wordpress.mediadoma.com/uk/jak-dodati-parametri-koloru-do-vashogo-specialnogo-bloku-gutenberga/" title="допис, у якому пояснюється додавання налаштувань кольорів і withColorsдокладно” >допис, у якому пояснюється додавання налаштувань кольорів і withColorsдокладно, якщо ви заплуталися.

По-друге, у цьому випадку ми зіткнемося з проблемою, описаною вище; де ми не можемо додати відповідний вбудований стиль до редактора. Рішення, яке я вибрав у цьому випадку, полягає в тому, щоб обгорнути блок Spacer усередині divредактора та застосувати відповідні класи та вбудований стиль до обгортання div. Це робить вибраний колір видимим у редакторі, коли блок не вибрано. Однак після вибору блоку WordPress додає власний власний світло-сірий фон до блоку, який покриває наш власний колір фону. Один CSS до редактора виправить це. Я поясню докладніше в кінці.

Кроки такі ж, як у прикладі вище. Спершу ми додаємо наш сценарій до редактора на PHP. Потім у Javascript ми фільтруємо attributesоб’єкт, editкомпонент Spacer і, нарешті, saveкомпонент Spacer.

Додаємо наш скрипт в редактор


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

Не забудьте налаштувати шлях до вашого сценарію. Мені подобається додавати «wp-edit-post» як залежність до сценарію, щоб він завантажувався досить пізно.

Це все PHP, що нам потрібно зробити. Решта записано в нашому файлі Javascript.

Додайте спеціальні атрибути

Як і в прикладі вище, ми додаємо фільтр blocks.registerBlockType, щоб додати додаткові елементи об’єкта до attributesоб’єкта блоку.

При роботі з withColorsнам потрібно додати два атрибути для кожного кольору. Ім’я нашого атрибута кольору тла є backgroundColor, що означає, що другий атрибут має бути названий customBackgroundColor. Це все пояснено в моїй публікації про обробку налаштувань кольорів у Gutenberg. Обидва мають бути типу string і застосовуватися лише до блоків типу Spacer.


function addSpacerAttributes(settings, name) {
    if (typeof settings.attributes !== 'undefined') {
        if (name == 'core/spacer') {
            settings.attributes = Object.assign(settings.attributes, {
                backgroundColor: {
                    type: 'string',
                },
                customBackgroundColor: {
                    type: 'string'
                }
            });
        }
    }
    return settings;
}
 
wp.hooks.addFilter(
    'blocks.registerBlockType',
    'awp/spacer-background-attribute',
    addSpacerAttributes
);

Додайте панель ColorSettings до Inspector

Другим кроком є додавання панелі параметрів кольору до Інспектора для блоку Spacer за допомогою фільтрації editor.BlockEdit.

Нам потрібно використовувати composeдля об’єднання компонента вищого порядку, отриманого від цього фільтра, і withColors. Іншими словами, ми просто обертаємо повернутий компонент у withColors. Як параметр withColorsми надаємо наш атрибут backgroundColor.

Усередині загорнутого компонента ми завжди повертаємо BlockEdit(рядок #9і #39для блоків Spacer). Для блоку типу Spacer ми також підключаємося InspectorControls, щоб додати PanelColorSettingsколір для нашого вибору. Це стандартна процедура додавання параметрів кольору.

У рядку #17 - 34ми вручну генеруємо необхідний клас та/або вбудований стиль. Потім у рядку #38ми додаємо обтікаючий div BlockEditз цими класами та вбудованими стилями.

Результатом є нова повністю функціональна панель налаштувань кольору в Inspector for Spacer blocks.

Вибір кольору палітри або спеціального кольору справді впливатиме на обтікання div у редакторі. Але ви можете побачити це, лише коли знімете вибір із блоку Spacer!

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

Додайте спеціальний клас і вбудований стиль, щоб зберегти

Нарешті нам потрібно відфільтрувати blocks.getSaveContent.extraPropsта застосувати необхідний клас та/або вбудований стиль для інтерфейсу. Знову ж таки, це дуже схоже на те, що ми зробили в прикладі 1 вище. Якщо було вибрано колір палітри, нам потрібно додати назву класу, яка відповідає стандартам WordPress для налаштувань кольору (” has-<PALETTESLUG>-background-color“). Якщо вибрано спеціальний колір, нам потрібно додати вбудований стиль із шістнадцятковим кольором.

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


function applySpacerBackground(props, blockType, attributes) {
    if (blockType.name == 'core/spacer') {
        const { backgroundColor, customBackgroundColor } = attributes;
 
        // For improved class name handling, use classnames library. Or do it manually like..
        let className = (props.className != undefined)? props.className: '';
        if (backgroundColor != undefined) {
            className += ' has-' + backgroundColor + '-background-color';
        }
        props.className = className;
        if (customBackgroundColor != undefined) {
            Object.assign(props, { style: { ...props.style, backgroundColor: customBackgroundColor }});
        }
    }
    return props;
}
 
wp.hooks.addFilter(
    'blocks.getSaveContent.extraProps',
    'awp/spacer-apply-class',
    applySpacerBackground
);

За допомогою наведеного вище коду інтерфейс тепер ідеально візуалізує блоки Spacer з нашим власним вибором кольорів!

Останнім (необов’язковим) виправленням є додавання CSS до редактора. Вам потрібно буде додати вбудований CSS або таблицю стилів редактора. Наприклад, ви можете поставити таблицю стилів у той самий PHP-хук, який ми використовували для розміщення нашого файлу Javascript. Я не буду вдаватися в подробиці того, як це зробити; але CSS, який вам знадобиться, схожий на наведений нижче. Все, що він робить, це встановлює для Spacer background-colorуспадкований колір (він успадкує від нашого обтікання div), коли блок вибрано:


.block-library-spacer__resize-container.is-selected { 
    background-color: inherit; 
}

PS: Майте на увазі, що це може бути змінено в майбутньому. Гутенберг все ще активно розвивається.

Висновок

У цій публікації ми ознайомилися з двома методами впровадження користувальницьких налаштувань до існуючих блоків WordPress Gutenberg. Це цілком можливо для простих налаштувань, які, можливо, вимагають лише класу або вбудованого стилю. Ми розглянули застереження, які, я сподіваюся, будуть виправлені в наступних версіях Гутенберга!

Джерело запису: awhitepixel.com