Функция add_shortcode() в WordPress: описание и примеры использования

Функция add_shortcode() в WordPress используется для регистрации новых шорткодов. Шорткод — это своего рода мини-программа, которая может быть вставлена в контент поста или страницы и заменена на специфический HTML-код или другой вывод.

add_shortcode( string $tag, callable $callback );

Параметры:

• $tag — название шорткода, который будет использоваться в контенте. Должно быть уникальным.
• $callback — функция-обработчик, которая вызывается при встрече с шорткодом. Эта функция получает три аргумента: массив атрибутов шорткода, содержимое (если это парный шорткод), и сам тег шорткода.

Основные особенности:

• Каждый шорткод должен быть уникальным. Если два шорткода имеют одинаковый тег, будет использован тот, который был зарегистрирован последним.
• Функция шорткода должна возвращать результат через return, а не через echo.
• Имена атрибутов шорткода автоматически приводятся к нижнему регистру.

Примеры использования add_shortcode()

1. Простая регистрация шорткода

Создадим шорткод [myshortcode foo="bar"], который выведет значение атрибута foo:

add_shortcode( 'myshortcode', 'my_shortcode_function' );

function my_shortcode_function( $atts ) {
    return "foo = " . $atts['foo'];
}

Теперь, если использовать шорткод [myshortcode foo="bar"] в посте или странице, он будет заменен на: foo = bar.

2. Шорткод с атрибутами по умолчанию

В этом примере создадим шорткод [customtag foo="bar"], который имеет значения атрибутов по умолчанию:

add_shortcode( 'customtag', 'customtag_function' );

function customtag_function( $atts ) {
    $atts = shortcode_atts( array(
        'foo' => 'default foo',
        'baz' => 'default baz'
    ), $atts );

    return "foo = {$atts['foo']}, baz = {$atts['baz']}";
}

Если шорткод [customtag] будет использован без атрибутов, он выведет: foo = default foo, baz = default baz.

3. Шорткод с контентом

Создадим шорткод [contenttag]содержимое[/contenttag], который выведет вложенный контент:

add_shortcode( 'contenttag', 'contenttag_function' );

function contenttag_function( $atts, $content = "" ) {
    return "Содержимое: " . $content;
}

Использование шорткода [contenttag]Привет, мир![/contenttag] выведет: Содержимое: Привет, мир!.

4. Шорткод в классе

Если ваш плагин написан в виде класса, вы можете зарегистрировать шорткод с помощью метода класса:

class MyPlugin {
    public static function my_shortcode_function( $atts, $content = "" ) {
        return "Содержимое шорткода: $content";
    }
}

add_shortcode( 'class_shortcode', array( 'MyPlugin', 'my_shortcode_function' ) );

Теперь шорткод [class_shortcode]Содержимое[/class_shortcode] будет работать в рамках класса.

5. Вставка iframe через шорткод

Пример шорткода для вставки iframe:

add_shortcode( 'iframe', 'generate_iframe' );

function generate_iframe( $atts ) {
    $atts = shortcode_atts( array(
        'href'   => 'https://example.com',
        'height' => '600px',
        'width'  => '800px'
    ), $atts );

    return '<iframe src="' . esc_url($atts['href']) . '" width="' . esc_attr($atts['width']) . '" height="' . esc_attr($atts['height']) . '"></iframe>';
}

Шорткод [iframe href="https://google.com" height="480" width="640"] выведет соответствующий iframe с заданными параметрами.

6. Шорткод с подключением шаблона

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

add_shortcode( 'my_template', 'my_template_shortcode' );

function my_template_shortcode( $atts ) {
    ob_start();
    get_template_part( 'shortcode-templates/my-template' );
    return ob_get_clean();
}

Теперь шорткод [my_template] будет загружать и выводить шаблон my-template.php из папки shortcode-templates.

7. Шорткод для вывода случайного числа

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

add_shortcode( 'random_number', 'generate_random_number_func' );

function generate_random_number_func( $atts ) {
    // Устанавливаем значения по умолчанию для минимального и максимального числа
    $atts = shortcode_atts( array(
        'min' => 1,
        'max' => 100
    ), $atts );

    // Генерируем случайное число
    $random_number = rand( $atts['min'], $atts['max'] );

    // Возвращаем сгенерированное число
    return "Random number: $random_number";
}

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

[random_number min="10" max="50"]

Результат:

Random number: 25

8. Шорткод для отображения цитаты дня

Шорткод, который выводит случайную цитату из заранее заданного массива цитат.

add_shortcode( 'quote_of_the_day', 'display_quote_func' );

function display_quote_func( $atts ) {
    // Массив с цитатами
    $quotes = array(
        "Success is not the key to happiness. Happiness is the key to success.",
        "Don't watch the clock; do what it does. Keep going.",
        "Keep your face always toward the sunshine—and shadows will fall behind you.",
        "The only way to do great work is to love what you do.",
        "Success is not how high you have climbed, but how you make a positive difference to the world."
    );

    // Выбираем случайную цитату
    $random_quote = $quotes[array_rand($quotes)];

    // Возвращаем выбранную цитату
    return "<blockquote>$random_quote</blockquote>";
}

9. Шорткод для вывода списка последних постов

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

add_shortcode( 'recent_posts', 'show_recent_posts_func' );

function show_recent_posts_func( $atts ) {
    // Значения по умолчанию
    $atts = shortcode_atts( array(
        'posts' => 5,
    ), $atts );

    // Получаем последние посты
    $recent_posts = wp_get_recent_posts( array(
        'numberposts' => $atts['posts'],
        'post_status' => 'publish'
    ) );

    // Генерируем HTML для списка постов
    $output = '<ul>';
    foreach( $recent_posts as $post ){
        $output .= '<li><a href="' . get_permalink($post["ID"]) . '">' . $post["post_title"] . '</a></li>';
    }
    $output .= '</ul>';

    // Возвращаем результат
    return $output;
}

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

[recent_posts posts="3"]

10. Шорткод для обратного отсчета

Шорткод, который отображает обратный отсчет до заданной даты.

add_shortcode( 'countdown', 'countdown_func' );

function countdown_func( $atts ) {
    // Устанавливаем значение по умолчанию для даты
    $atts = shortcode_atts( array(
        'date' => '2024-12-31'
    ), $atts );

    // Получаем текущую дату и конечную дату
    $current_date = time();
    $target_date = strtotime($atts['date']);

    // Рассчитываем разницу
    $days_left = ($target_date - $current_date) / (60 * 60 * 24);

    // Возвращаем количество дней до даты
    return "Days left until " . date('F j, Y', $target_date) . ": " . floor($days_left);
}

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

[countdown date="2024-12-25"]

Результат:

Days left until December 25, 2024: 71

Заключение

Функция add_shortcode() предоставляет мощные возможности для создания настраиваемого контента в WordPress. Используя ее, вы можете значительно расширить функциональность сайта, внедряя сложные элементы HTML и PHP в обычные посты и страницы через простые текстовые конструкции.