Создание собственных WACT тегов

Мы предполагаем, что вам уже знакомы материалы следующих разделов:

• "Как работает компилятор WACT-шаблонов",
• "Типы тегов"

То есть вам должны быть знакомо следующее:

• какие типы тегов существуют, и от какого класса нужно отнаследоваться в том или ином случае.
• что такое code_writer, и какие наиболее часто используемые методы у него есть.
• какие методы есть в классе WactCompilerTreeNode, вызываемый в процессе компиляции шаблона.

Теги хранятся в файлах с именем some_tag_name.tag.php, который должен быть расположен в одной из директорий вида src/template/tags (при использовании WEB_APP пакета). Обратите внимание на окончание .tag.php.

Перед самой декларацией класса тега существует зона комментариев в стиле phpDoc - это зона аннотаций тега, например:

<?php
/**
 * Include another template into the current template
 * @tag core:INCLUDE
 * @req_const_attributes file
 * @forbid_end_tag
 */
class WactCoreIncludeTag extends WactCompilerTag
{
[...]
}
?>

Полный список аннотация для тегов:

• tag - название тега, которое может использовать внутри шаблона. Регистр не имеет значения. Начиная с версии WACT 0.3 поддерживаются алиасы, то есть можно указывать несколько названий тегов через запятую, например: @tag params,param.
• req_attributes - список атрибутов тега, которые должны обязательно присутствовать в шаблоне.
• req_const_attributes - список атрибутов тега, которые должны иметь константные значения.
• suppress_attributes - список атрибутов тега, которые не должны показываться после рендеринга тега на этапе выполнения шаблона. Другими словами это список атрибутов только для этапа компиляции. Данная аннотация актуальна только для тегов класса WactRuntimeComponentHTMLTag и его дочерних.
• forbid_parsing - указывает нужно ли обрабатывать компилятором содержимое внутри тега. Используется, например, у тега <core:literal>, где имеет значение true. По-умолчанию равно false.
• parent_tag_class - указывает название класса родительского тега, внутри которого обязан находиться. Если эта аннотация указана, а родительский тег не найден - будет сгенерирована ошибка компиляции.
• restrict_self_nesting - запрещает тегу иметь в качестве непосредственного родителя аналогичный тег.
• forbid_end_tag - запрещает тег иметь открывающий и закрывающий тег. То есть для данных тегов доступна только короткая форма, например, <find:params />.
• runat - указывает, должен ли тег компилироваться как WACT-тег. По-умолчанию равно server и обычно не указывается Эта аннтация актуальна для тегов класса WactRuntimeComponentHTMLTag, таких как <input>, <form>, где стоит client. Это значит, что тег будет интерпретироваться как обычный htlm-тег до тех пор не будет явно указана необходимость компиляции, например, <form runat='server'>
• runat_as - указывает имя класса тега, который нужно найти среди родительских тегов и посмотреть его значение runat. Актуально для тегов форм, таких как <input>, которые наследуют значение runat от тега класса WactFormTag.
• convert_to_expression - указывает список атрибутов тега, которые могут использовать краткую форму выражения, без {$}, например <list:list from='#books'> вместо <list:list from='{$#books}'>

То, какие методы перекрывать, зависит от типа создаваемого тега:

Если это будет обычный тег (не имеющий html-аналога), тогда вы скорее всего будете наследоваться от WactCompilerTag или WactRuntimeComponentTag и вам лучше всего перекрывать следующие методы:

• generateBeforeContent($code_writer)
• generateAfterContent($code_writer)
• generateTagContent($code_writer)

Если вы создаете тег-контекст, когда вы скорее всего будете наследоваться от WactRuntimeDatasourceComponentTag. Будьте внимательны - метод generateBeforeContent($code_writer) уже перекрыт.

Если вы создаете тег, у которого есть html-аналог, тогда скорее всего вам будет удобнее отнаследоваться от WactRuntimeComponentHTMLTag или WactRuntimeDatasourceComponentHTMLTag и перекрывать методы:

• generateBeforeOpenTag($code_writer)
• generateAfterOpenTag($code_writer)
• generateBeforeCloseTag($code_writer)
• generateAfterCloseTag($code_writer)

Начиная с версии 0.5 если вы желаете поддерживать динамические атрибуты в тегах, то вам нужно лишь в нужном месте вызвать у этого атрибута метод generateExpression($code_writer). Пример - это атрибут from тега <list:list>, о котором рассказано на странице "Как работает компилятор WACT-шаблонов". Все действия, связанные с подготовкой (так называемая прегенерация), находится к классе WactCompilerTag. Именно поэтому при создании дочерних классов от класса WactCompilerTag рекомендуется перекрывать методы generateBeforeContent($code_writer) и generateAfterContent($code_writer) (в некоторых случаях - generateTagContent($code_writer)), но не generate($code_writer).