Логотип

Документация по макросам и шаблонам UMI.CMS

Формирование данных на сервере: протокол UMap

Описание

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". В зависимости от сериализатора, могут происходить следующие события:

  1. Преобразование данных

  2. Отправка клиенту необходимых заголовков и вывод содержимого буфера в браузер

  3. Сохранение данных в файл

Следующий пример возьмет карту сайта по адресу 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>
Была ли данная статья полезна?