WordPress: шорткод с параметрами

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

Шорткод может принимать дополнительные параметры, обычно они обозначаются как «атрибуты»:

[bologer title="Bologer.ru"]
Какой-то собственный текст внутри шорткода
[/bologer]

Функцию обработки шорткода может принимать 3 параметра:

• $atts — массив — [$tag] атрибуты
• $content — строка — контент поста
• $tag — строка — название шорткода в формате [$tag]

function bologer_shortcode($atts = [], $content = null, $tag = '') {}

Обработка атрибутов

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

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

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

• Укажите параметры по умолчанию
• Используй нормализацию ключей атрибутов в массиве используя array_change_key_case()
• Парсить атрибуты используя shortcode_atts()
• Обезопасить выводимые данные

Полный пример

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

[bologer] шорткод будет принимать атрибут title и отображать всё внутри «коробки» <div> элемента, на которые мы может наложить собственные CSS стили.

<?php
function bologer_shortcode($atts = [], $content = null, $tag = '')
{
    // делаем все ключи массива в нижнем регистре
    $atts = array_change_key_case((array)$atts, CASE_LOWER);
 
    // перезаписываем все атрибуты по умолчания значениями пользователя
    $bologer_atts = shortcode_atts([
                                     'title' => 'WordPress.org',
                                 ], $atts, $tag);
 
    // начала вывода
    $o = '';
 
    // начало элемента "коробки"
    $o .= '<div class="bologer-box">';
 
    // заголовок
    $o .= '<h2>' . esc_html__($bologer_atts['title'], 'bologer') . '</h2>';
 
    // проверяем есть ли внутри еще шорткоды
    if (!is_null($content)) {
        // делаем вывод безопасным используя фильтр the_content хук на $content
        $o .= apply_filters('the_content', $content);
 
        // рекурсивно запускаем шорткод парсер
        $o .= do_shortcode($content);
    }
 
    // закрывающийся элемент "коробки"
    $o .= '</div>';
 
    // возвращаем вывод
    return $o;
}
 
function bologer_shortcodes_init()
{
    add_shortcode('bologer', 'bologer_shortcode');
}
 
add_action('init', 'bologer_shortcodes_init');