SEO Маяк

Всем привет! Сегодня на seo-mayak.com интересная и не менее полезная тема — добавление кнопок в html редактор WordPress.

С версии 3.3 разработчики WordPress внедрили Quicktags API, тем самым предоставив нам возможность добавлять в html редактор свои кнопки с произвольными функциями, причем всего несколькими строчками кода.

Что такое Quicktags API? Quicktags можно перевести, как «Быстрые метки», а вот об API расскажу немного подробней.

Аббревиатура API расшифровывается, как «Application Programming Interface» и означает — интерфейс программирования приложений или можно так перевести — интерфейс прикладного программирования.

Другими словами — это готовый код, который существенно упрощает работу программиста. Наверное все знакомы с библиотекой jQuery, написанной на языке JavaScript.

Если разобраться, то jQuery и есть своего рода API, так как данная библиотека существенно облегчает написание кода. Задачи, которые на JavaScript реализовываются за 20 строк, на jQuery можно уложиться в 5-6 строк. Думаю, определение API теперь должно быть понятно.

Quicktags API — это JavaScript функция, которая позволит нам существенно расширить функционал HTML редактора WordPress, причем без особых трудностей.

Пора уже перейти к практике. Поехали!

JavaScript API функция

Шаблон скрипта Quicktags выглядит следующим образом:

<script type="text/javascript">
QTags.addButton( id, display, arg1, arg2, access_key, title, priority, instance );
</script>

Теперь давайте разберемся с параметрами.

id (обязательный)- ID кнопки.

ID может состоять из любого уникального набора латинских символов или цифр. Если посмотреть исходный код, то любая кнопка редактора имеет стандартный набор HTML тегов.

Для примера возьмем исходный код кнопки b (выделение жирным):

<input type="button" id="qt_content_strong" class="ed_button button button-small" aria-label="Жирный" value="b"/>

На примере видно, что ID идет вторым параметром, и то, что мы впишем в параметр «id» будет подставлено после:

qt_content_

display (обязательный) — Название кнопки.

Текст, вписанный в данный параметр, станет значением HTML атрибута value:

value="b"

Параметр display может также состоять из любых латинских символов или цифр, но имейте в виду — это не просто название кнопки, а ее видимое обозначение:

arg1 (обязательный) — Открывающий тег.

Открывающий тег может быть любой, например: <h3> или <span>, все зависит от задачи, возложенную на кнопку.

Этот параметр в исходном коде вы конечно не найдете, но с помощью Quicktags API действие привяжется к кнопке.

arg1 (необязательный) — Закрывающий тег.

Понятно, что в данный параметр вписывается ответный тег, например: </h3> или </span>. Почему параметр необязательный, по-моему не трудно догадаться, просто есть и не парные теги.

access_key (необязательный) — буква для горячих клавиш.

То, что будет вписано в качестве параметра access_key станет значением HTML атрибута accesskey:

accesskey="z"

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

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

title (необязательный) — Описание кнопки.

Тут тоже должно быть все понятно. В данном параметре вписываем описание кнопки, например «Заголовок h3». В html это будет выглядеть так:

title="Заголовок h3"

priority (необязательный) — Позиция кнопки.

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

1-9 — первая позиция;
10-19 — вторая позиция;
20-29 — третья позиция
и т.д.

Например, если вписать цифру 5, то кнопка будет первой в ряду.

instance (необязательный) — Экземпляр класса.

Не совсем понял, что это за параметр. По всей видимости подразумевается возможность помещать кнопку в определенный экземпляр Quicktags, но что это за экземпляр, не очень понятно.

Правильное подключение скрипта Quicktags

Думаю надо объяснить, как правильно подключать скрипт Quicktags.

Разработчики создали специальный хук-событие admin_print_footer_scripts, который выведет скрипт Quicktags или любой другой скрипт в подвал админки. Все скрипты, подключенные через хук admin_print_footer_scripts будут выведены в исходный код только в том случаи, если открыта админ-панель.

К чему я это говорю. Просто я знаю, что некоторые веб-мастера выводят скрипты, которые предназначены исключительно для работы в админке, с помощью хука wp_footer. Надо понимать, что хук wp_footer будет выводить скрипты, как в исходный код админки, так и самого сайта, что конечно неправильно.

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

add_action( 'admin_print_footer_scripts', 'html_button' );
function html_button() {
	if ( wp_script_is('quicktags') ){
?>
	<script type="text/javascript">
	QTags.addButton('Параметры');
    </script>
<?php
  }
}

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

Теперь перейдем к конкретным примерам.

Добавление кнопок в html редактор на примерах

Добавим кнопку, которая будет заключать выделенный текст в теги <h3></h3>:

add_action( 'admin_print_footer_scripts', 'html_button' );
function html_button() {
	if ( wp_script_is('quicktags') ){
?>
	<script type="text/javascript">
	QTags.addButton( 'eg_h3', 'h3', '<h3>', '</h3>', 'h', 'Заголовок h3', 1 );
    </script>
<?php
  }
}

Теперь давайте подробно разберем все прописанные мной параметры:

QTags.addButton( 'eg_h3', 'h3', '<h3>', '</h3>', 'h', 'Заголовок h3', 1 );

eg_h3 — ID идентификатор кнопки;
h3 — display название кнопки, иконка;
<h3> — arg1 открывающий тег;
</h3> — arg2 закрывающий тег. Если закрывающего тега нет, то указываем пустые кавычки '';
h — access_key горячая клавиша. Можно не указывать просто оставив пустые кавычки;
Заголовок h3 — title описание кнопки, которое будет всплывать при наведении;
1 — priority — приоритет или местоположение кнопки среди других. Если ничего не указывать, по умолчанию кнопка получит приоритет 140-150.

Вот что получится в итоге:

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

Для примера, приведу коды кнопок, которые я добавил в свой html редактор:

add_action( 'admin_print_footer_scripts', 'html_button' );
function html_button() {
	if ( wp_script_is('quicktags') ){
?>
	<script type="text/javascript">
	QTags.addButton( 'eg_h3', 'h3', '<h3>', '</h3>', 'h', 'Заголовок h3', 1);
	QTags.addButton( 'eg_hr', 'hr', '<hr />', '', 'r', 'Горизонтальная линия', 201 );
	QTags.addButton( 'eg_php', 'php', '<pre class="brush: php">', '</pre>', 'z', 'Подсветка PHP синтаксиса', 111 );
	QTags.addButton( 'eg_css', 'css', '<pre class="brush: css">', '</pre>', 'w', 'Подсветка CSS синтаксиса', 112 );
	QTags.addButton( 'eg_krug', 'krug', '<div class="krug">', '</div>', 'e', 'Объявление', 113 );
	QTags.addButton( 'eg_feed', 'feed', '<span class="external-reference" data-link="http://feedburner.google.com/fb/a/mailverify?uri=seo-mayakcom&amp;loc=ru_RU">', '</span>', 'x', 'Cсылка на feed', 114 );
	</script>
<?php
	}
}

Я теперь даже ajax-ссылку на подписку в feedburner вывожу с помощью кнопки. Супер удобно!

Привязка к кнопке произвольной функции

Кроме простого добавления кнопок, со стандартными задачами, разработчики в Quicktags API предусмотрели возможность привязывать к кнопке произвольную JavaScript функцию.

QTags.addButton( 'id', 'display', название функции);

Приведу пример функции, которая будет срабатывать при нажатии на кнопку «class» и выводить блок div с произвольным классом, который надо будет вписать в модальное окно:

add_action( 'admin_print_footer_scripts', 'html_button_class' );
function html_button_class() {
	if ( wp_script_is('quicktags') ){
?>
	<script type="text/javascript">
        QTags.addButton( 'my_prompt', 'class', div_class);
        function div_class() {
        var new_class = prompt( 'Введите название класса:', '' );     
        if ( new_class ) {
        QTags.insertContent('<div class="' + new_class + '"></div>');
      }
    }
	</script>
<?php
	}
}

Результат:

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

Зарезервированные параметры

В таблице представлен список всех зарезервированных параметров и во избежании ошибок лучше их не использовать.

Удаление кнопок из html редактора

Для удаления не нужных кнопок с панели HTML редактора, разработчики WordPress предусмотрели специальный хук-фильтр quicktags_settings.

Допустим нам надоели стандартные кнопки и мы хотим их все удалить. Вуаля:

function remove_html_buttons($buttons) {
$buttons['buttons'] = '/';
return $buttons;
}
add_filter('quicktags_settings', 'remove_html_buttons');

В редакторе остались, только те кнопки которые я сам создал:

Если же мы хотим оставить некоторые стандартные кнопки, то во второй строчке функции, в кавычках через запятую перечисляем ID нужных кнопок. Например:

function remove_html_buttons($buttons) {
$buttons['buttons'] = 'strong,em,link,code,more';
return $buttons;
}
add_filter('quicktags_settings', 'remove_html_buttons');

Важно! Пробелов после запятых быть не должно. Результат:

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

До встречи!

С уважением, Виталий Кириллов

Статьи по теме:

Свои кнопки в редактор TinyMCE WordPress
Кнопка в редактор TinyMCE для ajax-ссылки
Функция wp_editor() — текстовый редактор в комментариях