XF 2 [KL] Notification Service Framework (NSF) - Инструкция для разработчиков

Совместимость с XenForo: 2.0

Введение:
Это руководство предназначено для предоставления Вам всей необходимой информации для интеграции Вашей собственной сторонней службы уведомлений или обмена сообщениями с [KL] Notification Service Framework (NSF). Вы должны быть знакомы с базовым созданием плагина для XenForo 2.0, так как я не буду подробно описывать необходимые для этого шаги.

Начнём:
Это руководство начинается с того, что Вы уже создали плагин XenForo 2.0 для службы уведомлений или сообщений. Убедитесь, что у Вас настроен установочный файл, так как Вам понадобятся процессы установки и удаления для интеграции.

Запись в базу данных:
Чтобы структура могла зарегистрировать Вашу новую службу, Вам нужно будет добавить запись в таблицу xf_kl_nsf_service в своей базе данных. Таблица базы данных содержит следующие столбцы:
service_id - уникальный идентификатор, указывающий на Вашу службу обмена сообщениями. Он также будет использоваться для создания классов.
name - название XenForo_Phrase, которое содержит название Вашей службы. Оно будет использоваться в основном для выпадающего меню "Служба уведомлений" в области учётной записи.
form_template - название шаблона, который содержит Вашу конфигурационную форму для интерфейса.
service_directory - корневое пространство имени Вашего плагина. Оно используется для построения классов.

Настройки в панели управления:
Если для Вашего плагина необходимы какие-либо настройки (например, API-ключ), пожалуйста, сгруппируйте их в панели управления "klNSFOptions (Notification Service Options)". Я рекомендую использовать порядок отображения из трех или более цифр и разделить разные варианты ровно на 10.

Конфигурация формы пользователя:
Затем Вам нужно будет создать форму, которая позволит Вашим пользователям вводить всю необходимую информацию для Вашей службы. Я рекомендую использовать пример, описанный ниже, для унифицированного внешнего вида:
Code:
Please, Log in or Register to view codes content!


В шаблоне уже есть враппер для учётной записи и выбор сервиса внизу. Если Вы не включите последний код в шаблон, то пользователи не смогут больше выбирать другую услугу, как только они выбрали одну.
Если Вы укажете свои поля в схеме kl_nsf_service_data[YOUR_OPTION_NAME], то структура автоматически сохранит данные для Вас.
Расширяя \KL\NotificationServiceFramework\Pub\Controller\Account, Вы получите доступ к двум методам: _postSave($service_id) и _preSave($service_id). Вы можете расширить их для необходимой обработки. Пожалуйста, не распространяйте фактический метод сохранения напрямую, а также обязательно вызывайте родительский до или после сохранения в своём расширении.

Средство визуализации HTML:
Поскольку большинство служб обмена сообщениями имеют только небольшую поддержку html, то все уведомления должны сначала пройти через визуализатор HTML. Ваш рендерер должен быть расположен в service_directory\Html\Renderer\service_id и должен расширять абстрактный класс \KL\NotificationServiceFramework\Html\Renderer. Если Вы хотите просто передать выход шаблона, Вы должны оставить класс пустым.

Сервис:
Теперь, когда Вы всё настроили, пришло время реализовать фактический сервис. Ваша служба должна быть расположена в service_directory\Service\service_id и должна расширять абстрактный класс \KL\NotificationServiceFramework\Service\AbstractService. Вам необходимо будет реализовать два метода: isActive() и sendAlert(), чтобы он работал, как описано ниже:

isActive:
Эта функция не имеет параметров. Ваша задача - убедиться, что Ваш плагин настроен и будет работать корректно. В качестве примера возьмём:
Please, Log in or Register to view URLs content!
, который использует этот метод для проверки того, что API-ключ Telegram и botId настроены в параметрах панели управления администратора. Верните значение true, если Ваша служба готова к работе, в противном случае используйте значение false.

sendAlert:
Эта функция поставляется с двумя параметрами: \XF\Entity\User $user - является пользователем, который получит сообщение. Данные, сохранённые в форме конфигурации пользователя, будут храниться в $user->kl_nsf_service_data и $message, вывод вашего средства визуализации HTML. Фреймворк оставит реализацию фактического обслуживания для Вас, поэтому от функции не ожидается возвратного значения.

Дополнительно:
Хранение данных:
Если Вам потребуется место для дополнительных опций (например,
Please, Log in or Register to view URLs content!
хранит последнее смещение полученных сообщений), то Вы можете использовать таблицу базы данных: xf_kl_nsf_data со следующей формой:

data_id:
Уникальный идентификатор хранимых данных

value:
Ваши данные в формате сериализации JSON

Удаление:
Обязательно удалите все записи из таблиц: xf_kl_nsf_service и xf_kl_nsf_data при удалении! Также убедитесь, что Ваш плагин способен обрабатывать деинсталляцию, даже если NFS отсутствует (например, он уже удален)!