Ответы

lss

Ответ - XML документ, который серверный скрипт должен отправить в ответ на поступивший запрос. Мы тут разбираем в каком виде серверные скрипты должны формировать ответы.

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

Ответ представляет собой XML документ

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

• Декларативное описание набора строк rowset
• Декларативное описание экранной формы

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

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

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

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

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

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

Набор строк, отправляя запрос, ожидает ответ. Ответ обычно приходит в тот набор строк, который отправил запрос. В зависимости от ответа содержимое может различаться, но обычно имеет примерно такой вид:

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

• response.name - тип ответа,
  • ok - запрос выполнен успешно
  • error - ошибка, все отправленные пакетом запросы не прошли
  • disconnected - принудительная авторизация
  • exec - запрос содержит внутри себя только комманду на принудительное выполнение запроса, и не содержит никаких сведеней о выполненной операции. Обычно дополнительный довесок к ответу
• response.message - выдать сообщение
• response.exec - после обработки ответа послать на сервер новый запрос. Формат строкового описания запроса: #this|#parent|#focus|#form|<rowset>.<requestName>.<requestMode>

Обычно ответ содержит внутри себя строки, которые должен принять на клиенте набор строк. Структура элемента row универсальна, ей можно описать любое допустимое со строкой действие. Обычно это - добавить новую строку или подменить содержимое существующей строки в наборе строк на клиенте.

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

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

Более наглядный способ сообщить о необходимости удалить строку. Эквивалентен элементу row с атрибутом row.delete=1

Более наглядный способ сообщить о необходимости добавить строку. Эквивалентен элементу row с атрибутом row.new=1

Более наглядный способ передать строке новые значения полей, рассчитанные на сервере, но еще не отписанные в базу - результат запроса change. Эти значения будут отпишутся в базу при сохранении строки. Эквивалентно элементу row с атрибутами fieldname.change=«новое значение поля»

Позволяет задать значения данным экранной формы. Данные в последствии доступны для чтения посредством вызова get('#data.name').

Самый распространенный ответ, означает что запрос обработан успешно. Если не содержит дочерних элементов row, то обрабатывается в зависимости от от запроса так, как должно быть при его успешном выполнении.

<response name="ok" message="<текст сообщения>" exec="<строковое описание запроса>">
  <row/>
  ...
  <row/>
<response>

Ответ, требующий выполнения запросов

<response name="exec" message="<текст сообщения>" exec="<строковое описание запроса>" sync="1|0">
  <param name="<имя параметра>" value="<значение>">значение</param>
  <param name="<имя параметра>" value="<значение>">значение</param>
  ...
  <param name="<имя параметра>" value="<значение>">значение</param>
<response>

Ошибка при выполнении запроса. Ошибка отменяет выполнение действия, соответствующего запросу.

<response name="error" message="<текст сообщения об ошибке>"/>

Если атрибут message опущен, то сообщение не выводится, но запрашиваемое действие запрещается

Ответ содержит декларативное описание источника данных.

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

или

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

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

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

Возвращает описание экранной формы, которую надо отобразить