Создаём свою систему WordPress Messaging System, часть 2

() translation by (you can also view the original English article)

Для тех, кто здесь впервые - обратите внимание, что сейчас мы находимся в процессе построения собственной системы пользовательских сообщений в связке с WordPress. Для этого используем существующие API, настраиваем их под себя, что даст нам в итоге более гибкий и удобный функционал.

Из первого урока:

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

Хотя предыдущий курс the series preceding this one повторять не обязательно, рекомендую изучить материалы первого урока the preceding tutorial. Поскольку сегодняшняя тема будет его продолжением (так построен весь цикл).

Итак, цель этой серии уроков – дать навык объектно-ориентированного программирования системы пользовательских сообщений внутри WordPress API для настроек их работы под нужды ваших клиентов.

Перед тем, как начать, приготовьте необходимый набор инструментов.

Прежде, чем начать

Прочтите предыдущую статью.
Установите PHP 5.6.25 и MySQL 5.6.28.
Установите Apache или Nginx.
Подключите WordPress 4.6.1.
Держите наготове свой любимый IDE или другой редактор.

Если вам удобней иметь «всё-в-одном», запустите MAMP. Если подзабыли, как это всё работает, перечитайте these articles.

Курсовой план обучения

Если вдруг вы пропустили прошлый урок the previous tutorial, вот наша программа обучения:

В первом уроке мы освоим базовые навыки по созданию плагина и определимся, что для этого нужно.
Во второй части научимся применять плагин в самом простом виде страницы администратора WordPress. Сделаем некоторые настройки hook вручную, проверим их для связи с сервером. Заложим фундамент нашего Settings Messenger.
В этом уроке начнём реализацию сделанных настроек Messenger, добавим поддержку успешных и ошибочных сообщений, коснёмся вопросов безопасности.
Закончим курс, связав вместе все наработки, посмотрим их в действии и получим окончательный вариант плагина, готового к загрузке.

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

Возвращаемся к работе

Обсуждение закончили, давайте продолжим. Сейчас мы имеем основу плагина для его активации Settings и просмотра на странице администратора Tuts+ Custom Message Example.

Как вы могли видеть ранее (и проследите в дальнейшем), код страницы очень прост:

<div class="wrap">

    <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>

    <p class="description">
        We aren't actually going to display options on this page. Instead, we're going
        to use this page to demonstration how to hook into our custom messenger.
    </p><!-- .description -->
</div><!-- .wrap -->

Я привёл его здесь ещё раз, потому что сейчас мы начнём создавать свой пользовательский messenger.

Для его создания мы должны иметь:

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

Внедрение пользовательского Hook

Определение собственного хука в код заданной функции не так страшно, как может показаться. Большинство из вас хорошо знакомы с командами add_action и add_filter, но как их можно применить для внедрения личного хука?

Очень просто: через команду do_action меняем характеристику, заданную в WordPress. К примеру, в код, указанный выше, пропишите сразу за тегом h1 следующее:

<div class="wrap">

    <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
  <?php do_action( 'tutsplus_settings_messages' ); ?>

	<p class="description">
		We aren't actually going to display options on this page. Instead, we're going
		to use this page to demonstration how to hook into our custom messenger.
	</p><!-- .description -->
</div><!-- .wrap -->

Неплохо получилось? Теперь нам нужно зарегистрировать функцию, которая будет срабатывать при каждом вызове hook. Прежде чем мы это сделаем, давайте убедимся, что все находимся на странице do_action .

Вот то, что разработчик говорит о действии do_action:

Эта функция действительна для всех команд, назначенных хуком $tag. Простым вызовом этой функции можно приступать к созданию нового хука вручную, присвоив ему имя в параметрах $tag.

Если пояснение кажется не совсем понятным, разберём его на примере. Так что давайте посмотрим.

2. Регистрация функции

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

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

Кроме того, заложим основу класса, который мы будем совершенствования в ближайших уроках. Теперь добавьте в ваш плагин файл class-settings-messenger.php в каталоге admin (и не волнуйтесь, все это будет доступно для скачивания).

<?php

class Settings_Messenger {

    public function init() {

    }
}

Напоминаю, что мы не используем в этом курсе пространства имён и автозагрузки (хотя можем о них узнать из we've covered them before). Обратите внимание, что я буду предоставлять код для метода init .

Теперь, вернувшись к плагину bootstrap файла,tutsplus-custom-message.php, добавьте следующий код в главную функцию:

<?php

function tutsplus_custom_messaging_start() {

    $plugin = new Submenu(
        new Submenu_Page()
    );
    $plugin->init();

    $messenger = new Settings_Messenger();
    $messenger->init();
}

Сейчас вернёмся к init функции в Settings_Messenger и подключим к нашим действиям.

<?php

public function init() {
    add_action( 'tutsplus_settings_messages', array( $this, 'display_message' ) );
}

Обратите внимание в коде выше, что первым в списке add_action идёт имя нашего пользовательского hook. Следующий описывает метод, с помощью которого сообщение будет выведено на панели администратора. Оно пока ещё не записано (так что если вы попытаетесь запустить этот код, получите сообщение об ошибке).

Сейчас исправим.

3. Отображение настраиваемого сообщения

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

<?php

public function display_message() {
    echo 'This is an example message.';
}

И если код прописан верно, вы должны увидеть что-то вроде этого. Внимательно посмотрите под тегом h1, там вы должны увидеть предложения, которые мы включили выше.

An example of the message we want to display

Однако, есть проблема: наше сообщение не имеет типов разметки, который использует WordPress для обозначения успеха сообщения, предупреждения или ошибки.

Далее с этим разберёмся, а пока сделаем так, чтобы окно на дисплее показывало, что наш код сработал и команда выполнена успешно. В конце концов, мы сумели далеко продвинуться, правда? Мы выведем наши собственные сообщения через пользовательский hook с помощью класса сообщений, что мы создали.

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

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

Используйте код:

<?php

public function display_message() {

    $html = "
        <div class='notice notice-success'>
            <p>You have successfully displayed a custom success message.</p>
        </div><!-- .notice-success -->
    ";

    $allowed_html = array(
        'div' => array(
            'class' => array(),
        ),
        'p' => array(),
    );

    echo wp_kses( $html, $allowed_html );
}

И его действие увидите на следующем скриншоте:

Обратите внимание, что сообщение сохраняется. Здесь нет кнопки «сохранить», нет способа спрятать или изменить его вне кода. Но всё нормально, потому что это не тема нашего упражнения.

Несколько уточнений:

Класс атрибутов элемента div, который вы видите, заимствован непосредственно из WordPress. Так мы можем наследовать эти стили.
Некоторые сообщения могут быть скрыты. Рассмотрим это в дальнейшем.
$allowed_html , передаваемый для wp_kses сообщает, что ничего, кроме указанных элементов и атрибутов не отображается. Это очень хороший, сильный и чистый способ очистки данных.

И это все есть в данном курсе; однако мы с ним только знакомимся.

Заключение

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

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

Обратите внимание, я всегда рад ответить на вопросы в комментариях, и вы также можете зайти на мой blog или follow me на Twitter. Как обычно, поговорим о новостях софта для WordPress и всего, что с этим связано.

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