LSS Техническая документация

Эта страница только для чтения. Вы можете посмотреть её исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
====== Ответы ======
[[start:|lss]]
===== Введение =====
[[Response|Ответ]] - **XML** документ, который серверный скрипт должен отправить в ответ на поступивший [[Request|запрос]].
Мы тут разбираем в каком виде серверные скрипты должны формировать [[Response|ответы]].

Так как серверные скрипты - зона ответственности прикладного программиста, то важно соблюсти баланс: синтаксис ответов должен быть простым, наглядным, но в то же время гибким.

===== Общая структура ответа =====
Ответ представляет собой **XML документ**
<code>
<root type="lss" session="<идентификатор сессии>" csrftoken="<токен защиты CSRF уязвимости>">
  <response .../>
  <response .../>
  ...
  <response .../>
</root>
</code>
===== Ответы - декларативные описания =====
  * [[rowset-definition]]
  * [[form-definition]]

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

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

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

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

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

**Уровень приложения** отвечает за авторизацию и запуск на клиенте экранных форм. Тут обрабатываются запросы, требующие деклоративных описаний для запрашиваемой формы или главного меню системы.
===== Ответы, направляемые набору строк RowSet =====
**[[RowSet|Набор строк]]**, отправляя **[[Request|запрос]]**, ожидает **[[Response|ответ]]**. 
**[[Response|Ответ]]** обычно приходит в тот **[[RowSet|набор строк]]**, который отправил **[[Request|запрос]]**.  
В зависимости от **ответа** содержимое может различаться, но обычно имеет примерно такой вид:

<code>
<response 
  name="ok|error|disconnected|exec"
  message="<текст сообщения>"
  rowset="<имя набора строк>"
  exec="<строковое описание запроса>"
  
  paginator.from="<для пагинатора, с какой строки начиная>"
  paginator.count="<для пагинатора, сколько строк всего>"
>
  <row
    id="<id>" id.change="<newid>"

    row.readonly="0|1"
    row.color="0|1"
    row.destmode="after|before|first|last|append"
    row.destid="<id>"
    row.focus="0|1"
    row.delete="0|1"
    row.new="0|1"
    row.change="0|1"
    row.info="0|1"
    
    row.type="<type>"
    row.icon="<icon>"
    row.empty="0|1"
    row.final="0|1"

    fieldname="<значение поля>" 
    fieldname.readonly="0|1" 
    fieldname.visible="1|0" 
    fieldname.color="<color>"
    ...
    fieldname="<значение поля>"
  >
    <field name="<имя поля>" readonly="0|1" color="<color>" visible="1|0">значение поля</field>
  </row>
  ...
  <row/>
  
  <delete id="<id>"/>
  <append 
    id="<id>" 

    row.destmode="after|before|first|last|append"
    row.destid="<id>"
    row.focus="0|1"

    fieldname="<значение поля>" 
    ... 
    fieldname="<значение поля>"
  >
    <field name="<имя поля>" readonly="0|1" color="<color>">значение поля</field>
  </append>
  <shift id="<id>" row.destmode="after|before|first|last|append" row.destid="<id>"/>
  <change id="<id>" fieldname="<значение поля>" ... fieldname="<значение поля>">
    <field name="<имя поля>" readonly="0|1" color="<color>">значение поля</field>
  </change>
  
  <info row.focus.path="<value1>" name2="<value2>" ... nameN="<valueN>"></info>

  <marked row.type="" mode="list|mark|unmark|markall|unmarkall">id1, id2, id3, ... idN</marked>
  
  <data name1="<value1>" name2="<value2>" ... nameN="<valueN>"></data>
  
</response>
</code>
==== Значения атрибутов в ответе ====
=== Атрибуты response ===
  * **response.name** - тип **ответа**, 
    * **ok** - запрос выполнен успешно
    * **error** - ошибка, все отправленные пакетом запросы не прошли
    * **disconnected** - принудительная авторизация
    * **exec** - запрос содержит внутри себя только комманду на принудительное выполнение запроса, и не содержит никаких сведеней о выполненной операции. Обычно дополнительный довесок к ответу
  * **response.message** - выдать сообщение
  * **response.exec** - после обработки ответа послать на сервер новый запрос. Формат строкового описания запроса: #this|#parent|#focus|#form|<rowset>.<requestName>.<requestMode>
=== элемент row ===
Обычно ответ содержит внутри себя строки, которые должен принять на клиенте [[Rowset|набор строк]]. Структура элемента **row** универсальна, ей можно описать любое допустимое со строкой действие. Обычно это - добавить новую строку или  подменить содержимое существующей строки в [[Rowset|наборе строк]] на клиенте.

Атрибуты строки

  * **id** - уникальный идентификатор строки
  * **id.change** - иногда надо у уже существующей на клиенте строки поменять id. Например это надо для присвоения id новой строке, с изначально пустым id, после сохранения в базе.
  * **row.focus** - необязательный параметр, попытка сделать строку текущей. Значение по умолчанию - 0
  * **row.color** - необязательный параметр, имя используемой цветовой схемы отрисовки элементов строки.
  * **row.readonly** - необязательный параметр - запрет на редактирование. По умолчанию - 0. При конфликте значений - **приоритет запрета**: если где то запрещено, а где то разрешено, то запрещено.
  * **row.destmode**, **row.destid** - необязательные параметры, задают перемещение строки по источнику данных. Значение **destmode** по умолчанию - **append**. Значение **destid** по умолчанию - id текущей строки.
  * **row.delete** - если значение 1 то строку надо удалить
  * **row.new** - если значение 1 то эта новая строка, еще не сохраненная на сервере

Атрибуты строки, специфичные для работы дерева
  * **row.icon** - иконка узла дерева, если атрибута нет, то берется из row.type, иначе по умолчанию
  * **row.type** - тип узла, имеет смысл, если дерево состоит из узлов разной природы (организации, сотрудники, отпуска, больничные ...)
  * **row.final** - лист и не может содержать дочерних узлов (по умолчанию нет)
  * **row.empty** - дочерних узлов нет, но могут появится, соответственно отображается как лист, но доступны операции начитки и правки дочерних узлов

Атрибуты поля

  * **fieldname** - значение поля. Предполагается, что поле не будет содержать несохраненных изменений
  * **fieldname.change** - изменить значение поля. Предполагается, что поле изменено, и это изменение будет отписано на сервер при сохранении строки
  * **fieldname.visible** - необязательный параметр - видимость поля. По умолчанию - 1. При конфликте значений - **приоритет запрета**: если где-то не видно, а где-то видно, то не видно.  
  * **fieldname.readonly** - необязательный параметр - недоступность правки для поля. По умолчанию - 0. При конфликте значений - **приоритет запрета**.
  * **fieldname.color** - необязательный параметр - цветовая схема для поля. При конфликте значений приоритет у описания цветовой схемы поля
=== элемент delete ===
Более наглядный способ сообщить о необходимости **удалить строку**. Эквивалентен элементу **row** с атрибутом **row.delete=1**
=== элемент append ===
Более наглядный способ сообщить о необходимости **добавить строку**. Эквивалентен элементу **row** с атрибутом **row.new=1**
=== элемент change ===
Более наглядный способ передать строке новые значения полей, рассчитанные на сервере, но еще не отписанные в базу - результат **[[Request|запроса]]** **change**. Эти значения будут отпишутся в базу при сохранении строки. Эквивалентно элементу **row** с атрибутами **fieldname.change="новое значение поля"**

=== элемент data ===
Позволяет задать значения данным экранной формы. Данные в последствии доступны для чтения посредством вызова get('#data.name').
==== response name="ok" ====
Самый распространенный **ответ**, означает что **[[Request|запрос]]** обработан успешно. Если не содержит дочерних элементов **row**, то обрабатывается в зависимости от от **[[Request|запроса]]** так, как должно быть при его успешном выполнении.
<code>
<response name="ok" message="<текст сообщения>" exec="<строковое описание запроса>">
  <row/>
  ...
  <row/>
<response>
</code>
==== response name="exec" ====
Ответ, требующий выполнения запросов
<code>
<response name="exec" message="<текст сообщения>" exec="<строковое описание запроса>" sync="1|0">
  <param name="<имя параметра>" value="<значение>">значение</param>
  <param name="<имя параметра>" value="<значение>">значение</param>
  ...
  <param name="<имя параметра>" value="<значение>">значение</param>
<response>
</code>
==== response name="error" ====
Ошибка при выполнении запроса. Ошибка отменяет выполнение действия, соответствующего запросу.
<code>
<response name="error" message="<текст сообщения об ошибке>"/>
</code>
Если атрибут **message** опущен, то сообщение не выводится, но запрашиваемое действие запрещается

==== response name="definition" ====
Ответ содержит [[rowset-definition|декларативное описание источника данных]].
<code>
<response name="definition">
  Описание источника данных
</response>

или

<response name="ok">
  Описание источника данных
</response>

или упрощенно

<response>
  Описание источника данных
</response>

</code>







===== Ответы, направляемые приложению =====


==== response name="form" ====
Возвращает [[form-definition|описание экранной формы]], которую надо отобразить