-
В Invision Community шаблоны являются "прямого вида", то есть как данные на экран отображаются те же, что и представлены в шаблоне. Таким образом, основной HTML, который находится в шаблоне в оригинальном виде отправляется в браузер. В комплексном приложении нам необходимо принимать решение о том, что будет отображено.
Эти решения могут быть потенциально сделаны в PHP бэкэнде, но это не подходит в большинстве случаев; бэкэнд должен быть ориентирован на обработку данных, в то время как шаблоны контролируют отображение данных пользователю.
HTML логика позволяет нам принимать эти решения в наших шаблонах. То есть смешивая стандартный HTML код с некоторыми специальными тегами и операторами управления данными, большинство из которых очень похожи на PHP.
Какие еще особенности есть у шаблонов?
В одном шаблоне мы можем иметь логику, отображающую определённый HTML код в зависимости от выполнения определённого условия. Мы также можем создавать циклы данных, уменьшая повторы. К тому же в шаблонах можно использовать специальные теги, которые отображают плагины, преобразовывая их данные (например отображение даты из timestamp).
Основной синтаксис
Существует три основных типа синтаксиса, каждому из которых мы посвятим отдельную инструкцию.
Логические теги
Обрамляются двойными фигурными скобками. Контролируют поток данных в шаблоне. В этих тегах выражения могут быть любыми PHP выражениями. Например:
/* Основная структура */
{{if $condition}} ... {{else}} ... {{endif}}
/* Примеры других выражений */
{{if !$condition}}
{{if ( $color == 'green' && $size == 'big' ) || $condition}}
{{if count( $value ) > 2}}
Переменные
Заключаются в одинарные фигурные скобки. Выводят значения, переданные в шаблон (или значения из других источников, например циклов).
{$value}
Данные из плагинов
Передают данные через специальный плагин.
{pluginName="value"}
-
Как уже упоминалось в ознакомительной стать - Введение в синтаксис шаблонов, любые PHP выражения могут быть использованы в тегах HTML логики. Вы часто будете проверять выполняется ли выражение или нет:
{{if $value}} ... {{endif}}
..но есть и множество других возможностей.
Вы также можете использовать простые PHP функции в ваших выражениях. Например, вам может понадобиться условие, если массив имеет какие-либо элементы, то... , поэтому PHP функция count будет весьма кстати:
{{if count( $items ) > 0}} ... {{endif}}
Обратитесь к полной документации PHP для получения дополнительной информации.
Получение значений из IPS4
Вам может быть понадобится необходимость сравнить значения в программном обеспечении в ваших выражениях. Например, является ли включённой настройка, или имеет ли текущий пользователь ID.
Вы можете использоваться стандартный PHP подход для получения этих значений, IPS4 содержит некоторые сокращённые "константы", которые вы можете использовать для упрощения своей логики. Они используются следующим образом:
{{if settings.reputation_enabled}} ... {{endif}}
Этот короткий тег становится расширенным своим эквивалентом PHP, то есть это даёт вам доступ ко всем доступным методам и свойствам объекта.
Доступные теги:
request
Преобразует в \IPS\Request::i().
Доступ к переменным запроса, например
{{if request.some_param}}
member
Преобразует в \IPS\Member::loggedIn().
Объект текущего пользователя, например
{{if member.language()->isrtl}}
settings
Преобразует в \IPS\Settings::i().
Получение значений настроек системы (по ключу настройки), например
{{if settings.auto_polling_enabled}}
output
Преобразует в \IPS\Output::i().
Объект отображения, содержащий методы/свойства, используемые системой для отображения контента, например
{{if count( output.contextualSearchOptions )}}
theme
Преобразует в \IPS\Theme::i()->settings.
Доступ к настройкам темы, доступных в текущей теме, например
{{if theme.sidebar_position == 'right'}}
cookie
Преобразует в \IPS\\Request::i()->cookie.
Доступ к объекту cookie, например
{{if isset( cookie.hasJS )}}
Обратитесь к документации PHP фреймворка для получения полного списка свойств и методов, доступных для каждого класса.
-
Самая основаная логика проверки является if/else. Это позволяет вам размещать HTML при выполнении определённого условия, или другого HTML кода, если условие не выполнено.
Синтаксис прост:
{{if [expression]}}
HTML код отображается, если выражение истинно
{{else}}
HTML код отображается, если выражение не истинно
{{endif}}
Также применим тег elseif, который позволяет вам указать другие условия, если предыдущее условие не совпало.
{{if [expression]}}
HTML для отображения, если выражение истинно
{{elseif [expression]}}
HTML для отображения, если выражение истинно
{{else}}
HTML для отображения, если предыдущие два выражение не были истенными
{{endif}}
-
Стандартные PHP циклы поддерживаются как HTML теги логики.
Foreach
{{foreach [expression]}}
...
{{endforeach}}
Выражение это всё, что поддерживает PHP поддерживает в цикле. Переменные, которые определяет цикл, доступны в теле цикла:
<ul>
{{foreach $arrayOfItems as $id => $item}}
<li>{$id}: {$item}</li>
{{endforeach}}
</ul>
For
{{for [expression]}}
...
{{endfor}}
Например:
<ul>
{{for $i = 0; $i < count( $arrayOfItems ); $i++}}
<li>{$i}</li>
{{endfor}}
</ul>
Break и continue
Если вам нужно прервать или продолжить выполнение цикла, вы можете использовать соответствующие управляющие конструкции в PHP. Пример использования break:
{{foreach $arrayOfItems as $id => $item}}
{{if $id > 15}}
{{break;}}
{{endif}}
{{endforeach}}
-
Каждый шаблон может иметь собственные переменные, переданные в него PHP кодом бэкэнда, и эти переменные могут быть использованы в шаблоне для управлением его отображения. Обратитесь в нашим инструкциям Редактор шаблонов или Использование Режима дизайнера (в зависимости от вашего предпочтения), чтобы выяснить, как определить какие переменные доступны в каждом шаблоне.
Вы также можете получить доступ к различным объектам, созданным PHP фреймворком IPS4.
Переменные экранированы
Важно отметить, что по умолчанию все значения переменных HTML экранированы при выводе их в шаблонах. Это сделано в целях безопасности и гарантирует, что вы случайно не отобразили какой-нибудь вредоносный HTML код, который затем обработается браузером и отобразится пользователю. Если переменная $value содержит:
<strong>Пример</strong>
В шаблоне вывод будет выглядеть так:
Значение переменной: {$value}
После обработки будет так:
Значение переменной: <strong>Пример</strong>
Игнорирование экранизации
Конечно бывают ситуации, когда вы хотите отобразить исходный HTML код, не экранизированный. Для этого вы можете воспользоваться модификатором 'raw' для переменной, вот как он применяется:
Значение переменной: {$value|raw}
Использование данного модификатора для непроверенного контента может привести к проблемам с безопасностью. Контент, приходящий от редактора CKEditor безопасен для отображения с данным модификатором.
-
Часто бывает полезно преобразовать исходные значения, для этого в 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 для этого параметра.
-
Вы можете использовать произвольный PHP код в ваших шаблонах. Как правило это не рекомендуется делать, но, в некоторых ситуациях, является необходимым. Обратите внимание, шаблоны также поддерживают специальный тег выражений; рассмотрите вопрос использования тега, нежели произвольного PHP кода.
Для использования PHP кода, вы должны заключить его в двойные фигурные скобки:
{{$myVar = 0;}}
Не забудьте указать точку с запятой в конце вашего выражения.
Этот синтаксис применим только для одностроковых выражений. Если вы хотите вставить более массивный блок, каждая строка должна быть заключена в свои собственные фигурные скобки.
Примечание: шаблоны используют буферизацию отображения; попытки выполнить функции echo, print_r или подобные в середине шаблона может вызвать ошибки. Если вы хотите сделать это, мы рекомендуем использовать с выражением {{exit;}} для завершения скрипта.