Шорткоды и блоки

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

Шорткод

Шорткод — метка в квадратных скобках, которую WordPress заменяет результатом функции:

// functions.php
 
add_shortcode('year', function (): string {
    return date('Y');
});

Атрибуты

add_shortcode('button', function (array|string $atts): string {
    $atts = shortcode_atts([
        'url' => '#',
        'text' => 'Подробнее',
        'color' => 'blue',
    ], $atts);
 
    return sprintf(
        '<a class="button button-%s" href="%s">%s</a>',
        esc_attr($atts['color']),
        esc_url($atts['url']),
        esc_html($atts['text']),
    );
});

[button url="/books/" text="Все книги" color="green"]

shortcode_atts() подставляет значения по умолчанию и отбрасывает лишние атрибуты.

Содержимое между метками

add_shortcode('note', function (array|string $atts, ?string $content = null): string {
    return '<div class="note">' . do_shortcode(wp_kses_post($content ?? '')) . '</div>';
});

[note]Скидка действует до конца месяца.[/note]

do_shortcode() обрабатывает шорткоды, вложенные внутрь.

Шорткод с запросом

add_shortcode('latest_books', function (array|string $atts): string {
    $atts = shortcode_atts(['count' => 3], $atts);
 
    $books = get_posts(['post_type' => 'book', 'numberposts' => absint($atts['count'])]);
 
    $html = '<ul class="latest-books">';
 
    foreach ($books as $book) {
        $html .= sprintf('<li><a href="%s">%s</a></li>', esc_url(get_permalink($book)), esc_html($book->post_title));
    }
 
    return $html . '</ul>';
});

Блоки

В редакторе Gutenberg содержимое состоит из блоков: абзац, картинка, колонки. Свой блок редактор вставляет мышью и настраивает в боковой панели — не нужно помнить названия и атрибуты. Заготовку блока создаёт команда:

npx @wordpress/create-block@latest book-card

Она создаёт плагин с файлом описания block.json, скриптом редактора на React и шагом сборки.

Динамический блок

Блок, содержимое которого зависит от данных, — например, список свежих книг — выводят на PHP:

// book-card.php
 
add_action('init', function () {
    register_block_type(__DIR__ . '/build', [
        'render_callback' => function (array $attributes): string {
            $count = absint($attributes['count'] ?? 3);
 
            return do_shortcode('[latest_books count="' . $count . '"]');
        },
    ]);
});

Готовые макеты

Часто свой блок не нужен: достаточно сохранить сочетание стандартных блоков как макет (pattern). Редактор вставит его одним щелчком и изменит тексты:

add_action('init', function () {
    register_block_pattern('mytheme/call-to-action', [
        'title' => 'Призыв к действию',
        'categories' => ['featured'],
        'content' => '<!-- wp:heading --><h2>Готовы начать?</h2><!-- /wp:heading --><!-- wp:buttons --><div class="wp-block-buttons"><!-- wp:button --><div class="wp-block-button"><a class="wp-block-button__link">Написать нам</a></div><!-- /wp:button --></div><!-- /wp:buttons -->',
    ]);
});

Частая ошибка

Функция шорткода должна возвращать строку, а не выводить её. Если написать echo, текст появится не там, где стоит шорткод, а в самом начале содержимого записи. Когда разметку удобнее писать обычным HTML, оберните её в буфер:

add_shortcode('hello', function (): string {
    ob_start();
    ?>
    <p class="hello">Привет!</p>
    <?php
 
    return ob_get_clean();
});

Спасибо, что читаете!