Смеретеги
Поля підстановки (або теги Смереки, скорочено – смеретеги) є частинами HTML коду. Їх можна вживати в будь-який атрибутах, які містять HTML код, наприклад, в атрибуті HTMLCode.
Для того, щоб поля підстановки «ожили», потрібно, щоб вони були вставлені в HTML код сторінки; тоді Смерека, компілюючи сторінку, обчислить їх значення і підставить результати обчислень на місце смеретегів.
Отже, Смерека пропонує два основних способи вставки смеретегів : статичний, коли смеретеги записуються в шаблон сторінки, і динамічний, коли смеретеги записуються в текст якогось атрибута вершини (і цей атрибут сам вставляється в сторінку за допомогою смеретега). Зрештою, програміст Смереки, розробляючи власні модулі, може самостійно виконувати обчислення смеретегів, якщо стандартна процедура автоматичного обчислення не підходить.
Правила написання смеретегів
Смеретег – це XML тег. Як кожен XML тег, він може бути одинарним :
<Smereka [список атрибутів] />
або подвійним :
<Smereka [список атрибутів]>Текст підстановки</Smereka>
Одинарний тег мусить обов’язково закінчуватись косою рискою і знаком «більше», між якими не повинно бути пробілів. Як скрізь в XML, імена тегів і атрибутів чутливі до регістру символів!
Список атрибутів відповідає правилам XML :
Param1="Value1"… ParamN="ValueN"
Елементи списку розділяються пробілами. Ім’я атрибуту і значення атрибуту поєднуються знаком рівності, обов’язково без пробілів. Значення атрибутів обов’язково заключаються в лапки. Лапки в значеннях атрибутів не допускаються, замість них слід вживати сутність " (відміна за допомогою зворотньої косої \ не працює).
Згідно правил мови HTML теги, невідомі браузеру, не відображаються. Отже, якщо підстановка полів не виконується, то одинарний тег Смереки залишиться невидимим, а подвійний тег буде відображено як Текст підстановки.
Смеретеги-атрибути
Згідно правил мови HTML значення атрибута не може бути тегом. Щоб обійти це обмеження, Смерека пропонує альтернативний синтаксис смеретегів, де замість ламаних дужок використовуються фігурні :
З використанням такого альтернативного синтаксису можна будувати коректні конструкції на кшталт :
<img src="" />
Вкладені смеретеги
Смеретеги, записані з використанням синтаксису
<Smereka [список атрибутів]>Текст підстановки</Smereka>
можуть містити в тексті підстановки інші смеретеги. Для того, щоб правильно вказати послідовність замикаючих тегів </Smereka>, необхідно вживати числові суфікси :
<Smereka10 [список атрибутів]> Статичний текст підстановки <Smereka5 [список атрибутів]>Динамічний текст підстановки</Smereka5> <Smereka5 [список атрибутів]>Інший динамічний текст підстановки</Smereka5> <Smereka [список атрибутів]> Глибше вкладений текст </Smereka> </Smereka10>
Загальне правило полягає в тому, що текст підстановки не повинен містити тега 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.
Функція мусить повернути результат як рядок або порожній рядок, якщо виникла помилка.
Аналогічні правила діють і для методів, які передбачається викликати через смеретеги.