Whoa в 14:28, 21 ноября 2018

2018-11-21T14:28:57Z

Cmac в 12:04, 2 марта 2012

2012-03-02T12:04:55Z

Danil: переименовал «Протокол usel» в «Протокол USel»

2010-09-07T13:53:53Z

переименовал «Протокол usel» в «Протокол USel»

Sv в 12:44, 24 декабря 2009

2009-12-24T12:44:59Z

Sv в 12:44, 24 декабря 2009

2009-12-24T12:44:40Z

Sv: Новая страница: «ротокол для работы с данными системы. Представляет собой интерфейс для доступа к API-клас…»

2009-12-24T12:44:30Z

Новая страница: «ротокол для работы с данными системы. Представляет собой интерфейс для доступа к API-клас…»

Новая страница

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

== Описание ==
Протокол '''usel''' обеспечивает доступ к базе данных '''UMI.CMS''' используя [[API]] функции (классы [[umiSelection]] и [[umiSelectionParser]]).
Выборки из базы производятся по шаблонам, которые представляют собой [[XML]]-файлы в определенном формате. При запросе ресурса по протоколу '''usel''' производится следующим образом:
# По [[URI]] определяется название [[XML]]-файла, в котором описан запрос выборки
# В шаблон выборки подставляются параметры, переданные в [[URI]]
# Шаблон выборки трансформируется в объект выборки ([[umiSelection]])
# Выполняется выборка данных из [[База данных|БД]] ([[umiSelectionParser]])
# Результат выборки преобразуется в [[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'''.
<source lang="xml">
<target expected-result="pages">
<type module="news" method="item" />
<category>/news/politicheskiy_novosti/</category>
</target>
</source>

При использовании '''expected-result="pages"''' необходимо указать хоть один иерархический признак, по которому будет строиться запрос('''category'''). Например:
<source lang="xml">
<target expected-result="pages">
<type id="802" />
<category depth="10">/news/</category>
</target>
</source>

При использовании '''expecteed-result="count"''' по умолчанию считается количество объектов. Для того, чтобы явно задать необходимость считать количество страниц, нужно добавить атрибут '''force-hierarchy''' со значением '''"1"''':
<source lang="xml">
<target expected-result="count" force-hierarchy="1">
<type module="news" method="item" />
</target>
</source>

=== Тег "type" ===
Указывает '''тип данных''', по которому будут фильтроваться результаты выборки. Этот тег может встречаться несколько раз в рамках тега [[target]]. В таком случае они будут объединены логическим "ИЛИ".
Есть 2 способа указать [[тип данных]] используя тег '''type''':
* Указать [[id типа данных]], используя атрибут '''"id"'''
<source lang="xml">
<type id="4" /> 
</source>
* Указать [[назначение типа данных]], используя аттрибуты '''"module"''' и '''"method"'''.
<source lang="xml">
<type module="news" method="item" /> 
</source>

=== Тег "category" ===
Данный тег позволяет фильтровать результаты выборки по определенному разделу в дереве сайта. В качестве значения тега можно указать либо [[путь до страницы]], либо [[id страницы]]:
<source lang="xml">
<category>/market/</category>
<category>23771</category>
</source>

Помимо раздела можно указать глубину поиска атрибутом '''"depth"'''. По умолчанию его значение равно '''"0"''', что означает в данном случае поиск только в данном разделе без поиска по подразделам.
<source lang="xml">
<category depth="1">/market/</category> 
</source>

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

== Тег "property" ==
Позволяет фильтровать результаты выборки по значениям свойств. Сам тег '''"property"''' может иметь только 2 атрибута:
* '''name''' - обязательный атрибут, который содержит [[название поля]], по которому необходимо производить фильтрацию. Название поля всегда соответствует своему идентификатору в шаблонах данных за исключением 3 случая, когда в качестве значения атрибута '''"name"''' указано '''"name"'''. В этом случае считается, что фильтрация происходит по [[Название объекта|названию объекта]].
* '''value''' - содержание, по которому необходимо проводить фильтрацию. Обязательность этого атрибута зависит от типа поля.
* '''mode''' - необязательный атрибут который принимает значение '''"not"'''. В этом случае при фильтрации по этому полю будет использоваться логическое отрицание: т.е. будут выбраны все объекты или страницы, которые '''не''' содержат указанного значения.
Еще одно возможное значение появилось в 2.6: '''like''', обозначает, что будет искаться неточное соответствие.

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

<source lang="xml">
<property name="login" value="lyxsus" />
</source>

* Для типа [[Кнопка-флажок (Тип поля)|"Кнопка-флажок"]] значение указывается в атрибуте '''"value"''' и может быть равно, либо не равно '''"1"'''.
<source lang="xml">


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

</source>

<source lang="xml">


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

</source>

* Для числовых полей и полей, содержащий даты можно указать значение атрибуте '''"value"''' (тогда будет искаться точное сообщение), либо можно использовать интервальный поиска (используя теги '''"min-value"''' и '''"max-value"'''. Это актуально для следующих [[Тип поля|типов]]:
** [[Число (Тип поля)|Число]]
** [[Число с точкой (Тип поля)|Число с точкой]]
** [[Цена (Тип поля)|Цена]]
** [[Дата (Тип поля)|Дата]]
<source lang="xml">

<property name="price">
<min-value>100</min-value>
<max-value>500</max-value>
</property>
</source>

* Для фильтрации по полям типов [[Ссылка на дерево (Тип поля)|"Ссылка на дерево"]], [[Выпадающий список (Тип поля)|"Выпадающий список"]] и [[Выпадающий список со множественным выбором (Тип поля)|"Выпадающий список со множественным выбором"]] необходимо указывать значения используя теги "page" (для типа "Ссылка на дерево") или "object" (для типа [[Выпадающий список (Тип поля)|"Выпадающий список"]]).

=== Тег "object" ===
Используется для фильтрации по полям типа [[Выпадающий список (Тип поля)|"Выпадающий список"]] и [[Выпадающий список со множественным выбором (Тип поля)|"Выпадающий список со множественным выбором"]]. Находится внутри тега '''"property"''' и может указываться там несколько раз. В это случае значения будут объединены логическим "ИЛИ". Внутри тега '''"object"''' указывается [[Id объекта|id объекта]].
<source lang="xml">

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

=== Тег "page" ===
Используется для фильтрации по полям типа [[Ссылка на дерево (Тип поля)|"Ссылка на дерево"]]. Находится внутри тега "property" и может указываться там несколько раз. В это случае значения будут объединены логическим "ИЛИ". Внутри тега "page" указывается [[Id страницы|id страницы]], либо [[путь до страницы]].
<source lang="xml">

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

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

<source lang="xml">

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

<source lang="xml">

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

Для полей типа [[Дата (Тип поля)|"Дата"]] можно задать формат значения для поиска используя атрибут '''format''' (на данный момент "timestamp" либо "UTC").
<source lang="xml">
<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>
</source>

== Тег "sort" ==
Задает поле для сортировки результатов выборки. Атрибутом '''"order"''' задается направление сортировки:
* '''"ascending"''' - по возрастанию значения поля, указанного в теге '''"order"'''
* '''"descending"''' - по убыванию значения поля, указанного в теге '''"order"'''
По умолчанию считается, что атрибут '''"order"''' равен '''"ascending"'''.
<source lang="xml">

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

Помимо названия поля, данный тег может принимать следующие специальные значения:
* '''"name"''' - сортировать по имени объекта.
* '''"ord"''' - сортировать по [[Порядок страниц|порядку страниц]].
* '''"rand()"''' - сортировать в случайном порядке. в этом случае атрибут '''"order"''' использовать не надо.
<source lang="xml">

<sort>rand()</sort>
</source>

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

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

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

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

== Передача параметров в шаблон выборки ==
Для более гибкого использования шаблонов выборок в протоколе '''usel://''' можно использовать параметры.
Для этого в шаблоне выборки конкретные значения убираются и помечаются особым форматированием: '''"{...}"'''.
Есть 2 вида параметров в протоколе '''upage://''':
# Индексированные параметры - передаются через "/")
# Именованные параметры - передаются после знака "?" аналочино GET-параметрам в HTTP-запросе.

=== Индексированные параметры ===
Индексированные параметры передаются в запросе также, как и параметры макросов в протоколе [[udata|udata://]]:
usel://someSelection/'''param1'''/'''param2'''/'''param3'''
В шаблоне выборки для подстановки будут использоваться '''{1}''', '''{2}''', '''{3}''' соответственно.

=== Именованные параметры ===
Именованные параметры передаются как параметры запроса наподобие GET параметров:
usel://someSelection/?'''limit'''=10&'''page'''=3
Для подстановки их в шаблон выборки нужно писать '''{limit}''', '''{page}'''. Например:
<source lang="xml">
<limit page="{page}">{limit}</limit>
</source>

== Список протоколов ==
* [[udata|udata://]]
* [[upage|upage://]]
* [[uobject|uobject://]]
* [[ufs|ufs://]]
* [[umap|umap://]]

← Предыдущая		Версия 14:28, 21 ноября 2018
Строка 245:		Строка 245:
	<limit page="{page}">{limit}</limit>		<limit page="{page}">{limit}</limit>
	</source>		</source>
		+
		+	[[Категория:API]]

← Предыдущая		Версия 12:44, 24 декабря 2009
Строка 245:		Строка 245:
	<limit page="{page}">{limit}</limit>		<limit page="{page}">{limit}</limit>
	</source>		</source>
−
−	~~== Список протоколов ==~~
−	* [[udata\|udata://]]
−	* [[upage\|upage://]]
−	* [[uobject\|uobject://]]
−	* [[ufs\|ufs://]]
−	* [[umap\|umap://]]

← Предыдущая		Версия 12:44, 24 декабря 2009
Строка 1:		Строка 1:
−	~~ротокол~~ для работы с данными системы. Представляет собой интерфейс для доступа к [[API]]-классу [[umiSelection]]. Позволяет создавать шаблоны выборок из базы данных и в дальнейшем использовать их точно так же, как макросы.	+	Протокол для работы с данными системы. Представляет собой интерфейс для доступа к [[API]]-классу [[umiSelection]]. Позволяет создавать шаблоны выборок из базы данных и в дальнейшем использовать их точно так же, как макросы.

	== Описание ==		== Описание ==

@@ Строка 58: / Строка 58: @@
 </source>
-При использовании '''expecteed-result="count"''' по умолчанию считается количество объектов. Для того, чтобы явно задать необходимость считать количество страниц, нужно добавить атрибут '''force-hierarchy''' со значением '''"1"''':
+При использовании '''expected-result="count"''' по умолчанию считается количество объектов. Для того, чтобы явно задать необходимость считать количество страниц, нужно добавить атрибут '''force-hierarchy''' со значением '''"1"''':
 <source lang="xml">
 <target expected-result="count" force-hierarchy="1">

← Предыдущая	Версия 13:53, 7 сентября 2010
(нет различий)

Протокол USel - История изменений

Whoa в 14:28, 21 ноября 2018

Cmac в 12:04, 2 марта 2012

Danil: переименовал «Протокол usel» в «Протокол USel»

Sv в 12:44, 24 декабря 2009

Sv в 12:44, 24 декабря 2009

Sv: Новая страница: «ротокол для работы с данными системы. Представляет собой интерфейс для доступа к API-клас…»