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

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

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

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

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

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

Для регистрации шорткода используется функция add_shortcode. Давайте создадим простой шорткод [wpbook_hello], который выводит приветствие.

function wpbook_hello_shortcode() {
    return '<p>Привет от wpbook.ru!</p>';
}
add_shortcode('wpbook_hello', 'wpbook_hello_shortcode');

Добавьте этот код в файл functions.php вашей темы или в отдельный плагин. Теперь в любом посте, если вы вставите [wpbook_hello], появится текст с приветствием.

Почему важно возвращать контент, а не выводить с помощью echo

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

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

Чаще всего шорткодам нужны параметры для гибкости. Например, создадим шорткод [wpbook_button url="https://wpbook.ru" text="Посетить сайт"], который выведет кнопку.

function wpbook_button_shortcode($atts) {
    $atts = shortcode_atts(
        array(
            'url' => '#',
            'text' => 'Кнопка',
        ), $atts, 'wpbook_button');

    return '<a href="' . esc_url($atts['url']) . '" class="wpbook-button">' . esc_html($atts['text']) . '</a>';
}
add_shortcode('wpbook_button', 'wpbook_button_shortcode');

Этот код позволяет создавать кнопки с разными ссылками и текстом. Обратите внимание на функции esc_url и esc_html — они обеспечивают безопасность вывода, предотвращая XSS-атаки.

Подключаем стили для кнопок

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

function wpbook_enqueue_styles() {
    wp_enqueue_style('wpbook-shortcodes', get_stylesheet_directory_uri() . '/css/wpbook-shortcodes.css');
}
add_action('wp_enqueue_scripts', 'wpbook_enqueue_styles');

В файл wpbook-shortcodes.css добавьте стили:

.wpbook-button {
    display: inline-block;
    padding: 10px 20px;
    background-color: #0073aa;
    color: #fff;
    text-decoration: none;
    border-radius: 3px;
}
.wpbook-button:hover {
    background-color: #005177;
}

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

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

Например, создадим шорткод [wpbook_alert type="error"]Текст сообщения[/wpbook_alert], который выводит цветной блок с сообщением.

function wpbook_alert_shortcode($atts, $content = null) {
    $atts = shortcode_atts(array(
        'type' => 'info',
    ), $atts, 'wpbook_alert');

    $type_class = 'wpbook-alert-' . sanitize_html_class($atts['type']);
    return '<div class="wpbook-alert ' . esc_attr($type_class) . '">' . do_shortcode($content) . '</div>';
}
add_shortcode('wpbook_alert', 'wpbook_alert_shortcode');

Добавьте стили для разных типов сообщений:

.wpbook-alert { padding: 15px; border-radius: 4px; margin: 10px 0; }
.wpbook-alert-info { background-color: #d9edf7; color: #31708f; }
.wpbook-alert-error { background-color: #f2dede; color: #a94442; }
.wpbook-alert-success { background-color: #dff0d8; color: #3c763d; }

Пример использования вложенных шорткодов

Вы можете использовать внутри [wpbook_alert] другие шорткоды, например:

[wpbook_alert type="error"]Ошибка! Пожалуйста, нажмите [wpbook_button url="https://wpbook.ru/help" text="сюда"] для помощи.[/wpbook_alert]

Такой подход повышает гибкость и удобство работы с контентом.

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

При работе с пользовательскими данными, особенно передаваемыми через параметры шорткодов, важно соблюдать меры безопасности:

• Всегда используйте функции esc_html, esc_attr, esc_url для очистки вывода.
• Проверяйте и фильтруйте входящие данные, чтобы избежать внедрения вредоносного кода.
• Избегайте прямого вызова echo внутри шорткодов, чтобы не нарушать порядок вывода контента.

Готовые плагины для создания и управления шорткодами

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

• Shortcoder — позволяет создавать собственные шорткоды через удобный интерфейс.
• Insert PHP Code Snippet — позволяет создавать шорткоды с PHP-кодом.
• Custom Shortcodes — набор полезных шорткодов с возможностью расширения.

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

Как отлаживать шорткоды и избегать ошибок

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

• Используйте error_log для записи ошибок в лог сервера.
• Проверяйте корректность входящих параметров с помощью var_dump или print_r.
• Тестируйте шорткод с разными параметрами и в разных местах сайта.
• Избегайте конфликтов имён функций, добавляя префиксы (wpbook_ в наших примерах).

Например, добавление временного логирования:

function wpbook_debug_log($message) {
    if (WP_DEBUG === true) {
        error_log('[wpbook-debug] ' . print_r($message, true));
    }
}

Вызовите wpbook_debug_log($atts); внутри функции шорткода, чтобы увидеть переданные параметры.