Учебное пособие: создание слайдера в виде динамического блока Гутенберга

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

Что мы будем делать

Блок будет отображать простой слайдер с помощью скрипта jQuery Cycle2. Но вы можете использовать любой другой скрипт слайдера. Блок будет внутри редактора отображать список всех категорий, позволяя пользователю выбрать одну категорию. При отображении блока во внешнем интерфейсе он будет динамически извлекать сообщения из выбранной категории и показывать их избранные изображения в виде слайдов. Этот урок сделает его довольно простым, позволяя вам расширять и настраивать слайдер так, как вам нравится.

Я решил не отображать слайд-шоу в редакторе. Обычно вы должны убедиться, что рендеринг в редакторе и во внешнем интерфейсе одинаковый. Но в случае с ползунком я предпочитаю, чтобы он был простым, чтобы не утомлять пользователя постоянными анимациями в редакторе.

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

Весь код написан на Javascript ES6/ES2015+. Имейте в виду, что этот код нуждается в Babel для преобразования и сборки окончательных файлов Javascript. Ознакомьтесь с руководством ниже, если вы не знаете, как это сделать.

Настройте файлы

В этом примере мы создаем блок внутри темы. В папке с темой у меня есть подпапка, gutenberg/в которую я поместил свои package.jsonфайлы webpack-config.js. Внутри подпапки src/в этой папке я размещаю все свои файлы сборки. Моя конфигурация веб-пакета настроена на размещение файлов сборки в подпапке моей темы ‘ 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.

Зарегистрируйте блок Gutenberg в 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!

Зарегистрируйте пользовательский блок Gutenberg в 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! Давайте создадим новый пост, добавим новый блок и найдем наш блок в категории Common. Вот как сейчас выглядит наш блок:

Добавление настроек инспектора

Давайте добавим некоторые настройки в Инспектор (правая боковая панель редактора). Как уже упоминалось, наш блок имеет только одну настройку; количество слайдов. Здесь я рекомендую вам добавить больше настроек для вашего слайдера. Не забудьте зарегистрировать атрибуты для каждого добавляемого параметра.

Чтобы добавить что-то в Инспектор, мы используем компонент [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‘ to 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в строку #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массив в register_block_type()функцию PHP при работе с динамическими блоками. Для нашего блока это будет выглядеть так:

Теперь вернемся к нашей callback-функции рендеринга awp_gutenberg_slider_render(). Результат полностью зависит от вас, особенно если вы решили использовать другой скрипт слайдера. Ниже приведен простой пример.

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

Обратите внимание, как я добавляю правильный класс выравнивания блоков в строку #12. В результате должен получиться слайдер избранных изображений. Имейте в виду, что это базовый пример, который имеет некоторые недостатки. Например, мы получаем последние три сообщения из выбранной категории. Но если у одного из них нет избранного изображения, слайдер будет отображать только два сообщения.

Важно помнить, что нужно возвращать строку, а не выводить ее. Я также рекомендую использовать какую-то функциональность шаблонов в вашей теме для рендеринга динамических блоков, подобных этим. Исправление и построение HTML в виде строки может быстро превратиться в беспорядок.

Заключительные слова

В этом руководстве показано, как создать собственный динамический блок WordPress Gutenberg, в котором вы визуализируете его внешнее содержимое на PHP. И вы видели, как использовать компонент более высокого порядка withSelectдля запроса всех терминов категории и метод для отображения выбираемого списка.

Весь приведенный выше код написан максимально просто. Я добавил только абсолютный минимум настроек. Ползунок работает, но обычно вам нужно больше — например, сделать ссылки на слайды, показать заголовки из сообщений, стрелки ползунка или возможность настроить скорость или другие параметры ползунка. Идея состоит в том, чтобы показать вам основы и упростить расширение, развитие и изменение в соответствии с потребностями вашего проекта.