From In-Portal Developers Guide

Revision as of 16:16, 28 February 2009

This article is not finished yet! You see this message because current Article is finished yet or contains unverified information. How to write an Article.

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

Специальные тэги

Под термином "специальные тэги" в данной статье понимаются встроенные тэги, функциональность которых уже реализована в полном (или почти полном) объёме на уровне Kernel'а и для полноценной работы которых не требуется вносить какие-либо модификации в код.

Тэг m_DefineElement

Обязательные параметры:

• name

Описание:

Парный тэг, отмечает начало декларации блочного элемента. Технически допустима декларация неограниченного количества вложенных блочных элементов, однако использование такого стиля программирования является крайне нежелательным. Единственным идентификатором (признак, по которому различаются блоки) является имя блока. Блочные элементы возможно переопределять, объявляя блок с именем уже существующего, поэтому, во избежание коллизий, необходимо проявлять внимательность при выборе имени очередного блока. Блочные элементы доступны на любом уровне вложенности (scope) вне зависимости от того, на каком они были объявлены. При объявлении желательно указывать (декларировать) все используемые в нём параметры, это поможет не только избежать ошибок, когда по каким то причинам параметр не был передан при вызове (выводе) блока, но и даёт возможность, в случае необходимости, установить значения по-умолчанию для параметров (т.е. данные значения попадут в блок, если при вызове соответствующие параметры не были переданы).

Пример использования:

<inp2:m_DefineElement name="person" firstname="unknown" lastname="">
    Name: <inp2:m_Param name="firstname" /> <inp2:m_Param name="lastname" /><br/>
    Profession: <inp2:m_RenderElement name="profession" person="$lastname" />
</inp2:m_DefineElement>
 
<inp2:m_DefineElement name="profession" firstname="unknown" person="">
    <inp2:m_if check="m_Param" name="person" equals_to="Johnson">
        lawyer
    <inp2:m_else/>
        unknown
    </inp2:m_if>
    <br/>
</inp2:m_DefineElement>
 
<inp2:m_RenderElement name="person" firstname="John" lastname="Johnson" /><br/>
<inp2:m_RenderElement name="person" />

Результат выполнения кода:

Name: John Johnson
Profession: lawyer
 
Name: unknown
Profession: unknown

Пояснения:

В примере выше продемонстрировано декларирование параметров (например, параметры firstname и lastname в блоке person) и так же результат обработки блока, в который не были переданы все необходимые параметры. Так же продемонстрирован способ передачи полученных в вызываемом блоке параметров в следующий блок (параметр lastname внутри блока person).

Тэг m_RenderElement

Параметры:

• name
• design
• data_exists
• block_no_data
• pass_params

Описание:

Непарный тэг, используется для вызова, предварительно объявленного с помощью тэга m_DefineElement, блочного элемента. Может так же использоваться внутри блочного элемента. В параметре name необходимо указать имя блока, который необходимо обработать. Тэг m_RenderElement может так же быть парным. При этом необходимо указать параметр design, который позволяет действовать следующим образом: сначала обработать содержимое парного тэга m_RenderElement. Затем следует вызов блока, указанного в параметре design, который уже в свою очередь использует подготовленную информацию и выводит ей в окончательном оформлении (доступна через параметр content).

Пример использования:

<inp2:m_DefineElement name="sample" param1="">
    This is sample block<br/>
    This is sample parameter: <inp2:m_Param name="param1" /><br/>
    <inp2:m_RenderElement name="sample2" />
</inp2:m_DefineElement>
 
<inp2:m_DefineElement name="sample2">
    This is sub-block
</inp2:m_DefineElement>
 
<inp2:m_RenderElement name="sample" param1="test" />

Результат выполнения кода:

This is sample block
This is sample parameter: test
This is sub-block

Пояснения:

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

Тэг m_RenderElements

Обязательные параметры:

• design
• elements
• data_exists
• block_no_data
• pass_params

Описание:

Непарный тэг, в качестве параметра elements принимает список блоков, разделённых запятой, которые будут обработаны. Блоки обрабатываются в том же параметре, в котором они указаны в параметре elements.

Пример использования:

<inp2:m_DefineElement name="foo">
	foo
</inp2:m_DefineElement>
 
<inp2:m_DefineElement name="bar">
	bar
</inp2:m_DefineElement>
 
<inp2:m_RenderElements elements="foo,bar" />

Результат выполнения кода:

foo bar

Пояснения:

Блоки были обработаны в указанном порядке.

Тэг m_Capture

Обязательные параметры:

• to_var

Описание:

Парный тэг, используется для сохранения большого объёма информации в параметрах текущего шаблона (доступные через тэг m_Param). Может быть так же использован для сохранения данных в случаях, когда их непосредственное использование при передаче в виде параметров шаблона или блока может привести к неправильной обработке кода (см. пример ниже). Обязательный параметр to_var указывает имя переменной-параметра, в которую будет сохранён результат выполнения кода, помещённого между открывающим и закрывающим тэгами m_Capture. В выводе не окажется неинтерпретированных тэгов Inportal - весь код будет обработан и результат (если он будет) помещён в параметр с указанным именем. Вложенные тэги m_Capture будут так же корректно обработаны. Как и в случае с блочными элементами, генерируемыми тэгом m_DefineElement, тэг m_Capture так же успешно перепишет параметр, даже если такой уже существует. Причём, это относится не только к параметрам, инициализированным тэгом m_Capture, но и к параметрам шаблона/блока.

Пример использования:

<inp2:m_Capture to_var="example_var">
    "/>
    Этот текст может нарушить структуру данных в шаблоне.
</inp2:m_Capture>
 
<inp2:m_DefineElement name="test">
    Данный текст был безопасно передан:<br/>
    <inp2:m_Param name="sample" />
</inp2:m_DefineElement>
 
<inp2:m_Param name="example_var" result_to_var="example_var" />
<inp2:m_RenderElement name="test" sample="$example_var" />

Обратите внимание! В примере выше, после вызова m_Capture параметр с результатом работы тэга передаётся параметром в другой тэг используя короткую запись вида $param_name. Однако, в силу особенностей тэга m_Capture, результирующий параметр будет доступен только для тэга m_Param. Поэтому в примере приведён способ, который можно использовать для обхода данного ограничения.

Результат выполнения кода:

Данный текст был безопасно передан:
"/> Этот текст может нарушить структуру данных в шаблоне.

Пояснения:

В примере выше продемонстрировано как присвоить значению параметра результат обработки блока кода. С помощью конструкции <inp2:m_Param name="example_var" result_to_var="example_var" /> параметр, видимый только для тэга m_Param, становится возможным использовать в короткой записи для передачи в виде параметра другим тэгам. В принципе, параметр с "$" и так уже доступен, просто если параметр получился в результате обработки тэга Capture - сразу работать не будет, и нужно выполнять этот дополнительный код.

Тэги управления потоками данных - m_if, m_else, m_elseif

Начиная с Core v 4.3.9 доступен тэг m_ifnot который работает как тэг m_if в присутствии параметра inverse="inverse". Использование тэга m_ifnot является более предпочтительным во всех совместимых версиях Core.

Обязательные параметры:

• check (тэги m_if, m_elseif)

Специальные параметры:

• inverse (тэги m_if, m_elseif)

Описание:

Парный тэг m_if, а так же одиночные тэги m_else и m_elseif реализуют классическую структуру if-then-else внутри шаблонов. В качестве функции, определяющей как будет обработан тэг (с результатом true или false), используется вызов методов класса TagProcessor (или его наследников) с передачей необходимых параметров (зависит от используемого метода). Специальный параметр inverse указывает на то, что результат вычисления необходимо обратить (т.е. применить к нему логический оператор негации).

Пример использования:

<inp2:m_DefineElement name="colors" type="">
	<inp2:m_if check="m_Param" name="type" equals_to="bright">
		white, yellow, orange
	<inp2:m_elseif check="m_Param" name="type" equals_to="dark"/>
		black, green, blue
	<inp2:m_else/>
		neutral color: gray
	</inp2:m_if>
</inp2:m_DefineElement>
 
1) <inp2:m_RenderElement name="colors" type="bright" /><br/>
2) <inp2:m_RenderElement name="colors" type="dark" /><br/>
3) <inp2:m_RenderElement name="colors" /><br/>
 
<inp2:m_if check="m_Get" var="im_set" equals_to="" inverse="inverse">
    <!-- Этот код выполнится только тогда, года переменная "im_set" установлена и имеет значение отличное от пустой строки -->
    First case: <inp2:m_Get var="im_set" />
</inp2:m_if>
 
<inp2:m_Set im_set="123" />
 
<inp2:m_if check="m_Get" var="im_set" equals_to="" inverse="inverse">
    Second case: <inp2:m_Get var="im_set" />
</inp2:m_if>

Результат выполнения кода:

1) white, yellow, orange
2) black, green, blue
3) neutral color: gray
Second case: 123

Пояснения:

В примере выше, внутри блока colors, производится проверка значения параметра type (с помощью тэга предназначенного для работы с параметрами m_Param). Значение параметра сравнивается с константами (bright, dark) при помощи специального параметра equals_to, доступного во всех тэгах (см. ниже). Так же продемонстрировано использование специального параметра inverse.

Основные тэги для работы с шаблонами

Ниже представлено описание основных тэгов для работы с шаблонами.

Тэг m_Include

Обязательные параметры:

• template (псевдоним: t)
• data_exists
• block_no_data
• pass_params

Описание:

Непарный тэг m_Include используется для того, чтобы динамически подключать шаблоны. Обязательный параметр template (можно просто сокращённо - t) указывает путь к файлу шаблона включая его имя (без расширения ".tpl"). Подробнее о том, как формируется путь к шаблону рассказано в этой статье.

Пример использования:

<!-- Содержимое произвольного файла в каталоге "themes/theme_projectname/" -->
Weather in Riga: <inp2:m_Include t="default/weather_reports/riga" />
 
<!-- Содержимое файла "themes/theme_projectname/default/weather_reports/riga.tpl" -->
17°C, Current:Clear, Wind: NE at 13 km/h
 
<!-- Результат выполнения кода: -->
Weather in Riga: 17°C, Current:Clear, Wind: NE at 13 km/h

Пояснения:

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

Тэг m_ModuleInclude

Обязательные параметры:

• template
• data_exists
• block_no_data
• pass_params

Описание:

Непарный тэг m_ModuleInclude экивалентен m_include указанного шаблона у всех модулей. При этом, название папки с Front-End шаблонами модуля подставляется перед переданным тэгу шаблоном. Тэг m_ModuleInclude вызывает в цикле (для каждого модуля в системе) тэг m_Include и при это добавляет перед названием переданного в него шаблона название директории с шаблонами данного модуля.

Пример использования:

<inp2:m_ModuleInclude template="elements/content_boxes/home_page_items" />

Аналог тэгу m_ModuleInclude используя m_Include

<inp2:m_Include t="test" /> # Core
<inp2:m_Include t="custom/test" /> # Custom
<inp2:m_Include t="in-commerce/test" /> # In-commerce

Пояснения:

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

Тэг m_Param

Обязательные параметры:

• name

Описание:

Непарный тэг, возвращает значение указанного параметра из шаблона на текущем уровне вложенности. Допустим к использованию как в блоках (для получения параметров блока), так и в самом верхнем уровне вложенности (scope) - т.е. просто на шаблоне (для получения параметров переданных динамически подключённому шаблону или параметров, которые были инициализированы с помощью доступного во всех тэгах параметра result_to_var (см. ниже)).

Пример использования:

<inp2:m_DefineElement name="alternate" somename="">
    <inp2:m_Param name="somename" />
</inp2:m_DefineElement>
 
<inp2:m_DefineElement name="sample" test="">
    The value is: <inp2:m_Param name="test" /><br/>
    Alternate syntax: <inp2:m_RenderElement name="alternate" somename="$test" />
</inp2:m_DefineElement>
 
<inp2:m_RenderElement name="sample" test="foo" />

Результат выполнения кода:

The value is: foo
Alternate syntax: foo

Пояснения:

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

Тэг m_Set

Обязательные параметры:

• <имя переменной, которая будет установлена>

Описание:

Непарный тэг m_Set используется для того, чтобы установить переменную (присвоить значение), которая в последствии будет доступна для тэга m_Get и метода Application::GetVar. Установленная таким образом переменная перезапишет значение уже существующей (не зависимо от того, как предыдущая была получена - get/post/cookie). Допускается декларация сразу нескольких переменных за раз: <inp2:m_Set foo="1" bar="2" />.

Пример использования:

Setting variable ... <inp2:m_Set testvar="sample" /> <br/>
Variable value is: <inp2:m_Get name="testvar" />

Результат выполнения кода:

Setting variable ...
Variable value is: sample

Пояснения:

В примере выше показано, как можно устанавливать и получать переменные используя методы m_Set и m_Get.

Тэг m_Get

Обязательные параметры:

• name (псевдонимы: var,param)

Описание:

Непарный тэг, используется для получения значения переменных GET/POST/COOKIE. Основное отличие от параметров шаблона/тэга в том, что данные переменные глобальны в рамках шаблона (доступны на любом уровне вложенности) и могут быть переданы от пользователя, в то время как параметры могут быть объявлены только внутри шаблона и обладают ограниченной областью видимости.

Пример использования:

<inp2:m_Set foo="bar" />
foo = <inp2:m_Get name="foo" />

Результат выполнения кода:

foo = bar

Пояснения:

Пример демонстрирует способ, которым можно получить значение переменной (её происхождение (get, post, cookie переменная) не имеет значения).

Специальные параметры, доступные во всех тэгах

Перечисленные ниже специальные параметры доступны во всех тэгах. Они производят различные манипуляции с результатом (выводом) тэга, в котором они применены.

Параметр equals_to

Описание:

В качестве значения принимает строку (строковую константу либо переменную-параметр), сравнивает с результатом выполнения тэга и, если строки совпадают, подменяет результат (вывод) тэга на значение true (либо на false в противном случае). Есть так же возможность указать несколько значений в этом параметре, разделив их символом "|" (они будут объеденены логическим "или"). Используется в тэгах управления потоками данных.

Пример использования:

<inp2:m_Set test="sample" />
 
<inp2:m_if check="m_Get" var="test" equals_to="sample">
    Variable "test" has value of "sample".
</inp2:m_if>

Результат выполнения кода:

Variable "test" has value of "sample".

Пояснения:

В примере, приведённом выше, показано как специальный параметр equals_to может быть использован вместе с тэгом m_if.

Параметр result_to_var

Описание:

Данный параметр в качестве значения принимает имя параметра, значением которого будет установлен результат выполнения тэга. Если параметр с указанным именем уже объявлен - он будет перезаписан. Рекомендуется не злоупотреблять использованием данного параметра не только из соображения экономии ресурсов памяти, но и из за возможной неочевидности исходного кода (т.е. это может усложнить работу людям, которым придётся работать с этим кодом).

Пример использования:

<inp2:m_DefineElement name="sample">
    <inp2:m_Set foo="bar" />
    <inp2:m_Get var="foo" result_to_var="foo" />
    <inp2:m_RenderElement name="sample2" value="$foo" />
</inp2:m_DefineElement>
 
<inp2:m_DefineElement name="sample2" value="">
    value: <inp2:m_Param name="value" />
</inp2:m_DefineElement>
 
<inp2:m_RenderElement name="sample" />

Результат выполнения кода:

value: bar

Пояснения:

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

Параметр pass_params

Данный параметр доступен только в тэгах m_RenderElement, m_RenderElements, m_Include, m_ModuleInclude.

Описание:

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

Пример использования:

<inp2:m_DefineElement name="sample" testparam="">
    <inp2:m_if check="m_Param" name="testparam" equals_to="">
        Param has not been passed!
    <inp2:m_else/>
        Param has been passed: <inp2:m_Param name="testparam" />
    </inp2:m_if>
</inp2:m_DefineElement>
 
<inp2:m_Set testparam="test-value" />
<inp2:m_Get var="testparam" result_to_var="testparam" />
 
<inp2:m_RenderElement name="sample" /> <br/>
<inp2:m_RenderElement name="sample" pass_params="1" />

Результат выполнения кода:

Param has not been passed!
Param has been passed: test-value

Пояснения:

Пример демонстрирует разницу в обработке одного и того же блока в двух случаях: когда при вызове тэга m_RenderElement был передан параметр pass_params и в случае, когда этот параметр передан не был.

Параметры форматирования данных: html_escape, strip_nl, js_escape, trim

Описание:

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

Пример использования (html_escape):

<inp2:m_DefineElement name="foo"><b>HMTL</b> <i>formatted text</i></inp2:m_DefineElement>
 
<inp2:m_DefineElement name="sample" specparam="">
	Parameter applied: <inp2:m_Param name="specparam" /> <br/>
	Sample: "<inp2:m_RenderElement name="foo" $specparam="1" />" <br/>
</inp2:m_DefineElement>
 
<inp2:m_RenderElement name="sample" specparam="html_escape" />

Результат выполнения кода:

Parameter applied: html_escape <br/>
Sample: "&lt;b&gt;HMTL&lt;/b&gt; &lt;i&gt;formatted text&lt;/i&gt;" <br/>

Пример использования (strip_nl):

<inp2:m_DefineElement name="foo">
this is
multiline text
	with tabs
</inp2:m_DefineElement>
 
<inp2:m_DefineElement name="sample" specparam="">
	Parameter applied: <inp2:m_Param name="specparam" /> <br/>
	Sample: "<inp2:m_RenderElement name="foo" $specparam="1" />" <br/>
</inp2:m_DefineElement>
 
<inp2:m_RenderElement name="sample" specparam="strip_nl" />

Результат выполнения кода:

Parameter applied: strip_nl <br/>
Sample: "this is multiline text with	tabs" <br/>

Пример использования (js_escapel):

<inp2:m_DefineElement name="foo">
<script type="text/javascript">
    var x = 1;
</script>
</inp2:m_DefineElement>
 
<inp2:m_DefineElement name="sample" specparam="">
	Parameter applied: <inp2:m_Param name="specparam" /> <br/>
	Sample: "<inp2:m_RenderElement name="foo" $specparam="1" />" <br/>
</inp2:m_DefineElement>
 
<inp2:m_RenderElement name="sample" specparam="js_escape" />

Результат выполнения кода:

Parameter applied: js_escape <br/>
Sample: "<script type=\"text/javascript\">\n   var x = 1;\n   </'+'script>\n   " <br/>

Пример использования (trim):

<inp2:m_DefineElement name="foo">
this is
multiline text
	with tabs
</inp2:m_DefineElement>
 
<inp2:m_DefineElement name="sample" specparam="">
	Parameter applied: <inp2:m_Param name="specparam" /> <br/>
	Sample: "<inp2:m_RenderElement name="foo" $specparam="1" />" <br/>
</inp2:m_DefineElement>
 
<inp2:m_RenderElement name="sample" specparam="trim" />

Результат выполнения кода:

Parameter applied: trim <br/>
Sample: "this is
multiline text
    with tabs" <br/>

Пояснения:

Пример, приведённый выше, демонстрирует какой эффект каждый из специальных параметров оказывает на результат работы тэга (вывод), а именно:

• html_escape - применяет к результату php функцию htmlspecialchars прежде, чем вернуть его;
• strip_nl - удаляет из строки все символы переноса строки и символы возврата каретки, а если в качестве значения специального параметра указать "2" - то так же удалит и символы табуляции (strip_nl="2");
• js_escape - подготавливает строку для использования в JavaScript;
• trim - применяет к результату php функцию trim прежде, чем вернуть его.

Заметки редактора

Пока проверено только до тэга m_Include.

• Изменить порядок фрагментов в описании тэга с "список параметров, описание, примеры" на "описание, список параметров, примеры".
• Не описан тэг m_RenderElements // исправлено