Начальная страница

Николай Жарких (Киев)

Персональный сайт

?

Смеретеги

Поля подстановки (или теги Смереки, сокращенно – смеретеги) являются частями HTML кода. Их можно употреблять в любых атрибутах, содержащие HTML код, например, в атрибуте HTMLCode.

Чтобы поля подстановки «ожили», нужно, чтобы они вошли в HTML код страницы, тогда Смерека, компилируя страницу, вычислит их значения и подставит результаты вычислений на место смеретегов.

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

Правила написания смеретегов

Смеретег – это XML тег. Как каждый XML тег, он может быть одинарным:

<Smereka [список атрибутов] />

или двойным:

<Smereka [список атрибутов]>Текст подстановки</Smereka>

Одинарный тег должен обязательно заканчиваться косой чертой и знаком «больше», между которыми не должно быть пробелов. Как везде в XML, имена тегов и атрибутов чувствительны к регистру символов!

Список атрибутов соответствует правилам XML:

Param1="Value1… ParamN="ValueN"

Элементы списка разделяются пробелами. Имя атрибута и значение атрибута объединяются знаком равенства, обязательно без пробелов. Значения атрибутов обязательно заключаются в кавычки. Кавычки в значениях атрибутов не допускаются, вместо них следует употреблять сущность &6quot; (отмена с помощью обратной косой \ не работает).

Согласно правилам языка HTML теги, неизвестные браузеру, не отображаются. Итак, если подстановка полей не выполняется, то одинарный тег Смереки останется невидимым, а двойной тег будет отображен как Текст подстановки.

Смеретеги-атрибуты

Согласно правилам языка HTML значение атрибута не может быть тегом. Чтобы обойти это ограничение, Смерека предлагает альтернативный синтаксис смеретегов, где вместо ломаных скобок используются фигурные:

С использованием такого альтернативного синтаксиса можно строить корректные конструкции вроде:

<img src="" />

Вложенные смеретеги

смеретеги, записанные с использованием синтаксиса

<Smereka [список атрибутов]>Текст подстановки </Smereka>

могут содержать в тексте подстановки другие смеретеги. Для того чтобы правильно указать последовательность замыкающих тегов </Smereka>, необходимо использовать числовые суффиксы:

<Smereka10 [список атрибутов]>
 Статический текст подстановки
 <Smereka5 [список атрибутов]>Динамический текст
подстановки </Smereka5>
 <Smereka5 [список атрибутов]>Другой динамический
текст подстановки </Smereka5>
 <Smereka [список атрибутов]>
 Глубже вложенный текст
 </Smereka>
</Smereka10>

Общее правило заключается в том, что текст подстановки не должен содержать тега Smereka с тем же числовым суффиксом, что и охватывающий его тег.

Последовательность вычисления смеретегов

смеретеги исчисляются в следующей последовательности:

все теги вида <Smereka [список атрибутов]>Текст
подстановки </Smereka>
все теги вида 
все теги вида {{Smereka [список атрибутов]}Текст
подстановки{/ Smereka}
все теги вида <Smereka [список атрибутов] />

Знание этой последовательности может иметь определенную практическую пользу. Например, сложный смеретег вида

 <Smereka Func="GetDocTitle"
NodeId="{Smereka Func="GetAttr" AttrName="link" /}" />

делает именно то, что от него хотят: добывает значение атрибута link для текущей вершины и затем вычисляет значения DocTitle для этой вершины.

Обязательные атрибуты

Method="MethodName". Значением этого атрибута является имя метода объекта Page или его наследника. Если этот атрибут задан, будет вызван указанный метод и ему будет переданы остальные параметров. Если метод не найден, смеретег вернет пустую строку.

Func="FuncName". Значением этого атрибута является имя функции Смереки, которой будут переданы остальные параметров. Если функция не найдена, смеретег вернет пустую строку.

Module="ModuleName". Этот атрибут выступает в паре с атрибутом Func. Значением этого атрибута является имя модуля PHP, содержащий заданную функцию, например:

 <Smereka Module="aggregators/navigators.php"
Func="NavigatorItem" />

Следует знать, что наиболее популярные функции собраны в модуле smeretags/substfields.php, и этот модуль всегда подключается при компиляции смеретегов. Поэтому это значение можно не указывать (рекомендуется).

Если нужный модуль нельзя загрузить, смеретег вернет пустую строку.

Итак, обязательным является один из параметров Func|Method. Все остальные параметры являются необязательными и зависят от того, какой именно метод (функция) вызывается. Подробное описание возможных параметров помещено в описаниях соответствующих функций.

Контекстная вершина

При каждом вызове функции / метода смеретега Смерека передает ему параметр BaseNode, содержащий вершину, в контексте которой вычисляется смеретег. Этот параметр добавляется автоматически, и его не нужно указывать в списке параметров смеретега.

Следовательно, если другие параметры не определяют другого контекста вычислений, расчеты ведутся для вершины BaseNode.

Прототип функции

Чтобы функцию PHP можно было вызвать через аппарат смеретегов, она должна соответствовать такому прототипу:

 string FuncName (array $Params)

где $Params является ассоциативним массивом параметров. Он обязательно содержит хотя бы один элемент – BaseNode; другие параметры могут передаваться по мере необходимости.

Если смеретег содержит Текст подстановки, этот текст передается в параметре SmerekaValue.

Функция должна возвратить результат как строку или пустая строка, если произошла ошибка.

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