Создание новых Gutenberg блоков в WordPress с помощью WP BOX

По мере того как WordPress продолжает развиваться, редактор Gutenberg, представленный в WordPress 5.0, стал неотъемлемой частью экосистемы разработки. Gutenberg позволяет разработчикам создавать удобные и функциональные, переиспользуемые компоненты, которые обеспечивают отличный пользовательский опыт как в редакторе, так и на фронтенде сайта.

В этой статье мы пройдем через процесс создания блока Gutenberg для WordPress с помощью WP BOX.

Основные преимущества блоков Gutenberg:

• Поддержка вложенных блоков. Когда вы создаете, например, блок карточки, вы можете задать фиксированный набор вложенных блоков или позволить использовать любые блоки без ограничений. Контент-менеджер может использовать различные комбинации внутри, такие как отображение изображения с заголовком или заголовок с тегами внутри карточки, и разработчику не нужно создавать 10 различных вариаций блока карточки под разнообразный контент, карточка просто работает с любым.
• Независимость от других сущностей. Блок не зависит от других сущностей, таких как текущая страница или родительский блок, и не будет неожиданно вести себя по-разному при использовании в разных родительских блоках или на разных страницах. Хотя вы можете сделать его зависимым от данных, например, передавать цвет фона родительского блока во вложенный блок через свойства, но это не обязательно.
• Блоки работают быстро. Они быстро извлекаются из базы данных с помощью одного запроса для всей текущей страницы, быстро рендерятся и изменяют состояние при работе в редакторе, а также могут показать отличную скорость и производительность на фронтенде при соблюдении рекомендаций.

Когда потребуется создавать новые блоки Gutenberg?

Хотя WP BOX предлагает широкий выбор блоков Gutenberg, существуют ситуации, когда может потребоваться создание уникальных функциональных элементов или дизайна, которые не доступны по умолчанию. Создание собственных блоков Gutenberg позволяют разработчикам:

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

Требования

Перед тем, как приступить к созданию нового блока Gutenberg с WP BOX, вам следует:

• Иметь базовые знания JavaScript и React.
• Иметь базовые знания PHP, так как рендеринг на фронтенде осуществляется с его помощью.
• Быть знакомым с разработкой для WordPress.
• Иметь установленный WP BOX, выполнив шаги из руководства по установке.

Пошаговое руководство по созданию нового блока Gutenberg

1. Структура и примеры кода

Пользовательские блоки обычно создаются в виде плагина, который может быть использован с любой темой. Но в WP BOX мы будем использовать пайплайн для компиляции Tailwind, централизованной регистрации блоков и подключения. Эти блоки будут использоваться только WP BOX, поэтому мы создадим новый блок как компонент внутри темы.

Вам нужно создать новый каталог block-name и как минимум три файла в каталоге web/app/themes/wp-box/blocks с шаблонами кода:

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 3,
	"name": "wp-box/block-name",
	"title": "Block Name",
	"category": "layout",
	"icon": "admin-users",
	"attributes": {
		"richText": {
			"type": "string"
		}
	}
}

Этот файл создается по схеме WordPress, и нам нужно как минимум указать уникальное имя. Редактируемые пользователем поля создаются в виде «атрибутов». В этом примере мы создаем пользовательский атрибут с именем «richText», который будет возможно редактировать, также он будет отображаться на фронтенде.

<!-- block-name -->
<?php
$rich_text = ( $args['attributes']['richText'] ?? 'Block Name' );
?>
<div class="text-wrap p-4 php bg-theme-light-blue p-20 rounded-md text-heading-desktop text-center">
    <?php echo wp_kses_post($rich_text); ?>
</div>

Это шаблон, который отобразит содержание блока на фронтенде. Обратите внимание на классы Tailwind. Переменная $args из родительской области передается в render.php, вы можете использовать print_r($args) для просмотра переданных аргументов.

В нашем примере, мы будет использовать только значение «richText», указанное пользователем в редакторе.

import { registerBlockType } from '@wordpress/blocks';
import metadata from './block.json';
import {
	RichText,
	useBlockProps,
	BlockControls,
} from '@wordpress/block-editor';

registerBlockType( metadata, {
	edit: BlockEdit,
	save: BlockSave,
} );

function BlockEdit( props ) {
	const {
		isSelected,
		attributes: { richText },
		setAttributes,
	} = props;

	const blockProps = useBlockProps( {
		className: 'bg-theme-light-blue p-20 rounded-md text-heading-desktop text-center',
	} );

	const onChangeText = ( value ) => {
		setAttributes( { richText: value } );
	};

	return (
		<div { ...blockProps }>
			{ isSelected && <BlockControls /> }
			<RichText
				tagName="span"
				value={ richText }
				onChange={ onChangeText }
				placeholder="Button Text"
			/>
		</div>
	);
}

// eslint-disable-next-line no-unused-vars
function BlockSave( { attributes } ) {
	return null;
}

Давайте разберем этот код:

• registerBlockType: Эта функция регистрирует ваш блок в WordPress.
• edit: Функция, отвечающая за отображение блока в редакторе Gutenberg.
• save: Определяет, как контент блока сохраняется в базе данных.

Далее внутри BlockEdit метода происходит следующее: используется RichText компонент, добавляется вывод панели управления при выборе блока, повторяем классы Tailwind использованные в шаблоне для фронтенда, чтобы блок в редакторе выглядел также, и обрабатываем пользовательский ввод в компонент, сохраняя его в атрибуты блока и в базу данных при сохранении.

2. Компиляция React и Tailwind

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

make start

Эта команда запускает компиляцию Tailwind и React, стили CSS появятся в основном файле стилей по пути web/app/themes/wp-box/styles/dist/tailwind.css, а код React будет скомпилирован в файлы JavaScript в той же директории.

3. Регистрация и подключение блока

Этот этап автоматически обрабатывается темой, которая анализирует все файлы block.json в подкаталогах и регистрирует блоки и их ассеты там, где это необходимо.

На этом этапе вы можете попробовать добавить ваш новый блок в редакторе.

Тестирование нового пользовательского блока

Если вы выполнили все предыдущие шаги, то блок будет доступен для выбора в списке блоков редактора. Чтобы найти его начните писать имя, которое мы ему дали «Block Name».

В редакторе блок будет выглядеть вот так:

А так он будет выглядеть на фронтенде:

Заключение

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

Освоившись с созданием новых блоков, вы сможете легко создавать индивидуальные решения.