Протокол USel

Протокол для работы с данными системы. Представляет собой интерфейс для доступа к API-классу umiSelection. Позволяет создавать шаблоны выборок из базы данных и в дальнейшем использовать их точно так же, как макросы.

Описание

Протокол usel обеспечивает доступ к базе данных UMI.CMS используя API функции (классы umiSelection и umiSelectionParser). Выборки из базы производятся по шаблонам, которые представляют собой XML-файлы в определенном формате. При запросе ресурса по протоколу usel производится следующим образом:

1. По URI определяется название XML-файла, в котором описан запрос выборки
2. В шаблон выборки подставляются параметры, переданные в URI
3. Шаблон выборки трансформируется в объект выборки (umiSelection)
4. Выполняется выборка данных из БД (umiSelectionParser)
5. Результат выборки преобразуется в XML-документ и возвращается в качестве содержания ресурса

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

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

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

Пример URI:

usel://getSpecialNews/

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

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

Пример URI:

usel://getSomeCatalogItems/10/

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

Тег "selection"

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

• target
• property
• sort
• limit

Тег "target"

Тег target содержит теги, которые указывают, по какому типу данных необходимо отфильтровать результат, а также характер выборки (иными словами, ожидаемый результат). Ожидаемый результат выборки указывается атрибутом expected-result и может принимать 3 значения:

• objects - выборка вернет результат, состоящий из набора тегов "object", которые соответствуют объектам системы (класс umiObject: пользователи, заказы, баннеры и т.п.)
• objects count - вернет тоже, что и objects, но в конец добавит тег total - общее количество результатов выборки без учета limit
• pages - выборка вернет результат, состоящий из набора тегов "page", которые соответствуют страницам системы (класс umiHierarchyElement: страницы контента, новости, объекты каталога и т.п.)
• 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="pages" необходимо указать хоть один иерархический признак, по которому будет строиться запрос(category). Например:

<target expected-result="pages">
  <type id="802" />
  <category depth="10">/news/</category>
</target>

При использовании expecteed-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" /> <!-- Соответствует всем новостям на сайте -->

Тег "category"

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

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

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

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

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

Тег "property"

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

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

Еще одно возможное значение появилось в 2.6: like, обозначает, что будет искаться неточное соответствие.

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

• Для следующих строковых полей можно задавать значение внутри атрибута "value" (точное соответствие):
  • Строка
  • Текст
  • HTML-текст
  • Теги
  • Изображение
  • Файл
  • Число
  • Число с точкой
  • Цена
  • Дата

<property name="login" value="lyxsus" />

• Для типа "Кнопка-флажок" значение указывается в атрибуте "value" и может быть равно, либо не равно "1".

<!-- Выбрать все объекты или страницы, у которых чекбокс chk_box включен. -->

<property name="chk_box" value="1" />

<!-- Выбрать все объекты или страницы, у которых чекбокс chk_box выключен. -->

<property name="chk_box" mode="not" value="1" />

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

<!-- Выбрать все объекты или страницы, у которых значение поля "price" больше 100, но меньше 500. -->
<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", то этот тег игнорируется.

Тег "limit"

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

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

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

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

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

1. Индексированные параметры - передаются через "/")
2. Именованные параметры - передаются после знака "?" аналочино 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>

Список протоколов

• udata://
• upage://
• uobject://
• ufs://
• umap://