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

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

• "Компиляция и выполнение шаблона. Пример рендеринга MACRO-шаблона",
• "Как работает компилятор MACRO-шаблонов",

Теги хранятся в файлах с именем some_tag_name.tag.php, который должен быть расположен в одной из директорий вида src/macro пакетов или приложения, а также в папке /limb/macro/src/tags. Обратите внимание на окончание .tag.php - только их таких файлов информацию попадает в словарь тегов.

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

<?php
/**
 * @tag tag_name
 * @aliases alias1, alias2
 * @req_attributes param1, param2
 * @parent_tag_class parent_tag_class
 * @restrict_self_nesting
 * @forbid_end_tag
 */
class lmbMacroApplyTag extends lmbMacroTag
{ 
[...]
}
?>

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

• tag - название тега, которое может использовать внутри шаблона. Регистр не имеет значения.
• aliases - другие имена тегов. Можно указывать несколько альтернативных названий тегов через запятую, например: @aliases params,param.
• req_attributes - список атрибутов тега, которые должны обязательно присутствовать в шаблоне.
• parent_tag_class - указывает название класса родительского тега, внутри которого обязан находиться. Если эта аннотация указана, а родительский тег не найден - будет сгенерирована ошибка компиляции.
• restrict_self_nesting - запрещает тегу иметь в качестве непосредственного родителя аналогичный тег.
• forbid_end_tag - запрещает тег иметь открывающий и закрывающий тег. То есть для данных тегов доступна только короткая форма, например, {{include}} или {{include/}}, но не {{include}}[…]{{/include}}

• lmbMacroTag - используется в качестве родительского в самых общих случаях. Примеры подобных тего - {{include}}, {{list}}, {{list:item}} и т.д.

• lmbMacroPassiveTag - используется в качестве родительского в случаях, когда тег сам в комплируемый шаблон ничего не пишет, однако может писать, если его об этом попросить явно при помощи метода generateNow($code_writer)

• lmbMacroRuntimeWidgetTag - этот класс используется, если предполагается, что для работы тега потребуется какой-то объект-helper или widget. Пример такого тега: {{pager}}.

При использовании данного тега необходимо определить 2 атрибута:

• $widget_class_name - название класса widget-а
• $widget_include_file - путь до файла, который содержит определение класса $widget_class_name

Это определение можно сделать также в методе preParse(lmbMacroCompiler $compiler) (см. пример limb/macro/src/tags/form/input.tag.php)

lmbMacroRuntimeWidgetTag использует метод lmbMacroCodeWriter :: writeToInit($php_code), который используется для записи инициализирующего кода в генерируемый шаблон. lmbMacroRuntimeWidgetTag создает объект, как атрибут генерируемого класса с именем, которое можно получить при помощи метода getRuntimeVar(). getRuntimeVar() - возвращает кусок php-кода, который ссылается на объект widget-а, обычно это что-то вроде $this→tag_tag_id.

• lmbMacroRuntimeWidgetHtmlTag - этот класс используется в качестве родителя в случае, если MACRO-тег на этапе выполнения генерит html-тег, и для этого используется специальный widget, который наследуют от класса lmbMacroHtmlTagWidget.

lmbMacroRuntimeWidgetHtmlTag требует также указания атрибута $html_tag.

Примеры - это большинство тегов в папке limb/macro/src/tags/form/

• lmbMacroFormElementTag - этот класс используется в качестве родителя в случае, если MACRO-тег на этапе выполнения генерит какой-то аналоги html-тега элемента формы. Этот класс можно найти в файле limb/macro/src/tags/form/lmbMacroFormElementTag.class.php

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

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

• _generateBeforeContent($code_writer)
• _generateContent($code_writer)
• _generateTagContent($code_writer)

Главное, не забудьте вызвать родительский _generateContent($code_writer), так как именно в нем передается управление дочерним элементам.

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

• _generateBeforeOpeningTag($code_writer)
• _generateAfterOpeningTag($code_writer)
• _generateContent($code_writer)
• _generateBeforeClosingTag($code_writer)
• _generateAfterClosingTag($code_writer)

В принципе, можно в последнем случае также перекрывать метод _generateContent($code_writer).

Этот метод используется для предварительного анализа атрибутов тега, родительских элементов и т.д. Этот метод вызывается в тот самый момент, когда компилятор находит соответствующий тег в MACRO-шаблоне. Обычно этот метод используется для установки каких-то обязательных атрибутов до момента их автоматических проверок на более поздних этапах.

см. примеры: {{input}}, {{insert}} и нек. другие.