Как создать кастомный шорткод в WordPress: пошаговое руководство

Введение: Почему шорткоды — неотъемлемая часть WordPress

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

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

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

Шорткод — это специальный тег, который начинается с квадратных скобок, например [my_shortcode]. Когда WordPress обрабатывает контент, он заменяет такой тег на соответствующий HTML или PHP-код. Это позволяет:

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

Шорткоды могут принимать атрибуты, например [my_shortcode param1="value" param2="value"], что расширяет их функциональность и делает более гибкими.

Где используются шорткоды в WordPress

Шорткоды широко применяются в:

Плагинах: Например, плагин WooCommerce использует шорткоды для отображения товаров или корзины.
Темах: Многие темы предоставляют свои шорткоды для создания сложных блоков (например, [wp_pagenav]).
Кастомных решениях: Разработчики создают шорткоды для вывода пользовательских полей, интеграции с API или рендеринга графиков.

Они также могут использоваться в визуальных редакторах (например, Elementor, Gutenberg), где поддерживают drag-and-drop-интерфейс.

Как создать базовый шорткод: пошаговая инструкция

Создание шорткода включает два основных шага: регистрацию функции и определение её поведения. Давайте разберём процесс на примере простого шORTкода, который выводит приветственное сообщение.

Шаг 1: Регистрация шорткода с помощью `add_shortcode()`

Функция add_shortcode() связывает имя шорткода с callback-функцией, которая будет выполняться при его вызове. Она принимает два аргумента:

Имя шорткода (tag): Строка, например my_hello_world. Это то, что будет вставляться в контент.
Callback-функция: Функция, которая обрабатывает шорткод и возвращает HTML или другой контент.

function my_hello_world_shortcode() {
return 'Hello, World!';
}
add_shortcode('my_hello_world', 'my_hello_world_shortcode');

В этом примере шорткод [my_hello_world] будет заменён на абзац с текстом «Hello, World!».

Шаг 2: Определение callback-функции

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

function my_hello_world_shortcode($atts) {
// Обработка атрибутов (если они есть)
$atts = shortcode_atts(array(
'name' => 'Guest',
'color' => '#000000'
), $atts);
return sprintf(
'Hello, %s!',
esc_attr($atts['color']),
esc_html($atts['name'])
);
}
add_shortcode('my_hello_world', 'my_hello_world_shortcode');

В этом расширенном примере шорткод принимает атрибуты name и color, что позволяет изменять вывод. Например, [my_hello_world name="Alice" color="#ff0000"] даст:

Hello, Alice!

Работа с атрибутами шорткода: примеры и лучшие практики

Атрибуты делают шорткоды более гибкими. Они позволяют передавать параметры в callback-функцию и изменять её поведение. Давайте рассмотрим, как правильно их обрабатывать.

Как получить атрибуты с помощью `shortcode_atts()`

Функция shortcode_atts() помогает:

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

function my_shortcode_with_atts($atts) {
// Устанавливаем значения по умолчанию
$atts = shortcode_atts(array(
'title' => 'Default Title',
'link'  => '#'
), $atts);
return sprintf(
'%s',
esc_url($atts['link']),
esc_html($atts['title'])
);
}
add_shortcode('my_button', 'my_shortcode_with_atts');

Пример использования: [my_button title="Click Me" link="https://example.com"].

Обработка атрибутов вручную (без shortcode_atts)

Если вам нужно больше контроля, можно парсить атрибуты вручную с помощью shortcode_parse_atts() (доступно с WordPress 5.0):

function my_manual_atts_shortcode($atts) {
$parsed_atts = shortcode_parse_atts($atts);
if (isset($parsed_atts['size'])) {
$size_class = 'btn-' . sanitize_key($parsed_atts['size']);
} else {
$size_class = '';
}
return sprintf(
'',
esc_attr($size_class)
);
}
add_shortcode('my_manual_button', 'my_manual_atts_shortcode');

Пример: [my_manual_button size="large"].

Создание сложных шорткодов с динамическим контентом

Шорткоды могут выводить данные из базы данных, API или других источников. Рассмотрим примеры таких реализаций.

Пример 1: Шорткод для вывода последних постов

function latest_posts_shortcode($atts) {
$atts = shortcode_atts(array(
'count' => 5,
'category' => ''
), $atts);
$args = array(
'posts_per_page' => $atts['count'],
'cat' => $atts['category']
);
$query = new WP_Query($args);
ob_start();
if ($query->have_posts()) {
echo '';
while ($query->have_posts()) {
$query->the_post();
echo '' . get_the_title() . '';
}
echo '';
} else {
echo 'No posts found.';
}
wp_reset_postdata();
return ob_get_clean();
}
add_shortcode('latest_posts', 'latest_posts_shortcode');

Использование: [latest_posts count="3" category="5"].

Пример 2: Интеграция с API (например, погода)

function weather_shortcode($atts) {
$atts = shortcode_atts(array(
'city' => 'London',
'units' => 'metric'
), $atts);
$api_url = sprintf('https://api.openweathermap.org/data/2.5/weather?q=%s&units=%s&appid=YOUR_API_KEY', urlencode($atts['city']), $atts['units']);
$response = wp_remote_get($api_url);
if (is_wp_error($response)) {
return 'Error fetching weather data.';
}
$body = json_decode(wp_remote_retrieve_body($response));
if ($body->cod !== 200) {
return 'City not found.';
}
return sprintf(
'' .
'%s' .
'Temperature: %d°C' .
'Humidity: %d%%' .
'',
esc_html($body->name),
(int)$body->main->temp,
(int)$body->main->humidity
);
}
add_shortcode('weather', 'weather_shortcode');

Пример: [weather city="Moscow" units="metric"]. Не забудьте заменить YOUR_API_KEY на реальный ключ API.

Обработка ошибок и безопасность шорткодов

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

Экранирование данных: `esc_*()` функции

Все данные, которые выводятся на страницу, должны быть экранированы для защиты от XSS-атак. Основные функции:

esc_html(): Для HTML-контекста.
esc_attr(): Для атрибутов HTML.
esc_url(): Для URL.

function safe_shortcode($atts) {
$atts = shortcode_atts(array(
'user_input' => ''
), $atts);
return sprintf(
'Your input: %s',
esc_html($atts['user_input'])
);
}
add_shortcode('safe_example', 'safe_shortcode');

Проверка атрибутов на валидность

Не всегда можно доверять переданным атрибутам. Например, проверяйте:

Тип данных (число, строка).
Разрешенные значения (например, для выпадающих списков).

function validated_shortcode($atts) {
$allowed_sizes = array('small', 'medium', 'large');
$default_size = 'medium';
if (isset($atts['size']) && in_array(sanitize_key($atts['size']), $allowed_sizes)) {
$size = sanitize_key($atts['size']);
} else {
$size = $default_size;
}
return sprintf(
'',
esc_attr($size)
);
}
add_shortcode('validated_button', 'validated_shortcode');

Интеграция шорткодов с Gutenberg и визуальными редакторами

Современные редакторы WordPress (Gutenberg) поддерживают шорткоды, но для лучшего пользовательского опыта можно создать кастомный блок на их основе.

Как добавить шORTкод в Gutenberg

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

Использовать register_block_type() для создания кастомного блока.
Создать плагин с поддержкой JavaScript для рендеринга шорткодов в редакторе.

// Пример регистрации блока (для сложных случаев)
function register_shortcode_block() {
register_block_type('my-plugin/shortcode-block', array(
'render_callback' => function($attrs, $content = '') {
return do_shortcode('[my_custom_shortcode]');
},
));
}
add_action('init', 'register_shortcode_block');

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

Если ручная работа кажется сложной, используйте плагины:

Shortcoder: Позволяет создавать и управлять шорткодами через интерфейс.
Code Snippets: Для безопасного добавления кода в WordPress без редактирования файлов темы.
Shortcodes Ultimate: Набор готовых и кастомных шорткодов.

Заключение: Практические рекомендации по созданию шорткодов

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

Начинайте с простого: Начните с базовых шорткодов (например, для вывода текста или изображений) и gradually move to more complex logic.
Используйте обертки для кода: Обертывайте сложные логические блоки в функции, чтобы код был чистым и читаемым.
Не forget about security: Always sanitize and validate user input to prevent vulnerabilities like XSS or SQL injection.
Test your shortcodes: Test them in different contexts (Gutenberg, Classic Editor) and with various inputs to ensure compatibility.
Document your shortcodes: Add comments or a documentation page explaining how to use each shortcode, including available attributes.
Optimize for performance: Avoid heavy database queries or external API calls in shortcodes that render on every page load. Consider caching where possible.

Шорткоды — это не только инструмент для разработчиков, но и способ упростить работу для редакторов контента. Правильно реализованные шорткоды делают сайт более динамичным, гибким и удобным в управлении.

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

Удачи в создании своих первых кастомных шорткодов! 🚀