Описание
Umap - это средство для формирования данных на сервере в формате удобном для клиентской части приложения (ajax, flex).
На данный момент это единичный файл, который должен находиться по адресу ~/umaps/sitemap.xml
(или по адресу ~/templates/{имя_шаблона}/umaps/sitemap.xml
при использовании нового формата хранения шаблонов), и соответствовать схеме Umap.xsd
Предположим, что нам нужно предоставить стороннему сервису RSS-ленту (адрес ленты фиксирован требованиями стороннего сервиса - "ваш_сайт/newsfeed.xml") из новостей, которые выводятся кастомным макросом udata://news/newsfeed
. Проще всего сделать это именно через протокол Umap.
Формат файла
Файл sitemap.xml состоит из секций match
. Если такой файл существует, то при запуске системы путь в адресной строке анализируется на соответствие атрибуту pattern
каждого тега match
в файле sitemap.xml. Если соответствие найдено, то поиск прекращается и начинается обработка содержания тега match
. Если ни одного соответствия не найдено, то управление передается обратно системе.
Набор секций match
обрамляется корневым тегом sitemap
. Он может содержать атрибут @cache
.
Тег "match"
Для того чтобы при запросе newsfeed.xml отрабатывали наши условия - используем следующую конструкцию:
<match pattern="newsfeed.xml">
...
</match>
Атрибут "@pattern
" должен содержать любое регулярное выражение, по которому система определит, какую секцию файла sitemap.xml использовать. Например, если мы хотим сделать несколько новостных лент, скажем: /newsfeed/technology
, /newsfeed/sport
и т.д. мы можем использовать регулярное выражение вида ^newsfeed/(.*)$
и в дальнейшем использовать все то что удовлетворяет (.*)
в качестве параметров, определяющих результат на этапе генерации или трансформации данных.
Тег "generate"
Тег generate
определяет источник данных, который будет использован для секции. В атрибуте @src
указывается URI источника данных.
В атрибуте match может быть указан только один раз. В противном случае система выдаст ошибку.
После получения XML, данные помещаются в буфер, чтобы использоваться потом в качестве источника данных в тегах transform
, validate
и serialize
. Указывать в качестве источника данных можно:
Адрес локального XML-файла:
<generate src="./data/somefile.xml" />
Адрес удаленного XML-файла:
<generate src="http://www.somesite.ru/news/rss.xml" />
Адрес ресурса протокола UMI:
<generate src="udata://content/sitemap/" />
Тег "transform"
Инструкция transform
получает подготовленный xml-документ из буфера и совершает над ним xslt-преобразование
, используя xslt-шаблон, указанный в атрибуте @src
.
<transform src="./xsltTpls/newsfeed.xsl" />
После преобразования получившийся документ снова помещается в буфер и может быть использован либо для повторного преобразования (еще один тег transform
), либо для валидации (validate
) либо сериализации. Тег
transform
может быть указан 1 и более раз, либо не указан вовсе. Если тег не указан, то XML-документ в буфере не изменяется и передается дальше по конвейеру на валидацию или сериализацию.В случае использования тега
transform
несколько раз внутри одной секции match
, помните, что преобразования выполняются последовательно сверху вниз.Тег "validate"
Это инструкция для валидации XML-документа, находящегося в буфере. Позволяет проверять документ при помощи XML Schema, либо DTD. Если документ успешно проходит валидацию - осуществляется переход к следующей инструкции, в противном случае генерируется ошибка.
Пример использования валидации через dtd:
<validate dtd="./dtd/myformat.dat" />
Пример использования валидации через XML Schema:
<validate xsd="./xsd/myformat.xsd" />
Тег "serialize"
Берет данные из буфера, передает их в сериализатор, указанный в атрибуте @type
и запускает процесс сериализации. По умолчанию можно использовать параметры "xml", "html" или "file". В зависимости от сериализатора, могут происходить следующие события:
-
Преобразование данных
-
Отправка клиенту необходимых заголовков и вывод содержимого буфера в браузер
-
Сохранение данных в файл
Следующий пример возьмет карту сайта по адресу udata://content/sitemap/
, преобразует ее используя xslt-шаблон ./xsltTpls/plainSitemap.xsl
и выведет в броузер как html-файл:
<match pattern="^my\.xml$">
<generate src="udata://content/sitemap/" />
<transform src="./xsltTpls/plainSitemap.xsl" />
<serialize type="html" />
</match>
Вывод XML без трансформаций как xml-файл:
<match pattern="^my\.xml$">
<generate src="udata://content/sitemap/" />
<serialize type="xml" />
</match>
Передача HTTP-заголовков сериализатору
Cериализатор может принимать список заголовков в качестве параметров. Например:
<match pattern="^my\.xml$">
<generate src="udata://content/sitemap/" />
<transform src="./xsltTpls/plainSitemap.xsl" />
<serialize type="html">
<param name="headers">
<param name="Status" value="301 Moved" />
<param name="Location" value="http://localhost/" />
</param>
</serialize>
</match>
Тег "redirect"
Совершает редирект на страницу с адресом, указанным в атрибуте @uri
. Пример:
<match pattern="^old_url$">
<redirect uri="/new_url/" />
</match>
Опционально можно задать HTTP-статус, с которым будет совершено перенаправление:
<match pattern="^old_url$">
<redirect uri="/new_url/">
<param name="status" value="301" />
</redirect>
</match>
В теге match
может присутствовать только 1 тег redirect
.
Пример файла sitemap.xml
<?xml version="1.0" encoding="utf-8"?>
<sitemap cache="10000">
<match pattern="^umaps.test.ajax.search$">
<param name="cache" value="10" />
<generate src="udata://search/search_do//{q}" />
<transform src="./xsltTpls/ajax/search.xsl" />
<serialize type="xml" />
</match>
<match pattern="search.ajax">
<param name="cache" value="60" />
<generate src="udata://search/search_do//{q}" />
<transform src="./xsltTpls/ajax/search.xsl" />
<serialize type="xml" />
</match>
<match pattern="search.html">
<param name="cache" value="60" />
<generate src="udata://search/search_do//{q}" />
<serialize />
</match>
<match pattern="^images/(.*)$">
<generate src="ufs://images/{1}" />
<serialize type="xml" />
</match>
</sitemap>