Поиск сообщества

Часто бывает полезно преобразовать исходные значения, для этого в IPS4 существуют плагины шаблонов. Плагины шаблонов принимают значения и, при необходимости, некоторые аргументы и отдают преобразованное значения. Синтаксис плагинов шаблонов: {pluginkey="<value>" argument="..."} Значение может быть простой строкой или переменной, полученной откуда-либо. Плагины шаблонов всегда могут быть использованы в шаблонах, но некоторые из них также могут использоваться в CSS файлах. Именно они указаны ниже. Доступные плагины {advertisement="$location"} HTML для указанное местоположения рекламы. Параметры $location - допустимое расположение рекламного блока. {datetime="$timestamp" dateonly="[boolean]" norelative="[boolean]" lowercase="[boolean]" short="[boolean]"}Отображает время, отформатированное в соответствии с локалью пользователя Параметры $timestamp - временная метка (timestamp), преобразованная в дату; dateonly - отображает только дату (без времени); norelative - по умолчанию, будет использоваться относительное время (например 5 часов назад). Чтобы всегда показывалось абсолютная дата/время, установите значение в true; lowercase - по умолчанию, строчка даты будет начинаться с заглавной буквы, где это необходимо (например, Вчера, 11:49). установка параметра в true приведёт к нижнему регистру, для использования в предложении; short - использует очень короткий формат даты (для мобильных устройств). {expression="$expression" raw="[boolean]"} Позволяет вставлять результат произвольных PHP выражений в шаблоны. Выводится результат выражения. Может быть использован в CSS файлах. Параметры $expression - действительное выражение PHP, которое обеспечивает вывод чего-то; raw - по умолчанию, результат выражения экранирован. Установка данного параметра в значение true выводит исходный результат. Будьте осторожны! Это может представлять угрозу для безопасности. {file="$file" extension="[string]"} Выводит URL адрес файла, хранимого классом обработки файлов IPS4. Может быть использован в CSS файлах. Параметры $file - любой экземпляр класса \IPS\File, или строка, представляющая хранимый URL адрес файла; extension - расширение хранения файлов, используемое хранения оригинального файла, например calendar_Events. Если не указано, предполагается core_Attachment. {filesize="$sizeInBytes" decimal="[boolean]"} Форматирует указанный filesize и выводит соответствующую удобочитаемую форму. Параметры $sizeInBytes - целое число, представляющее размер файла в байтах, которое должно быть отформатировано; decimal - должно ли filesize быть рассмотренным в КБ (то есть 1кб = 1024 байт) или 1 = 1000. Все значения всегда округляются до одного знака после запятой. {insert="$filename"} Включает файл PHP скрипта. Параметры $filename - Название файла PHP скрипта для вставки. Вывод файла буферизируется и отображается. {lang="$languageKey" sprintf="[string]" htmlsprintf="[string]" pluralize="[string]" wordbreak="[boolean]" ucfirst="[boolean]"} Вставляет фразу из языковой системы в выбранном пользователем языке. Параметры $languageKey - ключ языковой фразы для вставки; sprintf - разделённый запятыми список значений для замены в языковой строке. Эти значения HTML экранизированы; htmlsprintf - разделённый запятыми список значений для замены в языковой строке. Эти значение не HTML экранизированы. Будьте осторожны! pluralize - разделённый запятыми список значений для передачи любых плюрализационных выражений в языковую строку; wordbreak - если true, добавляет теги <wbr> к возвращаемой строке для предотвращения строк, нарушающих ширину страницы; ucfirst - определяет, должен ли быть первый символ строки в верхнем регистре. {member="$propertyToDisplay" id="[integer]" group="[boolean]" raw="[boolean]"} Выводит свойство или результат метода, вызываемого в объекте пользователя. Параметры $propertyToDisplay - Одно из свойств или методов, доступных в объекте пользователя. Например: link() или name. id - ID пользователя для загрузки и отображения. Если не указано, используется текущий пользователь. group - Если true, данный тег работает вместо группы пользователя (и поэтому $propertyToDisplay должен быть свойств или методов группы). raw - по умолчанию, возвращённый вывод HTML экранирован. Установка этого параметра в true подразумевает, что вывод не будет экранирован. Будьте осторожны с этим! {number="$number"} Форматирует число согласно локали пользователя (например, с помощью запятых или периодов). Параметры $number - число для форматирования. {prefix="$CSSPropertyName" value="[string]"} Короткий тег, который подставляет префикс к переданному CSS свойству. Может быть использован в CSS файлах. Параметры $CSSPropertyName - название свойства для префикса. Поддерживаемые свойства: transition, transform, animation, animation-name, animation-duration, animation-fill-mode, animation-timing-function, user-select, box-sizing, background-size. value - значение CSS свойства. {request="$requestParameter" raw="[boolean]"} Вставляет значение параметра запроса. Параметры $requestParameter - параметр из объекта запроса для вставки; raw - по умолчанию, возвращаемое значение HTML экранировано. Если этот параметр установлен в true, вывод не будет HTML экранирован. Будьте осторожны с этим! {resource="$path" app="[string]" location="[string]" noprotocol="[boolean]"} Возвращает абсолютный URL адрес указанного ресурса. Может быть использован в CSS файлах. Параметры $path - относительный путь к запрашиваемому ресурсу (пусть относительно директории /resource текущей темы); app - приложение, к которому принадлежит ресурс; location - Местоположение (front/admin/global); noprotocol - делает результирующий URL адрес без протокола (то есть не включает http:// или https:// в начале, может быть полезен для ресурсов, которые не могут быть загружены по http или https протоколу). {setting="$settingKey" escape="[boolean]"} Вставляет значение настройки системы. Может быть использован в CSS файлах. Параметры $settingKey - ключ настройки для вставки; escape - по умолчанию выводится исходное значение. Если вам нужно получить HTML экранированное значение, передайте true для этого параметра.

Поскольку редактор в IPS4 использует CKEditor, вам доступен полный набор плагинов для установки. Если есть функция редактора, которую вы хотели бы иметь, проверьте репозиторий плагинов и поищите уже готовый доступный плагин. В настоящее время поддерживаются плагины, которые только добавляют кнопку в панель инструментов CKEditor. Пожалуйста, не устанавливайте плагины, которые добавляют другие виды функциональных возможностей или которые могут вызвать проблемы с вашим сообществом. Установка CKEditor плагина Для начала перейдите на страницу Кастомизация > Редактор > Тулбары в вашем админцентре. Нажмите кнопку "Добавить кнопку" и во всплывающем окне выберите вкладку Плагин CKEditor. Устанавливаемый плагин должен быть совместим с версией редактора CKEditor, которая используется на текущей версии Invision Community. Текущая версия вашего IPS4 отображается здесь же - во всплывающем окне, поэтому вы можете проверить совместимость плагина. Далее укажите zip файл скачанного вами плагина и сохраните форму. Если плагин установился успешно, вы увидите новую кнопку в тулбаре "Кнопки не в редакторе" снизу страницы. Теперь вы можете перенести его в ваш активный тулбар и управлять его настройками доступа. Если плагин не установился Случается так, что плагин не может установиться, это происходит потому, что: Он не добавляет кнопку В настоящее время поддерживаются только плагины, которые добавляют кнопки в редактор, другие виды плагинов не поддерживаются редактором IPS4. Он не поддерживает установленную версию CKEditor Убедитесь, что плагин, который вы устанавливаете, совместим с версией вашего редактора CKEditor. Директория редактора CKEditor не имеет разрешения на запись Директория /applications/core/interface/ckeditor/ckeditor/plugins должна быть доступна для записи (CHMOD 777) для возможности установки в неё плагинов.

Это руководство продемонстрирует как шаг за шагом создать простой в использовании плагин. Здесь вам будет показано, как создать плагин, отображающий сообщение в верхней части каждой страницы форума. Шаг 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&section=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: Загрузка вашего плагина Поздравляем, вы только что создали свой первый плагин! Теперь можно установить его на другие сайты. Global_Message.xml

“Плагины” позволяют разработчикам изменять или расширять функциональность приложений в Invision Community. Это руководство подробно описывает различные функции, доступные при использовании “Плагинов”. Описание многих функций доступно в Plugin Developer Center - чтобы получить доступ к нему нужно активировать режим разработчика. После того как будет активирован режим разработчика, кнопка "Создать плагин" появится в админпанели в разделе Систем --> Возможности --> Плагины. Используйте ее, чтобы создать свой плагин, после чего вы будете перенаправлены в Plugin Developer Center. Назначение плагинов Плагины отличаются от приложений тем, что они предназначены для расширения функционала существующих приложений. Есть хуки кода и хуки тем, которые позволяют подключиться к существующему коду в других приложениях и манипулировать им - отличный вариант для расширения функционала. Если вы поняли что хотите добавить качественно отличающиеся функции которые не пересекаются с существующими, вы можете создать новое приложение. Распространение плагинов В режиме разработчика ваши плагины создаются в виде файлов в файловой системе. Когда ваш плагин готов к публикации, Invision Community скомпилирует его в виде отдельного XML файла, которым можно поделиться и который может быть установлен другими, например, в нашем файловом архиве или официальном IPS Marketplace. Просто скачайте файл XML из Plugin Developer Center.

В соседней инструкции мы рассмотрели процесс установки нового приложения в IPS4, установка плагина ни чем не отличается от установки приложения. Для установки плагина в IPS4 вам нужно посетить страницу плагинов Система > Возможности > Плагины в ваешм админцентре. Здесь вы можете нажать кнопку "Установить новый плагин" и указать xml файл устанавливаемого плагина. Для обновления плагина воспользуйтесь соответствующей кнопкой: Всегда следуйте рекомендациям разработчиков сторонних продуктов для установки их плагинов и приложений.

В Invision Community 4 реализовано два типа модификаций - плагины и приложения. Плагины, как правило, состоят из одного установочного xml файла и позволяют изменить или дополнять функционал сайта. Приложения же имеют несколько десятков файлов (зависит от функционала приложения) и устанавливаются совсем другим способом. Подробнее про установку приложений в Invision Community 4 читайте в соответствующей статье. Установка плагина Установка плагина на сайт осуществляется только из админцентра. Зайдите в него и перейдите по вкладкам: Система --> Возможности --> Плагины. Нажмите на кнопку 'Установить новый плагин'. Перед вами откроется окно с возможностью выбора xml файла плагина. Укажите файл и дождитесь окончания установки. После окончания процесса установки в списке появится устанавливаемый плагин, а справа от его названия кнопки с действиями, которыми мы можем управлять плагином: Настроить (если плагин с настройками)УдалитьЗагрузить новую версиюИнформация о плагине