Статьи

Простое руководство по API WordPress Quicktags

Февраль 25, 2019

Начиная с версии 4.0, в WordPress имеется 18 встроенных API . Все они чрезвычайно важны для различных аспектов WordPress, и вместе они помогают WordPress быть самой гибкой системой управления контентом в мире.

Одним из таких API-интерфейсов является API-интерфейс Quicktags, который позволяет разработчикам плагинов и тем добавлять новые кнопки в текстовый режим (обычно называемый режимом HTML) редактора WordPress. В этом руководстве мы узнаем, что такое API-интерфейс Quicktags и как использовать API для создания новых кнопок для редактора HTML.

Что такое Quicktags API?

Несмотря на то, что это больше, WordPress обычно используется как «система управления контентом», и WordPress должен позволять пользователям легко и эффективно управлять контентом . Вот почему WordPress поставляется с TinyMCE, одним из лучших редакторов WYSIWYG («Что видишь, то и получаешь») всех времен и, возможно, наиболее подходящий редактор контента для WordPress. TinyMCE предлагает несложный опыт редактирования контента для пользователей, который одновременно отображает контент почти как точный предварительный просмотр того, что они собираются опубликовать.

Но некоторые пользователи не любят это видеть. Фактически, некоторые пользователи предпочитают видеть исходный код контента, чтобы иметь полный контроль над тем, что они собираются публиковать. Или, может быть, пользователь будет в «Визуальном редакторе» и захочет проверить и проверить исходный код. Вот где «HTML-редактор» вступает в игру. Режим HTML редактора WordPress отображает исходный код содержимого и ничего более.

В верхней части редактора HTML есть кнопки, которые мы называем «кнопки быстрого набора», и они позволяют редактировать содержимое, не переключаясь обратно в визуальный редактор. Используя API Quicktags, мы можем создавать новые кнопки наряду с существующими.

Использование API Quicktags

Использовать API Quicktags очень просто, потому что, хотя основной файл quicktags.js содержит гораздо больше, мы будем (и должны) использовать только одну функцию: QTags.addButton() .

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

01
02
03
04
05
06
07
08
09
10
11
12
<?php
 
function load_my_quicktags() {
 
    // Load the `my-quicktags.js` file with the `QTags.addButton()` functions.
    wp_enqueue_script( ‘my-quicktags’, ‘http://the.url/to/my-quicktags.js’, array( ‘quicktags’ ) );
 
}
 
add_action( ‘admin_enqueue_scripts’, ‘load_my_quicktags’ );
 
?>

Но если у вас нет выбора, кроме как напечатать скрипт в строке, вы можете сделать это с помощью следующего фрагмента кода:

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
<?php
 
function load_my_quicktags_inline() {
 
    if ( wp_script_is( ‘quicktags’ ) ) { ?>
     
        <script>
         
            // The `QTags.addButton()` functions go here.
         
        </script>
     
    <?php }
 
}
 
add_action( ‘admin_print_footer_scripts’, ‘load_my_quicktags_inline’ );
 
?>

Довольно легко, правда? Обратите внимание, что на этот раз мы использовали действие admin_print_footer_scripts .

Параметры QTags.addButton()

Функция QTags.addButton() имеет восемь параметров:

01
02
03
04
05
06
07
08
09
10
QTags.addButton(
    id,
    display,
    arg1,
    arg2,
    access_key,
    title,
    priority,
    instance
);
  • id (строка, обязательная): уникальный идентификатор, который будет значением HTML- ID для кнопки быстрого набора. (Имейте в виду, что к значению идентификатора каждой кнопки будет автоматически 'qt_content_' строка 'qt_content_' .)
  • display (строка, обязательно): текст для отображения на кнопке.
  • arg1 (строка или функция, требуется): начальный тег для вставки или имя функции обратного вызова.
  • arg2 (строка, необязательно): конечный тег для вставки при необходимости.
  • access_key (строка, необязательно): ключ доступа для кнопки.
  • title (строка, необязательно): значение title HTML для кнопки.
  • priority (целочисленный, необязательный): место, куда пойдет ваша кнопка: 1–9 за первое место, 11–19 за второе место, 21–29 за третье место и т. д.
  • instance (строка, необязательно): конкретный экземпляр Quicktags, чтобы кнопка отображалась только там, если на странице имеется более одного экземпляра Quicktags. (Если это не установлено, кнопка будет добавлена ​​ко всем экземплярам.)

Основное использование: создание простых кнопок

Поначалу Quicktags API может показаться пугающим и сложным (особенно если ваши знания JavaScript такие же слабые, как и я ), но, как вы сейчас увидите, нет ничего страшного в написании крошечных кусочков кода для создания кнопок Quicktag.

Давайте начнем с чего-то простого: предположим, что вы собираетесь добавить две кнопки с шорткодом — сначала один с коротким кодом, а после с другим. Вот что вы делаете:

1
2
3
4
5
6
QTags.addButton(
    ‘info-box’,
    ‘info box’,
    ‘[infobox]’,
    ‘[/infobox]’
);

Видишь, как это легко? Все, что вам нужно сделать, это установить идентификатор, имя кнопки и строки для печати при нажатии кнопки. Вы также не можете установить второй аргумент (четвертый параметр) и напечатать самодостаточный шорткод:

1
2
3
4
5
QTags.addButton(
    ‘signature’,
    ‘signature’,
    ‘[signature]’
);

Вот и все, что нужно знать об основном использовании кнопок Quicktag!

Расширенное использование: запуск функций обратного вызова

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

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

Теперь давайте сделаем два быстрых примера. Первая — классическая кнопка alert :

1
2
3
4
5
6
7
8
9
QTags.addButton(
    ‘alert’,
    ‘alert’,
    my_alert
);
 
function my_alert() {
    alert( ‘Hello Quicktag!’ );
}

Как вы можете догадаться, на экране появляется «Hello Quicktag!» сообщение. Теперь давайте сделаем что-нибудь с подсказкой:

01
02
03
04
05
06
07
08
09
10
11
12
13
QTags.addButton(
    ‘my_prompt’,
    ‘alert’,
    my_prompt
);
 
function my_prompt() {
    var my_class = prompt( ‘Enter a class name:’, » );
     
    if ( my_class ) {
        QTags.insertContent(‘<div class=»‘ + my_class +'»></div>’);
    }
}

Это немного сложнее: он просит вас ввести имя класса и печатает div с указанным вами классом.

Вывод

Как я уже говорил ранее, API выглядит немного пугающим. Но, как вы можете видеть, использовать его довольно просто — даже при использовании его для запуска функций обратного вызова. В режиме HTML есть несколько очень преданных пользователей, и они будут очень признательны, если вы добавите одну или две кнопки при разработке темы или плагина.

Как вы относитесь к Quicktags API? Рассматриваете ли вы использовать его, или у вас есть что-то еще, чтобы добавить к этому учебнику? Скажите нам, что вы думаете, комментируя ниже. И если вам понравилась статья, не забудьте поделиться ею с друзьями!

42
Share: