Стандартные шорткоды WordPress #

В WordPress уже есть определённый набор шорткодов, например тот же шорткоды галереи, с которым мы уже познакомились ранее.

Другие стандартные шорткоды это:

Экранирование шорткодов #

А точнее, как сделать так, чтобы шорткод присутствовал в контенте вашего поста, но не выполнялся? Или другими словами, как я вывел шорткоды в предыдущей главе поста, не выполняя их?

Всё, что нужно сделать, это обернуть его ещё в одни квадратные скобки, вот так:

Если же у вашего шорткода есть открывающий и закрывающий тег, то он будет выглядеть следующим образом:

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

[[шорткод] ... [/шорткод]]

Ну и про HTML-сущности тоже помним, да? [шорткод]

На самом деле именно в этом моменте можно кекнуть, потому что часто встречаю уроки по WordPress, где их отображают с пробелом, типо [ gallery] и при этом уточняют, что пробел нужно удалить 😹

Как создать шорткод WordPress? #

1. Простой пример #

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

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

• Код можете вставить в файл functions.php (я имею ввиду тот, который находится в директории вашей текущей темы). Больше информации о вставке кода.
• Имя шорткода должно быть обязательно в нижнем регистре и содержать только буквы латинского алфавита, цифры и символ подчеркивания.
• Мы использовали функцию site_url() для вывода текущего адреса сайта.

2. Шорткод с параметрами (атрибутами) #

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

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

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

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

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

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

Давайте возьмём шорткод из предыдущего примера и немного переколдуем его. Напомню, что шорткод выглядел так: [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] я писал выше).

4. Используем буферизацию для вывода прямо в шорткоде #

Иногда бывает, что никак не получается внутри шорткода возвратить результат, например мы используем функцию get_template_part() внутри. Что делать в таких ситуациях?

Решается это довольно легко – при помощи буферизации.

function truemisha_shortcode_callback() {
	ob_start();
	// тут можно сразу выводить при помощи echo()
	// или get_template_part( 'entry' );
	// или закрывать тег ?> и выводить сразу HTML
 
	$output = ob_get_contents(); // всё, что вывели, окажется внутри $output
	ob_end_clean();
 
	return $output;
}

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

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

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 — собственно сама кнопка, создайте этот файл в директории с темой (или там, где вам удобно, но не забудьте в этом случае поменять путь к нему).

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.

Подробнее на сайте https://misha.agency/wordpress/shortcodes.html?ysclid=m0nk2dslaf328831831