ACF 5.8 — блоки ACF для Gutenberg: создание пользовательских блоков на PHP

Зачем нужны ACF Blocks

Gutenberg — новый блочный редактор WordPress — открывает разработчикам возможность создавать собственные типы блоков. Но вручную создавать блоки крайне сложно: даже простой блок отзывов требует огромного объёма JavaScript-кода.

ACF Blocks решает эту проблему. Теперь можно создавать пользовательские блоки для Gutenberg, используя привычные PHP и HTML вместо сложного JavaScript. Вся тяжёлая работа ложится на плагин — разработчику остаётся только настроить и написать шаблон.

Всего три шага — и блок готов к использованию.

Шаг 1 — Регистрация блока

Регистрация блока напоминает регистрацию типа записи в WordPress. Функция `acf_register_block()` принимает массив настроек: имя, описание, иконка, категория и callback-функция для отрисовки.

add_action('acf/init', 'my_acf_init');
function my_acf_init() {

    // проверяем существование функции
    if( function_exists('acf_register_block') ) {

        // регистрируем блок отзывов
        acf_register_block(array(
            'name'              => 'testimonial',
            'title'             => __('Отзыв'),
            'description'       => __('Пользовательский блок для отзывов.'),
            'render_callback'   => 'my_acf_block_render_callback',
            'category'          => 'formatting',
            'icon'              => 'admin-comments',
            'keywords'          => array( 'отзыв', 'цитата' ),
        ));
    }
}

Параметры настройки аналогичны тем, что принимает JavaScript-функция `registerBlockType()` в WordPress.

Шаг 2 — Создание группы полей

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

В правилах местоположения достаточно выбрать правило «Блок» и указать зарегистрированный тип блока. После этого поля будут отображаться при редактировании блока в Gutenberg.

Шаг 3 — Отрисовка блока

Последний шаг — указать ACF, как отрисовывать блок. Это тот же процесс, что и для обычных полей ACF, только HTML и PHP оборачиваются в функцию.

Callback-функция, указанная в `render_callback`, отвечает за вывод HTML. Рекомендуется использовать модульный подход: подключать шаблонную часть через параметр `$block`.

function my_acf_block_render_callback( $block ) {

    // преобразуем имя ("acf/testimonial") в slug ("testimonial")
    $slug = str_replace('acf/', '', $block['name']);

    // подключаем шаблон из папки "template-parts/block"
    if( file_exists( get_theme_file_path("/template-parts/block/content-{$slug}.php") ) ) {
        include( get_theme_file_path("/template-parts/block/content-{$slug}.php") );
    }
}

Сам шаблон блока:

<?php
/**
 * Block Name: Testimonial
 *
 * Шаблон отображения блока отзывов.
 */

// получаем поле изображения (массив)
$avatar = get_field('avatar');

// создаём id для стилизации
$id = 'testimonial-' . $block&#91;'id'&#93;;

// создаём класс выравнивания из настроек блока
$align_class = $block&#91;'align'&#93; ? 'align' . $block&#91;'align'&#93; : '';

?>
<blockquote id="<?php echo $id; ?>" class="testimonial <?php echo $align_class; ?>">
    <p><?php the_field('testimonial'); ?></p>
    <cite>
        <img src="<?php echo $avatar&#91;'url'&#93;; ?>" alt="<?php echo $avatar&#91;'alt'&#93;; ?>" />
        <span><?php the_field('author'); ?></span>
    </cite>
</blockquote>
<style type="text/css">
    #<?php echo $id; ?> {
        background: <?php the_field('background_color'); ?>;
        color: <?php the_field('text_color'); ?>;
    }
</style>

Для подключения стилей используются стандартные хуки `admin_enqueue_scripts` и `wp_enqueue_scripts`.

Блоки и метабоксы — в чём разница

ACF Blocks не заменяют метабоксы. Метабоксы по-прежнему остаются важной частью процесса разработки и сохраняют данные как «meta» — отдельные значения в таблице `wp_postmeta`. Разработчик полностью контролирует, где и когда они появляются в шаблонах темы. Это идеальный вариант для сайтов с фиксированной структурой.

Блоки сохраняют данные внутри `post_content` в виде JSON в HTML-комментариях. Пользователь сам решает, где разместить блок в тексте статьи. Это удобно для блогов и контентных страниц.

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

Режим предпросмотра

Главное преимущество Gutenberg перед классическим редактором — блоки лучше отражают реальный вид страницы. ACF Blocks поддерживает это через режим предпросмотра: достаточно нажать кнопку «Переключить на предпросмотр» в настройках блока.

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

Выравнивание блоков

ACF Blocks поддерживает панель выравнивания Gutenberg. Блоки можно выравнивать по центру, влево или вправо, а также использовать режимы «широкий» и «на всю ширину» для выхода за пределы контейнера.

Когда ожидать

ACF Blocks будет включён как в бесплатную, так и в PRO-версию ACF 5.8. Клиенты ACF PRO могут протестировать бета-версию 5.8.0-beta1 уже сейчас — достаточно скачать её из личного кабинета.