Завершающие советы по разработке дополнений для WordPress

2020-10-20

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

Советы по разработке дополнений для WordPress

стандарты кода WordPress;
как избежать конфликтов имён в глобальном пространстве имён (префиксы и классы);
комментарии в коде;
безопасность.

Больше советов по разработке дополнений для WordPress

правильный способ добавления скриптов и стилей (register, enqueue и localize);
AJAX-вызовы;
фильтры и события.

В этой, заключительной, статье цикла я расскажу о трёх важных вещах, которые крайне важны для написания качественного кода, хоть и не влияют на него непосредственно.

1. Отладка

1. Отладка

Самое первое, что вы должны сделать, прежде чем начать писать код плагина – разрешить отладку, как это рекомендует документация WordPress. Так вы увидите всё, что происходит в системе: ошибки, предупреждения, информацию интерпретатора.

Чтобы разрешить отладку, добавьте в ваш файл wp-config.php следующий код:

define('WP_DEBUG', true);

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

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

// all errors will be saved to a debug.log log file inside the /wp-content/ directory
define('WP_DEBUG_LOG', true);

// not display errors in HTML
define('WP_DEBUG_DISPLAY', false);

Другая опция режима отладки, которую я часто использую, сохраняет все запросы к базе данных в массив. Она выглядит так:

define('SAVEQUERIES', true);

Обычно я использую все эти настройки (особенно последнюю) совместно с плагинами Debug Bar и Debug Bar Console. Если вы ещё не знаете о них, попробуйте сразу их установить и начать использовать при отладке плагина или темы. Вы увидите, как это упростит работу.

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

2. Документация

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

Я рекомендую разделять документацию на секции или разделы, самые важные из которых должны освещать следующие вопросы:

установка;
настройка;
краткое руководство по использованию;
часто возникающие вопросы;
требования.

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

Если ваш плагин создаёт фильтры или функции обратного вызова, их описание лучше вынести на отдельные страницы.

Вкладки

Вкладки в справке – отличный способ помочь пользователям в работе с плагином или темой, не перенаправляя их на другой сайт. Обычно информация в этих вкладках зависит от контекста текущей страницы:

Например, один из моих плагинов, Social PopUP, использует вкладку справки, чтобы объяснить использование шорткодов:

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

/**
 * Initialize the plugin by loading admin scripts & styles and adding a
 * settings page and menu.
 *
 * @since     1.0.0
 */
function __construct(){
    [...]
    //Help Tab
    add_action( 'load-post.php',  array( $this, 'my_admin_add_help_tab') );
}

/**
 * Add help tab to the spucpt post type
 * @since  1.0
 * @return void
 */
function my_admin_add_help_tab () {

    $screen = get_current_screen();

    if( 'spucpt' != $screen->id ) {
        return;
    }

    // Add my_help_tab if post type is spucpt
    $screen->add_help_tab( array(
        'id'        => 'my_help_tab',
        'title'     => __( 'Shortcodes' ),
        'content'   => 'Hello content goes here',
    ) );
}

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

Для добавления справки на страницу опций вы можете воспользоваться кодом, который приведён как образец в кодексе WordPress:

<?php 
add_action('admin_menu', 'my_admin_add_page');
function my_admin_add_page() {

    $my_admin_page = add_options_page( __( 'My Admin Page', 'map' ), __( 'My Admin Page', 'map' ), 'manage_options', 'map', 'my_admin_page' );

    // Adds my_help_tab when my_admin_page loads
    add_action( 'load-' . $my_admin_page, 'my_admin_add_help_tab' );
}

function my_admin_add_help_tab () {

    $screen = get_current_screen();

    // Add my_help_tab if current screen is My Admin Page
    $screen->add_help_tab( array(
        'id'        => 'my_help_tab',
        'title'     => __( 'My Help Tab' ),
        'content'   => '<p>' . __( 'Descriptive content that will show in My Help Tab-body goes here.' ) . '</p>',
    ) );
}
?>

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

3. Интернационализация

Интернационализация (AKA i18n, потому что между первой “i” и последней “n” в слове “Internationalization” помещается ровно 18 букв) – это вишенка на торте, символизирующем качественный программный продукт.

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

В чём разница между интернационализацией и локализацией?

Интернационализация (i18n) – это процесс построения программного продукта, который может быть без проблем переведён на другие языки. Локализация (l10n) – собственно процесс перевода.

Как WordPress поддерживает перевод?

WordPress использует популярную библиотеку gettext, работу которой можно кратко описать так:

разработчики оборачивают переводимые строки в вызов специальной функции;
специальные утилиты разбирают код, выделяют из него строки, нуждающиеся в переводе, и сохраняют их в файлах формата POT (Portable Object Template);
переводчики работают с POT-файлами, а результат их работы выражается в PO-файлах (тот же POT, только с переводом);
PO компилируется в бинарный формат MO для ускорения доступа к строкам во время выполнения программы.

Как создавать переводимые строки?

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

Есть несколько способов создать переводимые строки в зависимости от способа их использования: используется ли строка как переменная, выводится ли на экран при помощи echo и т. д. Наиболее часто используемыми функциями-обёртками являются __() и _e(). Давайте рассмотрим их применение на конкретных примерах:

// creating a variable
$hello =  __( 'Hello, Im a translatable string', 'my-text-domain' );

echo '<h2>'. __( 'Hello, Im a translatable string', 'my-text-domain' ) . '</h2>';

// to do an echo you can use
_e( 'Hello, Im a translatable string', 'my-text-domain' );

// When you have variables in the string you do:
printf( __( 'We deleted %d posts.', 'my-text-domain' ), $count );

// Or multiple variables
printf( __( 'Your name is %1$s, and your last name is %2$s.', 'my-text-domain' ), $name, $lastname );

Другая полезная функция – _n() – используется для множественного числа. Эта функция принимает 4 аргумента:

singular – форма единственного числа;
plural – форма множественного числа;
count – количество объектов, которое определяет, какая форма будет использована;
text domain – идентификатор text-domain.

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

printf( _n( 'We deleted one post.', 'We deleted %d posts.', $count, 'my-text-domain' ), $count );

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

wp_enqueue_script( 'script-handle', … );
wp_localize_script( 'script-handle', 'objectL10n', array(
    'alert'         => __( 'This is an alert message', 'my-text-domain' ),
    'submit'        => __( 'Submit', 'my-text-domain' ),
) );

Включение перевода плагина

Мы уже разместили обёртки для всех переводимых строк. Самое время включить перевод. Для этого мы поместим в функцию инициализации плагина следующий код:

function myplugin_init() {

    $plugin_dir = basename( dirname( __FILE__ ) );
    load_plugin_textdomain( 'my-text-domain', false, $plugin_dir );
}
add_action( 'plugins_loaded', 'myplugin_init' );

Этот код будет пытаться загрузить из каталога вашего плагина MO-файл с именем my-text-domain-{locale}.mo. Часть {locale} будет заменена на код языка в зависимости от языковых настроек файла wp_config.php. Например, если мой язык настроен так:

define ('WPLANG', 'es_ES');

файл, который WordPress попытается загрузить, будет называться my-text-domain-es_ES.po. С темами дело обстоит примерно так же, плюс необходимо добавить в файл functions.php такой код:

load_theme_textdomain( 'my_theme_textdomain' );

Основное отличие состоит в том, что система будет искать файл {locale}.mo вместо my-text-domain-{locale}.mo, как в предыдущем примере.

Дополнительные сведения об i18n содержатся в Кодексе WordPress.

Заключение

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

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

Буду рад, если вы примете участие в обсуждении этой серии статей.