K4:Описание специальных тэгов
From In-Portal Developers Guide
(→Параметр pass_params: дополнение) |
m (1 версия) |
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. |
| ||
---|---|---|
Статьи в этой категории | ||
Contents |
Специальные тэги
Под термином "специальные тэги" в данной статье понимаются встроенные тэги, функциональность которых уже реализована в полном (или почти полном) объёме на уровне 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: "<b>HMTL</b> <i>formatted text</i>" <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_RenderElement | Не описан параметр design и то, что тэг RenderElement в некоторых случаях может быть парным. // исправлено |
Тэги управления потоками данных - m_if, m_else, m_elseif | Написать, что начиная с Core v 4.3.9 доступен тэг <inp2:m_ifnot который работает как тэг <inp2:m_if inverse="inverse" и что вместо параметра inverse рекомендуется использовать именно <inp2:m_ifnot. // исправлено |
Тэг m_Set | Не написано о том, что можно за одно использование тэга установить сразу несколько переменных и как это сделать. // исправлено |
Параметр equals_to | Не описана возможность передачи сразу нескольких значений в параметр equals_to. // исправлено |
(константу либо переменную-параметр), | Немного неоднозначно написано и получается, как буд-то можно передать название константы в качестве значения в параметр equals_to. // исправлено |
sid | Нужно убрать упоминание слова sid из всех примеров в статье. // исправлено |
Тэг m_ModuleInclude | Сверху написано, что обязательный параметр "t", а снизу в примере используется "template". Я думаю, что "template" обязательный, а "t" это его псевдоним, как с случае с тэгом m_Include. // исправлено |
Тэг m_ModuleInclude (2) | Можно написать, что тэг m_ModuleInclude вызывает в цикле (для каждого модуля в системе) тэг m_Include и при это добавляет перед названием переданного в него шаблона название директории с шаблонами данного модуля. Неплохо было-бы также привести код в шаблоне (из m_Include тэгов), который будет эквивалентен вызову данного тэга. Примеры построения путей к подключаемым через этот тэг шаблонам тоже не помешают. // исправлено |
t | Параметр "t" не всегда заключён в тэг code. // например где? |
Параметры форматирования данных: html_escape, strip_nl, js_escape, trim | Нужно разбить на разные главы, чтобы легче было понять пример. Названия блоков вида "s1" и "s2" также не очень понятные. // исправлено
Не описан параметр cache_timeout. // потому что эта функциональность толком не работает! |
- Изменить порядок фрагментов в описании тэга с "список параметров, описание, примеры" на "описание, список параметров, примеры".
- Не описан тэг m_RenderElements // исправлено