Логотип

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

Макросы: протокол UData

Протокол UData предназначен для получения результата выполнения макросов в XML-формате. Рассмотрим применение протокола UData в XSLT-шаблонах на примере макроса %content menu()%.

Просмотр результатов работы макросов в виде XML

Чтобы увидеть результат работы макроса %content menu()% в XML-формате, наберем в адресной строке браузера http://ваш_сайт/udata/content/menu. Вы увидите страницу, подобную следующей:

<?xml version="1.0" encoding="utf-8" ?>
<udata module="content" method="menu">
    <items>
        <item id="22896" link="/"
            xlink:href="upage://22896">О компании</item>
        <item id="16520" link="/market/"
            xlink:href="upage://16520">Каталог</item>
        <item id="16528" link="/contacts/"
            xlink:href="upage://16528">Контакты</item>
    </items>
</udata>

Замечание

Для версий до 2.8: если на странице http://ваш_сайт/udata/content/menu отображается сообщение, что протокол UData недоступен, создайте в корневой папке сайта пустой файл с именем scheme.udata.allow и обновите страницу.

Для версий, начиная с 2.8: необходимо указать параметр udata.http.allow = "1" в файле config.ini в секции [streams] (см. Секция [streams]).

Внимание

Из соображений безопасности после окончания этапа разработки файл scheme.udata.allow настоятельно рекомендуется удалить. В противном случае некоторые данные, получаемые по этому протоколу через http, могут быть доступны любому посетителю сайта.

Для версий, начиная с 2.8, рекомендуется отключить соответствующую настройку в config.ini.

Добавление результатов работы макроса в шаблон

Добавим меню в XSLT-шаблон с помощью функции document() и инструкции xsl:apply-templates:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:output method="html" encoding="utf-8" />

 <xsl:template match="/">
  <html>
    <head>
        <title><xsl:value-of select="/result/@title" /></title>
    </head>
    <body>

      <div id="main-menu">
        <ul>
          <xsl:apply-templates select="document('udata://content/menu')//item" mode="menu" />
        </ul>
      </div>

      <div id="content">
        <h1><xsl:value-of select=".//property[@name ='h1']/value" /></h1>
        <xsl:value-of select=".//property[@name ='content']/value" disable-output-escaping="yes"/>
      </div>
    </body>
  </html>
 </xsl:template>

 <xsl:template match="item" mode="menu">
   <li>
     <a href="{@link}"><xsl:value-of select="." /></a>
   </li>
 </xsl:template>

</xsl:stylesheet>

Первый выделенный жирным шрифтом фрагмент означает, что в начале страницы будут выведены пункты меню сайта, второй фрагмент — что для каждого элемента item будет выведена ссылка на адрес, заданный в атрибуте link данного элемента item, текстом которой служит текст данного элемента item (см. результаты макроса выше). После обновления страницы http://ваш_сайт/mypage вы увидите на ней меню сайта.

То что, второй блок <xsl:template></xsl:template> будет обрабатывать элементы item определяется по условию match="item".

Добавление результатов работы макроса с параметрами

Рассмотрим теперь пример вызова макроса с параметрами, например, %news lastlist('/vse_novosti/novosti_ekonomiki/', default, 3)%, где '/vse_novosti/novosti_ekonomiki/' — путь до ленты новостей, default — имя шаблона для вывода списка новостей, 3 — максимальное количество новостей на странице. Если при вызове макроса в XSLT-шаблоне одним из параметров является URL, то его необходимо заключить в круглые скобки. Таким образом, вызов макроса в XSLT-шаблоне должен выглядеть следующим образом:

<xsl:apply-templates select= "document('udata://news/lastlist/(/vse_novosti/novosti_ekonomiki/)/default/3')//item" mode="news"/>

В строке udata://news/lastlist/(/vse_novosti/novosti_ekonomiki/)/default/3, news соответствует модулю, lastlist — методу, далее следуют параметры.

Для того, чтобы вызвать макрос с динамическими параметрами, необходимо воспользоваться функцией concat():

<xsl:apply-templates select= "document(concat('udata://news/lastlist/', result/@pageId, '/default/3'))//item" mode="news"/>

При запросе из шаблона, рассмотренного выше, вместо result/@pageId, будет подставлен идентификатор текущей страницы (атрибут pageId тега result: см. «Формат UMI Data»).

Кэширование результатов вызова

Если установлен один из кэширующих бекэндов и включено кэширование на сайте, можно управлять кэшированием результатов вызова по протоколу UData. Для этого укажите после вызова по протоколу параметр ?expire = время_кэширования_в_секундах. Например:

<xsl:apply-templates select="document('udata://content/menu?expire=600')//item" mode="menu" />

Получение расширенных полей и групп

В версии 2.8.6 появилась возможность получать расширенные поля и группы полей через протокол UData. Данная возможность предназначена для удобства разработки сайта и знакомства со структурой объектов UMI.CMS. По умолчанию она отключена. Для включения этой возможности необходимо в файле настроек "config.ini", в секции "streams", выставить значение параметра udata.http.extended.allow равным "1". Чтобы посетители вашего сайта не смогли воспользоваться данной возможностью, выставьте значение параметра udata.http.allow равным "0", а также добавьте все необходимые ip-адреса в исключения, это можно сделать с помощью параметра udata.http.ip-allow секции "streams", в котором вам нужно будет указать ip-адреса через запятую.

Чтобы указать какие расширенные поля или группы полей Вы хотите получить в ответе макроса, необходимо к запросу добавить get-параметры "extProps" и/или "extGroups" соответственно. Список необходимых полей и групп указывается через запятую. Например:

<xsl:apply-templates select="document('udata://catalog/getObjectsList/void/(/market/hamsters/)/?extProps=price,photo&extGroups=short_info')" />

В результате отработки макроса с указанными параметрами будет получен примерно следующий ответ:


<udata module="catalog" method="getObjectsList" generation-time="0.215164">
    <lines>
        <item id="10" alt_name="homyachok_pushistyj" link="/market/hamsters/homyachok_pushistyj" xlink:href="upage://10">Хомячок пушистый
            <extended>
                <properties>
                    <property id="218" name="price" type="price">
                        <title>Цена</title>
                        <value xlink:href="udata://emarket/price/406">159</value>
                    </property><property id="369" name="photo" type="img_file">
                        <title>Фотография</title>
                        <value path="./images/cms/data/hamster_angor.jpg" folder="/images/cms/data" name="hamster_angor" ext="jpg" width="250" height="181">/images/cms/data/hamster_angor.jpg</value>
                    </property>
                </properties>
                <groups>
                    <group id="282" name="short_info">
                        <title>Краткие характеристики</title>
                        <property id="371" name="weight" type="float">
                            <title>Вес</title>
                            <value>211</value>
                        </property>
                        <property id="372" name="color" type="relation">
                            <title>Окрас</title>
                            <value>
                                <item id="356" name="Полосатый" type-id="109" ownerId="10" xlink:href="uobject://356"/>
</value> </property> <property id="373" name="vid" type="relation"> <title>Вид</title> <value> <item id="364" name="Ангорский" type-id="110" ownerId="10" xlink:href="uobject://364"/> </value>
</property> <property id="374" name="gender" type="relation"> <title>Пол</title> <value> <item id="371" name="Самец" type-id="111" ownerId="10" xlink:href="uobject://371"/> </value> </property> </group> </groups> </extended> </item> ... </lines> </udata>

Поля и группы находятся в блоке "extended". Блок "properties" содержит поля, а блок "groups" - группы.

Результаты работы макросов в формате JSON

Для того чтобы получить результаты работы макроса в формате JSON, допишите после вызова ".json".