Это руководство продемонстрирует как шаг за шагом создать простой в использовании плагин. Здесь вам будет показано, как создать плагин, отображающий сообщение в верхней части каждой страницы форума.
Шаг 1: Создание плагина
Для начала, вам нужно активировать режим разработчика. После того как режим разработчика будет активирован, в админпанели на странице Система --> Возможности --> Плагины появится кнопка "Создать плагин" . Нажмите на нее для того чтобы перейти в Plugin Developer Center.
Шаг 2: Создание хуков темы
Самый простой способ отображения сообщение в верхней части каждой страницы это создание хука темы. Хуки тем позволяют изменять содержимое шаблона. Мы будем менять шаблон "globalTemplate", который находится в "global" шаблонах, местоположении "front", приложения "core".
На вкладке "Hooks", создайте новый хук и выберите " core --> front: global" в качестве группы шаблонов. После создания, нажмите кнопку “Изменить”, а затем выберите "globalTemplate" в меню слева.
Выберите "Select Element", чтобы вывести содержимое шаблона и выбрать точку, которую вы хотите зацепить – хорошим местом будет <DIV ID="ipsLayout_mainArea">, а затем выберите пункт "Вставить содержимое внутри выбранного элемента (ов), в самом начале".
Теперь нужно указать содержимое вручную:
<div class="ipsMessage ipsMessage_information">Это глобальное сообщение</div>
После сохранения вы можете перейти на главную страницу, и сразу увидите сообщение, которое вы только что создали.
Поздравляем, вы только что создали простой плагин! Далее показано, как расширить этот функционал.
Шаг 3: Использование шаблонов
Удобно хранить весь HTML в шаблонах. Хотя этот подход работает отлично, HTML контент находится внутри кода вашего плагина, так что если кто-то после его установки захочет изменить в нем что-то (возможно, изменить CSS классы), ему будет трудно сделать это.
К счастью, создать HTML шаблон очень легко. Если вы посмотрите в директории на вашем компьютере/сервере, где установлен Invision Community, вы увидите папку "plugins" - внутри вы найдете каталог вашего плагина с именем, которое вы указали на шаге 1. Внутри есть папка dev/html. Внутри этой папки, файлы, создаваемые вами, будут доступны в виде шаблона.
Создайте файл с именем globalMessage.phtml добавьте в него следующее:
<ips:template parameters="" /> <div class="ipsMessage ipsMessage_information"> Теперь используется шаблон! </div>
В первой строке просто указываются любые параметры, которые будут переданы в шаблон (в нашем случае не нужны). После того, как файл был создан, отредактируйте хук темы и изменить его содержимое используя данный код:
{template="globalMessage" group="plugins" location="global" app="core"}
Это тэг шаблона, который подгружает содержимое шаблона. Все шаблоны, созданные с помощью плагинов создаются в группе "plugins" в "global", в приложении "core".
Как только это будет сделано, вы должны увидеть сообщение: "Теперь используется шаблон!".
В дополнение скажем, что если вы хотите добавить CSS код, вы можете просто добавить CSS файлы в папку dev/css, и они будут автоматически подключены. CSS файлы плагина компилируются вместе с внутренними CSS файлами IPS4 таким образом, чтобы они были доступны на каждой странице.
Шаг 4: Настройки и языковые строки
Теперь у вас есть глобальное сообщение - но сейчас нет никакого способа, чтобы настроить то, что оно отображает. Было бы удобно, если бы плагин имел простое меню настройки в админпанели, чтобы администратор мог использовать его для изменения содержимого.
Чтобы создать его, перейдите на вкладку "Настройки" в центре разработчика для вашего плагина и добавьте параметры. Для ключа, используйте globalMessage_content, и установите значение по умолчанию какое вам нравится. Очень важно убедиться, что ваш плагин начинает работать сразу после установки, до того как администратор его настроит, поэтому не оставляйте значения по умолчанию пустыми.
Создание настроек здесь выделяет пространство для них в базе данных, но вам все еще нужно создать форму, где администратор может редактировать функции плагина. Чтобы сделать это, опять же смотрим в папку вашего плагина в файловой системе; вы увидите файл под названием settings.rename.php. Во-первых, нужно его переименовать в settings.php затем открыть. Он уже содержит пример кода, чтобы вам было понятно. Измените первую строку кода ($form->add(...)) на это:
$form->add( new \IPS\Helpers\Form\Editor( 'globalMessage_content', \IPS\Settings::i()->globalMessage_content, FALSE, array( 'app' => 'core', 'key' => 'Admin', 'autoSaveKey' => 'globalMessage_content' ) ) );
Этот код использует помощника форм.
Теперь в разделе Плагины в админпанели, вы увидите новую кнопку "Изменить" рядом с плагином. При нажатии на нее всплывает форма с полем, где пользователь может заполнить сообщение.
Существует, однако, одна небольшая проблема. Ярлык для установки такой: "globalMessage_content" - очевидно, что его нужно изменить на что-то более понятное, для чего вам понадобиться языковая строка. Языковые строки в IPS4 простые пары key/value, хотя языковые строки могут использовать более сложные функции, такие как строки замены и плюрализацию.
Чтобы создать её, откройте в папке вашего плагина файл dev/lang.php. Он содержит только пустой массив. Добавьте элементы в этот массив:
$lang = array(
'globalMessage_content' => "Сообщение",
);
Теперь ярлык будет называться "Сообщение".
И, наконец, вам нужно сделать выбранное пользователем отображение сообщения. Чтобы сделать это, откройте файл globalMessage.phtml, созданный на шаге 3 и измените его содержимое:
<ips:template parameters="" /> {{if settings.globalMessage_content}} <div class="ipsMessage ipsMessage_information"> {setting="globalMessage_content"} </div> {{endif}}
Это добавляет некоторую логику шаблона, которая определяет, есть ли значение настроек и отображает сообщение только если оно есть, и тег шаблонов, который получает значение нашего параметра.
Шаг 5: Внесение изменений в базу данных
Идём далее, мы можем добавить кнопку "Закрыть" к сообщению, что позволит пользователям отключить сообщение, как только они прочитали его. Закрыл ли данный пользователь сообщение или нет, информация должна быть сохранена в базе данных.
Откройте папку dev/setup в каталоге вашего плагина. Здесь вы найдете файл под названием install.php. Этот файл запускается, если ваш плагин установлен. Если вам необходимо сделать последующие изменения базы данных в будущих версиях вашего плагина, вы можете создавать новые версии в центре разработчика, и файл будет создан для каждой версии, которую вы создаете. Вы должны убедиться, что любые ваши изменения сохранялись в файл install.php и соответствующий файл обновления.
Откройте install.php и добавьте этот код в метод шага 1:
\IPS\Db::i()->addColumn( 'core_members', array(
'name' => 'globalMessage_dismissed',
'type' => 'BIT',
'length' => 1,
'null' => FALSE,
'default' => 0,
'comment' => 'Если значение 1, пользователь закрыл сообщение'
) );
return TRUE;
Этот код добавляет новый столбец в таблицу core_members в базе данных, которая представляет собой таблицу, содержащую информацию о всех пользователях. Поле в столбце имеет тип BIT (что означает, что он может хранить только 1 или 0) - 0 будет указывать что пользователь не отключил сообщение (и оно будет показываться) а 1 укажет, что он закрыл его. Значение по умолчанию устанавливается равным 0.
Но нужно убедиться, что этот код создаст столбец при установке плагина. Для этого вам необходимо выполнить запрос на локальной базе данных. Выполните этот SQL запрос, используя любую предпочтительную систему для управления базами данных данных:
ALTER TABLE core_members ADD COLUMN globalMessage_dismissed BIT(1) NOT NULL DEFAULT 0 COMMENT 'If 1, the user has dismissed the global message';
Если пользователь закрыл сообщение, то его выбор необходимо будет сбросить, если администратор изменит содержимое сообщения. Для того, чтобы справиться с этим, добавьте эту строку в файл settings.php в каталоге плагина, сразу после вызова $form->saveAsSettings();.
\IPS\Db::i()->update( 'core_members', array( 'globalMessage_dismissed' => 0 ) );
Шаг 6: Создание хука кода
Теперь, когда вы выделили пространство в базе данных, где будет храниться флаг, вам нужно написать код, который будет устанавливать значение, и свяжет его с шаблоном.
Вам нужно добавить метод к контроллеру, который будет обрабатывать щелчок пользователя. Общий контроллер, предназначенный для такого рода событий доступен в \IPS\core\modules\front\system\plugins - хотя теоретически, можно добавить метод к любому контроллеру.
В центре разработчика, создаем хук кода на этот класс, открываем его (либо в админпанели, либо открыв файл, который был создан в каталоге хуков в каталоге плагина) и добавляем следующий код внутрь класса:
public function dismissGlobalMessage()
{
\IPS\Session::i()->csrfCheck();
if ( \IPS\Member::loggedIn()->member_id )
{
\IPS\Member::loggedIn()->globalMessage_dismissed = TRUE;
\IPS\Member::loggedIn()->save();
}
else
{
\IPS\Request::i()->setCookie( 'globalMessage_dismissed', TRUE );
}
\IPS\Output::i()->redirect( isset( $_SERVER['HTTP_REFERER'] ) ? $_SERVER['HTTP_REFERER'] : \IPS\Http\Url::internal( '' ) );
}
Важно точно понять что делает эта функция:
- Сначала она выполняет проверку CSRF. Поскольку это метод контроллера, он выполняется автоматически при доступе к соответствующему URL. Потому, что это влияет на пользователя (она изменяет предпочтение) крайне важно, чтобы она имела CSRF проверку. Если проверка не проходит, то выполнение будет остановлено автоматически.
- Она проверяет, является ли текущий пользователь зарегистрированным пользователем. \IPS\Member::loggedIn() возвращает объект \IPS\Member для текущего пользователя - если пользователь является гостем (не вошел на сайт) member_id будет равен 0. Если пользователь вошел в систему, она устанавливает свойство globalMessage_dismissed в TRUE и сохраняет элемент. Если пользователь залогинен, то она изменит столбец таблицы, созданный на шаге 5 для соответствующей строки в базе данных. Если пользователь не вошел в систему, она создает куки, таким образом пользователи, которые не вошли в систему, смогут скрыть сообщение.
- Затем она перенаправляет пользователя обратно на страницу где они были, или, если сервер не может предоставить ссылку, домашнюю страницу.
Теперь, когда событие создано, необходимо настроить шаблон, чтобы добавить кнопку сброса.
Изменим шаблон, созданный на шаге 3:
<ips:template parameters="" /> {{if settings.globalMessage_content and !member.globalMessage_dismissed and !isset( cookie.globalMessage_dismissed )}} <div class="ipsMessage ipsMessage_information"> <a href="{url="app=core&module=system§ion=plugins&do=dismissGlobalMessage" csrf="1"}" class="ipsMessage_code ipsType_blendlinks ipsPos_right"><i class="fa fa-times"></i></a></span> {setting="globalMessage_content"} </div> {{endif}}
Шаг 7: Добавление Javascript
Теперь у нас есть полностью функциональный плагин, который отображает сообщение всем пользователям, и которое они могут закрыть. Теперь можно добавить немного улучшений. Можно сделать так, чтобы сообщение закрывалось с помощью AJAX запроса, вместо перезагрузки страницы. Важно добавлять JavaScript только после того как уже готов весь основной функционал, чтобы пользователи, у которых отключен JavaScript, могли использовать ваш плагин, и поисковые системы могли получить доступ к контенту вашего плагина.
Для этого необходимо создать контроллер JavaScript. В директории dev/js в каталоге вашего плагина, создайте файл globalMessageDismiss.js со следующим кодом:
;( function($, _, undefined){
"use strict";
ips.controller.register('plugins.globalMessageDismiss', {
initialize: function () {
this.on( document, 'click', '[data-action="dismiss"]', this.dismiss );
},
dismiss: function (e) {
e.preventDefault();
var url = $( e.currentTarget ).attr('href');
var message = $(this.scope);
ips.getAjax()(url).done(function(){
ips.utils.anim.go( 'fadeOut', message );
}).fail(function(){
window.location = url;
});
}
});
}(jQuery, _));
Этот код выполняет следующее:
- Все, кроме содержания функций initialize и dismiss, требуется для JavaScript контроллера. Строка ips.controller.register указывает имя контроллера.
- Когда элемент с присоединенным JavaScript контроллером подгружается, запускается функция initialize. Лучше всего настроить обработчики событий здесь один раз и обрабатывать события в других функциях. Мы создаем здесь событие чтобы она срабатывала, при щелчке на какие-либо элементы, у которых есть селектор [data-action="dismiss"].
- Функция dismiss предотвращает первоначальное событие которое было задано по умолчанию (переход по щелчку на заданный URL), а затем определяет необходимые переменные (URL-адрес, куда ведет клик по кнопке, и окно сообщения). Затем он посылает AJAX запрос к указанному URL. Если это удается, окно сообщения исчезает, а если не удается, перенаправляет пользователя туда так, как если бы не было никакого JavaScript. При неудачном переходе к первоначальному URL, пользователь увидит фактическую ошибку.
Чтобы это все работало, вам нужно указать, что ваше сообщение должно использовать данный контроллер. В шаблоне, добавьте data-controller="plugins.globalMessageDismiss" к элементу “div”, а data-action="dismiss" к элементу “a”.
Для полноты картины, мы должны несколько скорректировать действия AJAX запроса. Хотя это не обязательно, если этого не сделать то, возможно, что если редирект перенаправит пользователя на страницу с ошибкой, AJAX расценит как неудавшийся запрос. Откройте файл action.php созданный на шаге 6 и измените строку редиректа:
if ( \IPS\Request::i()->isAjax() )
{
\IPS\Output::i()->sendOutput( NULL, 200 );
}
else
{
\IPS\Output::i()->redirect( isset( $_SERVER['HTTP_REFERER'] ) ? $_SERVER['HTTP_REFERER'] : \IPS\Http\Url::internal( '' ) );
}
После это сообщение будет плавно исчезать вместо перезагрузки страницы, при клике на кнопку “закрыть”.
Шаг 8: Загрузка вашего плагина
Поздравляем, вы только что создали свой первый плагин! Теперь можно установить его на другие сайты.