Выборки из БД: протокол USel

Выборки из БД: протокол USel
	Глава 2. XSLT-шаблонизатор UMI.CMS

Выборки из БД: протокол USel

Протокол USel обеспечивает доступ к базе данных UMI.CMS. Выборки из базы производятся по шаблонам, которые представляют собой XML-файлы в определенном формате.

При запросе ресурса по протоколу USel выборка производится следующим образом:

По URI определяется название XML-файла, в котором описан запрос выборки
В шаблон выборки подставляются параметры, переданные в URI
Выполняется выборка данных из БД
Результат выборки преобразуется в XML-документ и возвращается в качестве содержания ресурса

Все XML-файлы, которые содержат шаблоны USel должны находится в папке ~/usels/.

Просмотреть результаты, возвращаемые по указанному шаблону, можно набрав в адресной строке http://ваш_сайт/usel/имя_шаблона

Замечание

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

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

Правила разбора URI

Выборка без параметров

Пример URI:

usel://getSpecialNews/

Вернет результаты выброки по шаблону, описанному в файле ~/usels/getSpecialNews.xml

Выборка по параметрам

Пример URI:

usel://getSomeCatalogItems/10/?limit=5

Вернет результаты выброки по шаблону, описанному в файле ~/usels/getSomeCatalogItems.xml и подставит в шаблон вместо параметра {1} значение 10, а вместо {limit} — значение 5.

Формат файла

Тег "selection"

Корневой тег, который может содержать следующие теги:

target
property
sort
limit

Тег "target"

Тег target содержит теги, которые указывают, по какому типу данных необходимо отфильтровать результат, а также характер выборки (иными словами, ожидаемый результат).

Ожидаемый результат выборки указывается атрибутом expected-result и может принимать 5 значений:

objects — выборка вернет результат, состоящий из набора тегов object, которые соответствуют объектам системы (пользователи, заказы, баннеры и т.п.)
objects count — вернет тоже, что и objects, но в конец добавит тег total - общее количество результатов выборки без учета ограничения, указанного в теге limit
pages — выборка вернет результат, состоящий из набора тегов "page", которые соответствуют страницам системы (страницы контента, новости, объекты каталога и т.п.)
pages count — вернет тоже, что и pages, но в конец добавит тег total - общее количество результатов выборки без учета ограничения, указанного в теге limit
count — вернет только число, которое соответствует количеству объектов в выборке, согласно запросу

Внутри тега target могут находится теги type и category (Обратите внимание, что отсутствие этих тегов так же допустимо).

<target expected-result="pages">
 <type module="news" method="item" />
 <category>/news/politicheskiy_novosti/</category>
</target>

При использовании expected-result = "count" по умолчанию считается количество объектов. Для того, чтобы явно задать необходимость считать количество страниц, нужно добавить атрибут force-hierarchy = "1":

<target expected-result="count" force-hierarchy="1">
 <type module="news" method="item" />
</target>

Тег "type"

Указывает тип данных, по которому будут фильтроваться результаты выборки.

Этот тег может встречаться несколько раз в рамках тега target. В таком случае они будут объединены логическим "ИЛИ". Есть 2 способа указать тип данных используя тег type:

Указать id типа данных, используя атрибут id:

<!-- Соответствует типу "Пользователь" -->

<type id="4" />

Указать назначение типа данных, используя атрибуты module и method:
```


<type module="news" method="item" /> 
```
При идентификации при помощи атрибутов module и method для фильтрации будут использоваться только поля базового типа данных. При необходимости добавить дополнительное поле, либо добавьте его в базовый тип, либо используйте тег type c указанием id типа.

Список всех назначений типов можно посмотреть при помощи макроса system/hierarchyTypesList (см. «Дополнение: макрос /system/hierarchyTypesList»). Эти же сведения доступны в настройках модуля "Шаблоны данных".

Замечание

Если посмотреть на назначение типа "страницы контента", можно увидеть, что атрибут method у этого типа отсутствует. Чтобы использовать в вызовах USel привязку к типу "страницы контента" необходимо определять тег type следующим образом:

<type module="content" method="page" />

Тег "category"

Этот тег позволяет фильтровать результаты выборки по определенному разделу в дереве сайта. В качестве значения тега можно указать либо путь до страницы, либо id страницы:

<category>/market/</category>
<category>23771</category>

Помимо раздела можно указать глубину поиска атрибутом "depth". По умолчанию его значение равно "0", что означает в данном случае поиск только в данном разделе без поиска по подразделам.

<!-- Искать в разделе "/market/" и в его подразделах на 1 уровень глубины -->

<category depth="1">/market/</category>

Обратите внимание, что для выборки элементов из корня сайта, необходимо указывать идентификатор "0" а не путь "/" :

<category>0</category>

В рамках тега target, тег category можно использовать несколько раз.

Тег "domain"

Указывает домен, по которому будет проводиться выборка.
Можно указывать как имя домена, так и его id:

<domain>site.ru</domain>

<domain>2</domain>

Тег "property"

Позволяет фильтровать результаты выборки по значениям свойств. Тег property может иметь только 3 атрибута:

name — обязательный атрибут, который содержит название поля, по которому необходимо производить фильтрацию. Название поля всегда соответствует своему идентификатору в шаблонах данных за исключением 3 случая, когда в качестве значения атрибута "name" указано "name". В этом случае считается, что фильтрация происходит по названию объекта.
value — содержание, по которому необходимо проводить фильтрацию. Обязательность этого атрибута зависит от типа поля.
mode — необязательный атрибут который принимает значение "not" или "like".

В случае like будет искаться неточное соответствие значению, указанному в параметре value:
```
<property name="h1" value="хомя" mode="like"/>
```
В случае not при фильтрации по этому полю будет использоваться логическое отрицание: то есть будут выбраны все объекты или страницы, которые не содержат указанного значения:
```
<property name="active" value="1" mode="not"/>
```
Обратите внимание, что при использовании поля типа "Выпадающий список с множественным выбором", содержащего несколько значений, применение атрибута not при фильтрации по этому полю не приведет к ожидаемому результату, и объект (либо страница) все равно будет найден. Это связано с особенностями хранения данных поля этого типа в БД UMI.CMS.

Способ задания значения для фильтрации зависит от типа поля.

Для следующих строковых полей можно задавать значение внутри атрибута value (точное соответствие):
- строка
- текст
- HTML-текст
- теги
- изображение
- файл
- число
- число с точкой
- цена
- дата
```
<property name="login" value="sv" />
```

Для типа "кнопка-флажок" значение указывается в атрибуте value и может быть равно либо "0", либо "1".
Для числовых полей и полей, содержащий даты можно указать значение атрибуте value (тогда будет искаться точное сообщение), либо можно использовать интервальный поиска (используя теги min-value и max-value. Это актуально для следующих типов:
- число
- число с точкой
- цена
- дата
```


<property name="price">
 <min-value>100</min-value>
 <max-value>500</max-value>
</property>
```
Для фильтрации по полям типов "ссылка на дерево", "выпадающий список" и "выпадающий список со множественным выбором" необходимо указывать значения используя теги page (для типа "ссылка на дерево") или object (для типа "выпадающий список").

Тег "object"

Используется для фильтрации по полям типа "выпадающий список" и "выпадающий список со множественным выбором".

Находится внутри тега property и может указываться там несколько раз. В этом случае значения будут объединены логическим "ИЛИ". Внутри тега object указывается id объекта.

<!-- найти все объекты или страницы, у которых свойство "delivery_address" равно "26564" -->

<property name="delivery_address">
 <object>26564</object>
</property>

Тег "page"

Используется для фильтрации по полям типа "ссылка на дерево".

Находится внутри тега property и может указываться там несколько раз. В это случае значения будут объединены логическим "ИЛИ". Внутри тега page указывается id страницы, либо путь до страницы.

<!-- Найти все страницы, либо объекты, 
у которых свойство "recommend" равно странице с адресом "/market/akse.../", 
либо странице с id равным "23025" -->

<property name="recommed">
  <page>/market/aksessuary_dlya_homyachkov/povodki/povodok_leopardovyj/</page>
  <page>23025</page>
</property>

Теги "min-value" и "max-value"

Теги min-value и max-value используются для фильтрации числовых полей по принципу "не меньше чем" и "не больше чем":

min-value — указывает минимальное значение для фильтрации
max-value — указывает максимальное значение для фильтрации

<!-- Найти все объекты или страницы, у которых значение поля "price" больше, чем "50" -->

<property name="price">
 <min-value>50</min-value>
</property>

<!-- Найти все объекты или страницы, у которых значение поля "price" меньше, чем "150" -->

<property name="price">
 <max-value>150</max-value>
</property>

Для полей типа "дата" можно задать формат значения для поиска, используя атрибут format ("timestamp" либо "UTC").

<property name="last_request_time">
 <min-value format="timestamp">3600</min-value>
 <max-value format="UTC">2007-11-10 14:48:10</max-value>
</property>

Тег "sort"

Задает поле для сортировки результатов выборки. Атрибутом order задается направление сортировки:

ascending — по возрастанию значения поля, указанного в теге order
descending — по убыванию значения поля, указанного в теге order

По умолчанию считается, что атрибут order равен ascending.

<!-- Отсортировать результаты выборки в обратном порядке по полю "publish_time" -->

<sort order="descending">publish_time</sort>

Помимо названия поля, данный тег может принимать следующие специальные значения:

name — сортировать по имени объекта.
ord — сортировать по порядку страниц.
rand() — сортировать в случайном порядке; в этом случае атрибут order использовать не надо.

<!-- Отсортировать результаты выборки в случайном порядке -->

<sort>rand()</sort>

Замечание

Если ожидаемый результат выборки count, то тег sort игнорируется.

Тег "limit"

Используется для ограничения размера выборки и организации постраничного вывода информации.

В качестве значения тега передается количество элементов, которые будут присутствовать в выборке. Атрибут page используется для того, чтобы указать, какую страницу данных вернуть в результате выборки.

<!-- Вывести только 10 первых объектов или страниц в результате выборки -->

<limit page="0">10</limit>

Замечание

Если ожидаемый результат выборки count, то тег limit игнорируется.

Тег "option"

Используется для применения к выборке различных дополнительных условий. Имеет два атрибута:

name — обязательный атрибут, который содержит название опции.
value — значение, которое передаётся в опцию.

<!-- Объединить параметры поиска по полям логическим ИЛИ -->
<option name="or-mode" value="1" />

<!-- Производить поиск страниц только в корне сайта -->
<option name="exclude-nested" value="1" />

Передача параметров в шаблон выборки

Для более гибкого использования шаблонов выборок в протоколе USel можно использовать параметры. Для этого в шаблоне выборки конкретные значения убираются и помечаются особым форматированием: "{...}".

Есть 2 вида параметров, использующихся в шаблонах USel:

Индексированные параметры — эти параметры передаются через "/"
Именованные параметры — эти параметры передаются после знака "?", аналогично GET-параметрам в HTTP-запросе.

Индексированные параметры

Индексированные параметры передаются в запросе также, как и параметры макросов в протоколе UData:

usel://someSelection/param1/param2/param3

В шаблоне выборки для подстановки будут использоваться {1}, {2}, {3} соответственно.

Именованные параметры

Именованные параметры передаются как параметры запроса наподобие GET-параметров:

usel://someSelection/?limit=10&page=3

Для подстановки их в шаблон выборки нужно писать {limit}, {page}. Например:

<limit page="{page}">{limit}</limit>

Дополнение: макрос /system/hierarchyTypesList

Макрос /system/hierarchyTypesList существует только в версии для XSLT. Этот макрос выводит в XML-формате перечень зарегистрированных в системе назначений типов объектов.

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

<?xml version="1.0" encoding="utf-8" ?>
<udata module="system" method="hierarchyTypesList">
    <items>
        <item id="2" module="content">Страницы контента</item>
        <item id="4" module="users" method="user">Пользователи</item>
        <item id="5" module="catalog" method="category">Разделы каталога</item>
        <item id="6" module="catalog" method="object">Объекты каталога</item>
        <item id="8" module="users" method="users">Группы пользователей</item>
        <item id="9" module="news" method="rubric">Ленты новостей</item>
        <item id="11" module="news" method="subject">Сюжет публикации</item>
        <item id="12" module="vote" method="poll">Опрос</item>
        <item id="13" module="vote" method="poll_item">Ответ в опросе</item>

    …другие типы…

    </items>
</udata>

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

Аналогично кешированию результов вызова по протоколу UData (см. «Макросы: протокол UData»).

Выборки из БД в формате JSON

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