В WordPress имеется полезный инструмент, называемый шорткодами (shortcode), который позволяет без труда интегрировать динамический контент в статьи, страницы и виджеты, минуя сложные кодовые конструкции. Это существенно облегчает работу как пользователям, так и разработчикам, особенно с повторяющимися элементами. Шорткоды не только экономят время, но и делают редактирование контента более удобным и аккуратным.
Шорткоды представляют собой небольшие фрагменты кода, заключенные в квадратные скобки, например, [example_shortcode]. Они могут вызывать различные функции, включая отображение галерей, вставку видео, а также другие элементы, которые требуются для улучшения визуального восприятия контента. Создание собственного шорткода достаточно просто: для этого необходимо зарегистрировать его с помощью функции add_shortcode() в файле functions.php вашей темы.
Кроме того, шорткоды могут принимать параметры, что позволяет создавать более гибкие и модульные элементы. Например, можно задать размеры изображения или количество отображаемых постов. Это делает их мощным инструментом для кастомизации сайта под конкретные нужды. Не забывайте также о том, что многие популярные плагины WordPress, такие как WooCommerce и Contact Form 7, уже включают предустановленные шорткоды, что значительно расширяет возможности вашего сайта.
Важно помнить, что не следует злоупотреблять шорткодами, так как они могут усложнить структуру HTML-кода вашей страницы и сказываются на производительности. Рекомендуется использовать их осознанно, а также проверять, насколько они целесообразны в контексте вашего контента.
Что такое шорткод?
Шорткод (shortcode) представляет собой текст, заключённый в квадратные скобки (например, ), который при отображении заменяется на конкретный HTML или PHP-код. Система шорткодов позволяет внедрять в контент сложные функции, не ухудшая визуальную ясность записи.
Какие шорткоды присутствуют по умолчанию в WordPress
WordPress предлагает несколько встроенных шорткодов:
- gallery — отображает галерею изображений из медиабиблиотеки. Поддерживает атрибуты такие как ids, columns, size и многое другое.
- audio — выводит встроенный HTML5 аудиоплеер. Возможно использование атрибута src или вставка ссылки на аудио внутри шорткода.
- video — отображает HTML5 видеоплеер. Атрибуты включают src, poster, width, height.
- caption — добавляет подпись к изображению, часто используется автоматически при вставке изображений через редактор.
- embed — автоматически встраивает внешние медиа по ссылке (например, YouTube, Twitter, Vimeo и прочие). Этот шорткод чаще всего применяет WordPress при активированной авто-обработке ссылок.
Подпись к изображениюНекоторые темы и плагины могут изменять стандартное поведение встроенных шорткодов или добавлять новые параметры.
Синтаксис шорткода
Именование
Название шорткода может включать только латинские буквы, цифры, дефисы (-) и символы нижнего подчёркивания (_). Пробелы, специальные символы и знаки препинания использовать нельзя.
Примеры корректных названий:
[my_shortcode] [custom-gallery]Атрибуты
Шорткоды способны принимать параметры (атрибуты), которые задаются в скобках:
[button text="Нажми меня" url="https://example.com"]Атрибуты по умолчанию
При создании пользовательского шорткода можно задать значения атрибутов по умолчанию с применением функции shortcode_atts().
$atts = shortcode_atts( [ 'name' => 'Иван Петров', 'position' => 'Менеджер', ], $atts );Экранирование
Чтобы просто отобразить текст шорткода без выполнения, примените двойные квадратные скобки:
[[my_shortcode]]Вложение шорткодов
WordPress поддерживает вложенные шорткоды. Для их корректной работы следует использовать do_shortcode() внутри обработчика шорткода:
add_shortcode('my_shortcode', 'output_my_shortcode'); function output_my_shortcode( $atts, $content ) { return '' . do_shortcode( $content ) . ''; }Как шорткоды влияют на производительность?
Шорткоды сами по себе не создают нагрузку на сайт, однако могут вызывать функции плагинов или сторонние API, что может сказаться на времени загрузки. Поэтому важно оптимизировать коллбэк-функцию, осторожно обращаться с WP_Query и, если это возможно, кэшировать результаты.
Если шорткод использует внешние API для получения данных, рекомендуется применять транзиенты для кэширования ответов запросов.
add_shortcode( 'users_api', 'get_users_api_shortcode' ); function get_users_api_shortcode() { $endpoint = 'https://example-api.ru/users'; $response = wp_remote_post( $endpoint ); $transient_name = 'users_api'; $output = get_transient( $transient_name ); if( $output === false ) { set_transient( $transient_name, $response, HOUR_IN_SECONDS ); } return $output; }Создание своего шорткода
Для добавления нового шорткода в WordPress необходимо воспользоваться функцией add_shortcode. Она имеет два параметра:
- $name string обязательный – название шорткода
- $callback string обязательный – название функции, которая выполнится при выводе шорткода на странице. Эта функция получает три параметра:
- $atts array – массив атрибутов шорткода
- $content string – содержание шорткода, если используется закрывающий тег [content]Тут контент[/content]
- $tag string – название шорткода
add_shortcode( $name, $callback );Теперь давайте зарегистрируем новый шорткод person.
add_shortcode( 'person', 'output_shortcode_person' ); function output_shortcode_person() { /* код функции */ }Код следует расположить в файле functions.php. Если ваша тема регулярно обновляется, рекомендуется использовать дочернюю тему.
Чтобы убедиться в правильной работе, добавим шорткод на страницу в WordPress. После сохранения страницы, вместо [person] будет показано «Меня зовут Иван!».
Теперь давайте расширим функциональность шорткода и добавим параметры.
add_shortcode( 'person', 'output_shortcode_person' ); function output_shortcode_person( $atts ) { $atts = shortcode_atts( [ 'name' =>'Иван', 'position' => 'редактор' ], $atts ); return 'Меня зовут ' . $atts['name'] . ' и я ' . $atts['position'] . ' этого сайта!'; }Шорткод стал динамическим, и теперь можно добавлять различные параметры. Если не указать параметры, вывод будет «Меня зовут Иван и я редактор этого сайта».
При использовании шорткода укажите значения параметров, чтобы изменить стандартное сообщение. Например, [person name=»Александр» position=»администратор»] на странице покажет «Меня зовут Александр и я администратор этого сайта».
Буферизация вывода
Во всех предыдущих примерах использовался вывод простого текста. Однако, если ваш шорткод будет выводить большой HTML-код или работать с подключением файлов шаблона (get_template_part), следует применять буферизацию вывода.
Буферизация — это механизм PHP, позволяющий временно сохранять вывод (например, с помощью echo) в буфере, а затем извлекать его как строку для дальнейшего использования. В контексте шорткодов это позволяет:
- Избежать случайного вывода напрямую в браузер (вместо возврата из шорткода).
- Не использовать множество return и сложные конкатенации.
- Создавать чистую HTML-разметку в PHP-файлах.
- Улучшать читаемость кода.
Простой пример шорткода с буферизацией
Использование шорткода на сайте
Шорткоды можно использовать в любых частях сайта WordPress, но способ применения зависит от конкретного места их отображения.
Использование шорткода в Gutenberg
Для добавления шорткода в статью или страницу через Gutenberg, откройте редактор и вставьте новый блок Шорткод.
Введите название шорткода в квадратных скобках в соответствующем поле ввода.
Необходимо сохранить изменения, после чего можно оценить результаты использования шорткода.
Применение шорткода в классическом редакторе
Запустите классический редактор и введите нужный шорткод.
- Готово!
Применение шорткода в шаблонах
Хотя шорткоды обычно используются в содержимом страниц и записей, иногда может возникнуть необходимость применять их непосредственно в PHP-шаблонах вашей темы, например, в файлах single.php, page.php, footer.php и т.д. В таком случае WordPress предоставляет удобную функцию do_shortcode().
С помощью этой функции можно вручную запустить шорткод и отобразить его результат:
Для вывода шорткода с параметрами используйте следующий код:
Вставьте этот код в ту область вашего шаблона, где должен отображаться результат шорткода.
Удаление шорткода
Существует несколько способов удалить шорткод с сайта WordPress в зависимости от конкретной задачи.
Удаление шорткода с использованием функции remove_shortcode()
Если шорткод был зарегистрирован в коде темы или плагина, его можно удалить программным способом:
remove_shortcode('features');Рекомендуется вызывать remove_shortcode() во время инициализации (hook init) или позже, чтобы гарантировать, что шорткод уже зарегистрирован:
add_action('init', function() { remove_shortcode('features'); });Удаление всех зарегистрированных шорткодов
Чтобы полностью отключить все зарегистрированные шорткоды, используйте следующую функцию:
remove_all_shortcodes();Удаление шорткода из содержимого вручную
Если шорткод уже присутствует в записи или на странице, и вы хотите удалить только его визуальное представление, выполните следующие шаги:
- Запустите редактор выбранной записи.
- Найдите шорткод, например [features] в тексте.
- Удалите или замените его.
Удаление шорткода, добавленного плагином
Если шорткод был зарегистрирован сторонним плагином, наиболее правильный способ — отключить или удалить плагин.
Следует быть внимательным: это может повлиять на работу иных функций плагина.
Если плагин важен, но конкретный шорткод больше не требуется, воспользуйтесь функцией remove_shortcode().
Удаление шорткодов из содержимого при отображении
В случае если вы хотите автоматически убирать все (или конкретные) шорткоды при отображении поста, можно использовать фильтр:
add_filter('the_content', function($content) { $content = strip_shortcodes($content); return $content; });Для удаления конкретного шорткода воспользуйтесь следующим кодом:
add_filter('the_content', function($content) { $shortcode = '[features]'; return str_replace($shortcode, '', $content); });Функции WordPress для работы с шорткодами
- add_shortcode() – используется для регистрации нового шорткода.
- remove_shortcode() – удаляет конкретный шорткод по его имени.
- remove_all_shortcodes() – отключает все зарегистрированные шорткоды.
- shortcode_atts() – объединяет переданные атрибуты с предустановленными значениями.
- do_shortcode() – выполняет все шорткоды, найденные в строке.
- has_shortcode() – проверяет наличие указанного шорткода в контенте.
- shortcode_exists() – проверяет, зарегистрирован ли шорткод.
Частые проблемы при использовании шорткодов
- Использование echo вместо return
Шорткод должен возвращать значение, а не выводить его напрямую с помощью echo. В противном случае он может не отображаться или нарушить разметку.
// ❌ Неправильно! function my_shortcode() { echo 'Текст'; } // ✅ Правильно function my_shortcode()
- Пропуск обработки атрибутов по умолчанию
Без использования функции shortcode_atts() атрибуты становятся обязательными и могут привести к ошибке Undefined index.
// ❌ Ошибка! function my_shortcode($atts) { return 'URL: ' . $atts['url']; } // ✅ Правильно function my_shortcode() { $atts = shortcode_atts(['url' =>'https://example.com'], $atts); return 'URL: ' . esc_url($atts['url']); }- Небезопасный вывод данных
Отсутствие экранирования может создать уязвимости к XSS-угрозам. Необходимы функции esc_html(), esc_url(), esc_attr().
// ❌ Ошибка! function my_shortcode($atts) { return '' . $atts['text'] . ''; } // ✅ Правильно function my_shortcode() { return '' . esc_html($atts['text']) . ''; }- Отображение [shortcode] как текст
Это может происходить по нескольким причинам:
- Шорткод не зарегистрирован.
- Ошибка в написании имени шорткода.
- Шорткод был удален или отключен.
- Для получения контента используется функция get_the_content(), которая не обрабатывает контент с хуком the_content.
// Вместо этого используйте функцию the_content() the_content(); // или примените хук the_content к содержимому функции $content = apply_filters('the_content', get_the_content()); echo $content;