Как создать собственный шорткод в WordPress: подробное руководство

Шорткоды в WordPress — это мощный инструмент, позволяющий вставлять динамический контент в посты, страницы и виджеты с помощью простой короткой команды. Если стандартных шорткодов вам недостаточно, или нужно реализовать уникальный функционал, создание собственного шорткода — идеальное решение. В этой статье мы подробно разберём, как создавать и использовать собственные шорткоды, примеры кода и лучшие практики.

Что такое шорткод в WordPress и зачем он нужен

Шорткод — это небольшая метка в квадратных скобках, которая при выводе страницы заменяется на динамический контент. Например, стандартный шорткод [gallery] выводит галерею изображений. Создавая собственный шорткод, вы можете внедрять сложные функции без необходимости писать HTML или PHP в редакторе.

Это полезно для:

Вставки кастомных блоков контента
Вывода данных из базы или API
Автоматизации повторяющихся задач
Добавления интерактивных элементов

Шорткоды можно использовать не только в записях, но и в текстовых виджетах, шаблонах и даже в настройках темы.

Как создать собственный шорткод: базовый пример

Создание шорткода сводится к регистрации функции обратного вызова с помощью функции add_shortcode(). Например, создадим простой шорткод, который выводит текущую дату:

function wordpresses_show_date_shortcode() {
    return date('d.m.Y');
}
add_shortcode('show_date', 'wordpresses_show_date_shortcode');

Теперь, если в редакторе добавить [show_date], при выводе страницы появится текущая дата в формате дд.мм.гггг.

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

Шорткод с параметрами: как передавать и обрабатывать аргументы

Чаще всего шорткодам нужны параметры. Например, хотим выводить дату в разном формате или с префиксом. Добавим параметр format в шорткод [show_date]:

function wordpresses_show_date_shortcode($atts) {
    $atts = shortcode_atts( array(
        'format' => 'd.m.Y',
        'prefix' => '',
    ), $atts, 'show_date' );

    return $atts['prefix'] . date($atts['format']);
}
add_shortcode('show_date', 'wordpresses_show_date_shortcode');

Теперь можно писать [show_date format="Y-m-d" prefix="Сегодня: "] и получить, например, «Сегодня: 2024-06-01».

Функция shortcode_atts() помогает задать значения по умолчанию и объединить их с переданными параметрами.

Пример сложного шорткода: вывод списка последних записей

Рассмотрим более полезный пример — шорткод для вывода списка последних постов определённой категории с ссылками и датами:

function wordpresses_recent_posts_shortcode($atts) {
    $atts = shortcode_atts( array(
        'category' => '',
        'posts' => 5,
    ), $atts, 'recent_posts' );

    $query_args = array(
        'posts_per_page' => intval($atts['posts']),
        'post_status' => 'publish',
    );

    if (!empty($atts['category'])) {
        $query_args['category_name'] = sanitize_text_field($atts['category']);
    }

    $query = new WP_Query($query_args);

    if (!$query->have_posts()) {
        return '<p>Нет записей.</p>';
    }

    $output = '<ul class="wordpresses-recent-posts">';
    while ($query->have_posts()) {
        $query->the_post();
        $output .= '<li><a href="' . get_permalink() . '">' . get_the_title() . '</a> — <span class="date">' . get_the_date() . '</span></li>';
    }
    wp_reset_postdata();
    $output .= '</ul>';

    return $output;
}
add_shortcode('recent_posts', 'wordpresses_recent_posts_shortcode');

Такой шорткод можно использовать как [recent_posts category="novosti" posts="3"], чтобы вывести три последние записи из категории «новости».

Обработка безопасности и производительности

В примере мы используем функции sanitize_text_field() для очистки входных данных и wp_reset_postdata() для сброса глобальной переменной после запроса. Это важно, чтобы избежать проблем с безопасностью и нарушением цикла WordPress.

Использование шорткодов внутри PHP и виджетов

Иногда нужно вызвать шорткод не только в контенте, но и в шаблонах PHP. Для этого используйте функцию do_shortcode():

echo do_shortcode('[recent_posts category="blog" posts="5"]');

Также шорткоды поддерживаются в текстовых виджетах. Чтобы шорткоды работали в виджетах по умолчанию, добавьте в functions.php:

add_filter('widget_text', 'do_shortcode');

Полезные плагины для работы с шорткодами

Если вы хотите расширить функциональность шорткодов без программирования, обратите внимание на следующие плагины:

Shortcodes Ultimate — набор готовых шорткодов с большим количеством визуальных эффектов и элементов.
Custom Post Type UI — позволяет создавать свои типы записей, которые можно выводить через шорткоды.
WPBakery Page Builder и Elementor — визуальные конструкторы с поддержкой шорткодов.

Для разработчиков полезен также плагин Debug Bar с расширениями, чтобы отлаживать вывод шорткодов.

Советы по созданию качественных шорткодов

Чтобы ваши шорткоды были удобными и безопасными, соблюдайте несколько правил:

Используйте уникальный префикс в названиях функций и шорткодов (например, wordpresses_).
Обязательно обрабатывайте и очищайте входящие параметры.
Возвращайте результат, а не выводите его напрямую (используйте return, а не echo).
Добавляйте стили и скрипты корректно через wp_enqueue_style и wp_enqueue_script, чтобы не нарушать работу сайта.
Документируйте шорткод и параметры для удобства поддержки.

Как подключить стили и скрипты для шорткода

Чтобы подключить CSS и JS только когда используется шорткод, можно использовать следующий приём:

function wordpresses_enqueue_shortcode_assets() {
    wp_enqueue_style('wordpresses-shortcode-style', get_template_directory_uri() . '/css/shortcode-style.css');
    wp_enqueue_script('wordpresses-shortcode-script', get_template_directory_uri() . '/js/shortcode-script.js', array('jquery'), null, true);
}

function wordpresses_shortcode_with_assets($atts) {
    wordpresses_enqueue_shortcode_assets();
    return '<div class="wordpresses-special">Этот блок использует стили и скрипты.</div>';
}
add_shortcode('special_block', 'wordpresses_shortcode_with_assets');

Так вы не нагружаете сайт лишними ресурсами, а подключаете их только при необходимости.