Содержание
Секция описания запросов экранной формы
Введение
На уровне экранной формы можно описывать запросы, отправляемые экранной формой на сервер.
Во первых, можно влиять на внешний вид экранных элементов, нажатие на которые вызывает отправку запроса. Это параметры caption, icon, description. И динамически вычисляемые js_caption, js_icon, js_description соответственно.
Во вторых, можно влиять на доступность выполнения запроса, это параметр enabled и его динамически вычисляемый вариант js_enabled.
Можно перед вызовом запроса требовать подтверждения пользователем, это параметр confirm и js_confirm соответственно.
Можно связывать выполнение запроса с нажатием комбинации клавиш на клавиатуре, это параметр key.
Важный параметр save=«1» вызывает принудительную отписку не сохраненных изменений перед выполнением запроса, если такие изменения есть.
Описанный в этой секции запрос с именем onshow автоматически вызывается при открытии экранной формы, а onclose при закрытии.
Но самая востребованная возможность - описание цепочки последовательно вызываемых с клиента запросов. Элементы цепочки вызываются последовательно. В случае, если очередной запрос возвращает ошибку, выполнение цепочки прерывается.
Общий вид секции запросов
<requests>
<request
name="<имя запроса>"
mode="<подрежим>"
rowset="#form|#focus|<имя набора строк>"
icon="<иконка>"
caption="<заголовок>"
description="<подробное описание>"
enabled="1|0"
confirm="<текст запроса на подтверждение>"
js_enabled="<JavaScript выражение>"
js_visible="<JavaScript выражение>"
js_caption="<JavaScript выражение>"
js_icon="<JavaScript выражение>"
js_confirm="<JavaScript выражение>"
save="0|1"
key="ctrl+shift+alt+code"
/>
<params>
<param
name="<имя параметра>"
value="<значение>"
js_value="<JavaScript выражение>"
skipempty="0|1"
type="<тип параметра>"
enabled="1|0"
js_enabled="<JavaScript выражение>"
priority="0|1"
/>
...
</param>
</params>
<requests>
<request sync="1|0"/>
...
<request/>
</requests>
</request>
</requests>
Имя запроса, rowset
- Если у запроса задан параметр rowset, то по нему определяется, где именно запрос описан и кто его будет выполнять.
- rowset=<имя набора строк формы> - запрос связан с этим набором строк. Из него будет взято описание запроса, набор строк определит доступность выполнения запроса.
- rowset=«#form» - запрос описан в секции requests экранной формы. Если там такого запроса нет, то выполнение запроса недоступно.
- Если rowset не задан, обработка идет по мягкому сценарию. Если из контекста можно понять, о каком rowset идет речь, и этот rowset понимает этот запрос, то описание и выполнение запроса перенаправляется туда. Иначе проверяется секция requests экранной формы. Если и там описания запроса нет, то запрос считается корректным и отправляется на сервер. При этом предполагается, что запрос будет на сервере обработан контроллером экранной формы.
Рассмотрим пример:
<requests>
<request name="do-anythig">
<request name="exec-rebuild">
<param name="id" js_value="get('table1.id')"/>
</request>
<request rowset="table1" name="refresh"/>
<request rowset="table2" name="refresh"/>
</request>
</requests>
- запрос с именем do-anythig описан на уровне секции requests экранной формы. Его можно вызвать из управляющих экранных элементов формы, сославшись на это имя. Он не связан ни с каким rowset. Это запрос - цепочка. Он будет последовательно выполнять вложенные в него запросы.
- запросы name=«refresh» для rowset=«table1» и rowset=«table2» отсылают к наборам строк table1 и table2. Эти наборы строк должны быть описаны в разделе rowsets описания экранной формы. Особенности выполнения и параметры запросов берутся из них.
Общий смысл этого примера - выполнить на сервере, в контроллере экранной формы, пересчет. А затем, для корректного отображения результатов, перечитать изменившиеся данные.
Внешний вид управляющих экранных элементов, доступность, подтверждение
Расширим наш пример атрибутами, влияющими на внешний вид управляющих экранных элементов:
<requests>
<request name="do-anythig"
caption="Выполнить пересчет"
description="Этот запрос выполнит пересчет данных документа"
icon="rebuild"
confirm="Вы уверены, что хотите выполнить пересчет?"
>
<!-- содержимое запроса -->
</request>
</requests>
Запрос do-anything можно вызвать из управляющих экранных элементов. Соответственно, в описании запроса можно прописать отображаемые параметры:
- caption - название запроса, многие управляющие экранные элементы умеют его отображать.
- description - подробное описание запроса, обычно оно высвечивается при наведении мышки на управляющий экранный элемент.
- icon - иконка, многие управляющие экранные элементы умеют ее отображать.
- confirm - если параметр задан, то перед выполнением запроса отображается диалог, требующий подтверждения пользователя.
Эти параметры можно задавать не только статически, но и динамически:
<requests>
<request name="do-anythig"
js_caption="'Выполнить пересчет документа '+get('table1.code')"
js_description="'Этот запрос выполнит пересчет данных документа '+get('table1.code')"
js_confirm="'Вы уверены, что хотите выполнить пересчет документа '+get('table1.code')+'?'"
js_enabled="get('table1.mode')=='ok'"
>
<script name="icon">
<![CDATA[
function() {
var style=get('table1.style');
if (style==1) return 'iconName1';
if (style==2) return 'iconName2';
return 'iconNameAnother';
}
]]>
</script>
<!-- содержимое запроса -->
</request>
</requests>
Обычно, динамические выражения вычисляются на основе значений полей rowset. Если выражение сложное, и его неудобно описывать в атрибуте XML узла, можно вынести его в раздел script, описав внутри функцию на языке JavaScript. В примере так сделано для динамического вычисления значения icon. Важный динамический параметр js_enabled определяет доступность выполнения запроса.
Вызов запроса по горячей клавише
Запросом, объявленным в секции requests, можно назначить комбинацию горячих клавиш, обеспечив вызов запроса с клавиатуры. Для этого используется атрибут key. Его значение - код нажатой клавиши в сочетании с названиями вспомогательных клавиш: ctrl, shift, alt. Разделителем выступает +
Вместо кода клавиши можно использовать ключевые слова: enter, escape, space, ins, del. Другие клавиши надо обозначать их числовым кодом (из события onKeyDown JavaScript в браузере).
Можно ограничить область действия горячих клавиш, задав запросу атрибут rowset. Тогда сочетание клавиш будет вызывать запрос только в том случае, когда текущая (имеющая фокус ввода) экранная панель относится к этому набору строк.
Пример:
<requests>
<request name="do-anythig" key="ctrl+alt+enter" rowset="table1">
<!-- содержимое запроса -->
</request>
</requests>
В данном случае запрос do-anything представляет собой цепочку запросов. Она может быть вызвана нажатием комбинации горячих клавиш Ctrl+Alt+Enter, если имеющая фокус ввода экранная панель относится к набору строк table1.
Сохранение накопившихся изменений, перед выполнением запроса
Пример:
<requests>
<request name="do-anythig" save="1">
<!-- содержимое запроса -->
</request>
</requests>
Параметр save=«1» вызывает, перед выполнением запроса, сохранение на сервер всех не отписанных изменений, если они есть.
Передаваемые запросу параметры
В запросе можно описать передаваемые серверу значения параметров. Основные описатели параметра, это имя name и значение value. Значение может быть константой - тогда используется атрибут value, или выражением JavaScript - тогда используется атрибут js_value. Для построения выражений можно использовать функции доступа к данным LSS.
Атрибут skipempty=«1» указывает, что не следует передавать на сервер параметр, если его значение пусто. По умолчанию skipempty=«0» и параметры с пустым значением на сервер передаются.
Атрибут js_enabled позволяет задать выражение JavaScript, указывающее следует ли передавать параметр на сервер.
Атрибут type позволяет задать тип передаваемого в параметре значения, в соответствии с форматом данных LSS.
Пример:
<requests>
<request name="exec-rebuild">
<param name="id" js_value="get('table1.id')" skipempty="1"/>
<param name="mode" value="aBc"/>
<param name="style" js_value="get('table1.style')" js_enabled="get('table1.isstyle')==1"/>
<param name="dstart" value="2020-01-12" type="date"/>
</request>
</request>
</requests>
Выполнение цепочки запросов
Цепочка запросов объявляется в секции requests. При ее вызове, включенные внутрь цепочки запросы выполняются последовательно, один за другим. Пришедшая в ответе ошибка прерывает выполнение цепочки запросов.
Параметр запроса sync=«0» изменяет это поведение - такой запрос выполняется асинхронно, последующие запросы не ожидают результатов его выполнения. Этот параметр удобно использовать в конце цепочки, для перечитки нескольких rowset, затронутых запросом.
Рассмотрим пример:
<requests>
<request name="do-anythig">
<request name="exec-rebuild">
<param name="id" js_value="get('table1.id')"/>
</request>
<request rowset="table1" name="refresh" sync="0"/>
<request rowset="table2" name="refresh" sync="0"/>
</request>
</requests>
Запросы на событие onshow и onclose
Объявленные в секции requests запросы с именем onshow и onclose вызываются автоматически при открытии и закрытии экранной формы.
Пример:
<form name="formName">
<requests>
<request name="onshow">
<request name="exec-onshow-first" js_enabled="get('#data.first')"/>
<request name="exec-onshow-next" js_enabled="!get('#data.first')"/>
</request>
</requests>
</form>
Обратите внимание на значение get('#data.first'). Оно 1 при первом вызове формы и 0 при повторном получении формой фокуса ввода.
Часто бывает необходимым организовать перечитку данных экранной формы, когда из этой формы переключились в другую, там исправили важные данные, а потом вернулись обратно. Не модальные экранные формы в LSS между собой не взаимодействуют, работают изолированно. Соответственно, для согласования данных приходится организовывать перечитку при возврате форме фокуса ввода.