керівництво по синтаксису шаблонів

Відповісти

Topic author
Vpoltave
Адміністратор
Адміністратор
Повідомлень: 710
З нами з: 16 серпня 2013 23:18

керівництво по синтаксису шаблонів

#1

Повідомлення Vpoltave »

Це короткий опис того , як змінилися шаблони в phpBB3 порівняно з phpBB2 .
 
Клас шаблонів ( 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 має кілька обмежень:

- Повинен бути рівно один пробіл до і після знаку порівняння "=".
- При визначенні рядка, ви повинні використовувати одинарні лапки.

Іншими словами:

<!-- DEFINE $COLSPAN = 3 --> //Правильно
<!-- DEFINE $COLSPAN=3 --> //Неправильно
<!-- DEFINE $COLSPAN = 3 --> //Неправильно


<!-- DEFINE $CLASS = 'class1' --> //Правильно
<!-- DEFINE $CLASS = "class1" --> //Неправильно
Змінні користувача можуть бути очищені:
<!-- UNDEFINE $COLSPAN -->
За угодою для змінних шаблонів використовуються, крім зазначених вище, такі позначення:
- Змінні, що містять URL-адреси з префіксом "U_".
- Змінні для використання в керуючих структурах або інших формах - префікс "S_".
- При відображенні змінних префікс на екран не виводиться.


Відповісти