From In-Portal Developers Guide

Revision as of 14:50, 25 December 2008

Работа с шаблонами
Статьи в этой категории
Базовые сведения о тэгах и шаблонах Вывод данных в шаблоне Описание специальных тэгов Особенности работы с тэгами Компиляция шаблонов Ограничение доступа к шаблону

Данная статья открывает собой цикл статей, посвящённых синтаксическому анализатору шаблонов (template parser), использующемуся в платформе.

Синтаксический анализатор применяется для разбора шаблонов (файлов, имеющих расширение ".tpl") и их последующего преобразования в HTML-формат. При этом используется один главный файл PHP-файл ("index.php" на пользовательской части сайта или "admin/index.php" в административной консоли), через который ведётся обработка всех тэгов в шаблонах и пользователю в браузер выдаётся итоговый HTML-документ.

Шаблоны, в свою очередь, используются для разделения бизнес-логики от визуального оформления сайта. Тэги, которые используются в синтаксическом анализаторе ни в коем случае не являются дополнительным языком программирования, т.к. для этого существует PHP.

Синтаксический анализатор обрабатывает только правильно сформированные (well formed) XML тэги из пространства имён inp2. Далее в этой статье будут рассмотрены базовые вопросы, связанные с тэгами и шаблонами, а именно:

• процесс создание нового тэга с нуля;
• параметры тегов и шаблонов;
• область действия параметров;
• примеры и ограничения при работе с тэгами и шаблонами.

Добавление нового тэга

Добавление тэга можно разбить на следующие основные этапы:

• принятие решения о расположении тела тэга в классовой структуре обработчиков тэгов проекта;
• создание нового класса, который будет содержать тело тэга (только, если требуется);
• регистрация нового класса в фабрике классов (только, если на предыдущем этапе создавался класс);
• написание тела тэга в выбранном или созданном на предыдущем этапе обработчике тэгов.

Далее в статье будут описан каждый из выше упомянутых этапов создания тэга.

Расположение тэга

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

Создание обработчика тэгов

Создание обработчика тэгов начинается с создания файла, который в последствии будет содержать класс обработчика тэгов. Согласно правилам наименования файлов, содержащих классы, его название формируется путём замены всех дефисов в названии префикса на подчёркивания и добавления текста "_tp.php" в конец получившейся после этого строки. Для префикса "sample-prefix" название файла обработчика тэгов будет равно "sample_prefix_tp.php". Файл обработчика тэгов должен располагаться в директории, содержащей конфигурационный файл, в котором происходит его регистрация в фабрике классов. Для префикса "sample-prefix" это будет директория "custom/units/sample_prefix".

Далее в созданном ранее файле требуется определить класс обработчика тэгов. Название класса обработчика тэгов формируется из префикса по следующей схеме:

• первая буква каждого слова в префиксе делается заглавной;
• убираются дефисы;
• к результирующей строке добавляется текст "TagProcessor".

Например, если префикс называется "sample-prefix", то класс его обработчика тэгов будет называться "SamplePrefixTagProcessor". Данный класс в свою очередь должен быть наследником класса "kDBTagProcessor":

class SamplePrefixTagProcessor extends kDBTagProcessor {
 
}

Завершающим этапом в создании нового обработчика тэгов является его регистрация в фабрике классов. Класс обработчика тэгов регистрируется при помощи ключа TagProcessorClass в конфигурационном файле того префикса, с которым он будет связан. В данном примере это префикс "sample-prefix". Для регистрации требуется указать название класса обработчика тэгов и файл, в котором этот класс объявлен. Это будет наглядно показано на ниже приведённом примере.

$config = Array (
	'Prefix' => 'sample-prefix',
	'TagProcessorClass' =>	Array ('class' => 'SamplePrefixTagProcessor', 'file' => 'sample_prefix_tp.php', 'build_event' => 'OnBuild'),
);

Не описанный ранее ключ "build_event" используется для задания события, которое будет инициализировать объект. Для классов обработчиков тэгов это всегда событие OnBuild.

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

Добавление тэга в обработчик тэгов

После того, как успешно создан или найден класс обработчика тэгов, можно приступать к созданию метода, результат работы которого и будет выведен на странице, как результат работы нового тэга. Сам метод будет располагаться в классе обработчика тэгов. Согласно правилу именования тэгов каждое слово в названии метода должно начинаться с большой буквы. Также название данного метода может содержать только латинские буквы и цифры. Цифры желательно не использовать.

Синтаксический анализатор (template parser) при вызове метода, связанного с найденным им в шаблоне тэгом также будет передать ассоциативный массив параметров, переданных в сам тэг в качестве первого аргумента метода. Это будет наглядно показано на приведённом ниже примере:

class SamplePrefixTagProcessor extends kDBTagProcessor {
 
	/**
	 * Tag description
	 *
	 * @param Array $params
	 * @return string
	 */ 
	function PrintHelloWorld($params)
	{
		return 'Hello World! Param Value: [' . $params['sample_param'] . ']';
	}
}

На шаблоне вызов тэга выглядит следующим образом:

<inp2:sample-prefix_PrintHelloWorld />

Парные и непарные тэги

Все, обрабатываемые синтаксическим анализатором (template parser) тэги делятся на парные и непарные. Парные тэги от непарных отличаются тем, что они могут использовать заключённое в них содержание по своему усмотрению. Все, объявленные в классах обработчиков тэгов тэги непарные. В свою очередь все парные тэги системные и не подлежат переопределению. В общем виде парные и непарные тэги выглядят так:

непарный тэг:
<inp2:prefix.special_TagName param1="value1" param2="value2"/>
 
парный тэг:
<inp2:prefix_TagName param1="value1" param2="value2">
содержание тэга
</inp2:prefix_TagName>

Для разделения параметров тэга и его самого допускается использование любого количества разделительных символов (whitespace).

Ниже приведены примеры использования нескольких популярных тэгов.

• Непарные тэги:

а) <inp2:m_TemplatesBase module="Custom"/> - путь к папке с файлами темы модуля Custom.
б) <inp2:m_GetConfig var="Site_Name"/> - переменная конфигурации Site_Name.
с) <inp2:st_PageInfo type="meta_title"/> - название текущей страницы.

• Парные тэги:

а) Тэг условия.
<inp2:m_if check="m_Param" name="is_last">
...
</inp2:m_if>
 
б) Тэг определения блочного элемента в шаблоне.
<inp2:m_DefineElement name="menu_block">
	<td><inp2:m_Phrase name="lu_about_us"/></td>
</inp2:m_DefineElement>

Общая форма вызова тэга из шаблона

В общем виде форма вызова тэга на шаблоне имеет вид:

<inp2:prefix[.special]_TagName param1="value1" other_param='value2'/>

<img src="<inp2:m_TemplatesBase module='custom'/>img/spacer.gif" alt=""/>

Пример вызова тэга на шаблоне:

<inp2:test.front_PrintHelloWorld current_datetime="yes" />

Пример функции в классе TestTagProcessor

/**
 * Printing sample text and current date, when additional parameter is given
 *
 * @param Array $params
 * @return string
 */ 
function PrintHelloWorld($params)
{
	// проверка на special
	$ret = $this->Special == 'front' ? 'Hello World Front !' : 'Hello World !';
 
	// проверка установлен ли параметр 'current_datetime'	
	if (array_key_exists('current_datetime', $params) && ($params['current_datetime'] == 'yes')) {
		$ret .= ' ' . adodb_date('m/d/Y H:s');
	}
 
	return $ret;
}

Задание параметров по умолчанию

Параметры по умолчанию позволяют задать значения параметров для парных (блочных) тэгов и для шаблонов на тот случай, если эти тэги или шаблоны будут использоваться без передачи в них всех, используемых в них параметров.

Параметры шаблона по умолчанию

Параметры шаблона по умолчанию задаются вверху шаблона при помощи тэг m_DefaultParam. Если в теле такого шаблона будет использоваться такой параметр, но его значение не будет передано при вызове шаблона, то будет использовано значение по умолчанию. Это будет показано на ниже приведённом примере.

=== include_test.tpl ===
<inp2:m_DefaultParam param1="default_value1" param2="default_value2"/>
 
PARAM: [<inp2:m_Param name="param2"/>]
 
=== index.tpl ===
// выведет PARAM: [default_value2]
<inp2:m_include template="include_test"/>
 
// выведет PARAM: [given_value]
<inp2:m_include template="include_test" param2="given_value"/>

Параметры парного тэга по умолчанию

Параметры по умолчанию для парных тэгов задаются при их определении. Это будет показано на ниже приведённом примере.

<!-- определение блока -->
<inp2:m_DefineElement name="sample_element" as_label="" currency="USD">
	[<inp2:m_Param name="as_label"/> - <inp2:m_Param name="currency"/>]
</inp2:m_DefineElement>
 
<!-- использование блока передавая ему параметры -->
<inp2:m_RenderElement name="sample_element" as_label="1"/> // даст [1 - USD]
 
<!-- использование блока не передавая ему параметры -->
<inp2:m_RenderElement name="sample_element"/> // даст [ - USD]

Расположение шаблонов

Все шаблоны делятся на 2 группы по месту их применения:

• административная консоль;
• пользовательская часть сайта.

Далее будут описаны особенности расположения и использования шаблонов из обеих выше упомянутых групп.

Шаблоны в административной консоли

В административной консоли все шаблоны разделены по модулям. В каждом модуле в свою очередь есть директория "admin_templates", в которой содержатся все его шаблоны. Например если модуль называется "proj-base", то его шаблоны буду лежать в директории "proj-base/admin_templates". Под директорией "admin_templates" допускается создание других директорий для логической группировки шаблонов в пределах одного модуля. При использовании шаблона всегда следует писать название модуля перед названием шаблона, напр. "proj-base/users/users_list", а не просто "users/users_list". Если требуется подключить (include) оригинальную версию шаблона (если шаблон был подменён через ReplacementTemplates) то нужно написать "orginal:" перед названием шаблона, напр. "original:path/to/replaced/template".

Название модуля писать не обязательно только для шаблонов из директории "core/admin_templates".

В проектах разрешается создавать и изменять только шаблоны административной консоли, находящиеся в папке "custom/admin_templates", т.е. принадлежащие модулю "custom".

Шаблоны на пользовательской части сайта

На пользовательской части сайта все шаблоны разделены по темам (styles). Для каждой темы существует директория вида "themes/<theme_name>", где "<theme_name>" это значение поля Name конкретной темы. Все темы задаются в секции "Configuration -> Themes". Обычно достаточно создать папку с темой и шаблоны в ней и нажать кнопку "Rebuild Theme Files" на панели инструментов в списке тем для того, чтобы запись в таблице Theme создалась автоматически. Например, если путь к шаблону относительно корневой директории проекта "themes/theme_test/testing/sample_template.tpl", то для использования этого шаблона нужно указывать "testing/sample_template". При этом шаблон будет искаться в той теме сайта, которая указана в ссылке на сайт.

В проектах на платформе обычно используется только одна тема, с названием "theme_<project_name>", напр. "theme_fuse".

Область действия параметров

По умолчанию параметры переданные в блок или шаблон будут видны только в нём самом. Если требуется, передать значение индивидуального параметра в следующий блок или шаблон, то это можно сделать при помощи следующей конструкции param_name="$param_name". Если требуется передать все параметры из шаблона или блока в следующий шаблон, то это можно сделать указав параметр "pass_params". Все выше описанные варианты будут показаны на ниже приведённом примере.

== main.tpl ==
<inp2:m_DefaultParam main_param="sample_value" main_param2="test"/> <!-- Установка значения по умолчанию для параметров "main_param" и "main_param2". -->
 
<inp2:m_DefineElement name="sample_element">
	main param: [<inp2:m_Param name="main_param"/>]
	main param2: [<inp2:m_Param name="main_param2"/>]
</inp2:m_DefineElement>
 
<!-- Значение всех параметров из этого шаблона не будут доступны в подключаемом шаблоне и используемом блоке. -->
<inp2:m_include template="include_test"/>
<inp2:m_RenderElement name="sample_element"/>
 
<!-- Только значение параметра "main_param" будет доступно в подключаемом шаблоне и используемом блоке. -->
<inp2:m_include template="include_test" main_param="$main_param"/>
<inp2:m_RenderElement name="sample_element" main_param="$main_param"/>
 
<!-- Только значение параметра "main_param2", но под именем "main_param" будет доступно в подключаемом шаблоне и используемом блоке. -->
<inp2:m_include template="include_test" main_param="$main_param2"/>
<inp2:m_RenderElement name="sample_element" main_param="$main_param2"/>
 
<!-- Значения всех параметров этого шаблона будут доступны в подключаемом шаблоне и используемом блоке. -->
<inp2:m_include template="include_test" pass_params="true"/>
<inp2:m_RenderElement name="sample_element" pass_params="true"/>
 
== include_test.tpl ==
main param: [<inp2:m_Param name="main_param"/>]
main param2: [<inp2:m_Param name="main_param2"/>]

Назначения имён параметрам

Название параметра тэга, в котором передаётся название блока должно называться "render_as". В случае, когда в тэг передаётся несколько названий блоков, то названия параметров, в которых передаются названия блоков должны заканчиваться на "_render_as", напр. "user_render_as". Это будет показано на ниже приведённом примере.

<inp2:sample-prefix_PrintList render_as="sample_element" more_render_as="more_element"/>

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

Значение параметров по умолчанию

Если не задавать значения по умолчанию для необязательных параметров шаблона или блока, то при их (шаблона или блока) использовании будут выдаваться php warnings, что есть не очень хорошо. Для нахождения мест в шаблоне, где не заданы значения параметров по умолчанию лучше всего подходит отладчик.