Протокол USel

Материал из Umicms
Перейти к:навигация, поиск

Протокол для работы с данными системы. Представляет собой интерфейс для доступа к 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>

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

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

Тег "type"

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

<type id="4" /> <!-- Соответствует типу "Пользователь" -->

<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, обозначает, что будет искаться неточное соответствие.

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

<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>


Тег "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>
Источник — «https://wiki.umisoft.ru/index.php?title=Протокол_USel&oldid=8881»