Доку пишу (по мере свободного времени). В принципе все до безобразия просто:
В метаязыке есть секции (можно сказать аналог BEGIN ... END). В секции можно описать переменные-http-параметры, просто переменные, временную таблицу для указанного http-параметра, если он передается как множество значений, назначить секции запрос (т.е. тело секции будет выполнено на каждую запись запроса), назначить алиасы на переменные и поля (то есть вместо назначенного алиаса в тексте будет вставляться значение указанной переменной или поля) и работать с макросами, импортируя их с библиотеки макросов или описывая прямо внутри секции (макрос - аналог include - то есть при указании макроса в шаблоне, вместо него будет осуществлена вставка тела макроса, которое будет еще раз обработано на случай, если в нем есть другие управляющие операторы, например скрипт WatcomSQL или вызов другого макроса, подробнее о макросах нужно писать большую главу, фактически их следует рассматривать как inline повторно используемые вставки).
Общая структура секции такая (| указывает на возможность использования один из предложенных синтаксисов):
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
<!-- просто текст шаблона -->
<html>
<head>
<title>Тест</title>
</head>
<body>
<!-- начало описания секции SectionName -->
<!--<section name="SectionName"
sql="SELECT Field1 FROM Table1" | sql="{Text_SQL}"
>
<field name="Param1" alias="[Param1]" type="int" param="Param1"/>
<params name="#Param2" type="char(10)" param="Param2"/>
<field name="Var1" alias="[Var1]" type="long varchar" value="NULL"/>
<field name="Field1" alias="[Field1]"/>
<import name="Lib1.*"/>
<macro name="Macros1" type="T">Field1 = "[1]"</macro>
</section>-->
<!-- текст секции !-->
<!--!
// Выполнение кода WatcomSQL,
// который не будет виден при просмотре HTML шаблона
// в браузере и выглядеть как комментарий
SELECT List(Value, ',' ORDER BY NUM)
INTO @Var1
FROM #Param2;
!-->
<p {!
// Выполнение кода WatcomSQL,
// который будет виден при просмотре HTML шаблона
// в браузере и зато может удобно использоваться внутри HTML-тегов,
// в которых не разрешены вставки HTML-комментариев
IF @Var1 = ''
THEN
@Var1 = '*** нет переданных параметров ***';
END IF;
!} title="{*Macros1 {[Field1]}*}" >
Передан параметр с браузера: <b>[Param1]</b>
<br>
Переданы следующие значения параметра Param2: <b>[Var1]</b>
<br>
Поле Field1 равно: <b>[Field1]</b>
<br>
Результат Macros1: <!--*Macros1 {[Field1]}*-->
</p>
<!--</SectionName/>-->
<!-- конец секции SectionName -->
</body>
</html>
Здесь обьявляется секция "SectionName". Внутри нее обьявляются http-параметр Param1, переданный браузером. Так же обьявляется переменная Var1, инициализирующаяся начальным значением NULL (или можно было не указывать инициализирующее значение), в которую запросом собираются значения из временной таблички #Param2, обьявленной на значения http-параметра Param2. Сама секция создана как курсор на явно указанный запрос или же можно указать на переменную Text_SQL, в которой хранится текст запроса. На параметр Param1, переменную Var1 и поле запроса Field1 назначены соотвествующие алиасы [Param1], [Var1] и [Field1] - везде где они будут встречены в тексте, будет произведена замена на их реальные значения. Так как секция создана на запрос, то ее тело будет в результирующем тексте повторено столько раз, сколько запрос имеет записей. В ходе компиляции html-контента вместо макросов будут подставлены их тексты. В ходе уже выполнения генерации контента вставки кода на WatcomSQL будут выполнятся. Так что на выходе браузер получит примерно следующее:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
<!-- просто текст шаблона -->
<html>
<head>
<title>Тест</title>
</head>
<body>
<!-- начало описания секции SectionName -->
<p title="Field1 = "1">
Передан параметр с браузера: <b>100</b>
<br>
Переданы следующие значения параметра Param2: <b>A, B, C, D, E</b>
<br>
Поле Field1 равно: <b>1</b>
<br>
Результат Macros1: Field1 = "1"
</p>
<p title="Field1 = "2">
Передан параметр с браузера: <b> 100 </b>
<br>
Переданы следующие значения параметра Param2: <b>A, B, C, D, E</b>
<br>
Поле Field1 равно: <b> 2 </b>
<br>
Результат Macros1: Field1 = "2"
</p>
<p title="Field1 = "3">
...
</p>
<!-- конец секции SectionName -->
</body>
</html>
Что поддерживается:
1. Можно иметь вложенные секции, если в запросе вложенной секции сослаться на поле ее родительской, то таким образом можно элементарно организовать master-detail
2. Есть область видимости обьявленных переменных секций, где в дочерней секции можно обьявить переменную с таким же именем, как и родительской (вернее она уж правильнее сказать есть в WatcomSQL и просто мной используется).
3. Есть область видимости обьявленных алиасов, так же как и с переменными.
4. Вставки кода на WatcomSQL и указания макросов можно производить 2-мя способами:
Через html-комментарий: <!--! WatcomSQL !--> <!--* Macros *-->
Через дополнительный тег: {! WatcomSQL !} {* Macros *}
в тексте удобнее комментарии, чтобы при визуальном просмотре самого шаблона не было видно вставок и шаблон не ехал. Внутри описания HTML-тэгов удобнее через дополнительный тег, чтобы браузер увидел HTML-тэг в шаблоне, что он не смог бы сделать в комментарии.
5. Если http-параметр обьявлен в секции, но не был передан, то он будет иметь значение NULL.
6. Если http-параметр обьявлен в секции как набор значений, но не передан, то его указанная временная таблица будет не содержать записей.
7. Естественно внутри HTML шаблона можно описывать формы, пользоваться JavaScript и прочим.
8. Читать и писать на WatcomSQL генерируемый поток контента, который хранится в временной таблице #Result (Line). Таким образом можно спокойно в поток впихнуть из кода свои вставки, генерируя их на WatcomSQL, а не описывая их текстом шаблона.
9. Статическая и динамическая компиляция шаблона. При статической компиляции шаблона в БД создается WatcomSQL хранимая процедура, уже содержащая весь служебный код с текстом шаблона и все вставки макросов и WatcomSQL из шаблона, где ее просто достаточно вызвать. При динамической компиляции вызывается соотвествующая ХП MacroSQL, которой передается текст шаблона и на выходе она возвращает скомпилированный и готовый к выполнению через динамический SQL скрипт на WatcomSQL.
Ключевые слова
Описание параметров секции, ее тело и конец:
<!--section name="sectionname" sql="">
<name="" alias="" type="" value="" param=""/>
<params name="" type="" param=""/>
<import name=""/>
<macro name="" type=""> </macro>
</section>-->
<!--</sectionname/>-->
Ссылка на порядковый номер переданного параметра в макросе:
[1] [2] [3] ...
Вставка макроса:
<!--* MacrosName {Param1} {Param2} {Param3} ... *-->
{* MacrosName {Param1} {Param2} {Param3} ... *}
Выполнение кода WatcomSQL:
<!--! script; !-->
{! script; !}
Это то, что касается самого языка описания шаблонов. Помимо него есть система управления прототипами, позволяющая:
1. Визуально разрабатывать шаблоны, компилировать их и запускать.
2. Организовывать проекты (группы), состоящие из шаблонов, текстовых данных и бинарных данных.
3. Через единый веб-сервис централизованно организовать систему навигации сайта (где http-параметр Action определяет имя работающего режима проекта, и запускает соотвествующий шаблон на выполнение или же возвращает текст или бинарные данные). Разрешаются ссылки на шаблоны других проектов.
4. Поддерживается полное управление правами доступа к шаблонам по группам пользователей и групп пользователей. Так же есть поддержка прав вызова шаблонов проекта из другого проекта.
5. Осуществлять распостранение новых и измененных шаблонов посредством моей системы синхронизации версий БД (SCV).
P.S. Это вкратце. На самом деле система получилась неожидано сильно большая по функционалу и возможностям и в двух словах к сожалению ее не опишешь. Однако как мне кажется достаточно мощная - если посмотреть хотя бы на систему управления прототипами MacroSQL или уже реально работающий проект SCV, то видно, насколько получился мощный интерфейс, с показом информации, ее изменением, групповыми операциями и прочим. В принципе со всей уверенностью могу точно заявить, что например на системе MacroSQL прямо на ASA я могу накатать форумы, которые по возможностям для пользователей и модераторов, а так же по скорости будут однозначно превосходить форумы SQL.RU. В дальнейшем было бы неплохо поверх этой системы разработать движок веб-порталов, благо система управления контентом и права доступа уже существуют и неплохо работают. Плюс будет полезно в библиотеке макросов составить сборник полезных JavaScript. Ну и на будующее - сделать возможность интернализации шаблонов, правда пока сложно представляю, как это наиболее удачно сделать - как и любая палка о двух концах - с одной стороны код внутри шаблона дает преимущество по скорости написания, с другой стороны не дает возможность просто перерисовать шаблон на другой язык.
Еще P.S. Если будут желающие поюзать MacroSQL и помочь написать на него документацию, то я в принципе готов открыть его как freeware для ASA-шников, заодно дав доступ к SCV для получения последних обновлений по MacroSQL для синхронизации БД, где он используется. В принципе наверное выгодней его всем развивать как бесплатную систему, используя его возможности для разработки интернет и интранет решений как под свои проекты, так и отдельные (как мой к примеру SCV, куча приблуд по веб-администрированию проектов и серверов и прочих).
