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

Введение в создание шорткодов с параметрами в WordPress

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

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

Мы рассмотрим примеры кода, которые вы сможете адаптировать для своих нужд, а также обсудим важные моменты безопасности и производительности.

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

Шорткод — это небольшая метка в тексте, например [myshortcode], которую WordPress заменяет на определённый HTML или функционал. Параметры позволяют менять поведение шорткода без изменения кода. Пример с параметрами: [myshortcode title="Привет"].

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

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

Для создания собственного шорткода необходимо добавить функцию в файл functions.php вашей темы или в файл плагина. Используется функция add_shortcode(), которая связывает название шорткода с функцией вывода.

Ниже пример простого шорткода с параметром title:

function wpdetect_shortcode_example($atts) {
    // Устанавливаем значения параметров по умолчанию
    $atts = shortcode_atts(
        array(
            'title' => 'Заголовок по умолчанию',
        ), $atts, 'wpdetect_shortcode'
    );
    
    return '<h2>' . esc_html($atts['title']) . '</h2>';
}
add_shortcode('wpdetect_shortcode', 'wpdetect_shortcode_example');

Этот код создаёт шорткод [wpdetect_shortcode title="Ваш заголовок"], который выводит заголовок с заданным текстом.

Расширение шорткода: добавляем несколько параметров и логику

Часто требуется более сложное поведение. Например, шорткод для вывода кнопки с разным текстом и ссылкой. Добавим параметры text и url:

function wpdetect_button_shortcode($atts) {
    $atts = shortcode_atts(
        array(
            'text' => 'Нажми меня',
            'url' => '#',
            'color' => 'blue'
        ), $atts, 'wpdetect_button'
    );

    // Безопасная обработка параметров
    $text = esc_html($atts['text']);
    $url = esc_url($atts['url']);
    $color = sanitize_html_class($atts['color']);

    return '<a href="' . $url . '" class="wpdetect-button wpdetect-button-' . $color . '">' . $text . '</a>';
}
add_shortcode('wpdetect_button', 'wpdetect_button_shortcode');

Такой шорткод [wpdetect_button text="Перейти" url="https://wpdetect.ru" color="red"] создаст кнопку с заданным текстом, ссылкой и цветом.

Добавление стилей для кнопки

Чтобы кнопка выглядела красиво, добавим CSS. Можно подключить стили через wp_enqueue_style или добавить в style.css темы:

.wpdetect-button {
    padding: 10px 20px;
    text-decoration: none;
    border-radius: 4px;
    color: #fff;
    display: inline-block;
    font-weight: bold;
}
.wpdetect-button-blue { background-color: #0073aa; }
.wpdetect-button-red { background-color: #d54e21; }

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

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

Также стоит предусмотреть поведение при отсутствии обязательных параметров. Например, если параметр URL не задан, можно вывести предупреждение или использовать значение по умолчанию.

Пример: проверка обязательного параметра

function wpdetect_secure_shortcode($atts) {
    $atts = shortcode_atts(array('url' => ''), $atts, 'wpdetect_secure');

    if(empty($atts['url'])) {
        return '<div style="color:red;">Ошибка: параметр url обязателен.</div>';
    }

    $url = esc_url($atts['url']);
    return '<a href="' . $url . '">Ссылка</a>';
}
add_shortcode('wpdetect_secure', 'wpdetect_secure_shortcode');

Использование шорткодов в виджетах и Gutenberg

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

add_filter('widget_text', 'do_shortcode');

С редактором Gutenberg шорткоды также работают как обычно, но лучше использовать блок "Шорткод" для удобства.

Советы для разработчиков по интеграции шорткодов

• Тестируйте шорткоды на разных типах контента.
• Документируйте параметры для пользователей сайта.
• Следите за безопасностью и не выводите необработанный HTML.
• Используйте кэширование, если шорткод выполняет тяжёлые операции.

Вывод

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

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