Создание собственного шорткода в WordPress: пошаговое руководство

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

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

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

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

Далее мы рассмотрим, как реализовать такой шорткод на практике.

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

Чтобы создать шорткод, нужно написать PHP-функцию, которая возвращает HTML или другой вывод, и зарегистрировать её с помощью функции add_shortcode. Рассмотрим простой пример создания шорткода [wpqa_hello], который выводит приветствие.

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

Этот код регистрируем в файле functions.php вашей темы или в отдельном плагине. После этого при вставке в контент [wpqa_hello] появится текст с приветствием.

Как использовать параметры в шорткодах

Часто нужно передавать параметры в шорткод для динамического вывода. Например, шорткод [wpqa_hello name="Иван"] должен приветствовать конкретного пользователя.

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

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

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

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

function wpqa_recent_posts_shortcode($atts) {
    $atts = shortcode_atts(
        array('count' => 5),
        $atts,
        'wpqa_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="wpqa-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('wpqa_recent_posts', 'wpqa_recent_posts_shortcode');

Теперь, вставив [wpqa_recent_posts count="3"], вы получите список из трёх последних опубликованных постов с кликабельными заголовками.

Кастомизация и расширение функционала шорткодов

Вы можете расширять шорткоды, добавляя дополнительные параметры, стили и JavaScript. Например, добавим параметр для выбора категории:

function wpqa_recent_posts_shortcode($atts) {
    $atts = shortcode_atts(
        array(
            'count' => 5,
            'category' => ''
        ),
        $atts,
        'wpqa_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="wpqa-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('wpqa_recent_posts', 'wpqa_recent_posts_shortcode');

Теперь шорткод [wpqa_recent_posts count="3" category="novosti"] выведет последние три поста из категории «novosti».

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

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

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

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

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

При разработке собственных шорткодов учитывайте несколько рекомендаций:

• Используйте префиксы в названиях функций и шорткодов, чтобы избежать конфликтов с другими плагинами или темами (например, префикс wpqa_).
• Обязательно экранируйте вывод с помощью esc_html() или аналогичных функций, чтобы защититься от XSS-уязвимостей.
• Не выводите данные напрямую, возвращайте строку из функции — так шорткод будет работать корректно в любом месте.
• Используйте wp_reset_postdata() после кастомных запросов, чтобы не нарушать глобальный цикл WordPress.
• Документируйте параметры шорткода для удобства использования другими пользователями.

Как подключить CSS и JS для шорткодов

Если шорткод требует стили или скрипты, подключайте их с помощью wp_enqueue_style и wp_enqueue_script, используя хук wp_enqueue_scripts. Можно добавить проверку, чтобы загружать ресурсы только если шорткод используется на странице.

function wpqa_enqueue_shortcode_assets() {
    global $post;
    if (has_shortcode($post->post_content, 'wpqa_recent_posts')) {
        wp_enqueue_style('wpqa-shortcode-style', get_template_directory_uri() . '/css/wpqa-shortcode.css');
        wp_enqueue_script('wpqa-shortcode-script', get_template_directory_uri() . '/js/wpqa-shortcode.js', array('jquery'), null, true);
    }
}
add_action('wp_enqueue_scripts', 'wpqa_enqueue_shortcode_assets');