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

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

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

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

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

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

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

Рассмотрим самый простой пример — создадим шорткод, который выводит приветствие.

function wptemy_hello_shortcode() {
    return '<div>Привет, это мой первый шорткод!</div>';
}
add_shortcode('wptemy_hello', 'wptemy_hello_shortcode');

Теперь, если в записи или странице вставить [wptemy_hello], на сайте отобразится блок с текстом «Привет, это мой первый шорткод!».

Обратите внимание, что функция возвращает строку, а не выводит её напрямую. Это важно для корректной работы шорткодов.

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

Часто нужно, чтобы шорткод был гибким и мог принимать параметры. Например, поменять текст приветствия или цвет шрифта. Для этого функция шорткода принимает аргумент — массив параметров $atts.

Давайте добавим параметр name, который будет менять имя в приветствии.

function wptemy_hello_name_shortcode($atts) {
    $atts = shortcode_atts(
        array('name' => 'гость'),
        $atts,
        'wptemy_hello_name'
    );
    return '<div>Привет, ' . esc_html($atts['name']) . '!</div>';
}
add_shortcode('wptemy_hello_name', 'wptemy_hello_name_shortcode');

Теперь в редакторе можно использовать шорткод [wptemy_hello_name name="Андрей"], и пользователь увидит «Привет, Андрей!». Если параметр не указан, по умолчанию будет «гость».

Функция shortcode_atts помогает задавать значения по умолчанию и объединять их с переданными параметрами, а esc_html защищает вывод от XSS-уязвимостей.

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

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

Создадим шорткод wptemy_latest_posts с параметрами count (количество записей) и category (категория по slug).

function wptemy_latest_posts_shortcode($atts) {
    $atts = shortcode_atts(
        array(
            'count' => 5,
            'category' => ''
        ),
        $atts,
        'wptemy_latest_posts'
    );

    $query_args = array(
        'posts_per_page' => intval($atts['count']),
        '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="wptemy-latest-posts">';
    while ($query->have_posts()) {
        $query->the_post();
        $thumb = get_the_post_thumbnail(get_the_ID(), 'thumbnail');
        $title = get_the_title();
        $permalink = get_permalink();

        $output .= '<li>';
        if ($thumb) {
            $output .= '<a href="' . esc_url($permalink) . '">' . $thumb . '</a> ';
        }
        $output .= '<a href="' . esc_url($permalink) . '">' . esc_html($title) . '</a>';
        $output .= '</li>';
    }
    wp_reset_postdata();

    $output .= '</ul>';
    return $output;
}
add_shortcode('wptemy_latest_posts', 'wptemy_latest_posts_shortcode');

Использование: [wptemy_latest_posts count="3" category="novosti"] — выведет 3 последние записи из категории «novosti». Если параметр category опустить, будут показаны записи из всех категорий.

Как стилизовать вывод шорткода

Чтобы шорткод выглядел красиво, нужно добавить CSS. Можно подключить стили через файл темы или через хук wp_enqueue_scripts. Например:

function wptemy_enqueue_styles() {
    wp_enqueue_style('wptemy-shortcodes-style', get_template_directory_uri() . '/css/wptemy-shortcodes.css');
}
add_action('wp_enqueue_scripts', 'wptemy_enqueue_styles');

В файле wptemy-shortcodes.css можно прописать стили для класса .wptemy-latest-posts:

.wptemy-latest-posts {
    list-style: none;
    padding: 0;
}
.wptemy-latest-posts li {
    margin-bottom: 10px;
    display: flex;
    align-items: center;
}
.wptemy-latest-posts img {
    margin-right: 10px;
    border-radius: 4px;
}

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

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

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

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

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

• Всегда возвращайте контент из функции шорткода, а не выводите его напрямую через echo.
• Обрабатывайте и фильтруйте входящие параметры с помощью shortcode_atts и функций безопасности (esc_html, sanitize_text_field).
• Используйте уникальный префикс для функций и названий шорткодов, чтобы избежать конфликтов с другими плагинами или темами. В нашем случае — wptemy_.
• Тестируйте шорткод с разными параметрами и в разных местах сайта (записи, страницы, виджеты).
• Добавляйте стили и скрипты только при необходимости, чтобы не замедлять загрузку сайта.