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

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

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

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

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

Создание индивидуального шорткода: базовые шаги

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

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

    return '<p>Привет, ' . esc_html($atts['name']) . '! Добро пожаловать на наш сайт.</p>';
}
add_shortcode('wpmarketing_greeting', 'wpmarketing_greeting_shortcode');

Вызов шорткода: [wpmarketing_greeting name="Иван"] выведет: «Привет, Иван! Добро пожаловать на наш сайт.»

Разбор кода

Функция wpmarketing_greeting_shortcode принимает атрибуты, задаёт значение по умолчанию с помощью shortcode_atts и возвращает HTML с приветствием. Функция esc_html защищает от XSS-атак, экранируя данные.

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

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

function wpmarketing_latest_posts_shortcode($atts) {
    $atts = shortcode_atts(array(
        'category' => '',
        'posts' => 3,
    ), $atts, 'wpmarketing_latest_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>';
    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('wpmarketing_latest_posts', 'wpmarketing_latest_posts_shortcode');

Шорткод [wpmarketing_latest_posts category="marketing" posts="5"] выведет 5 последних записей из категории «marketing».

Объяснение

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

Практические советы по разработке шорткодов

Безопасность и санитизация данных

Всегда проверяйте и очищайте входящие данные. Для текстовых атрибутов используйте sanitize_text_field(), для числовых — intval(). Выводите HTML через функции экранирования, например, esc_html() или esc_url().

Кэширование результата шорткода

Если шорткод делает сложные запросы или выводит данные, которые меняются редко, стоит реализовать кэширование с помощью Transient API. Это снизит нагрузку на сервер.

function wpmarketing_cached_shortcode() {
    $cache_key = 'wpmarketing_cached_output';
    $output = get_transient($cache_key);

    if ($output === false) {
        // Генерация контента
        $output = '<p>Данные с кешированием</p>';
        set_transient($cache_key, $output, 12 * HOUR_IN_SECONDS);
    }

    return $output;
}
add_shortcode('wpmarketing_cached', 'wpmarketing_cached_shortcode');

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

Проверяйте шорткоды в разных контекстах: в редакторе Gutenberg, классическом редакторе, в виджетах. Используйте error_log() для вывода отладочной информации в файл журнала.

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

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

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

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

Пример комплексного шорткода с параметрами и HTML-форматированием

Например, создадим шорткод, который выводит блок с отзывом пользователя с параметрами имени, текста и рейтинга:

function wpmarketing_testimonial_shortcode($atts) {
    $atts = shortcode_atts(array(
        'author' => 'Аноним',
        'text' => 'Отзыв отсутствует.',
        'rating' => 5,
    ), $atts, 'wpmarketing_testimonial');

    $rating = intval($atts['rating']);
    if ($rating < 1) $rating = 1;
    if ($rating > 5) $rating = 5;

    $stars = str_repeat('★', $rating) . str_repeat('☆', 5 - $rating);

    $output = '<div class="wpmarketing-testimonial">';
    $output .= '<p class="testimonial-text">' . esc_html($atts['text']) . '</p>';
    $output .= '<p class="testimonial-author">— ' . esc_html($atts['author']) . '</p>';
    $output .= '<p class="testimonial-rating">' . $stars . '</p>';
    $output .= '</div>';

    return $output;
}
add_shortcode('wpmarketing_testimonial', 'wpmarketing_testimonial_shortcode');

Вызов: [wpmarketing_testimonial author="Елена" text="Отличный сервис!" rating="4"] выведет красиво оформленный отзыв с 4 звёздами.

Стили для блока можно добавить в CSS темы:

.wpmarketing-testimonial {
    border: 1px solid #ccc;
    padding: 15px;
    margin: 20px 0;
    background-color: #f9f9f9;
    border-radius: 5px;
}
.wpmarketing-testimonial .testimonial-text {
    font-style: italic;
    margin-bottom: 10px;
}
.wpmarketing-testimonial .testimonial-author {
    font-weight: bold;
    margin-bottom: 5px;
}
.wpmarketing-testimonial .testimonial-rating {
    color: #f39c12;
}