lss | Декларативное описание экранной формы

Заголовок содержит основные описатели экранной формы.

Экранная форма может быть модальной или не модальной. У модальной формы (modal=«1») надо задать размеры - высоту и ширину (width, height), в процентах от размера экрана или пикселях. Не модальная экранная форма размещается во вкладках, на всю ширину экрана, вместе другими открытыми не модальными экранными формами. Ее имя (name) уникально: повторное открытие новой формы автоматически закрывает открытую старую форму с тем-же именем, если такая есть. Посредством параметра tabindex можно управлять порядком размещения открытых форм во вкладках.

Имя экранной формы (name) не только обеспечивает уникальность размещения открытой формы во вкладках, но и передается на сервер в каждом запросе. Обычно, для экранной формы на сервере есть обрабатывающий ее запросы контроллер, и имя этого контроллера так-же задается параметром name. Однако, бывает ситуация, когда удобно разделить эти 2 понятия - имя вкладки задавать отдельно, контроллер отдельно. Тогда можно использовать описатель controller, его значение и будет передаваться на сервер в каждом запросе, в качестве имени экранной формы.

На открытие и закрытие экранной формы можно назначить событие: onshow и onclose. Это может быть отправляемый на сервер запрос, а может быть (в виде исключения, для особых надобностей) исполняемый на клиенте код JavaScript.

Вот примерный вид заголовка описателя экранной формы:

<form 
  name="<имя экранной формы>" 
  controller="<имя контроллера экранной формы на сервере>"
  caption="<текст заголовка экранной формы>"
  tabindex="0|Nпп"
  
  modal="0|1" 
  width="" 
  height="" 

  onshow="<имя запроса>"
  js_onshow="<JavaScript обработчик>"
  
  closable="1|0"
  onclose="<имя запроса>"
  js_onclose="<JavaScript обработчик>"
  
  js_onrequest="<JavaScript обработчик запросов, например: onFormRequest(param)>"
>

• name - имя экранной формы, обязательный параметр. Уникальное имя экранной формы во вкладках, для не модальных экранных форм. Задает передаваемое на сервер в запросах имя экранной формы (имя контроллера), если не задан параметр controller.
• controller - передаваемое на сервер в запросах имя экранной формы (имя контроллера). Если не задано, используется значение параметра name.
• caption - текст заголовка экранной формы, для не модальной экранной формы отображается в имени вкладки.
• tabindex - числовое значение, по умолчанию 0. Задает порядок размещения экранной формы во вкладках. Экранные формы с большим значением tabindex размещаются во вкладках позже, с меньшим раньше. Если значения одинаковые, то формы размещаются в порядке создания - созданные позднее размещаются позже.

По умолчанию экранная форма отображается во всю ширину экрана, во вкладках, вместе с другими открытыми не модальными экранными формами.

Существует 2 способа отобразить экранную форму модально.

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

<request name="form" form="formName" caption="Заголовок" modal="1" width="90%" height="360px" />

Во вторых, можно задатьэкранной формыэкранной формы параметры в заголовке описания экранной формы:

<form name="formName" caption="Заголовок" modal="1" width="90%" height="360px">
описание экранной формы
</form>

• modal - если значение 1, то надо отобразить форму модально. Если 0, то не модально. По умолчанию 0.
• width - ширина экранной формы, в процентах или пикселях. Имеет смысл только для модальных экранных форм.
• height - высота экранной формы, в процентах или пикселях. Имеет смысл только для модальных экранных форм.

Для модальной экранной формы событие на открытие возникает только 1 раз - после ее отображения. Для не модальной формы это событие возникает как при первом отображении экранной формы, так и при переключении вкладок открытых экранных форм. С текущей экранной формы можно уйти, переключившись на другую, а потом вернутся обратно. При первом отображении значение JavaScript функции get('#data.first') равно 1, при последующих 0.

На событие открытия экранной формы можно задать запрос, отправляемый на сервер. А можно написать исполняемый JavaScript код.

Пример обработки события onshow через отправку запроса:

<form name="formName" onshow="on-show">
  <requests>
    <request name="on-show">
      <request name="exec-onshow-first" js_enabled="get('#data.first')"/>
      <request name="exec-onshow-next" js_enabled="!get('#data.first')"/>
    </request>
  </requests>
</form>

• в заголовке событие onshow связываем с обработчиком on-show.
• в секции requests описываем запрос on-show в виде контейнера цепочки запросов.
• запрос exec-onshow-first отправляется на сервер при первом запуске экранной формы.
• запрос exec-onshow-next отправляется на сервер при последующем повторном переключении на экранную форму.

Эту обработку можно организовать иначе, ничего не объявляя в заголовке, а в секции requests объявив цепочку запросов с именем onshow:

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

Пример обработки события onshow через выполнение JavaScript

<form name="formName" js_onshow="console.log('onshow, first='+get('#data.first'))">
</form>

По умолчанию, экранную форму можно закрыть, нажав мышкой на закрывающий крестик. Параметр closable=«0» делает этот крестик недоступным. Такую экранную форму можно закрыть только программно:

• можно вызвать запрос close
• для не модальной формы можно открыть другую форму с тем-же именем.

Событие закрытия экранной формы возникает 1 раз - собственно, при ее закрытии. На событие закрытия экранной формы можно задать запрос, отправляемый на сервер. А можно написать исполняемый JavaScript код.

Пример обработки события onclose через отправку запроса:

<form name="formName" onclose="on-close">
</form>

Пример обработки события onclose через выполнение JavaScript

эксперементальная
<form name="formName" js_onclose="console.log('onclose')">
</form>

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

{
  request: 'имя запроса',
  form: 'имя экранной формы',
  rowset: 'имя набора строк',
  datasource: 'имя источника данных на сервере',
  xml: <запрос в виде XML узла>,
  json: <запрос, преобразованный в JSON>
}

В качестве ответа обработчик может вернуть:

• false - обработчик не смог обработать запрос на клиенте, надо передать запрос на сервер
• строка - запрос обработан на клиенте, содержимое строки надо преобразовать к xml и передать в качестве ответа
• json - запрос обработан на клиенте, содержимое json надо преобразовать к xml и передать в качестве ответа
• xml - запрос обработан на клиенте, содержимое, в виде xml, надо передать в качестве ответа