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

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

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

Шорткод — это небольшая метка в квадратных скобках, например [wpsetup_example], которая при отображении страницы заменяется на определённый контент или функциональность. Это позволяет:

• Упрощать добавление сложных элементов на страницу без знаний HTML и PHP.
• Разбивать код на повторно используемые части.
• Обеспечивать удобство для контент-менеджеров и редакторов.

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

Основы создания собственного шорткода в WordPress

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

function wpsetup_custom_shortcode( $atts ) {
    // Обработка атрибутов шорткода
    $atts = shortcode_atts( array(
        'text' => 'Привет, мир!',
    ), $atts, 'wpsetup_custom' );

    return '<div class="wpsetup-message">' . esc_html( $atts['text'] ) . '</div>';
}
add_shortcode( 'wpsetup_custom', 'wpsetup_custom_shortcode' );

В этом примере создаётся шорткод [wpsetup_custom text="Ваш текст"], который выводит текст внутри див-блока.

Обработка атрибутов шорткода

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

Безопасность вывода

Чтобы избежать уязвимостей, рекомендуется экранировать выводимые данные с помощью функций esc_html, esc_attr или подобным, в зависимости от контекста.

Пример: шорткод с динамическим выводом данных

Допустим, нам нужно создать шорткод, который выводит текущую дату и время с учётом часового пояса сайта.

function wpsetup_datetime_shortcode() {
    $datetime = current_time('Y-m-d H:i:s');
    return '<span class="wpsetup-datetime">Текущая дата и время: ' . esc_html( $datetime ) . '</span>';
}
add_shortcode( 'wpsetup_datetime', 'wpsetup_datetime_shortcode' );

Использование [wpsetup_datetime] выведет, например, «Текущая дата и время: 2024-06-05 14:23:00».

Создание шорткода с вложенным функционалом: вывод списка последних записей

Часто нужно вставить список последних записей блога с настраиваемым количеством. Сделаем шорткод с параметром count:

function wpsetup_recent_posts_shortcode( $atts ) {
    $atts = shortcode_atts( array(
        'count' => 5,
    ), $atts, 'wpsetup_recent_posts' );

    $query = new WP_Query( array(
        'posts_per_page' => intval( $atts['count'] ),
        'post_status' => 'publish',
    ) );

    if ( ! $query->have_posts() ) {
        return '<p>Записей не найдено.</p>';
    }

    $output = '<ul class="wpsetup-recent-posts">';

    while ( $query->have_posts() ) {
        $query->the_post();
        $output .= '<li><a href="' . esc_url( get_permalink() ) . '">' . esc_html( get_the_title() ) . '</a></li>';
    }

    wp_reset_postdata();

    $output .= '</ul>';

    return $output;
}
add_shortcode( 'wpsetup_recent_posts', 'wpsetup_recent_posts_shortcode' );

Такой шорткод: [wpsetup_recent_posts count="3"] выведет список из трёх последних опубликованных записей.

Советы по организации кода шорткодов

Пространство имён и уникальность

Чтобы избежать конфликтов, всегда добавляйте уникальные префиксы к именам функций и шорткодов, например, wpsetup_ в нашем случае.

Использование буферизации вывода

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

function wpsetup_buffered_shortcode() {
    ob_start();
    ?>
    <div class="wpsetup-buffered">Контент шорткода</div>
    <?php
    return ob_get_clean();
}
add_shortcode( 'wpsetup_buffered', 'wpsetup_buffered_shortcode' );

Так вы гарантируете, что шорткод всегда возвращает контент, а не выводит его напрямую.

Локализация

Если вы планируете распространять свои шорткоды, используйте функции перевода __() и _e() для локализации текста.

Расширение функционала: шорткод с параметрами и вложенными тегами

Можно создавать шорткоды, которые принимают содержимое между открывающим и закрывающим тегами, например:

function wpsetup_box_shortcode( $atts, $content = null ) {
    $atts = shortcode_atts( array(
        'color' => '#f0f0f0',
    ), $atts, 'wpsetup_box' );

    return '<div style="background-color:' . esc_attr( $atts['color'] ) . '; padding:15px; border-radius:5px;">' . do_shortcode( $content ) . '</div>';
}
add_shortcode( 'wpsetup_box', 'wpsetup_box_shortcode' );

Использование:

[wpsetup_box color="#dff0d8"]Это содержимое в цветной коробке.[/wpsetup_box]

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

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

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

• Shortcodes Ultimate — набор готовых шорткодов с визуальным редактором.
• WP Shortcode by MyThemeShop — простой и лёгкий плагин с базовыми шорткодами.
• Custom Shortcodes — позволяет создавать свои шорткоды через админку без кода.

Однако для уникальных задач лучше писать свои шорткоды, как показано выше.

Отладка и тестирование шорткодов

При создании шорткодов проверяйте их работу на разных страницах и с разными параметрами. Используйте функцию do_shortcode для программного вызова шорткодов в шаблонах:

echo do_shortcode('[wpsetup_custom text="Тест"]');

Это удобно для отладки и интеграции с темами.

Итоги

Создание собственных шорткодов — отличный способ расширить функциональность WordPress под конкретные задачи. Главное — использовать уникальные префиксы, обрабатывать атрибуты, защищать вывод и тестировать код. Приведённые примеры помогут быстро начать и сделать ваши страницы более интерактивными и удобными.