Функция add_shortcode() │ WP 2.5.0

Эта функция добавляет новый шорткод в WordPress.

Важно

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

Возврат

Функция ничего не возвращает (null).

Использование

add_shortcode( $tag, $callback );

• $tag (string) (обязательный) — имя шорткода, которое будет искаться в содержимом поста.
• $callback (callable) (обязательный) — функция, которая будет выполняться, когда шорткод найден. К любой функции шорткода передаются три параметра:
  • массив атрибутов ($atts)
  • содержимое шорткода или null, если оно не установлено ($content)
  • имя шорткода ($shortcode_tag)

Примеры

Пример 1: Одна функция для нескольких шорткодов

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

add_shortcode( 'baz-up', 'baz_func' );
add_shortcode( 'baz-down', 'baz_func' );

function baz_func( $atts, $content, $tag ) {
    // Общая логика, например, обработка переменных $atts
    $atts = shortcode_atts( array(
        'foo' => 'no foo',
        'baz' => 'default baz'
    ), $atts );

    if ( 'baz-up' === $tag ){
        $content = 'Содержимое шорткода [baz-up] является ' . $atts['foo'];
    } elseif ( 'baz-down' === $tag ){
        $content = 'Содержимое шорткода [baz-down] является ' . $atts['foo'];
    }

    return $content;
}

Пример 2: Регистрация шорткода с содержимым

Вот пример создания шорткода, который обрабатывает текст между шорткодами:

add_shortcode( 'baztag', 'baztag_func' );

function baztag_func( $atts, $content ) {
    return "содержимое = $content";
}

// Результат:
// Конструкция шорткода будет заменена на "содержимое = здесь текст"

Пример 3: Регистрация шорткода в стиле OOP

Если ваш плагин написан в классе:

add_shortcode( 'baztag', [ 'MyPlugin', 'baztag_func' ] );

class MyPlugin {
    public static function baztag_func( $atts, $content ) {
        return "содержимое = $content";
    }
}

Или

class MyPlugin {
    public function baztag_func( $atts, $content ) {
        return "содержимое = $content";
    }
}

$class = new MyPlugin();
add_shortcode( 'baztag', [ $class, 'baztag_func' ] );

Пример 4: Шорткод с атрибутами

Регистрация шорткода, который принимает атрибуты:

add_shortcode( 'footag', 'footag_func' );

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

// Результат:
// Шорткод [footag foo="bar"] будет заменён на "foo = bar" в тексте

Пример 5: Вставка iframe через шорткод

Создадим шорткод для вставки iframe:

add_shortcode( 'iframe', 'Generate_iframe' );

function Generate_iframe( $atts ) {
    $atts = shortcode_atts( [
        'href'   => 'http://example.com',
        'height' => '550px',
        'width'  => '600px',
    ], $atts );

    return sprintf( 
        '',
        $atts['href'],
        $atts['width'],
        $atts['height']
    );
}

// Использование:
// [iframe href="http://www.example.com" height="480" width="640"]

Пример 6: Подключение шаблонов тем через шорткод

Допустим, нам нужно подключить специальный файл через шорткод:

add_shortcode( '4cards', 'shortcode_4cards' );

function shortcode_4cards() {
    ob_start();
    get_template_part( 'templates/shortcodes/4_cards' );
    return ob_get_clean();
}

// Пример вызова шорткода: [4cards]

Пример 7: Передача необязательных атрибутов

Если в шорткоде не указаны атрибуты, первый аргумент будет пустой строкой. Проверим это перед обработкой:

function shortcode_callback( $attributes, string $content, string $shortcode ) {
    if ( ! is_array( $attributes ) ) {
        $attributes = [];
    }

    // Логика обработки
}

Пример 8: Установка списка разрешенных атрибутов шорткода

Чтобы шорткод имел только заданные параметры с заданными значениями по умолчанию, используйте функцию shortcode_atts():

add_shortcode( 'bartag', 'bartag_func' );

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

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

Пример 9: Вывод постов по ID через шорткод

Для получения поста по ID используйте следующий шорткод: [testimonials id="272"].

add_shortcode( 'testimonials', 'testimonials_shortcode_handler' );

function testimonials_shortcode_handler( $atts ) {
    global $post;

    $rg = (object) shortcode_atts( [
        'id' => null
    ], $atts );

    if ( ! $post = get_post( $rg->id ) )
        return '';

    $url = wp_get_attachment_url( get_post_thumbnail_id( $post->ID ) );

    $out = '
    

        

            
        
        

            
            
'. get_the_content() .'
            

                
                

                    '. esc_html( $post->author_name ) .'
                    '. esc_html( $post->author_designation ) .'
                
            
        
    
    ';

    wp_reset_postdata();
    return $out;
}

Замечания

• Глобальная переменная: $shortcode_tags

Изменения

С версии 2.5.0 добавлена функция add_shortcode.