Шорткоды

 /  38 комментариев

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

Например стандартный вордпрессовский шорткод [gallery] позволяет вывести галерею внутри поста.

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

Так же, как у функции могут быть аргументы, так и шорткод может иметь собственные параметры. Ещё один пример с шорткодом [gallery]:

[gallery size="large" ids="14243,14242,14241"]

В параметре ids перечислены ID изображений, входящих в галерею, параметр size — размер вставляемых изображений.

Простой пример создания шорткода

Создать свой шорткод не труднее, чем написать собственную функцию PHP. Например я решил создать шорткод [misha], который при вставке в пост будет выводить URL главной страницы сайта.

function true_misha_func( $atts ){
	return site_url(); // никаких echo, только return
}
 
add_shortcode( 'misha', 'true_misha_func' );

Код можете вставить в файл functions.php (я имею ввиду тот, который находится в директории вашей текущей темы).

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

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

Окей, я уже писал, что у шорткодов могут быть свои параметры, давайте теперь посмотрим как это делается.

В качестве примера я написал шорткод, который просто вставляет ссылку в пост, которая открывается в новой вкладке браузера target="_blank". Не думаю, что на деле он может быть полезен, но для нас сейчас главное — понять сам принцип работы шорткодов.

Параметров будет два: anchor и url — анкор (текст ссылки) и URL соответственно. Как будет выглядеть сам шорткод: [trueurl anchor="Мой блог" url="https://misha.blog/blog"]. Если параметр не будет указан в самом шорткоде, то будет использоваться его значение по умолчанию, заданное в функции.

function true_url_external( $atts ) {
	$params = shortcode_atts( array( // в массиве укажите значения параметров по умолчанию
		'anchor' => 'Миша Рудрастых', // параметр 1
		'url' => 'https://misha.blog', // параметр 2
	), $atts );
	return "<a href='{$params['url']}' target='_blank'>{$params['anchor']}</a>";
}
add_shortcode( 'trueurl', 'true_url_external' );

Названия атрибутов шорткодов также рекомендуется использовать в нижнем регистре. Значения же атрибутов могут содержать любые символы.

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

Давайте возьмём шорткод из предыдущего примера и немного переколдуем его. Напомню, что шорткод выглядел так:
[trueurl anchor="текст ссылки" url="URL ссылки"].

Что, если мы переделаем его следующим образом: [trueurl anchor="текст ссылки"]URL ссылки[/trueurl].

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

В соответствии с этим давайте переделаем наш код из предыдущего примера:

function true_url_external( $atts, $shortcode_content = null ) {
	$params = shortcode_atts( array(
		'anchor' => 'Миша Рудрастых'
	), $atts );
	return "<a href='" . do_shortcode($shortcode_content) . "' target='_blank'>{$params['anchor']}</a>";
}
add_shortcode( 'trueurl', 'true_url_external' );

Теперь шорткод следующего вида [trueurl anchor="главная"][misha][/trueurl] выведет ссылку на главную страницу вашего сайта (про шорткод [misha] я писал выше).

Добавляем кнопку вставки шорткода в визуальный редактор поста TinyMCE

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

1. PHP

Вне зависимости от того, будет ли ваша кнопка текстовая, либо с иконкой, будет ли она содержать дополнительные поля ввода (параметры шорткода) или нет — во всех случаях PHP-код регистрации кнопки будет одинаков.

// Хуки
function true_add_mce_button() {
	// проверяем права пользователя - может ли он редактировать посты и страницы
	if ( !current_user_can( 'edit_posts' ) && !current_user_can( 'edit_pages' ) ) {
		return; // если не может, то и кнопка ему не понадобится, в этом случае выходим из функции
	}
	// проверяем, включен ли визуальный редактор у пользователя в настройках (если нет, то и кнопку подключать незачем)
	if ( 'true' == get_user_option( 'rich_editing' ) ) {
		add_filter( 'mce_external_plugins', 'true_add_tinymce_script' );
		add_filter( 'mce_buttons', 'true_register_mce_button' );
	}
}
add_action('admin_head', 'true_add_mce_button');
 
// В этом функции указываем ссылку на JavaScript-файл кнопки
function true_add_tinymce_script( $plugin_array ) {
	$plugin_array['true_mce_button'] = get_stylesheet_directory_uri() .'/true_button.js'; // true_mce_button - идентификатор кнопки
	return $plugin_array;
}
 
// Регистрируем кнопку в редакторе
function true_register_mce_button( $buttons ) {
	array_push( $buttons, 'true_mce_button' ); // true_mce_button - идентификатор кнопки
	return $buttons;
}

В этом примере для получения URL папки с текущей темой я использовал функцию get_stylesheet_directory_uri(). true_button.js — собственно сама кнопка, создайте этот файл в директории с темой (или там, где вам удобно, но не забудьте в этом случае поменять путь к нему).

2.1. JavaScript. Пример простой кнопки

Займёмся содержимым файла true_button.js. Итак, создадим для начала простую кнопку, которая будет вставлять шорткод [misha].

(function() {
	tinymce.PluginManager.add('true_mce_button', function( editor, url ) { // true_mce_button - ID кнопки
		editor.addButton('true_mce_button', {  // true_mce_button - ID кнопки, везде должен быть одинаковым
			text: '[misha]', // текст кнопки, если вы хотите, чтобы ваша кнопка содержала только иконку, удалите эту строку
			title: 'Вставить шорткод [misha]', // всплывающая подсказка
			icon: false, // тут можно указать любую из существующих векторных иконок в TinyMCE либо собственный CSS-класс
			onclick: function() {
				editor.insertContent('[misha]'); // вставляем шорткод [misha] в редактор, также можно задать любое действие jQuery
			}
		});
	});
})();

В результате:

Кнопка вставки шорткода в редактор
Текстовый вариант кнопки вставки шорткода в визуальном редакторе TinyMCE.

2.2. Кнопка с иконкой, выпадающим списком и с возможностью задавать параметры шорткода

Начну с того, что вставлю (а точнее заменю) код в файл true_button.js:

(function() {
	tinymce.PluginManager.add('true_mce_button', function( editor, url ) { // id кнопки true_mce_button должен быть везде один и тот же
		editor.addButton( 'true_mce_button', { // id кнопки true_mce_button
			icon: 'perec', // мой собственный CSS класс, благодаря которому я задам иконку кнопки
			type: 'menubutton',
			title: 'Вставить элемент', // всплывающая подсказка при наведении
			menu: [ // тут начинается первый выпадающий список
				{
					text: 'Элементы форм',
					menu: [ // тут начинается второй выпадающий список внутри первого
						{
							text: 'Текстовое поле',
							onclick: function() {
								editor.windowManager.open( {
									title: 'Задайте параметры поля',
									body: [
										{
											type: 'textbox', // тип textbox = текстовое поле
											name: 'textboxName', // ID, будет использоваться ниже
											label: 'ID и name текстового поля', // лейбл
											value: 'comment' // значение по умолчанию
										},
										{
											type: 'textbox', // тип textbox = текстовое поле
											name: 'multilineName',
											label: 'Значение текстового поля по умолчанию',
											value: 'Привет',
											multiline: true, // большое текстовое поле - textarea
											minWidth: 300, // минимальная ширина в пикселях
											minHeight: 100 // минимальная высота в пикселях
										},
										{
											type: 'listbox', // тип listbox = выпадающий список select
											name: 'listboxName',
											label: 'Заполнение',
											'values': [ // значения выпадающего списка
												{text: 'Обязательное', value: '1'}, // лейбл, значение
												{text: 'Необязательное', value: '2'}
											]
										}
									],
									onsubmit: function( e ) { // это будет происходить после заполнения полей и нажатии кнопки отправки
										editor.insertContent( '[textarea id="' + e.data.textboxName + '" value="' + e.data.multilineName + '" required="' + e.data.listboxName + '"]');
									}
								});
							}
						},
						{ // второй элемент вложенного выпадающего списка, прост вставляет шорткод [button]
							text: 'Кнопка отправки',
							onclick: function() {
								editor.insertContent('[button]');
							}
						}
					]
				},
				{ // второй элемент первого выпадающего списка, просто вставляет [misha]
					text: 'Шорткод [misha]',
					onclick: function() {
						editor.insertContent('[misha]');
					}
				}
			]
		});
	});
})();

После вставки кода моя кнопка уже появилась и работает. Единственное только — у неё нет никакой иконки (ну кроме стрелочки вниз).

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

  • Встроенные иконки TinyMCE.
  • Другие иконочные шрифты, в том числе и dashicons.
  • Любую картинку через background-image.
  • Изображение, закодированное в base64.

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

i.mce-i-perec {
	background-image: url('perec.png');
}
кнопка с иконкой в редакторе TinyMCE

Если использовали этот же способ и иконка не появилась — попробуйте прописать к ней абсолютный URL.

Для подключения CSS используйте функцию wp_enqueue_style() либо хук admin_head.

Результат:

всплывающее окно с параметрами шорткода
Всплывающее окно, в котором можно задать параметры шорткода, появляющееся при нажатии на кнопку в визуальном редакторе.

Если вы хотите использовать dashicons, то ваш CSS для иконки перца будет выглядеть примерно следующим образом:

i.mce-i-perec {
	content: "\f511"; /* выбираем иконку и узнаем ее код тут https://developer.wordpress.org/resource/dashicons/ */
	font-family:'dashicons';
	font-size:20px; /* можно подкорректировать размер шрифта, если не устраивает*/
}

Применение шорткодов к переменным в PHP

Тут всё сводится к использованию одной функции — do_shortcode().

do_shortcode()

do_shortcode($content)
$content
(строка) (обязательный) Функция выполняет все шорткоды, которые содержатся в этом аргументе.

Функция в качестве параметра может содержать лишь один шорткод:

echo do_shortcode( '[misha]' );

Или шорткод и какой-то контент:

echo do_shortcode( '[trueurl anchor="Главная"]' . site_url() . '[/trueurl]' );

Популярный пример, позволяет получить или вывести содержимое поста с применением шорткодов при помощи функции get_the_content():

$content_shortcoded = do_shortcode(get_the_content());

Вот пожалуй и всё. Если у вас возникнут какие-то вопросы, пожалуйста, оставляйте их ниже в комментах, буду рад помочь.

Миша

В последние годы я долго не знал, что мне делать с сайтом misha.blog, ведь он практически не приносит никакого профита, но недавно я осознал, что моя миссия – способствовать распространению WordPress. Ведь WordPress – это лучший движок для разработки сайтов – как для тех, кто готов использовать заложенную структуру этой CMS, так и для тех, кто предпочитает headless решения.

Сам же я впервые познакомился с WordPress в 2009 году. Организатор WordCamp. Преподаватель в школах Epic Skills и LoftSchool.

Если вам нужна помощь с вашим сайтом или может даже разработка с нуля на WordPress / WooCommerce — пишите. Я и моя команда сделаем вам всё на лучшем уровне.

Комментарии 38

  • Sweeney 9 января 2015 #

    Спасибо, полезная информация

    Ответ
  • Артем 9 января 2015 #

    Отличная статья, Михаил! Спасибо огромное, для меня очень актуально.

    Ответ
  • Джама 15 января 2015 #

    Миша вы просто супер! Давно искал нечто подобное, но кроме quickadd(или нечто подобное) в сети было найти не реально, хлопаю двумя руками! =)

    Ответ
    • Миша 15 января 2015 #

      Спасибо 🙂

      Ответ
  • Дмитрий 10 марта 2015 #

    Как сделать выполнение шорткода, который выводится через advanced custom fields?

    Делаю поле
    ТЕКСТ
    Добавить к началу - [name
    Добавить в конец - age]

    Вставляю в записи "Ира"

    Вывод на странице [name Ира age]

    Хотя в записи это выглядит по-другому. Получается не выполняется как шорткод, а выводится просто. Как победить такое?

    Ответ
    • Миша 11 марта 2015 #

      Блин, с advanced custom fields не работал, сходу даже не смогу сказать.

      Могу сказать только, что так [name Ира age] шорткоды не выглядят.

      Ответ
      • Джама 11 марта 2015 #

        Я бы даже сказал, что скорее всего код должен выглядеть так [supershortcode name=Ира age=1]

        Ответ
  • VRS 18 апреля 2015 #

    Еще бы - как удалить все шорткоды из контента 😉

    Ответ
  • Антон 10 мая 2015 #

    Отличная статья! Спасибо! Есть вопрос!
    Как добавить пользовательскую ширину и высоту в шорткоде?

    К примеру [misha width="200" height="200" ]Контент[/misha] - подскажите функцию!?!
    Заранее спасибо!

    Ответ
    • Миша 10 мая 2015 #

      В функции, которая выводит шорткод нужно использовать параметры:

      $params = shortcode_atts( array(
		'width' => 'значение ширины по умолчанию',
		'height' => 'значение высоты по умолчанию'
), $atts );

      А вообще в статье всё есть 🙂

      Ответ
  • Артем 29 мая 2015 #

    Михаил, приветствую! Вопрос вот в чем, как прикрутить локализацию к этой форме, чтобы можно было на нескольких языках форму показывать?

    Ответ
    • Миша 29 мая 2015 #

      Привет!
      Вы имеете ввиду форму кнопки в редакторе?

      Ответ
      • Артем 29 мая 2015 #

        Та форма, которая появляется по нажатию на кнопку

        Ответ
  • alx dh 13 июля 2015 #

    Пытаюсь добавить третий элемент первого выпадающего списка (по аналогии со вторым) в примере 2.2. После этого кнопка пропадает с панели tinymce. Что я сделал не так?

    Ответ
    • Артем 13 июля 2015 #

      Скорее всего запятую забыли, поле второго элемента...

      Ответ
      • alx dh 13 июля 2015 #

        Стыдно )
        Спасибо, действительно, все так просто.

        Ответ
  • Дмитрий 20 июля 2015 #

    Добрый день, а как вывести php код через шотркод? Нуждно, чтобы через шорткод подгружалась вот эта функция rotator();

    Ответ
  • Евгений 6 августа 2015 #

    Здравствуйте, Михаил. Прочитал данный пост и решил сделать плагин, добавляющий кнопку в tinymce для добавления шорткода. Но код не работает, кнопка в tinymce не появляется. Подскажите пожалуйста, Михаил, что я делаю не правильно. WordPress версии 4.2.4. Файлы находятся в папке plugins/exform. Вот код.

    function ex_add_mce_button() {
    if ( current_user_can( 'edit_posts' ) && current_user_can( 'edit_pages' ) ) {
        add_filter( 'mce_external_plugins', 'ex_add_tinymce_script' );
        add_filter( 'mce_buttons', 'ex_register_tinymce_buttons' );
    }
}
 
function ex_add_tinymce_script($plugin_array){
    $plugin_array['ex_button_script'] = plugins_url( '/exform/ex_button.js', __FILE__) ;
    return $plugin_array;  
}
 
function ex_register_tinymce_buttons($buttons){
    array_push( $buttons, "ex_button"); // ex_button - ID кнопки
    return $buttons;
}
 
add_action('init', 'ex_add_mce_button');
    (function() {
    tinymce.PluginManager.add('ex_button_script', function( editor, url ) {
        editor.addButton('ex_button', {
            text: '[ex_form]',
            title: 'Вставить шорткод [ex_form]',
            icon: false,
            onclick: function() {
                editor.insertContent('[ex_form]');
            }
        });
    });
})();
    Ответ
    • Артем 6 августа 2015 #

      Вы кнопку не подключили в скрипте, вроде как. Первая строка скрипта должна быть так

      tinymce.PluginManager.add('ex_button', function( editor, url ) {

      А у вас так

      tinymce.PluginManager.add('ex_button_script', function( editor, url ) {
      Ответ
      • Евгений 7 августа 2015 #

        Всё, починил) когда путь до ex_button.js указывал не надо было в функции plugin_url() прописывать __FILE__. Вот так правильно:

        $plugin_array['ex_button_script'] = plugins_url( '/exform/ex_button.js') ;

        А строчка:

        tinymce.PluginManager.add('ex_button_script', function( editor, url ) {

        -рабочая. Кнопка дальше в скрипте подключается:

        editor.addButton('ex_button', {
        text: '[ex_form]',
        title: 'Вставить шорткод [ex_form]',
        icon: false,
        onclick: function() {
        editor.insertContent('[ex_form]');
        }
        });

        Ответ
  • Юрий 27 августа 2015 #

    Пока ещё сложно для меня

    Ответ
  • Andy 28 ноября 2015 #

    А я на 2 шаге остановилась.
    2.1. JavaScript. Пример простой кнопки

    После добавления файла с JavaScript и функциями, вся панель кнопок визуального редакторе исчезает.

    Ответ
    • Миша 28 ноября 2015 #

      Пожалуйста, прежде всего проверьте, всё ли у вас точно, как в статье? Если да, то откройте консоль браузера и сообщите мне, какие там ошибки (или скриншотом).

      Ответ
      • Andy 29 ноября 2015 #

        Миша, прошу прощения. Уже разобралась. Удалила весь код, проверяющий права пользователя (оставила только подключения JavaScript и TinyMCE). Всё заработало.

        Ещё пыталась перенести файл в папку js, но, видимо, функцию get_stylesheet_directory_uri() нужно как-то редактировать, какие-то параметры ей задавать внутри скобок, потому что в этом случае тоже панель редактора исчезает. Поэтому оставила файл js в корне сайта.

        А так всё отлично работает, огромное вам спасибо!!!

        Ответ
        • Миша 29 ноября 2015 #

          Отлично 🙂
          Ну если вы хотите перенести всё в папку js, тогда просто добавьте её тут:

          $plugin_array['true_mce_button'] = get_stylesheet_directory_uri() .'/js/true_button.js';
          Ответ
  • Ирина 3 декабря 2015 #

    Миша, подскажите как к шорткоду [CONTACT_FORM_TO_EMAIL id="1"], добавить идентификатор цели Яндекс Метрики, типа: yaCounterXXXXXX.reachGoal('TARGET_NAME')

    Ответ
    • Миша 4 декабря 2015 #

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

      Ответ
  • Алексей 3 февраля 2016 #

    Здравствуйте Михаил Подскажите пожалуйста как можно выделенную ссылку обернуть в шорткод чтобы в результате получилось

    [video src="https://youtu.be/ALJgzRdHtlE"]
    Ответ
    • Миша 3 февраля 2016 #

      Здравствуйте!
      Вы имеете ввиду при нажатии на кнопку?

      Ответ
      • Алексей 3 февраля 2016 #

        выделяем ссылку нажимаем на кнопку и ссылка оборачивается

        [video src="https://youtu.be/ALJgzRdHtlE"]
        Ответ
        • Миша 5 февраля 2016 #

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

          Ответ
  • Ильдар 9 ноября 2019 #

    Подскажите, если делаю include через шорткод, то в конце страницы выводит "1", почему так?

    function true_misha_func( $atts ){
	$file = include($_SERVER['DOCUMENT_ROOT'] . '/api/dice.php');
	return $file;
}
    Ответ
    • Ильдар 9 ноября 2019 #

      Разобрался, нужно просто include делать, без return. Всегда так, где-то спросишь, сразу ответ находишь 🙂

      Ответ
      • Миша 12 ноября 2019 #

        Огонь! 🔥

        Ответ
  • Дмитрий 20 февраля 2020 #

    А что если нужно вставить в шорткоде отдельный файл с HTML, php и js?

    Ответ

Оставить комментарий

× Отменить ответ
Если вы хотите добавить код, не забудьте обернуть его в <pre lang="php"></pre>, в случае несоблюдения этого условия в 99% случаях ваш коммент будет удалён, а автор заблокирован. Печалька.