Як створити Gutenberg блок WordPress за допомогою Advanced Custom Fields (ACF)

Привіт:) У цьому гайді покажу на прикладі як створити Gutenberg блок WordPress за допомогою популярного плагіну Advanced Custom Fields (ACF).

WordPress плагін ACF призначений для створення користувацьких полів для редагування контенту. Починаючи із версії 5.8.0, платна версія ACF Pro "вміє" створювати повноцінні Gutenberg-блоки на основі власних вбудованих полів (Текст, Зображення, Повторювач і т.п.) Цей функціонал називається ACF Blocks.

Офіційна документація рекомендує створювати нові блоки за допомогою JavaScript-бібліотеки React у середовищі Node.Js. А тому розробник повинен на достатньому рівні розуміти мову JavaScript та розбиратися у тонкощах роботи з бібліотекою. За допомогою ACF Blocks створення блоку стає простішим, бо виключається необхідність використання JavaScript-коду.

Як створити WordPress блок за допомогою ACF Blocks

Покажу весь процес створення на прикладі Gutenberg-блоку Відгуки.

Gutenberg-блок Відгуки

У блоці через редактор посту/сторінки користувач може задати та відредагувати наступні поля:

  • зображення (іконка) того, хто надсилає відгук;
  • його коментар;
  • ім’я;
  • короткий опис;
  • колір тексту й фону картки.
  1. Встановіть та активуйте плагін ACF Pro 5.8.0 або пізнішої версії.
  2. Створіть та активуйте дочірню WordPress-тему.

У своєму прикладі використовую дочірню тему Twenty Twenty-One Child Theme. Батьківською може бути як звичайна класична тема, так і блокова.

  1. Відкрийте каталог створеної дочірньої теми у будь-якому редакторі коду та у файлі functions.php додайте код
add_action( 'init', 'twentytwentyonechild_register_acf_blocks' );
function twentytwentyonechild_register_acf_blocks() {
    register_block_type( __DIR__ . '/blocks/testimonial' );
}

У коді міститься виклик вбудованої WordPress-функції register_block_type(), яка реєструє новий Gutenberg-блок. ЇЇ аргументом є шлях до каталогу __DIR__ . '/blocks/testimonial', у якому міститься необхідний файл block.json для коректної роботи блока. Моя користувацька функція twentytwentyonechild_register_acf_blocks() прив’язується до хуку init. А це означає, що вона буде викликана на початку життєвого циклу всіх процесів WordPress.

  1. В основному каталозі дочірньої теми створіть наступну структуру підкаталогів та файлів:
/wp-content/themes/twentytwentyone-child/acf-json
/wp-content/themes/twentytwentyone-child/blocks
/wp-content/themes/twentytwentyone-child/blocks/testimonial
/wp-content/themes/twentytwentyone-child/blocks/testimonial/block.json
/wp-content/themes/twentytwentyone-child/blocks/testimonial/testimonial.css
/wp-content/themes/twentytwentyone-child/blocks/testimonial/testimonial.php
  1. У файл block.json додайте код
{
    "name": "acf/testimonial",
    "title": "Testimonial",
    "description": "A custom testimonial block that uses ACF fields.",
    "style": [ "file:./testimonial.css" ],
    "category": "formatting",
    "icon": "admin-comments",
    "keywords": ["testimonial", "quote"],
    "acf": {
        "mode": "preview",
        "renderTemplate": "testimonial.php"
    },
    "supports": {
        "anchor": true
    }
}

Значення JSON-ключів:

  • name. Унікальний ідентифікатор блоку з простором імен.  Він має відповідати формату "простір імен/назва-блоку".  Блоки ACF за замовчуванням використовують простір імен acf.
  • title. Мітка для блоку, що використовується в інтерфейсах користувача ACF і WordPress.
  • description. Коротке пояснення призначення блоку, яке відображається під час його редагування.
  • style. Це посилання на CSS-файл, директиви якого буде застосовано у редакторі та користувацькій частині блоку. У цьому випадку файл testimonial.css знаходиться у тому ж каталозі, що й block.json.
  • category. Категорія, у якій буде згруповано блок під час відображення у функціоналі вставки блоків (наприклад, ТЕКСТ, МЕДІА, ДИЗАЙН, ВІДЖЕТИ, ВСТАВКИ).
  • icon. Іконка, пов’язана з блоком. Дозволяється використовувати Dashicons (https://developer.wordpress.org/resource/dashicons/), або SVG.
  • keywords. Масив пошукових міток, потрібних щоб допомогти редакторам сайту знайти ваш блок.
  • acf. Ключ ACF, який дозволяє встановити режим попереднього перегляду (preview, auto або edit) і вказує на файл шаблону, що використовується для малювання полів ACF у блоці. У моєму випадку це testimonial.php. Як і у випадку зі стилями, файл шаблону знаходиться у тому ж каталозі, що й block.json.
  • supports. Це об’єкт, що вказує на функції, які блок підтримує або замінює (перевизначає). Наприклад спеціальні кольори, вирівнювання тексту або адаптивне вбудовування.
Повний список метаданих доступний в оф. документації:

https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/
  1. Створіть групу ACF-полів.

Файл testimonial.php, на який посилається block.json, міститиме всю логіку відображення ACF-полів. А тому їх потрібно створити через адмін-меню ACF -> Групи полів. Для цього спочатку створіть нову групу із назвою "Block: Testimonial". Далі додайте потрібні поля.

  • Quote. Тип: Текстова область (Text Area). Містить цитату як текст відгуку.
  • Author. Тип: Текст (Text). Ім’я того, хто залишив відгук.
  • Role. Тип: Текст (Text). Короткий опис. Наприклад, посада.
  • Image. Тип: Зображення (Image). Фото або іконка того, хто залишив відгук.
  • Color Settings. Тип: Акордеон (Accordion). Група полів нижче, які містять палітру кольорів для фону та тексту.
  • Background Color. Тип: Вибір кольору (Color Picker). Колір фону картки відгуку.
  • Text Color. Тип: Вибір кольору (Color Picker). Колір тексту відгуку.
Група ACF-полів
  1. Створіть Gutenberg-блок.

Прокрутіть сторінку донизу, знайдіть секцію Налаштування та клацніть на вкладці Location Rules. В групі опцій Показувати групу полів, якщо оберіть відповідно наступні значення:

  • Блок,
  • дорівнює,
  • Testimonial.
  1. Збережіть зміни, клацнувши кнопку Save Changes.

Одразу після цього в каталозі /wp-content/themes/twentytwentyone-child/acf-json з’явиться файл group_xxxxxx.json зі всіма необхідними для Gutenberg-блоку даними.

Щоразу, коли оновлюється група полів "Block: Testimonial" та зберігаються зміни, наявний файл group_xxxxxx.json оновлюється і замінюється останньою інформацією.

  1. Створіть шаблон блоку.

У файлі /wp-content/themes/twentytwentyone-child/blocks/testimonial/testimonial.php розмістіть код

<?php
/**
 * Testimonial Block template.
 *
 * @param array $block The block settings and attributes.
 */

// Load values and assign defaults.
$quote             = !empty(get_field( 'quote' )) ? get_field( 'quote' ) : 'Your quote here...';
$author            = get_field( 'author' );
$author_role       = get_field( 'role' );
$image             = get_field( 'image' );
$background_color  = get_field( 'background_color' ); // ACF's color picker.
$text_color        = get_field( 'text_color' ); // ACF's color picker.
$quote_attribution = '';

if ( $author ) {
    $quote_attribution .= '<footer class="testimonial__attribution">';
    $quote_attribution .= '<cite class="testimonial__author">' . $author . '</cite>';

    if ( $author_role ) {
        $quote_attribution .= '<span class="testimonial__role">' . $author_role . '</span>';
    }

    $quote_attribution .= '</footer><!-- .testimonial__attribution -->';
}

// Support custom "anchor" values.
$anchor = '';
if ( ! empty( $block['anchor'] ) ) {
    $anchor = 'id="' . esc_attr( $block['anchor'] ) . '" ';
}

// Create class attribute allowing for custom "className" and "align" values.
$class_name = 'testimonial';
if ( ! empty( $block['className'] ) ) {
    $class_name .= ' ' . $block['className'];
}
if ( ! empty( $block['align'] ) ) {
    $class_name .= ' align' . $block['align'];
}
if ( $background_color || $text_color ) {
    $class_name .= ' has-custom-acf-color';
}

// Build a valid style attribute for background and text colors.
$styles = array( 'background-color: ' . $background_color, 'color: ' . $text_color );
$style  = implode( '; ', $styles );
?>

<div <?php echo esc_attr( $anchor ); ?>class="<?php echo esc_attr( $class_name ); ?>" style="<?php echo esc_attr( $style ); ?>">
    <div class="testimonial__col">
        <blockquote class="testimonial__blockquote">
            <?php echo esc_html( $quote ); ?>

            <?php if ( !empty( $quote_attribution ) ) : ?>
                <?php echo wp_kses_post( $quote_attribution ); ?>
            <?php endif; ?>
        </blockquote>
    </div>

    <?php if ( $image ) : ?>
        <div class="testimonial__col">
            <figure class="testimonial__image">
                <?php echo wp_get_attachment_image( $image['ID'], 'full', '', array( 'class' => 'testimonial__img' ) ); ?>
            </figure>
        </div>
    <?php endif; ?>
</div>

Коротко по коду.

Перші рядки — коментар, в якому вказується інформація, що цей файл є шаблоном для блока.

Наступний блок коду отримує значення створених ACF-полів для блоку та зберігає їх у відповідних змінних.

// Load values and assign defaults.
$quote             = !empty(get_field( 'quote' )) ? get_field( 'quote' ) : 'Your quote here...';
$author            = get_field( 'author' );
$author_role       = get_field( 'role' );
$image             = get_field( 'image' );
$background_color  = get_field( 'background_color' ); // ACF's color picker.
$text_color        = get_field( 'text_color' ); // ACF's color picker.
$quote_attribution = '';

Далі передається ідентифікатор прив'язки (HTML-якір), який редактори можуть вводити для кожного блоку в редакторі.

HTML-якір для Gutenberg блоку

Наступна конструкція повністю виключає можливість у редакторі блоку задати йому унікальний клас (див. опцію ДОДАТКОВІ КЛАСИ CSS):

// Create class attribute allowing for custom "className" and "align" values.
$class_name = 'testimonial';
if ( ! empty( $block['className'] ) ) {
    $class_name .= ' ' . $block['className'];
}

Далі перевіряються будь-які спеціальні класи вирівнювання, які ввімкнено за замовчуванням і успадковані від API блоків ядра WordPress. Крім того, передаються власний колір фону та колір тексту.

if ( ! empty( $block['align'] ) ) {
    $class_name .= ' align' . $block['align'];
}
if ( $background_color || $text_color ) {
    $class_name .= ' has-custom-acf-color';
}

Нарешті, задається логіка виведення блоку. Задаються стиль фону, кольори тексту тощо:

// Build a valid style attribute for background and text colors.
$styles = array( 'background-color: ' . $background_color, 'color: ' . $text_color );
$style  = implode( '; ', $styles );

В кінці коду виведення HTML-шаблону блоку та підставлення у нього даних із заповнених ACF-полів:

<div <?php echo esc_attr( $anchor ); ?>class="<?php echo esc_attr( $class_name ); ?>" style="<?php echo esc_attr( $style ); ?>">
    <div class="testimonial__col">
        <blockquote class="testimonial__blockquote">
            <?php echo esc_html( $quote ); ?>

            <?php if ( !empty( $quote_attribution ) ) : ?>
                <?php echo wp_kses_post( $quote_attribution ); ?>
            <?php endif; ?>
        </blockquote>
    </div>

    <?php if ( $image ) : ?>
        <div class="testimonial__col">
            <figure class="testimonial__image">
                <?php echo wp_get_attachment_image( $image['ID'], 'full', '', array( 'class' => 'testimonial__img' ) ); ?>
            </figure>
        </div>
    <?php endif; ?>
</div>
  1. Додайте стилі для блоку.

У файлі /wp-content/themes/twentytwentyone-child/blocks/testimonial/testimonial.css розмістіть код:

.testimonial {
    --testimonial-font-family: Baskerville,Baskerville Old Face,Hoefler Text,Garamond,Times New Roman,serif; 
    --testimonial-font-size: 1.5rem;
    --testimonial-spacing: 0.5rem;
}

.testimonial {
    align-items: center;
    box-sizing: border-box;
    display: flex;
    flex-wrap: wrap;
}

.testimonial > * {
    box-sizing: border-box;
    flex-grow: 1;
    min-width: 0;
    overflow-wrap: break-word;
    width: 100%;
    word-break: break-word;
}

.testimonial__blockquote {
    align-self: center;
    font-family: var(--testimonial-font-family);
    font-size: var(--testimonial-font-size);
    line-height: 1.18;
    padding: calc(4 * var(--testimonial-spacing)) calc(4.5 * var(--testimonial-spacing)) calc(2.5 * var(--testimonial-spacing));
    position: relative;
}

.testimonial__blockquote::before {
    color: currentColor;
    content: "“";
    display: block;
    font-family: var(--testimonial-font-family);
    font-size: calc(8 * var(--testimonial-spacing));
    position: absolute;
    top: calc(-1.25 * var(--testimonial-spacing));
}

.testimonial__attribution {
    font-family: var(--wp--preset--font-family--system-font);
    font-size: calc(0.6 * var(--testimonial-font-size));
    line-height: 1.5;
    margin-top: calc(2 * var(--testimonial-spacing));
}

.testimonial__author {
    font-style: normal;
    font-weight: 700;
}

.testimonial__role {
    display: block;
}

.testimonial__image {
    box-sizing: border-box;
    height: 100%;
    line-height: 0;
    margin-bottom: 0;
}

.testimonial__image img {
    height: 100%;
}

.testimonial__img {
    box-sizing: border-box;
    max-width: 100%;
    object-fit: cover;
}

@media (min-width: 600px) {
    .testimonial {
        flex-wrap: nowrap;
    }

    .testimonial__col:first-of-type {
        flex-basis: 64%;
    }

    .testimonial__col:last-of-type {
        flex-basis: 38%;
    }
}

Практично немає обмежень щодо стилю ваших блоків. Код вище зможете змінювати на свій розсуд, бо саме ви вирішуєте, як виглядатиме ваш блок.

  1. Протестуйте блок.

Відкрийте сторінку або пост на редагування, додайте блок Testimonial, заповніть його поля та збережіть зміни.

Редагування Gutenberg блоку Testimonial
Завантажити код готової WordPress-теми.

Джерело: https://www.advancedcustomfields.com/resources/create-your-first-acf-block/

Ще статті за категорією:
Ще статті за тегом:
Позначки
Михайло Петров
Михайло Петров

Мене звати Михайло. Я є WordPress-розробником. Створюю сайти з "нуля", розробляю плагіни, оновлюю наявний функціонал та підтримую готові проєкти.

Залишити відповідь

Ваша e-mail адреса не оприлюднюватиметься. Обов’язкові поля позначені *