Пять способов расширения функциональности стандартных блоков в WordPress

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

Но бывают ситуации, когда стандартных блоков недостаточно. Например, блоку нужно добавить отступ, или обернуть блок в дополнительный div. Бывает и наоборот, стандартный блок предоставляет слишком много опций, которые лучше спрятать от клиента.

Для таких ситуаций в WordPress cуществует несколько инструментов о которых я расскажу в этой статье.

Начнем с самого простого способа. К любому стандартному блоку в WordPress можно добавить дополнительный CSS класс, который потом можно использовать в стилях темы или вкладке Дополнительные стили в настройках.

Допустим нам необходимо добавить нижний отступ в 100 px к блоку Обложка на одной из страниц. Для этого добавим к нему класс mb-large:

… и затем в дополнительных стилях создадим новое CSS правило:

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

Если вы планируете использовать это изменение постоянно, лучше использовать другой способ — стиль блока.

Так же как и в первом способе, дополнительные стили добавляют к блоку CSS класс. Разница заключается в том, что зарегистрированные стили появляются в специальном разделе в редакторе, и чтобы добавить стиль не нужно вводить СSS класс вручную, достаточно просто кликнуть на него. Разберем на примере.

На одном из проектов мне нужно было стилизовать компонент, который выглядел примерно так:

Это отличный кейс чтобы использовать блок Группа и создать для него дополнительный стиль Карточка, потому что такая комбинация элементов повторялась на большом количестве страниц.

Чтобы добавить стиль, используем функцию registerBlockStyle():

Если вы не писали код для нового редактора ранее, советую прочитать статью в которой я подробно рассказал как настроить проект для Gutenberg.

После того как мы добавили код из примера выше, в редакторе должен появиться дополнительный стиль для блока Группа:

Если кликнуть на этот стиль, то к блоку добавится новый CSS класс is-style-card.

Последнее, что нужно сделать это написать стили для этого класса:

Как я уже писал ранее, этот способ хорошо применять, в случае если вы планируете использовать эту модификацию блока постоянно.

У этого способа есть ограничения — у каждого блока может быть активен только один стиль. То есть мы не можем создать отдельный стиль для внешнего вида блока, и отдельный стиль для отступа, и использовать их вместе. Для таких случаев стоит использовать Вариации или Фильтры, о которых я расскажу далее.

Вариации блоков очень похожи на стили блоков, но позволяют делать намного больше. Основная разница заключается в том, что вариация появляется в редакторе в виде отдельного блока (хоть таковым и не является) и позволяет задать иконку, заполнить атрибуты блока и добавить внутренние блоки.

Чтобы разобраться, создадим вариацию на основе предыдущего примера. Основная идея — позволить пользователям добавлять на страницу блок Группа с уже включенным стилем Карточка, заполненным заголовком, параграфом текста и ссылкой.

Регистрация вариации выполняется с помощью функции registerBlockVariation():

Обратите внимание на параметр className внутри параметра attributes — так мы указываем какой стиль будет использоваться блоком. Шаблон внутренних блоков задан внутри параметра innerBlocks.

Если мы все сделали правильно, то в меню вставки блоков должен появиться новый «блок» СTA (Call To Action):

… кликнув на который, пользователь сможет добавить блок Группа, с уже заданными внутренними блоками и стилем Карточка.

Этот способ пригодится если функционала стандартных блоков достаточно и нужно просто сэкономить время на создании повторяющихся элементов.

Одно из ограничений этого способа — возможность создать вариацию только для одно блока. Да, можно создать вариацию для блока Группа и добавить сколько угодно внутренних блоков, но если вам нужно создать более сложную повторяющуюся структуру страницы, лучше использовать Паттерны. О них и поговорим далее.

Паттерны — относительно новый инструмент в WordPress, который позволяет регистрировать структуру из нескольких блоков и далее вставлять ее на страницы в несколько кликов.

Я подробно рассказал о паттернах в отдельной статье. Прочитайте ее, чтобы подробно ознакомиться с этим инструментом.

Вкратце рассмотрим, как зарегистрировать новый паттерн. Допустим мы часто используем следующую структуру страницы:

На изображении видно, что мы используем следующие блоки:

Для того чтобы зарегистрировать подобный паттерн, необходимо сначала создать такую комбинацию на пустой странице и скопировать ее содержимое в режиме кода.

Далее используем функцию register_block_pattern():

Обратите внимание, что свойство 'content' должно быть подготовлено для вывода на экран (escaped). Это можно сделать с помощью инструмента CodeBeautify.

Если все сделано верно, то в редакторе должен появится новый паттерн:

Паттерны — один из моих любимых инструментов, потому что ими просто пользоваться, их быстро регистрировать и они во многих случаях заменяют шаблоны страниц.

Методы, которые я описал выше позволяют совершать большое количество манипуляций со стандартными блоками, но бывают ситуации, когда этого и этого не достаточно. Приведу несколько примеров. Допустим вам необходимо:

Эти и другие задачи можно решить с помощью фильтров.

Фильтры — пожалуй самый гибкий и в то же время сложный инструмент для работы со стандартными блоками. Раздела статьи однозначно не хватит чтобы подробно описать работу фильтров, поэтому мы кратко разберм какие бывают фильтры и рассмотрим несколько примеров.

Фильтры блоков можно условно разделить на две группы: PHP и JavaScript.

Блоки в PHP можно фильтровать с помощью знакомой функции addFilter() и хука render_block.

Предположим, что нам необходимо добавить div c классом wp-block-list-wrapper ко всем блокам Список:

Из примера видно, что функция prefix_add_list_block_wrap() сначала проверяет с каким блоком мы имеем дело, и если это core/list } — оборачивает контент блока в дополнительный div.

Если мы все сделали правильно то маркап всех списков будет выглядеть вот так:

Стоит отметить, что этот способ не изменяет вывод блока в редакторе, а работает только с фронтэндом. Если вам необходимо изменить блок в обоих контекстах, стоит использовать JS фильтры.

JavaScript фильтры работают похожим образом. Они используют функцию addFilter() из пакета wp.hooks и в самой простой форме JS фильтр выглядят примерно так:

Первое что бросается в глаза в отличии от add_filter() в PHP, это дополнительный параметр namespace (не путать с PHP namespace). Согласно официальной документации этот параметр должен содержать уникальный идентификатор функции обратного вызова: vendor/plugin/function. Но примеры из той же статьи используют другую структуру: plugin/what-filter-does или plugin/component-name/what-filter-does. Я использую последний вариант.

Другое отличие заключается в том, что именно JavaScript фильтры могут фильтровать. Некоторые работают с простыми строками, другие с объектами, третьи с React компонентами.

Разберем простой пример, допустим нам необходимо урбать опции выравнивания у блока Обложка. На практике это будет выглядеть примерно так:

Этот пример использует фильтр registerBlockType для модификации объекта supports в опциях блока.

Сначала мы проверяем что работаем именно с блоком Обложка (core/cover) далее с помощью lodash.assign создаем новый объект опций блока и с помощью lodash.merge заменяем в нем свойство align. Методы lodash нужны чтобы избежать мутации оригинального объекта settings.

Если мы все сделали правильно, возможность выбора выравнивания исчезнет из тулбара:

В этом примере мы рассмотрели один из доступных фильтров. Если вы хотите узнать о JS фильтрах больше советую изучить официальную документацию и прочитать статью которую я написал для CSS-Tricks в которой я рассматриваю более сложный пример.

В этой статье мы разобрали пять способов расширения блоков WordPress. Подводя итог, повторим когда какой способ использовать