Руководство по синтаксису шаблонов.

Это краткое описание того, как изменились шаблоны в phpBB3 по сравнению с phpBB2.

[url=http://www.phpbbguru.net/kb/styling/template-syntax-tutorial/]Руководство по синтаксису шаблонов[/url]

Класс шаблонов (template) сам по себе не сильно изменился по сравнению с phpBB2. Поэтому, если вы уже знакомы с API, вы можете смело пропустить данный материал. Однако следует заметить, что благодаря улучшению синтаксиса языка, такого как внедрение условных операторов, автоматического определения языковых строковых переменных и т.д., появилась возможность избежать избыточного объявления данных и переноса части логики в файлы шаблонов.

Переменные.

Примечание: Для передачи данных в шаблоны используются переменные шаблона. По соглашению имена переменных всегда в верхнем регистре. Переменные, используемые для передачи данных в шаблоны, заключаются в фигурные скобки. Остальные переменные, например в условиях, используются в шаблонах непосредственно.

Переменные стиля.

Переменные, связанные со стилем, имеют префикс "T_". Они объявляются, как правило, в основном коде phpBB3.

Есть ряд переменных, установленных в includes/functions.php , которые являются общими для всех шаблонов и могут быть весьма полезны для авторских изменений стиля.

Переменная шаблона	Описание	Пример
T_THEME_PATH	Путь к папке файлов темы текущего стиля (css файлам)	./styles/prosilver/theme
T_TEMPLATE_PATH	Путь к папке файлов шаблонов текущего стиля	./styles/prosilver/template
T_IMAGESET_PATH	Путь к папке файлов набора изображений текущего стиля (иконкам)	./styles/prosilver/imageset
T_IMAGESET_LANG_PATH	Путь к папке изображений, зависимых от языка, текущего стиля (кнопки)	./styles/prosilver/imageset/en
T_IMAGES_PATH	Путь к папке изображений	./images/
T_SMILIES_PATH	Путь к папке смайлов	./images/smilies/
T_AVATAR_PATH	Путь к папке аватар	./images/avatars/upload/

Языковые переменные.

Языковые переменные определяются автоматически.

Вы можете использовать их в шаблонах, предваряя их имя префиксом "L_": {L_EXAMPLE_LANG_VAR}

Языковые переменные имеют вид "L_LANGUAGE_KEY", где "LANGUAGE_KEY" является ключом существующей записи в языковом файле. Эти переменные назначаются автоматически.

Аналогично языковые переменные для использования в JavaScript: "LA_LANGUAGE_KEY".

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

Для этого используется метод assign_var.

Назначение единичной переменной:

$template->assign_var('FOO', $foo);

Назначение массива переменных:

$template->assign_vars(array(
	'FOO' => $foo,
	'BAR' => $bar,
	'BAZ' => $baz
	));

Блоки.

Блоки используются для объявления некоторого числа однотипных объектов, например тем и постов ("циклический вывод").

while ($row = $db->sql_fetchrow($result))
{
	$template->assign_block_vars('loopname', array(
		'FOO' => $row['foo'],
		'BAR' => $row['bar']
	));
}

Вложенные циклы:

while ($topic = $db->sql_fetchrow($result))
{
	$template->assign_block_vars('topic', array(
		'TOPIC_ID' => $topic['topic_id']
	));

	while ($post = $db->sql_fetchrow($result))
	{
		$template->assign_block_vars('topic.post', array(
			'POST_ID' => $post['post_id']
		));
	}
}

Имя файла.

Теперь файлы шаблонов имеют расширение ".html" вместо ".tpl", что было сделано просто для использования подсветки синтаксиса в редакторах.

Элементы синтаксиса.

Переменные.

Основной синтаксис для простых (не блочных) переменных остался таким же, как и в phpBB2, то есть переменные принимают вид {X_YYYYY} с данными, передаваемыми из источника (PHP-файла). Отметим, что в отличие от phpBB2 большинство строковых языковых переменных не передаются из источника в шаблон. Когда языковая переменная найдена {L_YYYYYY} phpBB3 прежде всего смотрит, есть ли подобная переменная {'YYYYYY' => 'что-то там...',} в языковых файлах. Если это так, он её использует. Это значительно уменьшает необходимость присвоения множества новых языковых переменных при написании модов.

Блоки.

Базовый уровень цикла остался прежним и имеет форму:

<!-- BEGIN loopname -->
markup, {loopname.X_YYYYY}, etc.
<!-- END loopname -->

Однако теперь он имеет некоторые дополнения. Прежде всего вы можете задать начальную и конечную точку цикла. Например:

<!-- BEGIN loopname(2) -->
markup
<!-- END loopname -->

Цикл начнется с третьего вхождения (помните, что отсчет начинается с нуля). Дополнения этому являются:

loopname(2,4): Старт с третьего значения, конец на четвертом.
loopname(-4): Старт с четвертого с конца значения.
loopname(2,-4): Старт с третьего значения, конец на четвертом с конца.

Помните, что метод исчисления (индексации) может измениться Подмигивает

Следующее дополнение это BEGINELSE:

<!-- BEGIN loop -->
markup
<!-- BEGINELSE -->
markup
<!-- END loop -->

Это приведет к выводу содержимого между BEGINELSE и END, если цикл не будет иметь значений. Например, при выводе пустых форумов без тем. В нектором смысле это замена существующим переключателям (switch_).

Вы также можете проверить имеет ли ваш цикл значения (не пустой ли он), подобно использованию sizeof() в PHP:

<!-- IF .loopname -->
<!-- BEGIN loopname -->
markup, {loopname.X_YYYYY}, etc.
<!-- END loopname -->
<!-- ENDIF -->

Это имеет смысл, если вы например хотите предотвратить вывод пустого тега <select> , который не будет валидным в XHTML.

Включенные файлы шаблонов.

Возможность назначать переменной отдельный шаблон, существовавшая в phpBB2, например, для вывода выпадающего меню jumpbox, больше не используется в phpBB3. Вместо этого (возможно лучше, возможно нет, но определенно более гибко) используется включение INCLUDE в простой форме:

<!-- INCLUDE filename -->

Вы можете обратить внимание, что в phpBB3 шаблоны начинаются с включения overall_header.html или simple_header.html и т.д. В phpBB2 контроль вывода заголовка (header) полностью находился в коде PHP. В phpBB3 автор стиля может выводить всё, что ему угодно. Вы можете создать новые шаблоны, отличные от входящих в стандартный набор, и включать их так как, вам удобно. Это может быть весьма удобным для вывода общего меню, или нескольких. При этом нет необходимости менять файлы кода, как в phpBB2.

PHP.

Весьма спорное решение - возможность включения PHP-кода в шаблоны. Это достигается путем использования следующих тегов:

<!-- PHP -->
echo "hello!";
<!-- ENDPHP -->

Вы также можете подключить внешний PHP-файл:

<!-- INCLUDEPHP somefile.php -->

Помните, что путь к включенному PHP-файлу указывается от корневой папки (root), а не от папки шаблонов!
Примечание: наиболее правильно со стороны разработчиков стилей не использовать включение кода PHP. Эта возможность была предусмотрена для размещения баннеров (кода баннеров) конечными пользователями без необходимости модифицирования множества файлов, как в phpBB2. По умолчанию использование PHP в шаблонах запрещено и администратору необходимо специально активировать эту возможность.

Условные / Управляющие структуры.

Наиболее существенным дополнением в phpBB3 являются условия или управляющие конструкции, типа: "Если выполняется что-то, то сделать следующее". Система весьма напоминает Smarty. Сначала она может немного смутить пользователей, но обладает огромным потенциалом и большой гибкостью. В наиболее простом виде она представляет собой следующую форму:

<!-- IF expr -->
markup
<!-- ENDIF -->

Условие (expr) может принимать много форм, например:

<!-- IF loop.S_ROW_COUNT is even -->
markup
<!-- ENDIF -->

Это означает вывод содержимого (markup) если значение переменной S_ROW_COUNT четное в текущей итерации цикла (то есть условие expr имеет значение истины TRUE). Вы можете использовать различные методы для описания условий сравнения (стандартные и текстовые, указанные ниже в квадратных скобках):

== [eq]
!= [neq, ne]
<> (аналогично !=)
!== (не эквивалентно по значению и типу)
=== (эквивалентно по значению и типу)
> [gt]
< [lt]
>= [gte]
<= [lte]
&& [and]
|| [or]
% [mod]
! [not]
+
-
*
/
<< (побитовый сдвиг влево)
>> (побитовый сдвиг вправо)
| (логическое ИЛИ)
^ (логическое XOR)
& (логическое И)
~ (логическое отрицание)
is (может использоваться для присоединения к операции сравнения)
even (чётное)
odd (нечётное)

Кроме простого сравнения, используя условия (IF) вы можете также последовательность сравнений:

<!-- IF expr1 -->
markup
<!-- ELSEIF expr2 -->
markup
.
.
.
<!-- ELSEIF exprN -->
markup
<!-- ELSE -->
markup
<!-- ENDIF -->

Каждое условие будет последовательно проверено на истинность и соответствующее содержимое быдет выведено при нахождении необходимого значения. Не стоит всегда использовать ELSEIF, если достаточно ELSE для значения "все остальное".

Так что вы можете делать со всеми этими дополнениями? Возьмем, к примеру, окраску строк на странице просмотра форума. В phpBB2 цвета строки были предварительно объявлены в файле-источнике (PHP) как row color1, row color2 или row class1, row class2. В phpBB3 эта операция переехала в шаблон, и может выглядеть немного сложнее на первый взгляд, но не слишком сложно:

<table>
	<!-- IF loop.S_ROW_COUNT is even -->
	<tr class="row1">
	<!-- ELSE -->
	<tr class="row2">
	<!-- ENDIF -->
		<td>HELLO!</td>
	</tr>
</table>

Это приводит к использованию class row1 для чётных строк и class row2 для остальных. Большое дело, скажите вы, phpBB2 тоже делал это! Действительно, но сейчас вы не ограничены использование только class row1 или row2 ... Вы можете любой другой class, определить собственный стиль и т.п. К тому же вы не ограничены двумя цветами и т.д.

<table>
	<!-- IF loop.S_ROW_COUNT > 10 -->
	<tr bgcolor="#FF0000">
	<!-- ELSEIF loop.S_ROW_COUNT > 5 -->
	<tr bgcolor="#00FF00">
	<!-- ELSEIF loop.S_ROW_COUNT > 2 -->
	<tr bgcolor="#0000FF">
	<!-- ELSE -->
	<tr bgcolor="#FF00FF">
	<!-- ENDIF -->
		<td>hello!</td>
	</tr>
</table>

Это пример вывода фиолетового цвета для первых двух строк, синего для строк 3 - 5, зеленого для строк 6 - 9, красного для остальных. Так можно построить градиент, например.

Что ещё можно сделать? Например, с помощью условия проверить авторизацию пользователя.

<!-- IF S_USER_LOGGED_IN -->
markup
<!-- ENDIF -->

Это заменяет существующий в phpBB2 метод использования нулевого размера массива и BEGIN/END.

Переменные пользователя.

Вы также можете легко определить переменные (логические или типа int) внутри шаблона. Это может быть полезным, например, если вы хотите организовать последовательный множественный вывод содержимого:

<!-- IF expr1 -->
<!-- DEFINE $COLSPAN = 3 -->
<!-- ELSEIF expr2 -->
<!-- DEFINE $COLSPAN = 4 -->
<!-- ELSE -->
<!-- DEFINE $COLSPAN = 1 -->
<!-- ENDIF -->

...

<tr><td colspan="{$COLSPAN}">...</td></tr>
<tr><rd colspan="{$COLSPAN}">...</td></tr>

Примечание: ключевое слово DEFINE имеет несколько ограничений:

- Должен быть ровно один пробел до и после знака сравнения "=".
- При определении строки, вы должны использовать одинарные кавычки.

Другими словами:

 //Правильно
 //Неправильно
 //Неправильно

 //Правильно
 //Неправильно

Переменные пользователя могут быть очищены:



По соглашению для переменных шаблонов используются, кроме указанных выше, следующие обозначения:
- Переменные, содержащие URL-адреса с префиксом "U_".
- Переменные для использования в управляющих структурах или других формах - префикс "S_".
- При отображении переменных префикс на экран не выводится.

Переменные.

Переменные стиля.

Языковые переменные.

Назначение единичной переменной:

Назначение массива переменных:

Блоки.

Вложенные циклы:

Имя файла.

Элементы синтаксиса.

Переменные.

Блоки.

Включенные файлы шаблонов.

PHP.

Условные / Управляющие структуры.

Переменные пользователя.

Ссылка на эту страницу