====== Запросы ======
[[start:|lss]]
===== Введение =====
[[Request]] - это то, что [[Viewer]] посылает на сервер, запрашивая данные или инструкции. Мы тут разбираем, в каком виде запросы приходят в серверный скрипт, и что там с ними надо делать.

===== Общая структура запроса =====
Запрос представляет собой **XML документ**:

<code>
<root type="lss" version="1.0" session="<идентификатор сессии>" csrftoken="<токен защиты от CSRF уязвимости>">
  <request .../>
  <request .../>
  ...
  <request .../>
<root>
</code>

Внутри узла **<root>** расположены дочерние узлы **<request>** идентифицирующие запрос, который надо выполнить. Они имеют вид:

<code>
<request 
  request|name="<запрос>"
  mode="<режим запроса, для каждого допустимы свои режимы>"
  form="<имя экранной формы>"
  datasource="<имя источника данных на сервере>" 
  rowset="<имя набора данных на клиенте>"
  id="<id текущей строки>" 
  row.new="0|1"
  
  row.type="<для дерева, тип узла>"
  row.parentid="<для дерева, id родительского узла>"
  row.parenttype="<для дерева, тип родительского узла>"
  
  from.id=""
  from.type="<для дерева, тип узла>"
  from.parentid="<для дерева, id родительского узла>"
  from.parenttype="<для дерева, тип родительского узла>"
  
  paginator.from="<начальная строка>"
  paginator.count="<максимальное кол-во строк>"
>
  <param name="<имя параметра>" type="<тип данных>">значение</param>
  ...
  <param/>
</request>
</code>

Атрибуты **datasource**, **rowset**, **id** есть только у запросов, отправленных источниками данных.

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

В параметрах передаются данные, специфичные для контекста выполнения запроса.

===== Схема обработки запроса =====
Узел **<root>** с запросами приходит в обработчик. Запросы обрабатываются последовательно, вместе в контексте общей транзакции. Если не получилась - то не проходит все.

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

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

**Уровень источника данных** ничего не знает о специфике использования запроса в конкретной форме. Тут расположен максимально абстрагированный от контекста использования код, поддерживающий работу источника данных.

**Уровень формы** обеспечивает взаимодействие источников данных между собой, в контексте конкретной экранной формы. Отсюда, затронутым обработкой источникам данных, посылаются задания на перечитку.

**Уровень приложения** отвечает за авторизацию и запуск на клиенте экранных форм. Тут обрабатываются запросы, требующие деклоративных описаний для запрашиваемой формы или главного меню системы.

===== Запросы, адресованные уровню приложения =====
==== request name="connect" ====
Запрос на соединение с сервером. Вызывается в приложении один раз за сеанс, при идентификации пользователя. Предполагает параметры **login** и **password**. Предполагает в ответ ошибку или успешное соединение с указанием Id сессии. 
<code>
<request name="connect">
  <param name="login">значение</param>
  <param name="password">значение</param>
</request>
</code>
==== request name="disconnect" ====
Запрос на разрыв соединение с сервером.
<code>
<request name="disconnect"/>
</code>

==== request name="form" ====
Запрос на получение [[form-definition|декларативного описания экранной формы]]. Имя запрашиваемой формы брать из параметра **form**. Возвращает [[form-definition]], по нему экранная форма будет построена и отображена.
<code>
<request 
  request|name="form" 
  mode|form="<имя формы>"
  modal="0|1"
  width="<ширина модального окна>"
  height="<высота модального окна>"
>
  <params>
    <param name="">значение</param>
    <param name="">значение</param>
    <param name="">значение</param>
    <param name="">значение</param>
  </params>
</request>
</code>

===== Запросы, адресованные уровню источника данных =====
Уровень источника данных обычно ничего не знает о специфике использования запроса в конкретной форме. Тут расположен максимально абстрагированный от контекста использования код, поддерживающий работу конкретного источника данных.

Источник данных может поддерживать любые запросы, но некоторые из них стандартизированны, их мы и опишем.

==== request name="definition" ====
**Синхронный** запрос на получение [[rowset-definition|описания источника данных]], вызывается один раз перед первым обращением для инициализации. Предполагается ответ "definition" -  корректное [[rowset-definition|описание источника данных]]. Это описание должно быть максимально абстрагировано от контекста использования, внутри конкретной формы оно будет подправленно под контекст.

==== request name="refresh" ====
Запрос на перечитку данных. При вызове дочерние узлы очищаются, выставляется статус - **loaded**, пока не придет ответ - новое содержимое строк.
  * параметр **row.focus.id** перечитывает с позиционированием на заданный id
  * параметр **row.focus.path** для дерева - перечитывает с позиционированием на заданный path - список id через ;
  * параметр **row.focus.getpath** для дерева - находит **path** по **id** и перечитывает с этим **path**. Источник данных должен поддерживать метод **get.path**, вычисляющий **path** по **filter.id**

==== request name="navigate" ====
  * параметр **row.focus.id** - id на которое необходимо позиционировать указатель
  * параметр **row.focus.path** для дерева - список id через ; позиционирует, раскрывая по необходимости
Если строка с таким id начитана, то позиционируется на нее, если нет, то вызывается refresh

==== request name="expand" ====
Если набор строк поддерживает этот запрос, то он считается древовидным. Пока обрабатывается синхронно. Начитывает значения дочерних узлов дерева. Параметры **row.parentid** и **row.parenttype** берутся из текущего узла дерева (для начитываемых узлов он родительский)

==== request name="refreshrow" ====
Запрос на перечитку строки данных. Содержимое строки заменяется значениями из ответа
==== request name="save" ====
**Синхронный запрос** на сохранение строки в базе. 
Предполагается, что данные будут сохранены в базе посредством insert или update и в ответ будет выслано "row" с новыми значениями полей строки.
Если id пусто, то добавляем новую строку и возвращаем ее id, если id не пусто, то правим существующую строку.

==== request name="append" ====
**Синхронный запрос** на формирование новой строки, в параметрах контекст выполнения операции, и установка ее в качестве текущей. 
Предполагается ответ - строка со сформированным значением id и заполненными, сообразно переданным параметрам, остальными полями.
  * mode=**after**, before, last, first - куда помещать по умолчанию строку
  * mode=into - только для деревьев
==== request name="copy" ====
Копирует помеченную строку, относительно текущей строки. Скопированную строку делает текущей

==== request name="move" ====
Переносит помеченную строку, относительно текущей строки. Скопированную строку делает текущей. Имеет смысл только для деревьев.


==== request name="delete" ====
**Синхронный запрос** на удаление строки. Предполагается, что строка будет удалена и в ответ придет подтверждение удаления строки.
  * вариант mode=mark предназначен для удаления помеченных строк

==== request name="shift" ====
Синхронный запрос на изменение порядка следования текущей строки
  * mode=after, before, last, first - куда сдвигать текущую строку

==== request name="change" ====
**Синхронный запрос** на событие – поле изменено. В параметрах новое значение изменившегося поля, контекст использования. Предполагается ответ "change" - команда на изменение значения некоторых полей.
  * mode=<имя поля>
==== request name="get" ====
**Синхронный запрос** получение дополнительной информации из контроллера источника данных. Вызывается автоматически, предполагается ответ "info".

===== Обработка уровня формы =====
Уровень формы обеспечивает взаимодействие источников данных между собой в контексте конкретной экранной формы. Отсюда, затронутым обработкой источникам данных, посылаются задания на перечитку.

====== Запросы, обрабатываемые на клиенте особым образом ======
Обрабатываются на клиенте, не передаются серверу, могут вызываться из requests экранной формы
  * **undo** - откат изменений в строке
  * **collapse** - свернуть узел дерева
  * **mark** - пометить строку для последующей операции link или move
  * **set** - задать значения полям текущей строки
===== request name="none" =====
  * Обрабатываются на клиенте (ничего не передается на сервер), уровня формы
===== request name="close" =====
Вызывает закрытие экранной формы - обычной и модальной.
  * закрыть текущую активную экранную форму
<code>
<request name="close"/>
</code>
  * Варианты для закрытия произвольной экранной формы по имени
<code>
<request name="close" mode|form="<имя формы>"/>

<request name="close">
  <param name="name|form" value="<имя формы>"/>
</request>
</code>

===== request name="data" =====
Изменяет содержимое данных формы. Данные доступны для чтения через вызов get('#data.name'). Запрос выполняется на клиенте, обращения к серверу не происходит.
<code>
<request name="data">
  <param name="" value=""/>
  ...
  <param name="" value=""/>
</request>
</code>
===== request name="log" =====
Средство отладки. Отображает через console.log свои параметры. Запрос выполняется на клиенте, обращения к серверу не происходит.
<code>
<request name="log">
  <param name="" value=""/>
  ...
  <param name="" value=""/>
</request>
</code>

===== request name="panel" =====
Обязательный параметр id - id панели
  * mode=focus - позволяет передать фокус ввода на панель.
  * mode=print - для панели webbrowser распечатать содержимое
  * mode=refresh - для панели webbrowser принудительно перечитать
<code>
<request name="panel" mode="focus">
  <param name="id" value="panel-id"/>
</request>

<panel id="panel-id">
</panel>
</code>
===== request name="httpget" =====
Вызывает загрузку из сервера на клиент файла по указанному адресу. Значения параметров подставляются в адрес
<code>
<request name="httpget" url="<адрес>" mode="get|open" window="<имя окна, для open>">
  <param name="http.url" value="<адрес>">
  <param name="http.mode" value="get|open">
  <param name="http.window" value="<имя окна для open>">
  <param name="http.window.width" value="<ширина окна>">
  <param name="http.window.height" value="<высота окна>">

  <param name="" value="">
  ..
  <param name="" value="">
</request>
</code>

===== request name="httpput" =====
Вызывает загрузку с клиента на сервер файла по указанному адресу. Значения параметров подставляются в адрес
<code>
<request name="httpput" url="<адрес>" ext="jpg;png;xls;doc;pdf;zip" cancelcontinue="0|1" ignorecancel="0|1">
  <param name="http.url" value="<адрес>">
  <param name="http.ext" value="jpg;png;gif;xls;doc;pdf;zip">

  <param name="" value="">
  ..
  <param name="" value="">
</request>
</code>