Підручник: Створення слайдера як динамічного блоку Гутенберга

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

Що ми зробимо

Блок відтворить простий повзунок за допомогою сценарію jQuery Cycle2. Але ви можете використовувати будь-який інший сценарій слайдера. Блок усередині редактора відобразить список усіх категорій, дозволяючи користувачеві вибрати одну категорію. Під час відображення блоку у інтерфейсі він динамічно отримуватиме публікації з вибраної категорії та показуватиме їх зображення у вигляді слайдів. Цей підручник зробить його досить простим, дозволяючи розширювати та регулювати повзунок, як завгодно.

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

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

Весь код написаний на Javascript ES6 / ES2015+. Майте на увазі, що цей код потребує Babel для трансформації та створення остаточних файлів Javascript. Перегляньте посібник нижче, якщо ви не знаєте, як.

Налаштуйте файли

У цьому прикладі ми створюємо блок всередині теми. У папці теми у мене є вкладена папка «gutenberg/», де я розмістив свої package.jsonта webpack-config.js. У вкладеній папці «src/» цієї папки я розміщую всі свої файли збірки. Моя конфігурація webpack налаштована на розміщення файлів збірки у підпапці моєї теми «assets/js/».

Створіть новий порожній вихідний файл theme-folder/gutenberg/src/block-slider.jsі налаштуйте Webpack для створення файлу збірки в theme-folder/assets/js/block-slider.js. Ви можете змінити розташування та/або назви файлів як завгодно, просто не забудьте налаштувати код нижче.

Також нам потрібно завантажити необхідний скрипт слайдера. Ви можете завантажити Cycle2 за цим посиланням або скористатися будь-яким іншим сценарієм слайдів і налаштувати код нижче. Я поміщаю jquery.cycle2.min.jsфайл у папку своєї теми /assets/js/.

Я також підготую невеликий файл CSS, який буде завантажено лише в редакторі. Ми лише невеликий фрагмент стилю, щоб вибрати оптимальну категорію. Я створюю порожній файл editor-block-slider.cssі поміщаю його в theme-folder/assets/css/.

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

Зареєструйте блок Гутенберга в PHP

Усі блоки Гутенберга мають бути зареєстровані в [register_block_type](https://developer.wordpress.org/reference/functions/register_block_type/)(). Я вважаю за краще викликати його всередині функції, підключеної до init. Перший параметр — це назва вашого блоку, включаючи простір імен. Я вирішив викликати свій сценарій повзунка awp/slider(налаштуйте, як вам подобається). Другий аргумент – це масив аргументів.

У тій самій функції я зареєструю сценарій збірки за допомогою [wp_register_script](https://developer.wordpress.org/reference/functions/wp_register_script/)()та зареєструю свій CSS-файл редактора за допомогою [wp_register_style](https://developer.wordpress.org/reference/functions/wp_register_style/)(). Обидва ці маркери будуть додані як аргументи до «editor_script» та «editor_style» відповідно. Що стосується залежностей, то я додав кілька найпростіших пакетів для сценарію, щоб гарантувати, що наш сценарій блоку завантажується в правильному порядку. Що стосується стилю редактора, використання ‘ wp-edit-blocks‘ є хорошою залежністю, щоб уникнути перевизначення ваших стилів.

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

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

function awp_gutenberg_slider_render($attributes, $content) {
    return 'Slider render comes here.';
}

Ми повернемося до функції візуалізації PHP у самому кінці цього уроку. Тепер настав час переходити до Javascript!

Зареєструйте спеціальний блок Гутенберга в Javascript

Давайте відкриємо block-slider.jsвихідний файл. На цьому етапі я запусту сценарій (npm run start), щоб перетворити все, що ми робимо в цьому файлі, у файл збірки. Нам потрібно зареєструвати блок за допомогою [registerBlockType](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/)(). Перегляньте посилання, щоб побачити всі можливі аргументи.

Як ми вирішили в register_block_type()PHP, наш блок називається awp/slider. Ми також хочемо додати два атрибути до блоку, як згадувалося раніше: один для ідентифікатора вибраного терміна та один для кількості слайдів.

Мені також подобається додати функцію вирівнювання блоків. Його буде додано автоматично шляхом додавання «align» до supportsоб’єкта. Якщо вам потрібні всі вирівнювання блоків, ви можете просто встановити alignзначення true. Однак повзунок, вирівняний за лівим або правим краєм, не має особливого сенсу, тому я визначу конкретні типи вирівнювання блоків, які підтримує цей блок: «Вирівнювання по центру» (‘ center‘), «Широка ширина» (‘ wide‘) і «Повна ширина» (‘ full‘). Крім того, щоб визначити вирівнювання за замовчуванням і зробити його доступним з PHP, я додаю ‘ align‘ як атрибут до нашого блоку.

Я встановлюю аргумент блоку editна окремий компонент, який ми створимо далі. І нарешті saveфункція просто повертає null, тому що це динамічний блок.

Нам потрібно визначити компонент для editвластивості. Перед реєстраційним кодом я визначаю функціональний компонент BlockEdit, який просто рендерить a divі a Placeholderз деяким фіктивним текстом.

[Placeholder](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/placeholder)є гарним компонентом для відтворення області для налаштувань – і не обов’язково для фактичного відтворення блоку. Усередині Placeholderкомпонента ми відображаємо список термінів на вибір.

На цьому етапі наш блок має бути доступний у WordPress Gutenberg! Давайте створимо нову публікацію, додамо новий блок і знайдемо наш блок у категорії «Загальні». Ось так зараз виглядає наш блок:

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

Давайте додамо деякі налаштування до Інспектора (права бічна панель редактора). Як згадувалося, наш блок має лише одне налаштування; кількість слайдів. Тут я рекомендую вам додати більше налаштувань для блоку повзунка. Не забудьте зареєструвати атрибути для кожного параметра, який ви додаєте.

Щоб додати щось до інспектора, ми використовуємо компонент [InspectorControls](https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/inspector-controls)( ). wp.blockEditorВсередині ми візуалізуємо [PanelBody](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/panel#panelbody)( wp.components), щоб додати новий розділ, що згортається. Потім ми просто візуалізуємо [RangeControl](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/range-control)( wp.components), щоб створити параметр введення для вибору кількості слайдів. Ми встановлюємо мінімум 1 і максимум 10. Ми підключаємо подію valueand onChangeдо атрибута numSlides.

За допомогою наведеного вище коду ми тепер маємо отримати гарний розділ із повзунком діапазону для встановлення кількості слайдів.

Знову ж таки, я рекомендую вам пограти, додавши додаткові налаштування до повзунка. Наступним кроком є ​​створення елемента для відтворення списку категорій на вибір.

Створення компонента вибору категорії

Щоб наш код був охайним і придатним для повторного використання, давайте створимо компонент селектора категорії в окремому файлі. У папці збірки я створюю новий файл awp-category-picker.js.

У цьому файлі ми визначаємо компонент, який буде переглядати всі категорії, які зараз є в WordPress, і відтворювати їх певним чином. Щоб отримати категорії, нам потрібно загорнути його всередину так званого компонента вищого порядку, який забезпечить наш компонент тим, що нам потрібно через властивості. Для цього ми будемо використовувати [withSelect](https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect). Усередині withSelectми можемо зробити запит на отримання всіх категорій у WordPress за допомогою селектора магазину [select](https://developer.wordpress.org/block-editor/packages/packages-data/#select)(). Ми можемо використовувати:

щоб отримати всі терміни в межах наданої системи таксономії. Якщо ви не знайомі з компонентами вищого порядку та селекторами в WordPress Gutenberg, у мене є публікація, яка пояснює цю концепцію більш детально: Створення спеціального блоку Gutenberg – Частина 10: Отримання повідомлень і компонентів вищого порядку.

Оскільки нам потрібно експортувати компонент із цього файлу, ми розміщуємо комбінацію withSelectта наш визначений компонент у export defaultоператорі. Наш CategorySelectкомпонент просто повертає div з деяким фіктивним текстом, щоб ми могли бачити, що він працює. withSelectМає надати атрибут " " termsдля CategorySelect. Я додав до console.log()цієї опори, щоб ми могли побачити, що вона працює.

Останнє, що нам потрібно зробити, це фактично імпортувати та використати цей компонент селектора категорії в нашому спеціальному блоці.

Назад block-slider.jsспочатку нам потрібно імпортувати компонент у верхній частині файлу. А всередині нашого Placeholderкомпонента ми просто візуалізуємо компонент.

За допомогою наведеного вище коду ваш блок тепер має відтворити div із CategorySelectкомпонента. Якщо ви відкриєте консоль у своєму браузері, ви також повинні побачити деякі журнали. Пам’ятайте, що withSelectце асинхронний запит, що означає, що він може відображатися кілька разів. Перший раз(и) умови опори є null. Але в останній(і) журнал(и) має бути масив термінів категорії.

Чудово! Давайте продовжимо працювати з нашим CategorySelectкомпонентом і змусимо його фактично відтворювати список термінів, дозволяючи користувачеві вибрати один!

Відтворення списку термінів на вибір

Існує багато способів відобразити список варіантів, де користувач може вибрати один елемент. Якщо вам потрібне щось справді просте, ви можете відобразити стандартний спадний список вибору ([SelectControl](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/select-control)). Це повністю залежить від вас. Я вибрав чистіший і приємніший підхід, використовуючи [MenuGroup](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/menu-group)( wp.components) і [MenuItem](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/menu-item)( wp.components).

Усередині MenuGroupкомпонента нам потрібно прокрутити props.termsмасив, і для кожного елемента ми хочемо відобразити MenuItemкомпонент, який відображає назву терміна. І, звичайно, ми хочемо відобразити це, лише якщо props.termsщось дійсно містить (асинхронний запит, пам’ятаєте?).

Я дав MenuGroupкомпоненту спеціальний клас, оскільки нам потрібно буде націлити його за допомогою CSS. І я встановив проп roleна MenuItem« menuitemradio», щоб переконатися, що одночасно можна вибрати лише один. За замовчуванням вони працюють як прапорці, що дозволяє вибрати кілька елементів.

За допомогою наведеного вище коду наш блок тепер (через невелику секунду) має відобразити гарний список усіх категорій у вашому екземплярі WordPress.

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

У наш editor-block-slider.cssфайл додайте:

.awp-categoryselect div {
    max-height: 200px;
    overflow: hidden scroll;
    border: 1px solid #b3bcc0;
}

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

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

Нам block-slider.jsпотрібно передати поточний вибраний термін (значення атрибута termId) і функцію для оновлення вибраного терміна (setAttributes) як атрибути до нашого компонента селектора категорії.

У наведеному вище коді в рядку #6ми визначаємо функцію, яка просто оновлює атрибут termId. Ми передаємо це ім’я функції як властивість CategorySelectу line #17. А в рядку #16ми передаємо поточне значення termId. За допомогою ми можемо оновити наш CategorySelectкомпонент, щоб відобразити вибраний елемент і дозволити користувачеві фактично вибрати термін.

Знову awp-category-picker.jsми додаємо кілька нових реквізитів до MenuItem. Ми повертаємо trueабо falseдля реквізиту, незалежно від того, isSelectedчи поточний ідентифікатор терміна збігається з поточним вибраним. Ми запускаємо selectTermфункцію в onClickподії, передаючи ідентифікатор терміна. А щоб вибраний елемент був візуальним, ми умовно додаємо іконку перед кожним пунктом.

При цьому наш селектор категорії має виглядати так:

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

Це було все для частини редактора та Javascript! Те, що залишилося, це візуалізація інтерфейсу, яку ми зробимо в PHP.

Відобразіть динамічний блок у PHP

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

Спочатку нам потрібно поставити сценарій cycle2 у інтерфейс, щоб наш код слайдера фактично перетворився на слайдер. Ми робимо це за допомогою простої функції, підключеної до wp_enqueue_scripts. Налаштуйте наведене нижче, якщо ви вибрали інший сценарій повзунка.

add_action('wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'cycle2-slider-js', 
        get_template_directory_uri(). '/assets/js/jquery.cycle2.min.js', 
        ['jquery'], 
        '', 
        true
    );
});

По-друге, ми хочемо повернутися до register_block_type()виклику функції. Коли ми обробляємо динамічні блоки, ми обов’язково повинні додати новий аргумент; attributes. У цьому аргументі ми визначаємо всі атрибути, які ми визначили registerBlockTypeв Javascript, включаючи їхні значення за замовчуванням. Якщо ми цього не зробимо, не всі атрибути будуть доступні в нашому зворотному виклику візуалізації. Якщо атрибут залишився без змін у редакторі блоків, атрибут і його значення не будуть доступні в масиві атрибутів у PHP. Тому я рекомендую вам завжди додавати attributesмасив до функції PHP register_block_type(), коли ви працюєте з динамічними блоками. Для нашого блоку це виглядатиме так:

Тепер ми повернемося до нашої функції рендерингу зворотного виклику awp_gutenberg_slider_render(). Вихід повністю залежить від вас, особливо якщо ви вибрали інший сценарій слайдера. Нижче наведено простий приклад.

Основна ідея полягає в тому, що ми перевіряємо, чи був обраний термін ($attributes['termId']). Якщо він заповнений, ми створюємо [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/)()з аргументами для кількості дописів ($attributes['numSlides']) та ідентифікатора вибраної категорії. Потім необхідно створити належний HTML для роботи cycle2, циклу перегляду публікацій і відображення їх зображень у вигляді слайдів.

Зверніть увагу, як я додаю належний клас вирівнювання блоків у рядок #12. У результаті має вийти повзунок представлених зображень. Майте на увазі, що це базовий приклад, який має деякі недоліки. Наприклад, ми отримуємо останні три публікації з вибраної категорії. Але якщо припустити, що один із них не має представленого зображення, повзунок відображатиме лише два дописи.

Важливо пам’ятати, що потрібно повертати рядок, а не повторювати його. Я також рекомендую використовувати деякі функції шаблонів у вашій темі для динамічного рендерингу блоків, як ці. Виправлення та створення HTML як рядка може швидко стати безладним.

Заключні слова

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

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