From In-Portal Developers Guide

Revision as of 20:20, 13 March 2009

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

This is an introductory article in a series of articles describing the In-Portal CMS template parser.

The template parser parses templates (files with the ".tpl" file extension) and renders them in HTML. For this the system uses one main PHP file ("index.php" on the front end website and "admin/index.php" in the administrative console), through which all tags are processed, to output HTML to the browser.

Templates are used for separating business logic from the visual design of the site. You will not find any files in In-Portal CMS containing PHP and HTML together! Although the tags used by the template parser contain a lot of functionality, they are by no means to be considered an additional programming language, because for that we have PHP!

The template parser processes only [http://www.w3schools.com/xml/xml_dtd.asp well formed XML tags with the namespace inp2. This article will discuss the basics of templates and tags, specifically:

• Creating a tag from the start;
• Tag and template parameters;
• Parameter scope;
• Examples and restrictions/limitations of working with tags and templates.

Adding a New Tag

Adding a tag can be broken down into the following steps:

• Deciding on the location of the body of the tag in the class structure of the project's tag processors;
• Creating a new class, that's going to contain the body of the tag (if necessary);
• Registering the new tag in factory.php class (only if a class was created in the previous step);
• Writing the body of the tag in the chosen or created tag processor.

Following we'll discuss the details of each of the above stages of creating a tag.

Tag Placement

In most cases, a new tag should be placed in the tag processor, with the prefix that it's using. For example, if there's an "int_Tests" table for the "test" prefix, then the tag that's using this table would be located in the tag processor (e.g. "TestTagProcessor"), that's tied to the "test" prefix.

Creating a Tag Processor

Creating a tag processor starts with creating the file, which will contain the tag processor class. The naming convention for files that contain classes is as follows, the filename is formed by replacing all dashes in the prefix with an underscore followed by tp.php, e.g. "sample_prefix_tp.php". The tag processor file must be in the same directory that contains the unit config, which indicates where it's registered in the class factory. For example, for the prefix "sample-prefix", the directory would be "custom/units/sample_prefix".

Furthermore, in the above created file, it's required to define the tag processor class. The Class name for the tag processor is formed based on the prefix as follows:

• the first letter of each word in the prefix is capitalized;
• all dashes are removed;
• "TagProcessor" is added to the resulting line.

For example, if the prefix is "sample-prefix", then the class of its tag processor is going to be called "SamplePrefixTagProcessor". This class must be the child of the class "kDBTagProcessor":

class SamplePrefixTagProcessor extends kDBTagProcessor {
 
}

The final step in creating new tag processors is registering in the class factory. The tag processor class is registered using the key TagProcessorClass in the config file for the prefix to which it will be connected. In the present example, that prefix is "sample-prefix". To register the tag processor, we must specify the name of the tag processor class and the file where its declared. This is illustrated in the below example.

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

The key that wasn't described above is called "build_event", that is used for the event task, which will initialize the object. For tag processor classes, this will always be the event OnBuild.

All class names, registered in the class factory are cached so we must reset cache before changes will take effect.

Adding a Tag to the Tag Processor

After successfully creating or finding the class of the tag processor, we can start writing the method whose output will be displayed on the page as a result of the new tag. The method itself will be located in the class of the tag processor. Following tag naming conventions, each word in the method name must start with a capital letter. Also, each method's name may contain only Latin letters and numbers, although it's preferred that numbers aren't used.

The (template parser) upon calling the method indicated in the tag in the template will also pass an associative array of parameters, passed to the tag itself as the first argument of the method. This is illustrated in the following example:

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

In the template, the tag call looks like this:

<inp2:sample-prefix_PrintHelloWorld />

Paired and Unpaired Tags

All tags processed by the template parser are either tag pairs (opening and closing tag) or solo tags (self-closing). Paired tags differ from self-closing tags in that paired tags can use the code/text within them at their discretion. All tags declared in tag processor classes are self-closing tags. All paired tags are system tags and cannot be changed/overwritten. In general, paired and non-paired tags look like this:

non-paired/self-closing tag:
<inp2:prefix.special_TagName param1="value1" param2="value2"/>
 
paired tag:
<inp2:prefix_TagName param1="value1" param2="value2">
text contained in tag
</inp2:prefix_TagName>

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

To separate tag parameters from the tag any number of whitespace characters can be used.

Below are examples and explanations of a couple common tags.

• Unpaired tags::

а) <inp2:m_TemplatesBase module="Custom"/> - path to the directory containing the theme files for the module Custom.
б) <inp2:m_GetConfig var="Site_Name"/> - config variable Site_Name.
с) <inp2:st_PageInfo type="meta_title"/> - page title.

• Paired tags:

а) Tag conditions.
<inp2:m_if check="m_Param" name="is_last">
...
</inp2:m_if>
 
б) Tag defining a block element in a template.
<inp2:m_DefineElement name="menu_block">
	<td><inp2:m_Phrase name="lu_about_us"/></td>
</inp2:m_DefineElement>

General form for calling a tag in a template

The general form for calling a tag in a template looks as follows:

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

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

Example of calling a tag in a template:

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

Example of a function the class TestTagProcessor

/**
 * Printing sample text and current date, when additional parameter is given
 *
 * @param Array $params
 * @return string
 */ 
function PrintHelloWorld($params)
{
	// check for special
	$ret = $this->Special == 'front' ? 'Hello World Front !' : 'Hello World !';
 
	// check whether parameter 'current_datetime' is set	
	if (array_key_exists('current_datetime', $params) && ($params['current_datetime'] == 'yes')) {
		$ret .= ' ' . adodb_date('m/d/Y H:s');
	}
 
	return $ret;
}

Setting default parameters

Default parameters allow assigning parameter values for paired (block) tags and for templates for the case where the given tags or templates will be used without passing to them all the parameters that they use.

Default template parameters

Default template parameters are set at the top of the template using the tag m_DefaultParam. If a parameter is going to be used in the body of a tag, but it's value isn't passed when the template is called, then it's default parameter will be used. This is demonstrated on the below example.

=== include_test.tpl ===
<inp2:m_DefaultParam param1="default_value1" param2="default_value2"/>
 
PARAM: [<inp2:m_Param name="param2"/>]
 
=== index.tpl ===
// will output PARAM: [default_value2]
<inp2:m_include template="include_test"/>
 
// will output PARAM: [given_value]
<inp2:m_include template="include_test" param2="given_value"/>

Default Paired Tag Paramaters

Default parameters for paired tags tags are specified in their definition. This is demonstrate on the below example.

<!-- block definition -->
<inp2:m_DefineElement name="sample_element" as_label="" currency="USD">
	[<inp2:m_Param name="as_label"/> - <inp2:m_Param name="currency"/>]
</inp2:m_DefineElement>
 
<!-- using the block and passing it parameters -->
<inp2:m_RenderElement name="sample_element" as_label="1"/> // даст [1 - USD]
 
<!-- using the block without passing it parameters -->
<inp2:m_RenderElement name="sample_element"/> // даст [ - USD]

Location of Templates

All templates are divided into 2 groups based on where they are used:

• administrative console;
• front end site.

Below will be described the specifics concerning location and purpose of templates from both of the above groups.

Administrative Console Templates

All administrative console templates are divided by modules. Following, each module has its own "admin_templates" directory, which contains all of its admin templates. For example, if the module is called "proj-base", then its admin templates will be in the "proj-base/admin_templates" directory. Under the "admin_templates" directory, it's allowed to create other directories to logically group templates within a single module. When using a template, one must always write the module name preceding the template name, for example "proj-base/users/users_list", instead of simply "users/users_list". If one has to include the original version of a template (if the template was changed through ReplacementTemplates) then one must write "orginal:" before the template name, for example "original:path/to/replaced/template".

Writing the module name is not required for templates in the "core/admin_templates" directory.

For projects, creating and changing administrative console templates is only allowed for templates in the "custom/admin_templates" folder, i.e. belonging to the module "custom".

Front-end Templates

Front-end templates are divided by theme(styles). There's a directory for each theme such as "themes/<theme_name>", where "<theme_name>" is the Name field of the actual template. All templates are defined in the "Configuration -> Themes" section. Usually, creating a theme folder with templates inside of it and pressing the "Rebuild Theme Files" button in the themes toolbar is enough for an entry to be automatically created in the Theme table. For example, if the path to the template relative to the project's root directory is "themes/theme_test/testing/sample_template.tpl", then to use the template one can write "testing/sample_template". The template will then look in the theme that's indicated in the site URL.

In projects, there's usually only one theme, named "theme_<project_name>", for example "theme_estore".

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

По умолчанию параметры переданные в блок или шаблон будут видны только в нём самом. Если требуется, передать значение индивидуального параметра в следующий блок или шаблон, то это можно сделать при помощи следующей конструкции 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, что есть не очень хорошо. Для нахождения мест в шаблоне, где не заданы значения параметров по умолчанию лучше всего подходит отладчик.