====== Заголовок описания экранной формы ======
[[start:|lss]] | [[form-definition]]
===== Введение =====
Заголовок содержит основные описатели [[form-definition|экранной формы]].

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

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

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

===== Общий вид заголовка =====
Вот примерный вид заголовка описателя [[form-definition|экранной формы]]:
<code>
<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)>"
>
</code>
===== Название экранной формы, контроллер, заголовок =====
  * **name** - имя [[form-definition|экранной формы]], обязательный параметр. Уникальное имя [[form-definition|экранной формы]] во вкладках, для не модальных экранных форм. Задает передаваемое на сервер в [[request|запросах]] имя [[form-definition|экранной формы]] (имя контроллера), если не задан параметр **controller**.
  * **controller** - передаваемое на сервер в [[request|запросах]] имя [[form-definition|экранной формы]] (имя контроллера). Если не задано, используется значение параметра **name**.
  * **caption** - текст заголовка [[form-definition|экранной формы]], для не модальной [[form-definition|экранной формы]] отображается в имени вкладки.
  * **tabindex** - числовое значение, по умолчанию 0. Задает порядок размещения [[form-definition|экранной формы]] во вкладках. [[form-definition|Экранные формы]] с большим значением **tabindex** размещаются во вкладках позже, с меньшим раньше. Если значения одинаковые, то [[form-definition|формы]] размещаются в порядке создания - созданные позднее размещаются позже.
===== Параметры модальных экранных форм =====
По умолчанию [[form-definition|экранная форма]] отображается во всю ширину экрана, во вкладках, вместе с другими открытыми не модальными [[form-definition|экранными формами]].

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

Во первых, можно в запросе вызова [[form-definition|экранной формы]] указать, что она должна отображаться модально:
<code>
<request name="form" form="formName" caption="Заголовок" modal="1" width="90%" height="360px" />
</code>
Во вторых, можно задатьэкранной формыэкранной формы параметры в заголовке описания [[form-definition|экранной формы]]:
<code>
<form name="formName" caption="Заголовок" modal="1" width="90%" height="360px">
описание экранной формы
</form>
</code>
  * **modal** - если значение 1, то надо отобразить [[form-definition|форму]] модально. Если 0, то не модально. По умолчанию 0.
  * **width** - ширина [[form-definition|экранной формы]], в процентах или пикселях. Имеет смысл только для модальных [[form-definition|экранных форм]].
  * **height** - высота [[form-definition|экранной формы]], в процентах или пикселях. Имеет смысл только для модальных [[form-definition|экранных форм]].
===== Открытие экранной формы =====
Для модальной [[form-definition|экранной формы]] событие на открытие возникает только 1 раз - после ее отображения. 
Для не модальной [[form-definition|формы]] это событие возникает как при первом отображении [[form-definition|экранной формы]], так и при переключении вкладок открытых [[form-definition|экранных форм]]. С текущей [[form-definition|экранной формы]] можно уйти, переключившись на другую, а потом вернутся обратно.
При первом отображении значение JavaScript функции **get('#data.first')** равно 1, при последующих 0.

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

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

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

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

Эту обработку можно организовать иначе, ничего не объявляя в заголовке, а в секции **requests** объявив цепочку [[request|запросов]] с именем **onshow**:
<code>
<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>
</code>

Пример обработки события **onshow** через выполнение JavaScript
<code>
<form name="formName" js_onshow="console.log('onshow, first='+get('#data.first'))">
</form>
</code>

===== Закрытие экранной формы =====
По умолчанию, [[form-definition|экранную форму]] можно закрыть, нажав мышкой на закрывающий крестик.
Параметр **closable="0"** делает этот крестик недоступным. Такую [[form-definition|экранную форму]] можно закрыть только программно:
  * можно вызвать [[request|запрос]] **close**
  * для не модальной [[form-definition|формы]] можно открыть другую форму с тем-же именем.

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

Пример обработки события **onclose** через отправку [[request|запроса]]:
<code>
<form name="formName" onclose="on-close">
</form>
</code>

Пример обработки события **onclose** через выполнение JavaScript
<code>эксперементальная
<form name="formName" js_onclose="console.log('onclose')">
</form>
</code>

===== Перехват и обработка запросов экранной формы на клиенте =====
Это функция эксперементальная. Есть возможность перехватывать на клиенте отправляемые на сервер [[request|запросы]], обрабатывать их на клиенте, и возвращать ответ, не обращаясь к серверу. 
Обработчик **js_onrequest** получает отправляемый на сервер [[request|запрос]] в следующем виде:
<code>
{
  request: 'имя запроса',
  form: 'имя экранной формы',
  rowset: 'имя набора строк',
  datasource: 'имя источника данных на сервере',
  xml: <запрос в виде XML узла>,
  json: <запрос, преобразованный в JSON>
}
</code>
В качестве [[response|ответа]] обработчик может вернуть:
  * **false** - обработчик не смог обработать [[request|запрос]] на клиенте, надо передать [[request|запрос]] на сервер
  * **строка** - [[request|запрос]] обработан на клиенте, содержимое строки надо преобразовать к xml и передать в качестве [[response|ответа]]
  * **json** - [[request|запрос]] обработан на клиенте, содержимое json надо преобразовать к xml и передать в качестве [[response|ответа]]
  * **xml** - [[request|запрос]] обработан на клиенте, содержимое, в виде xml, надо передать в качестве [[response|ответа]]