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

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

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

Шорткод — это специальный тег в тексте, который WordPress заменяет на динамический контент. Например, [gallery] — встроенный шорткод для вывода галереи. Атрибуты позволяют настраивать вывод: количество элементов, стиль, параметры и прочее. Например, [gallery columns="3" size="medium"].

Создание своих шорткодов с атрибутами даёт гибкость и позволяет облегчить управление контентом без необходимости писать код непосредственно в редакторе.

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

Для регистрации шорткода используем функцию add_shortcode(). В обработчике шорткода принимаем параметры.

function wp0_shortcode_example( $atts ) {
    // Определяем значения по умолчанию
    $atts = shortcode_atts( array(
        'color' => 'red',
        'text' => 'Привет, мир!'
    ), $atts, 'wp0_example' );

    // Возвращаем HTML с применением атрибутов
    return '<div style="color:' . esc_attr( $atts['color'] ) . '">' . esc_html( $atts['text'] ) . '</div>';
}
add_shortcode( 'wp0_example', 'wp0_shortcode_example' );

В этом примере шорткод [wp0_example color="blue" text="Текст"] выведет синий текст «Текст».

Обработка и валидация атрибутов шорткода

Важно не доверять входным данным — всегда используйте функции esc_attr(), esc_html() и другие для безопасного вывода. Также можно валидировать значения, например, проверять, что цвет — это допустимое значение.

Пример расширенной валидации цвета:

function wp0_validate_color( $color ) {
    $allowed_colors = array( 'red', 'blue', 'green', 'black', 'white' );
    return in_array( strtolower( $color ), $allowed_colors ) ? $color : 'red';
}

function wp0_shortcode_example_validated( $atts ) {
    $atts = shortcode_atts( array(
        'color' => 'red',
        'text' => 'Привет, мир!'
    ), $atts, 'wp0_example' );

    $color = wp0_validate_color( $atts['color'] );

    return '<div style="color:' . esc_attr( $color ) . '">' . esc_html( $atts['text'] ) . '</div>';
}
add_shortcode( 'wp0_example_validated', 'wp0_shortcode_example_validated' );

Шорткод с вложенным контентом (enclosing shortcode)

Иногда нужно, чтобы шорткод обрабатывал текст внутри себя, например [wp0_box]Текст внутри[/wp0_box]. Для этого обработчик принимает второй параметр — контент.

function wp0_shortcode_box( $atts, $content = null ) {
    $atts = shortcode_atts( array(
        'bgcolor' => '#f0f0f0'
    ), $atts, 'wp0_box' );

    $output = '<div style="background-color:' . esc_attr( $atts['bgcolor'] ) . '; padding: 10px; border: 1px solid #ccc;">';
    $output .= do_shortcode( $content );
    $output .= '</div>';

    return $output;
}
add_shortcode( 'wp0_box', 'wp0_shortcode_box' );

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

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

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

function wp0_recent_posts_shortcode( $atts ) {
    $atts = shortcode_atts( array(
        'posts' => 5,
        'category' => ''
    ), $atts, 'wp0_recent' );

    $args = array(
        'posts_per_page' => intval( $atts['posts'] ),
        '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>';
    while ( $query->have_posts() ) {
        $query->the_post();
        $output .= '<li><a href="' . esc_url( get_permalink() ) . '">' . esc_html( get_the_title() ) . '</a></li>';
    }
    $output .= '</ul>';

    wp_reset_postdata();

    return $output;
}
add_shortcode( 'wp0_recent', 'wp0_recent_posts_shortcode' );

Использование: [wp0_recent posts="3" category="novosti"] выведет 3 последние записи из категории «новости».

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

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

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

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

• Clearfy Pro — помогает оптимизировать и управлять функционалом WordPress, в том числе шорткодами.
• WPRemark — плагин для создания форм и интерактивных элементов, поддерживает шорткоды с атрибутами.

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