Стандартные блоки в WordPress позволяют создавать страницы разной сложности. От простейших текстовых до сложных с многоколоночной структурой, изображениями, аудио и видеоконтентом.
Но бывают ситуации, когда стандартных блоков недостаточно. Например, блоку нужно добавить отступ, или обернуть блок в дополнительный div. Бывает и наоборот, стандартный блок предоставляет слишком много опций, которые лучше спрятать от клиента.
Для таких ситуаций в WordPress cуществует несколько инструментов о которых я расскажу в этой статье.
1. Дополнительный CSS Класс
Начнем с самого простого способа. К любому стандартному блоку в WordPress можно добавить дополнительный CSS класс, который потом можно использовать в стилях темы или вкладке Дополнительные стили в настройках.
Допустим нам необходимо добавить нижний отступ в 100 px к блоку Обложка на одной из страниц. Для этого добавим к нему класс mb-large:
… и затем в дополнительных стилях создадим новое CSS правило:
Этот способ подходит для случаев, когда нужно быстро добавить небольшое изменение на одной-двух страницах.
Если вы планируете использовать это изменение постоянно, лучше использовать другой способ — стиль блока.
2. Стили Блоков
Так же как и в первом способе, дополнительные стили добавляют к блоку CSS класс. Разница заключается в том, что зарегистрированные стили появляются в специальном разделе в редакторе, и чтобы добавить стиль не нужно вводить СSS класс вручную, достаточно просто кликнуть на него. Разберем на примере.
На одном из проектов мне нужно было стилизовать компонент, который выглядел примерно так:
Это отличный кейс чтобы использовать блок Группа и создать для него дополнительный стиль Карточка, потому что такая комбинация элементов повторялась на большом количестве страниц.
Чтобы добавить стиль, используем функцию registerBlockStyle():
Если вы не писали код для нового редактора ранее, советую прочитать статью в которой я подробно рассказал как настроить проект для Gutenberg.
После того как мы добавили код из примера выше, в редакторе должен появиться дополнительный стиль для блока Группа:
Если кликнуть на этот стиль, то к блоку добавится новый CSS класс is-style-card.
Последнее, что нужно сделать это написать стили для этого класса:
Как я уже писал ранее, этот способ хорошо применять, в случае если вы планируете использовать эту модификацию блока постоянно.
У этого способа есть ограничения — у каждого блока может быть активен только один стиль. То есть мы не можем создать отдельный стиль для внешнего вида блока, и отдельный стиль для отступа, и использовать их вместе. Для таких случаев стоит использовать Вариации или Фильтры, о которых я расскажу далее.
3. Вариации Блоков
Вариации блоков очень похожи на стили блоков, но позволяют делать намного больше. Основная разница заключается в том, что вариация появляется в редакторе в виде отдельного блока (хоть таковым и не является) и позволяет задать иконку, заполнить атрибуты блока и добавить внутренние блоки.
Чтобы разобраться, создадим вариацию на основе предыдущего примера. Основная идея — позволить пользователям добавлять на страницу блок Группа с уже включенным стилем Карточка, заполненным заголовком, параграфом текста и ссылкой.
Регистрация вариации выполняется с помощью функции registerBlockVariation():
Обратите внимание на параметр className внутри параметра attributes — так мы указываем какой стиль будет использоваться блоком. Шаблон внутренних блоков задан внутри параметра innerBlocks.
Если мы все сделали правильно, то в меню вставки блоков должен появиться новый «блок» СTA (Call To Action):
… кликнув на который, пользователь сможет добавить блок Группа, с уже заданными внутренними блоками и стилем Карточка.
Этот способ пригодится если функционала стандартных блоков достаточно и нужно просто сэкономить время на создании повторяющихся элементов.
Одно из ограничений этого способа — возможность создать вариацию только для одно блока. Да, можно создать вариацию для блока Группа и добавить сколько угодно внутренних блоков, но если вам нужно создать более сложную повторяющуюся структуру страницы, лучше использовать Паттерны. О них и поговорим далее.
4. Паттерны Блоков
Паттерны — относительно новый инструмент в WordPress, который позволяет регистрировать структуру из нескольких блоков и далее вставлять ее на страницы в несколько кликов.
Я подробно рассказал о паттернах в отдельной статье. Прочитайте ее, чтобы подробно ознакомиться с этим инструментом.
Вкратце рассмотрим, как зарегистрировать новый паттерн. Допустим мы часто используем следующую структуру страницы:
На изображении видно, что мы используем следующие блоки:
Для того чтобы зарегистрировать подобный паттерн, необходимо сначала создать такую комбинацию на пустой странице и скопировать ее содержимое в режиме кода.
Далее используем функцию register_block_pattern():
Обратите внимание, что свойство 'content' должно быть подготовлено для вывода на экран (escaped). Это можно сделать с помощью инструмента CodeBeautify.
Если все сделано верно, то в редакторе должен появится новый паттерн:
Паттерны — один из моих любимых инструментов, потому что ими просто пользоваться, их быстро регистрировать и они во многих случаях заменяют шаблоны страниц.
5. Фильтры Блоков
Методы, которые я описал выше позволяют совершать большое количество манипуляций со стандартными блоками, но бывают ситуации, когда этого и этого не достаточно. Приведу несколько примеров. Допустим вам необходимо:
- добавить нижний отступ к блоку, у которого уже активен один из стилей. И такой же отступ нужно добавить к нескольким другим блокам;
- отключить некоторые опции у отдельного блока, например выравнивание, и оставить при этом глобальные настройки без изменений
- добавить дополнительный div вокруг блока
- добавить CSS класс всем блокам одного типа
Эти и другие задачи можно решить с помощью фильтров.
Фильтры — пожалуй самый гибкий и в то же время сложный инструмент для работы со стандартными блоками. Раздела статьи однозначно не хватит чтобы подробно описать работу фильтров, поэтому мы кратко разберм какие бывают фильтры и рассмотрим несколько примеров.
Фильтры блоков можно условно разделить на две группы: PHP и JavaScript.
5.1 PHP Фильтры
Блоки в PHP можно фильтровать с помощью знакомой функции addFilter() и хука render_block.
Предположим, что нам необходимо добавить div c классом wp-block-list-wrapper ко всем блокам Список:
Из примера видно, что функция prefix_add_list_block_wrap() сначала проверяет с каким блоком мы имеем дело, и если это core/list } — оборачивает контент блока в дополнительный div.
Если мы все сделали правильно то маркап всех списков будет выглядеть вот так:
Стоит отметить, что этот способ не изменяет вывод блока в редакторе, а работает только с фронтэндом. Если вам необходимо изменить блок в обоих контекстах, стоит использовать JS фильтры.
5.2 JavaScript Фильтры
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. Подводя итог, повторим когда какой способ использовать
- Дополнительный CSS — небольшая модификация на одной-двух страницах.
- Стиль блока — повторяющаяся на нескольких страницах модификация блока. Каждый блок может иметь только один активный стиль.
- Вариация блока — повторяющаяся на нескольких страницах модификация блока, с более сложной структурой. Может включать стиль блока, заполнять атрибуты, и иметь внутренние блоки.
- Паттерн блока — похож на вариацию но может включать несколько блоков верхнего уровня. Подходит для создания полных страниц.
- Фильтр блока — позволяет добавлять и отключать некоторые свойства блоков, а так же редактировать маркап стандартных блоков.
Спасибо, отличная статья! Просто и понятно. Добавил в закладки.
про хук render_block - не знал.
а на js wp.hooks давно смотрю и думаю засунуть в SvelteJS - чтобы получить модульность, расширяемость и позднее связывание как у wp.