Полное руководство по шорткодам на WordPress

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

Если вы хотите добавить галерею, вам нужно просто ввести следующий код:

[gallery ids="47 ,86, 92, 64, 48, 75, 89, 80" columns="4" size="medium"]

Он выведет галерею с указанными идентификаторами изображений. В ней будет 4 колонки, а их максимальный размер ‘medium’ (в соответствии с определением WordPress). Здесь не нужен никакой HTML-код.

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

В этом руководстве я расскажу все, что нужно знать о шорткодах. Вы узнаете, как работать с Shortcode API, создавая свои собственные.

Что такое шорткод?

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

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

Краткая история

Впервые шорткоды стали популярны благодаря программному обеспечению для онлайн-форумов под названием Ultimate Bulletin Board (UBB). В 1998 году они представили BBCode (Bulletin Board Code), набор простых в использовании тегов, позволяющих пользователям форматировать свои сообщения.

Будучи легким языком разметки, BBCode работает по тем же принципам, что и HTML, только гораздо проще.

Использование предопределенных элементов также надежнее, поскольку пользователи не могут вставить HTML-код и создать уязвимости в системе безопасности. Например, кто-либо со злым умыслом может использовать тег <script>, чтобы выполнить код JavaScript и нарушить функциональность сайта.

Вскоре после этого другие программы для создания онлайн-форумов, такие как phpBB, XMB Forum и vBulletin, добавили функцию BBCode в свои доски объявлений.

По тем же соображениям безопасности ВордПресс не позволяет выполнять PHP-код внутри содержимого сайта. Чтобы преодолеть это ограничение, в 2008 году в WordPress 2.5 появилась функция шорткодов — Shortcode API. Он оказался одной из самых используемых опций для многих разработчиков плагинов и тем WP.

Что такое шорткоды WordPress?

Шорткоды WordPress — это строки с квадратными скобками ([ ]), которые превращаются в нечто увлекательное на фронтенде. Они дают пользователям простой способ создавать и изменять сложный контент, не думая о HTML или кодах для встраивания.

2 типа шорткодов

В WordPress существует 2 типа рассматриваемых кодов. Самозакрывающиеся и закрывающиеся. Могут быть как с атрибутами, так и без них.

Некоторые шорткоды функционируют как с атрибутами, так и без них. Это зависит от того, как они определены.

Шорткоды WordPress по умолчанию

WordPress поставляется с 6 шорткодами по умолчанию:

• audio — встраивание аудиофайлов на ваш сайт. Он включает простые элементы управления воспроизведением, такие как Play & Pause.
• caption — с помощью этого шорткода можно обернуть подписи вокруг контента. В основном он используется для добавления надписей к изображениям, но вы можете применить его для любого элемента HTML.
• embed — расширение стандартной функции oEmbed. Этот шорткод позволяет задавать различные атрибуты для встраиваемых изображений, например, устанавливать их максимальные размеры.
• gallery — вставьте простую галерею на сайт. Вы можете применить атрибуты, чтобы определить, какие изображения используются, и кастомизировать ее внешний вид.
• playlist — отобразите коллекцию аудио- или видеофайлов с помощью этого самозакрывающегося шорткода. Благодаря атрибуту стиля можно придать ему «темный» режим.
• video — вставьте видеофайл и воспроизведите его с помощью простого видеоплеера. Он работает со следующими форматами: mp4, webm, m4v, webm, ogv, wmv, flv.

Как использовать шорткоды WordPress

Использование их в WordPress — процесс несложный. Все зависит от того, куда вы хотите добавить их на своем сайте. Обязательно прочитайте документацию, чтобы понять, как они работают. Узнайте, какие атрибуты он поддерживает, чтобы вы могли получить именно то, что хотите.

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

Сначала перейдите в редактор страницы/публикации, куда хотите вставить шорткод.

Если вы используете редактор Gutenberg, можете добавить тег в отдельный блок Shortcodes. Его можно найти в разделе «Виджеты».

Используете классический редактор (или плагин)? Тогда вводите теги шорткодов классическим способом. Некоторые могут даже иметь кнопку на экране редактора, позволяющую легко их вставить.

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

Шорткоды также можно вставлять в виджеты сайдбара. Чтобы добавить их, перейдите в раздел «Внешний вид», далее «Виджеты» и добавьте элемент «Текст» туда, куда вы хотите его применить.

Вставьте шорткод в виджет «Текст» и сохраните его. Можете зайти на фронтенд вашего сайта и увидеть вывод его в сайдбаре.

Использование шорткодов WordPress в хедере и футере

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

Скажем, вы хотите добавить кнопку призыва к действию в футер или во все посты перед разделом комментариев. Здесь пригодится функция обратного вызова do_shortcode().

Нужно добавить следующий код в header.php, footer.php или любой из файлов шаблона темы:

<?php echo do_shortcode("[name_of_your_shortcode]"); ?>

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

Краткое введение в API шорткодов

WordPress Shortcode API определяет, как вы можете использовать шорткоды для кастомизации и расширения функциональности сайта. Он позволяет разработчикам создавать уникальный контент (например, формы, карусели, слайдеры и т.д.), который пользователи могут добавлять на свои ресурсы, вставив соответствующий шорткод.

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

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

Понимание основ API шорткодов

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

Если таковой найден, Shortcode API берет на себя управление и возвращает вывод шорткода(ов). Возвращенная строка вывода заменяет его тег в том месте, где он был добавлен.

Вы регистрируете шорткод в WordPress с помощью функции add_shortcode(). Вот как это делается:

add_shortcode( 'shortcode_name', 'shortcode_handler_function' );

• shortcode_name — тег, который WordPress будет искать при разборе содержимого поста. Shortcode API рекомендует использовать только строчные буквы, цифры и символы подчеркивания для определения его значения (избегайте тире).
• shortcode_handler_function — функция обратного вызова, которая будет выполнена после того, как ВордПресс подтвердит наличие зарегистрированного шорткода.

Функция-обработчик определяется следующим образом:

function shortcode_handler_function( $atts, $content, $tag ){ }

• $atts — ассоциативный массив (т.е. массив пар ключ-значение). Если вы не зададите никаких атрибутов, по умолчанию будет использована пустая строка.
• $content — вложенное содержимое, если определяете включенный шорткод. Функция-обработчик отвечает за то, чтобы значение $content было возвращено в вывод.
• $tag — значение тега (в примере выше — shortcode_name ). Если два или более используют одну и ту же функцию обратного вызова (что допустимо), значение $tag поможет определить, какой шорткод вызвал функцию-обработчик.

API анализирует тег, атрибуты и вложенное содержимое (если оно есть), передавая значения в функцию-обработчик, которая обрабатывает их и возвращает выходную строку. Она заменяет макрос шорткода на фронтенде сайта. То, что вы в итоге увидите в браузере, и есть этот вывод.

Куда добавлять кастомные скрипты шорткодов?

Вы можете добавить скрипты кастомных шорткодов в файл functions.php темы или включить их в плагин.

Если вставляете его в документ темплейта, то запустите функцию add_shortcode() как есть.

Но если добавляете ее в плагин, я рекомендую инициализировать ее только после полной загрузки WordPress. Вы можете обеспечить это, обернув функцию add_shortcode() внутри другой. Это называется оберткой:

function shortcodes_init() {
    add_shortcode( 'shortcode_name', 'shortcode_handler_function' )
}
add_action('init', 'shortcodes_init');

Функция add_action() подключает shortcodes_init, чтобы она срабатывала только после завершения загрузки WordPress (это называется хук ‘init’).

Как создать кастомный шорткод в WordPress (уровень для начинающего)

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

Чтобы выполнить приведенные ниже шаги, потребуется опыт работы с PHP-кодом и редактирования файлов темы WordPress. К концу этой статьи у вас будет готов к работе первый кастомный шорткод ВордПресс. Начнем с самого простого варианта, а затем перейдем к более сложным.

Пример 1: Шорткод с использованием 2026

Давайте создадим шорткод под названием 2026, который будет выводить текущий год на вашем сайте.

Я использую плагин barebones для внедрения функций шорткода. Вы можете добавить его в файл functions.php своей темы и получить те же результаты, но я не рекомендую это делать. Хотя для тестирования и обучения это нормально.

Давайте начнем с разработки плагина. Создайте новую папку в каталоге /wp-content/plugins/.

Обратите внимание на его расположение.

Я назвал свой плагин «salcodes», но вы можете назвать свой как угодно.

В каталоге расширения salcodes создайте PHP-файл с таким же названием (salcodes.php). После этого добавьте в документ плагина следующий заголовок:

<?php
/*
Plugin Name:  Salcodes
Version: 1.0
Description: Output the current year in your WordPress site.
Author: Name
Author URI: https://www.site.com/
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: salcodes
*/

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

Теперь зарегистрируем шорткод и его функцию-обработчик. Для этого добавьте следующий код в файл плагина:

add_shortcode( 'current_year', 'salcodes_year' );
function salcodes_init(){
    function salcodes_year() {
    return getdate()['year'];
    }
}
add_action('init', 'salcodes_init');
/** Always end your PHP files with this closing tag */
?>

• Тег @return в PHP-комментарии определяет тип возвращаемого результата. За ним следует его краткое описание.
• current_year — это тег или имя шорткода. Он определяет самозакрывающуюся метку, которую нужно добавить в контент, в данном случае это будет 2026.
• salcodes_year — имя обработчика шорткода, она будет возвращать строку вывода. Определим эту функцию обратного вызова в следующих строках. Поскольку мы создаем простой самозакрывающийся шорткод, вам не нужно передавать ему какие-либо значения переменных, таких как $attributes, $content или $tag.
• salcodes_init — это обертка, она подключается к ‘init’, чтобы убедиться, что шорткод будет зарегистрирован и запущен только после завершения загрузки WordPress. Встроенная в ВордПресс функция add_action() делает это возможным.
• getdate() — это функция PHP, которая возвращает массив информации о дате текущей отметки времени. Ключ year содержит актуальное значение (в виде 4-значной строки). Таким образом, getdate()[‘year’] возвращает текущий год. Это тот результат, который нам нужен.

Сохраните файл плагина. Теперь проверим, работает ли короткий код так, как нужно.

Добавьте шорткод в любое место на сайте (страница, публикация и т.д.). Я вставлю его в виджет «Текст» на сайдбаре моего веб-проекта.

Как и ожидалось, он отлично работает.

Пример 2: Шорткод для CTA-кнопки

Давайте создадим кастомизируемый шорткод для CTA-кнопки. Он тоже будет самозакрывающимся.

Я хочу, чтобы пользователи могли кастомизировать размер и цвет CTA-кнопки с помощью HTML-атрибутов шорткода. Поэтому его href, id, class, target и label, могут легко применяться для этого.

Используйте атрибуты id и class для стилизации кнопки, поскольку они являются обычными CSS-селекторами.

Я не оборачиваю здесь функцию-обработчик, чтобы упростить объяснение.

add_shortcode( 'cta_button', 'salcodes_cta' );

function salcodes_cta( $atts ) {
    $a = shortcode_atts( array(
        'link' => '#',
        'id' => 'salcodes',
        'color' => 'blue',
        'size' => '',
        'label' => 'Button',
        'target' => '_self'
    ), $atts );
    $output = '<p><a href="' . esc_url( $a['link'] ) . '" id="' . esc_attr( $a['id'] ) . '" class="button ' . esc_attr( $a['color'] ) . ' ' . esc_attr( $a['size'] ) . '" target="' . esc_attr($a['target']) . '">' . esc_attr( $a['label'] ) . '</a></p>';
    return $output;
}

Здесь есть что рассказать. Я объясню все построчно, чтобы вы поняли, как это работает.

• В предыдущем разделе мы рассмотрели add_shortcode() и то, как она функционирует.
• shortcode_atts() — это функция WordPress, которая объединяет атрибуты кастомного шорткода с известными. При необходимости она заполняет значения по умолчанию (которые вы также можете задать самостоятельно). В результате получится массив, содержащий все ключи из известных атрибутов, объединенные с именами из кастомных вариантов.
• Внутри функции-обработчика шорткода определяем переменную ($a) и присваиваем ее массиву, возвращенному shortcode_atts(). Мы даем атрибутам значения по умолчанию с помощью синтаксиса: ‘attribute’ => ‘default-value’. Например, в приведенном выше коде устанавливаем имя label на Button с использованием ‘label’ => ‘Button’.
• Мы можем извлечь значения для каждого ключа атрибута с помощью синтаксиса PHP для массивов: $a[‘attribute’].
• В переменной $output хранится HTML-код элемента button (тег <a> с классом ‘button’). Это строка, которая возвращается функцией.

Если вы хотите установить в качестве ссылки по умолчанию URL главной страницы сайта, вы можете воспользоваться home_url() WordPress.

Давайте попробуем применить шорткод без заданных атрибутов, и посмотрим, что будет выведено.

Если вам интересно, для чего нужны двойные квадратные скобки ([[cta_button]]), то они называются экранирующим коротким кодом. Они помогают выводить любой зарегистрированный шорткод на сайте в виде обычного текста, как на картинке ниже.

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

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

function salcodes_enqueue_scripts() {
    global $post;
    if( is_a( $post, 'WP_Post' ) && has_shortcode( $post->post_content, 'cta_button' ) ) {
        wp_register_style( 'salcodes-stylesheet',  plugin_dir_url( __FILE__ ) . 'css/style.css' );
        wp_enqueue_style( 'salcodes-stylesheet' );
    }
}
add_action( 'wp_enqueue_scripts', 'salcodes_enqueue_scripts' );

Функция salcodes_enqueue_scripts() определяет глобальную переменную $post, а затем подтверждает два условия через:

• is_a(): проверяет, является ли $post экземпляром объекта WP_Post. Он относится ко всем типам постов в WordPress.
• has_shortcode(): проверяет, содержит ли контент публикации шорткод [cta_button].

Если оба условия верны, функция регистрирует и подключает таблицу стилей style.css, находящуюся в папке CSS. plugin_dir_url( $file ) позволяет легко получить URL каталога плагина.

Наконец, давайте протестируем шорткод [cta_button], добавив его в содержимое публикации:

На изображении ниже показано, как CTA-кнопка выглядит на фронтенде:

Теперь, когда вы узнали, как определять кастомные атрибуты и включать стили, добавляйте другие функции в шорткод CTA Button. Например, можете дать пользователям возможность вставлять анимацию, эффекты наведения и другие стили кнопок.

Пример 3: Шорткод с использованием $content

В качестве последнего примера давайте создадим вложенный шорткод под названием [boxed]. Он будет выводить любой контент между своими тегами в виде коробки с разноцветными заголовками.

Для начала зарегистрируем шорткод и определим его функцию-обработчик.

add_shortcode( 'boxed', 'salcodes_boxed' );

function salcodes_boxed( $atts, $content = null, $tag = '' ) {
    $a = shortcode_atts( array(
        'title' => 'Title',
        'title_color' => 'white',
        'color' => 'blue',
    ), $atts );
    
    $output = '<div class="salcodes-boxed" style="border:2px solid ' . esc_attr( $a['color'] ) . ';">' . 
               '<div class="salcodes-boxed-title" style="background-color:' . esc_attr( $a['color'] ) . ';">' . 
               '<h3 style="color:' . esc_attr( $a['title_color'] ) . ';">' . esc_attr( $a['title'] ) . '</h3></div>' . 
               '<div class="salcodes-boxed-content"><p>' . esc_attr( $content ) . '</p></div>' . 
               '</div>';
    
    return $output;
}

• $content = null — регистрирует шорткод как вложенный тип. Вы можете использовать переменную $content внутри функции-обработчика, чтобы изменить вывод по своему усмотрению.
• $tag = ”— здесь задается переменная $tag шорткода. В данном примере она не нужна, но включить ее рекомендуется.

В этом примере изменяем содержимое с помощью встроенных стилей CSS.

Но если два коротких кода используют одну и ту же таблицу стилей, вам придется загружать ее при использовании любого из них. Поэтому давайте обновим функцию salcodes_enqueue_scripts():

function salcodes_enqueue_scripts() {
    global $post;
    $has_shortcode = has_shortcode( $post->post_content, 'cta_button' ) || has_shortcode( $post->post_content, 'boxed' );
    if( is_a( $post, 'WP_Post' ) && $has_shortcode ) {
        wp_register_style( 'salcodes-stylesheet', plugin_dir_url( __FILE__ ) . 'css/style.css' );
        wp_enqueue_style( 'salcodes-stylesheet' );
    }
}
add_action( 'wp_enqueue_scripts', 'salcodes_enqueue_scripts' );

$has_shortcode — определяемая пользователем переменная, которая проверяет, существует ли один из шорткодов на странице/в посте. Оператор || (OR) делает это возможным.

Давайте проверим [boxed].

На скришноте ниже показан полученный результат.

Теперь, когда вы узнали, как создавать собственные шорткоды, можете создать их по-своему.

Шорткоды WordPress: плюсы и минусы

Шорткоды и блоки Gutenberg

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

А если хотите вставить их, то в Gutenberg даже есть специальный инструмент. Блоки — это новые шорткоды.

Это объясняет, почему все популярные шорткоды преобразуются в блоки. Многие разработчики WordPress переключились на то, чтобы их продукты и сервисы работали исключительно в редакторе Gutenberg.

Заключение

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

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