Шорткоды в WordPress

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

[gallery]

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

[gallery ids="56,184"]

После загрузки страницы с таким шорткодом на неё добавлена галерея с двумя фотографиями (под номерами id 58 и 184).

Простейшие шорткоды

WordPress позволяет создавать свои собственные шорткоды. Попробуем создать свой собственный шорткод. Для этого откройте файл functions.php и добавьте в него следующую функцию:

function Mouse(){
   return 'Я люблю сыр!';
}
 
add_shortcode( 'mouse_shortcode', 'Mouse' );

Функция "add_shortcode" принимает два параметра. Первый - это название шорткода. Второй - название функции, которая его обрабатывает.

Теперь если в тексте записи будет присутствовать конструкция "[mouse_shortcode]", то она будет заменена на предложение "Я люблю сыр!".

Название шорткода должно содержать только латинские буквы, цифры и символы подчёркивания. Для каждого шорткода может быть только одна функция-обработчик!

Функция, прикреплённая к шорткоду, должна возвращать значение, а не распечатывать его. То есть в функции должен быть "return" и не должно быт вывода, к примеру, через "echo". Сам шорткод в тексте публикации будет заменён на этот вывод функции.

Попробуем сделать шорткод с параметром, доработав предыдущий пример.

Шорткоды с параметром

function Mouse( $atts ){
   return $atts['who'] . ' люблю ' . $atts['food'] . '!';
}

add_shortcode( 'mouse_shortcode', 'Mouse' );

Теперь в публикации добавим такой шорткод:

[mouse_shortcode who="Я" food="сыр"]

При открытии страницы с таким шорткодом произойдёт его обработка: он заменится на фразу "Я люблю сыр!".

Давайте чуть усложним пример и добавим проверку значений атрибутов "who" и "food". Зададим им значения по умолчанию в случаи их отсуствия. Делается всё это одной функцией - shortcode_atts:

function Mouse( $atts ){
   $params = shortcode_atts(
      array( // значения параметров по умолчанию
         'who' => 'Я',     // значение атрибута "who" по умолчанию
         'food' => 'сыр', // значение атрибута "food" по умолчанию
      ), 
      $atts
   );
   return $params['who'] . ' люблю ' . $params['food'] . '!';
}
 
add_shortcode( 'mouse_shortcode', 'Mouse' );

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

Функция shortcode_atts не только задаёт значения по умолчанию, но и отсеивает те, которые не существуют в массиве "по умолчанию".

Закрывающиеся шорткоды

WordPress позволяет делать закрывающиеся шорткоды. Такие коды открываются и закрываются как HTML теги. Но только вместо брекитов <тег>текст</тег> используются скобки [тег]текст[/тег]. Содержание половинок шорт кода передаётся функции-обработчику во втором параметре. Продемонстрируем это, модифицировав предыдущий пример:

function Mouse( $atts, $shortcode_content = ' ' ){
   $params = shortcode_atts(
      array( // значения параметров по умолчанию
         'who' => 'Я',     // значение атрибута "who" по умолчанию
      ), 
      $atts
   );
   return $params['who'] . ' люблю ' . $shortcode_content . '!';
}
 
add_shortcode( 'mouse_shortcode', 'Mouse' );

Попробуем вставить в публикацию конструкцию:

[mouse_shortcode who="Я"]сыр[/mouse_shortcode]

После загрузки страницы мы увидим надпись "Я люблю сыр!".

Шорткод внутри шорткода

Внутри функции-обработчика шорткода можно принудительно обработать другой шорткод из контента первого. К примеру, придумаем конструкцию, в которой один шорткод обрамляется другим:

[mouse_shortcode][cheese_shortcode][/mouse_shortcode]

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

function Cheese(){
   return 'сыр';
}
function Mouse( $atts, $shortcode_content = ' ' ){
   return 'Я люблю ' . do_shortcode($shortcode_content) . '!';
}
 
add_shortcode( 'mouse_shortcode', 'Mouse' );
add_shortcode( 'cheese_shortcode', 'Cheese' );

В результате наши шорткоды превратятся в "Я люблю сыр!". А если бы мы не сделали вызов функции "do_shortcode", то получили бы "Я люблю [cheese_shortcode]!".