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

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

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

Что такое шорткод и зачем создавать собственный

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

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

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

Как зарегистрировать шорткод в WordPress

Регистрация шорткода происходит с помощью функции add_shortcode(). Она принимает два параметра: имя шорткода и callback-функцию, которая будет вызываться при обработке шорткода.

Рассмотрим пример простого шорткода, который выведет приветствие:

function wpbe_hello_shortcode() {
    return 'Привет, это мой первый шорткод!';
}
add_shortcode('wpbe_hello', 'wpbe_hello_shortcode');

Теперь в записи или на странице можно вставить [wpbe_hello], и на сайте появится текст: "Привет, это мой первый шорткод!".

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

Добавляем параметры в шорткод: базовый пример

Чтобы сделать шорткод более гибким, можно добавить параметры. Например, пусть наш шорткод принимает параметр name, который будет подставлять имя в приветствие.

function wpbe_hello_shortcode($atts) {
    $attributes = shortcode_atts(
        array(
            'name' => 'Гость',
        ),
        $atts
    );

    return 'Привет, ' . esc_html($attributes['name']) . '!';
}
add_shortcode('wpbe_hello', 'wpbe_hello_shortcode');

Теперь, вызвав шорткод [wpbe_hello name="Алексей"], вы получите на сайте: "Привет, Алексей!". Если параметр не передан, по умолчанию будет "Гость".

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

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

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

Вот пример реализации:

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

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

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

    $query = new WP_Query($args);

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

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

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

    wp_reset_postdata();

    $output .= '</ul>';

    return $output;
}
add_shortcode('wpbe_recent_posts', 'wpbe_recent_posts_shortcode');

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

• [wpbe_recent_posts] — выведет 5 последних записей;
• [wpbe_recent_posts count="3"] — выведет 3 последних записи;
• [wpbe_recent_posts category="novosti"] — выведет 5 последних записей из категории "novosti";
• [wpbe_recent_posts count="4" category="blog"] — выведет 4 записи из категории "blog".

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

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

Важно всегда проверять и фильтровать входящие данные в шорткодах, чтобы избежать XSS-уязвимостей и других проблем безопасности. В нашем примере выше мы использовали esc_html() и sanitize_text_field() для очистки данных.

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

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

Подключение внешних стилей и скриптов для шорткода

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

Пример подключения CSS для шорткода:

function wpbe_enqueue_shortcode_assets() {
    wp_enqueue_style('wpbe-shortcode-style', get_stylesheet_directory_uri() . '/css/wpbe-shortcode.css');
}

function wpbe_recent_posts_shortcode($atts) {
    wpbe_enqueue_shortcode_assets();
    // остальной код шорткода
}

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

Заключение: когда и почему стоит создавать собственные шорткоды

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

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