====== Декларативное описание экранной формы ======
[[start:|lss]]
===== Введение =====
[[form-definition]] - XML описание, по которому строится экранная форма

Работа экранного интерфейса [[Viewer]] грубо выглядит так:
  * [[Viewer]] посылает [[Request|запрос]] на сервер
  * В [[Response|ответ]] получает описание экранной формы
  * По описанию экранная форма отображается и начинает работать
Описание экранной формы декларативно и статично. Оно не меняется в процессе работы формы. Оно практически не содержит программного кода (за исключением динамически вычисляемых выражений), все нестандартное поведение обеспечивается обращением к серверным скриптам.

===== Формат описания экранной формы =====
Описание экранной формы состоит из следующих крупных разделов:
<code>
<form name="<имя формы>">
  <rowsets>
  <!-- секция описания наборов строк экранной формы -->
  </rowsets>
  
  <requests>
  <!-- секция описания запросов экранной формы -->
  </requests>

  <scripts>
  <!-- секция описания скриптов JavaScript экранной формы -->
  </scripts>
  
  <!-- секция data -->
  <data <name1>="<value1>" <name2>="<value2>" ... <nameN>="<valueN>"/>
  
  <panels>
  <!-- секция описания визуальных элементов (панелей) экранной формы -->
  </panels>
</form>
</code>

==== Заголовок описания экранной формы ====
<code>
<form 
  name="<имя формы>" 
  controller="<имя контроллера формы на сервере, по умолчанию берется из имени формы>"
  caption="<текст заголовка>"
  tabindex="0|Nпп"
  
  js_caption="<JavaScript выражение для вычисления заголовка>"
  
  modal="0|1" 
  width="" 
  height="" 

  onshow="<имя запроса>"
  js_onshow="<JavaScript обработчик>"
  
  closable="1|0"
  onclose="<имя запроса>"
  js_onclose="<JavaScript обработчик>"
  
  js_onrequest="<JavaScript обработчик запросов, например: onFormRequest(param)>"
>
</code>
  * [[form-definition-header | Подробное описание заголовка]]

==== Секция описания наборов строк ====
<code>
  <rowsets>
    <rowset 
      name="rowset" 
      datasource="имя источника" 
      readonly="0|1"
    >
      Изменения в описании источника данных по сравнению с контекстно независимым описанием
      <rowsets>
        Список дочерних наборов строк
      </rowsets>
    </rowset>
    ...
    <rowset/>
  </rowsets>
</code>
[[form-definition-rowsets]]
==== Секция описания запросов уровня формы ====
<code>
  <requests>
    <request 
      name="<имя запроса>" 
      mode="<подрежим>" 
      rowset="#form|#focus|<имя набора строк>" 
      icon="<иконка>"
      caption="<заголовок>"
      description="<подробное описание>"
      enabled="1|0"
      confirm="<текст запроса на подтверждение>"
      message="<текст сообщения>"
      
      event="onclose|onshow"

      js_enabled="<JavaScript выражение>"
      js_visible="<JavaScript выражение>"
      js_caption="<JavaScript выражение>"
      js_icon="<JavaScript выражение>"
      js_confirm="<JavaScript выражение>"
      js_message="<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>
</code>

  * [[form-definition-requests | Подробное описание секции запросов]]

==== Секция описания скриптов JavaScript ====
<code>
  <scripts>
    <script event|script|name="onshow">
    </script>
    <script event|script|name="onclose">
    </script>
    <script event|script|name="onrequest">
    </script>
  
    <script event|script|name="<имя скрипта>">
<![CDATA[
function(p1,p2,p3) {
тело JavaScript функции, обязательно должно начинаться на function(
  return result;
}
]]>
    </script>
    
    <script event|script|name="имя скрипта">
<![CDATA[
Произвольное выражение на JavaScript
]]>
    </script>
    
  </scripts>
</code>

[[form-definition-scripts]]

==== Секция описания начальных значений данных формы ====
<code>
<data name1="<value1>" ... nameN="<valueN>"/>
</code>

==== Секция описания панелей ====
<code>
  <panels>
    <panel
      type="<тип панели>"
      rowset="<имя набора строк>"
      caption="<заголовок>"
      color="<цвет>"
      align="middle|top|bottom|left|right|center"
      splitter="0|1"
      js_visible="<выражение JavaScript>"
      row.type="<тип подходящего узла набора строк>"
      width="<ширина>"
      height="|высота|auto"

      minwidth="<минимальная ширина (в px), совместно со splitter=1>"
      minheight="<минимальная высота (в px), совместно со splitter=1>"

      focus="0|1"
      border="0|1"
      padding="<отступ сверху и снизу>"
      fontsize="normal|s|l|xl|xxl"
      color.readonly="gray|white"
      id="<id панели>"
      
      onaction="<имя запроса>"
      onshow="<имя запроса>"
      js_onaction="<выражение JavaScript>"
      js_onshow="<выражение JavaScript>"
    >
      <events>
        <request name="" event="onaction|onshow"/>
      </events>
      
      <fields>
        Список полей источника данных
      </fields>
      
      <toolbar default="0|1" menu="0|1">
        <request
          name|request="<имя запроса>"
          mode="<подрежим запроса>"
          rowset="<имя набора строк>|#this|#parent|#focus|#form"
          caption="<текст>"
          description="<подробное описание>"
          confirm="<текст>"
          lock="0|1"
          icon="<иконка>"
          enabled="1|0"
          js_enabled="<выражение>"
          js_visible="<выражение>"
          js_confirm="<выражение>"
          js_caption="<выражение>"
          js_icon="<выражение>"
          style="icon|text|icontext"
          action="1|0"
          
          save="0|1"
          close="0|1"
          
          form="<имя формы для запроса form>"
          modal="0|1" - для запроса form модальность запускаемой формы
          closable="1|0"
          width="<ширина>"
          height="<высота>"
        >
          <params>
            <param 
               name="<имя параметра>" 
               js_value="<значение параметра JavaScript>" 
               value="<значение параметра>"
               js_enabled="<JavaScript выражение>"
               enabled="1|0"
               skipempty="0|1"
            />
          </params>
          
          <results>
            <result name="<имя в #data>" value="<имя в #result>"/>
            ...
            <result name="<имя в #data>" value="<имя в #result>"/>
          </results>
          
          <requests>
            <request/>
            ...
            <request/>
          </requests>
        </request>
        <separator/>
        ...
        <request/>
      </toolbar>

      <menu default="0|1">
        <request>
          <requests>
            <request/>
            ...
            <request/>
          </requests>
        </request>
        <separator/>
        ...
        <request/>
      </menu>

      <menubar default="0|1">
        <request>
          <requests>
            <request/>
            ...
            <request/>
          </requests>
        </request>
        <separator/>
        ...
        <request/>
      </menubar>

      <buttons>
        <request align="left|right|top" style="default|success|info|warning|danger"/>
        <separator/>
        ...
        <request/>
      </buttons>
      
      
      <panel/>
      ...
      <panel/>
      
    </panel>
    
  </panels>
  
</form>
</code>

[[form-definition-panels]]

==== Секция <panels> ====
Содержит описания панелей, из которых собирается экранный интерфейс формы.
=== Полезные атрибуты <panel> ===
  * **type** - тип панели, в настоящий момент реализованы типы: **panel**, **tab**, **accordion**, **grid**
  * **align** - выравнивание: center, left, right, top, bottom
  * **rowset** - имя набора строк
=== Дочерние узлы <panel> ===
  * panels, panel - внутри панели могут содержаться дочерние панели, их описание может группироваться внутри узла <panels>, а может лежать непосредственно внутри родительского узла <panel>

===== Виды панелей =====
==== panel ====
Панель - контейнер, дочерние панели могут размещаться как:
  * align="top" - должна быть понятна высота панели
  * align="bottom" - должна быть понятна высота панели
  * align="left" - должна быть понятна ширина панели
  * align="right" - должна быть понятна ширина панели
  * align="center" - должны быть понятны ширина и высота панели
  * align=""
==== scroll ====
Панель - контейнер, все дочерние панели размещаются как при align="top". Если суммарная высота дочерних панелей превышает высоту родительской панели, появляется прокрутка

==== tab ====
Контейнер дочерних панелей, в виде TabFrame
  * атрибут **bestchild**=1 - отображать только одну (первую подходящую) дочернюю панель. Анализируется row.type и js_visible
  * возможность динамически определять **текущую панель** при **смене строки**
    * привязать к панели **rowset**, смена строки в котором вызывает смену текущей панели
    * у дочерних панелей атрибуты **best**, **js_best** - если у текущей панели признак best, то она остается текущей, иначе первая с признаком best

==== accordion ====
Контейнер дочерних панелей в виде аккордеона
  * атрибут **bestchild**=1 - отображать только одну (первую подходящую) дочернюю панель. Анализируется row.type и js_visible


==== grid ====
дополнительные признаки панели
  * **style**=grid|list|report (возможно, в будущем будет реализован card)
  * **waitanimate**="0|1" - отображать ожидание загрузки анимированным gif
  * **noheader** - не показывать заголовки 0|1
  * **noselect** - не показывать текущую строку 0|1
  * **mark.icon**=mark|check
дополнительные признаки полей
  * **noscroll** - включить поле в непрокручиваемую область слева 0|1
  * **clipboard** - возможность выделения текста для переноса в буфер обмена 0|1
  * **align** - left|right|center
  * **lightclick** - 0|1 обработка легкого нажатия мышки (как для пометки mark), имеет смысл для check и icons
дополнительный тип поля
  * type=html - содержимое интерпретируется как HTML, реализована CSS поддержка таблиц для таких полей:
<code>
<table class="table"> ... </table>
<table class="table hover"> ... </table>
</code>

==== tree ====
Панель дерева. Источник данных древовидный. Особым образом обрабатываются атрибуты row:
  * **row.type** - тип узла, если дерево состоит из разнородных узлов
  * **row.icon** - иконка, если поля нет, то из id.treetype, иначе стандартная
  * **row.final** - не может быть дочерних элементов
  * **row.empty** - нет дочерних элементов (но могут быть)
Следующие данные берутся из полей, в качестве имен можно использовать стандартные имена, или переопределять их в секции **fields** набора строк. Если набор строк разнородный, и содержит разные описатели fields для разных типов узлов, то для разных типов узлов можно задать разные имена полей
  * **name** - поле, из которого брать текст метки, можно переопределить в fields как name="имя поля"
  * **description** - поле, из которого брать всплывающую подсказку, можно переопределить в fields как description="имя поля"

дополнительные признаки панели
  * **mark.icon**=mark|check

==== treemenu ====
Реализует древовидное меню, умеющее по DblClick запускать экранные формы. Панель аналогична панели **tree**, но использует дополнительный параметр **collapse**, означающий необходимость свернуть панель при запуске экранной формы, и развернуть при получении фокуса ввода на панель:
<code>
  <panel type="treemenu" rowset="<имя набора строк>" collapse="0|1"/>
</code>
Особым образом интерпретируются следующие поля набора строк:
  * **form** - поле, содержащие имя запускаемой формы, может быть переопределено в секции fields treemenu.form="имя поля"
  * **params** - поле, содержащие параметры запускаемой формы, может быть переопределено в секции fields treemenu.params="имя поля"
==== fields ====
Панель позволяет совместно разместить несколько полей набора строк
<code>
<panel type="fields" rowset="<имя набора строк>" captionup="0|1">
  <field name="<имя поля>" line="<имя строки>" column="<имя колонки>"/>
  ...
  <field/>
</panel>
</code>
Дополнительные параметры полей:
  * line - разные поля, имеющие одинаковые значения этого параметра размещаются вместе в одной строке. Поля, для которых параметр не задан, размещаются с новой строки.
  * column - поля, размещенные в разных строках, с одинаковым значением параметра column, совместно выравниваются по левому краю. По умолчанию, первые в колонке поля имеют одинаковое значение этого параметра, и соответственно, совместно выравниваются.
  * len - длина содержимого поля в символах
  * stretch - расширять
==== attribute ====
Панель атрибутов построена на базе панели **fields**, однако описания и значения полей берутся из таблицы, каждая строка - поле панели attribute. При перечитке таблицы панель перерисовывается, и отображает другие поля.

Для корректной работы, у источника данных панели должны быть следующие поля:
  * **caption** - название атрибута
  * **type** - тип атрибута: string|num|date|list|radio|memo|ref|caption
  * **len** - длина, обычно если не задана, то stretch=1
  * **dec** - имеет смысл для атрибутов типа num, знаков после запятой
  * **list** - имеет смысл для атрибутов list и radio, значения через ;
  * **action** - имя запроса, который надо выполнить по клику
  * **line** - имя строки, элементы с одинаковым значениям этого поля размещаются в одной строке
  * **value** - значение атрибута
  * Значение **row.readonly** строки интерпретируется как readonly поля
 

Работа справочника type=ref реализована кривовато, но работает. На все атрибуты используется один и тот-же справочник. Это может быть специально сделанный на сервере источник данных справочника, который по полученным параметрам понимает, что надо возвращать для текущего атрибута. 
У источника данных панели должно быть 2 поля:
  * **valueid** - поле type="ref", с прописанным вызовом общего для всех атрибутов справочника
  * **valuename** - поле refid="valueid" - корректно описанное поле refname, может называться как угодно, лишь бы ссылалось на valueid. Имеет смысл организовать источник данных на сервере так, что бы это поле было виртуальным, а  значение его было привязано к полю value.


==== html ====
Панель может отображать произвольный HTML текст по шаблону с макроподстановками или текст заголовка
<code>
<panel 
  type="html"
  style="|caption|title"
  bgcolor="<цвет фона>"
  color="<цвет надписи>"
  bgimage="<путь до картинки>"
  caption="<отображаемый текст>"
  size="small|medium|large"
  login="<имя пользователя>"
  js_tp="<JavaScript, возвращающий html содержимое шаблона>"
  js_tpname="<JavaScript, возвращающий имя шаблона>"
  js_tpvalue="<JavaScript, для нестандартных макроподстановок в шаблоне>"
>
<templates>
<template name="<имя шаблона>" js_enabled="<JavaScript пригодности шаблона>">
<![CDATA[
html текст
]]>
</template>
<template name="<имя шаблона>" js_enabled="<JavaScript пригодности шаблона>">
<![CDATA[
html текст
]]>
</template>
</templates>
</panel>
</code>

Макроподстановки
  * %%CAPTION%% - текст параметра caption
  * %%LOGIN%% - элемент с именем текущего пользователя (из параметра login) по клику запрос disconnect
  * %%выражение%% - см [[lssformat]] - как для подстановки в функцию get
Стили
  * caption - стиль заголовка панели, вариант medium и large позволяет увеличить размер. Внутри стиля caption доступен стиль params для таблицы параметров:
<code>
<table class="params">
  <tr>
    <td>Имя параметра</td><td>значение параметра</td>
  </tr>
  <tr>
    <td>Имя параметра</td><td>значение параметра</td>
  </tr>
</table>
</code>

==== htmllist ====
Панель для отображения списка, сформированного по произвольным HTML шаблонам
<code>
<panel 
  type="htmllist"
  style="tab|list|linklist" - имя HTML класса
  orientation="vertical|horizontal"
  js_tp="<JavaScript, возвращающий html содержимое шаблона>"
  js_tpname="<JavaScript, возвращающий имя шаблона>"
  js_tpvalue="<JavaScript, для нестандартных макроподстановок в шаблоне>"
>
<templates>
<template name="<имя шаблона>" js_enabled="<JavaScript пригодности шаблона>">
<![CDATA[
html текст
%%выражение для макроподстановки%%
]]>
</template>
<template name="<имя шаблона>" js_enabled="<JavaScript пригодности шаблона>">
<![CDATA[
html текст
]]>
</template>
</templates>
</panel>
</code>

=== Примеры ===
Горизонтально расположенные элементы, вроде закладок панелей:
<code>
<panel type="htmllist" style="tab" orientation="horizontal" rowset="<набор строк>">
<template>
<![CDATA[
%%rowset.name%%
]]>
</template>
</panel>
</code>

Вертикальный список элементов
<code>
<panel type="htmllist" style="list" orientation="vertical" caption="<заголовок>" rowset="<набор строк>">
<template>
<![CDATA[
%%rowset.name%%
]]>
</template>
</panel>
</code>


Вертикальный список элементов, визуально похожий на url ссылки
<code>
<panel type="htmllist" style="linklist" orientation="vertical" caption="<заголовок>" rowset="<набор строк>">
<template>
<![CDATA[
%%rowset.name%%
]]>
</template>
</panel>
</code>


Макроподстановки
  * выражение - см [[lssformat]] - как для подстановки в функцию get

==== list ====
Панель для отображения вертикального списка
<code>
<panel 
  type="list"
  rowset="<набор строк>"
  style="list|linklist"
  noselect="0|1"
  focusable="1|0"
  field="<имя поля>"
>
<field name="<имя поля>"/>
</panel>
</code>

==== tablist ====
<code>
<panel 
  type="tablist"
  rowset="набор строк"
  noselect="0|1"
  focusable="1|0"
  field="имя поля"
>
<field name="имя поля"/>
</panel>
</code>

==== multi ====
Панель для списка множественного выбора

Простое описание, поле должно быть refid
<code>
<panel 
  type="multi"
  style="list|check"
  dlgstyle="auto|list|check"
  rowset="<набор строк, содержащий выбранные строки>"
  onaction="<вызов формы выбора>"
>
  <field name="<имя refid поля>"/>
</panel>
</code>

Сложное описание, актуально для style=check с изменяющимся составом доступных галочек
<code>
<panel 
  type="multi"
  style="list|check"
  dlgstyle="auto|list|check"

  rowset="<набор строк, содержащий выбранные строки>"
  ref="<набор строк справочника, содержащий все возможные значения>"
  
  onaction="<вызов формы выбора>"
>
  <field name="<имя поля, содержащее ссылку>" mode="fieldid|rowsetid"/>
  <field name="<имя поля, содержащее наименование>" mode="fieldname|rowsetname"/>
  <field name="<имя поля справочника, содержащее наименование>" mode="refname|reftext"/>
</panel>
</code>

==== webbrowser ====
Эта панель в IFRAME отображает содержимое адреса
<code>
<panel 
  type="webbrowser" 
  rowset="<набор строк>" 
  url="<url адрес>" js_url="<JavaScript, вычисляющий адрес>" field="<имя поля>" 
  default="<url адрес>"
  noscript="0|1" 
  repaint="auto|manual"
  progress="0|1"
>
  <params>
    <param name="http.url" value="<url адрес>">
    <param name="<имя параметра>" value="<значение параметра>">
    ...
    <param/>
  </params>
</panel>
</code>
  * атрибут **url** задает адрес отображаемой в панели страницы
  * атрибут **field** задает имя поля, содержащего адрес отображаемой в панели страницы
  * атрибут **noscript** запрещает выполнение javascript в отображаемой в панели страницы
  * атрибут **repaint** 
    * **auto** по умолчанию, перечитка при любом изменении url, вызывается изменениями в связанном источнике данных 
    * **manual** имеет смысл только для фильтра, перечитка при вызове запросов refresh или refreshrow, если задан параметр default, то перед первой перечиткой отображается его содержимое
  * атрибут **progress** включает отображение индикатора прогресса загрузки содержимого iframe
  * параметры param пополняют адрес передаваемыми через url параметрами
  * параметр **http.url** позволяет задать url через параметры, как в запросах httpget или httpput
Особая обработка запроса panel:
  * panel.print - распечатать содержимое
  * panel.refresh - принудительно перечитать
<code>
<panel type="webbrowser" id="web-browser-id" url="/reports.php?name=test"/>

<request name="panel" mode="print">
  <param name="id" value="web-browser-id"/>
</request>

<request name="panel" mode="refresh">
  <param name="id" value="web-browser-id"/>
</request>
</code>
==== extcontrol ====
Панель позволяет подключить к экранной форме внешний HTML документ, с привязкой к среде разработки. В HTML документе, отображаемом внутри панели должна быть объявлена функция doLssRepaint(params), которая будет автоматически вызываться при перерисовке источника данных. В params передаются: источник данных, значения параметров, режим перерисовки (все, одна строка)
<code>
<panel type="extcontrol" url="<url адрес>">
  <params>
    <param name="<имя параметра>" value="<значение параметра>">
    ...
    <param/>
  </params>
</panel>
</code>
==== img ====
Эта панель отображает картинку, size="" - исходный размер
<code>
<panel type="img" url="<url адрес>" field="<имя поля>" size="contain|cover" onaction="action">
  <params>
    <param name="http.url" value="<url адрес>">
    <param name="<имя параметра>" value="<значение параметра>">
    ...
    <param/>
  </params>
</panel>
</code>
==== memo ====
Эта панель отображает текстовое memo поле с возможностью редактирования
<code>
<panel type="memo" field="<имя поля>" enter="0|1" readonly="0|1|manual">
  <field name="<имя поля>"/>
</panel>
</code>
  * readonly="manual" - в самом поле править нельзя, но в диалоге просмотра можно
==== allicons ====
Эта панель отображает все зарегистрированные в проекте иконки
<code>
<panel type="allicons"/>
</code>
==== chart ====
Эта панель отображает графики и диаграммы
<code>
<panel type="chart" chart="bar|line|radar|pie|polarArea|bubble">
  <field name="<имя поля>" mode="label"/>
  <field name="<имя поля>" mode="value"/>
  ...
  <field name="<имя поля>" mode="label"/>
</panel>
</code>

==== separator ====
Это панель разделитель. Отображается как разделительная линия. Например, можно с помощью ее отделять друг от друга панели fields
<code>
<panel type="fields" align="top">
</panel>

<panel type="separator" align="top"/>

<panel type="fields" align="top">
</panel>
</code>

==== form ====
Эта панель используется в главной экранной форме приложения. В ней размещаются (сменяя друг друга) динамически формируемые в процессе работы приложения экранные формы. 
Такая панель должна быть одна, иначе все запутается.
<code>
<panel 
  type="form" 
  form="<имя формы по умолчанию>"
  
  tab="0|1" 
  
  background="<url картинки фона>"
  bgopacity="<прозрачность фона>"
  bgsize="contain|cover"
  
  login="<имя текущего пользователя>"
  
  rowset="<имя набора строк главного меню системы>"
  menu.align="left|right|top|bottom"
  menu.width="<ширина меню>"
  menu.maxwidth="<максимальная ширина меню>"
  menu.height="<высота меню>"
  menu.maxheight="<максимальная высота меню>"
  menu.caption="<заголовок меню>"
  menu.size="small|medium|large"
  menu.showonempty="0|1"
>
<templates>
  <template name="logo">
<![CDATA[
html текст для логотипа
]]>
  </template>
</templates>
<requests>
  <request name="Имя кнопочки справа вверху"/>
  <request name="Имя кнопочки справа вверху"/>
</requests>
</panel>
</code>