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

Введение

Декларативное описание экранной формы - XML описание, по которому строится экранная форма

Работа экранного интерфейса LSS визуализатор грубо выглядит так:

LSS визуализатор посылает запрос на сервер
В ответ получает описание экранной формы
По описанию экранная форма отображается и начинает работать

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

Формат описания экранной формы

Описание экранной формы состоит из следующих крупных разделов:

<form name="<имя формы>">
  <rowsets>
  <!-- секция описания наборов строк экранной формы -->
  </rowsets>
  
  <requests>
  <!-- секция описания запросов экранной формы -->
  </requests>

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

Заголовок описания экранной формы

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

Подробное описание заголовка

Секция описания наборов строк

  <rowsets>
    <rowset 
      name="rowset" 
      datasource="имя источника" 
      readonly="0|1"
    >
      Изменения в описании источника данных по сравнению с контекстно независимым описанием
      <rowsets>
        Список дочерних наборов строк
      </rowsets>
    </rowset>
    ...
    <rowset/>
  </rowsets>

Подробное описание секции наборов строк

Секция описания запросов уровня формы

  <requests>
    <request name="onshow"/>
    <request name="onclose"/>
    
    <request 
      name="<имя запроса>" 
      mode="<подрежим>" 
      rowset="#form|#focus|<имя набора строк>" 
      icon="<иконка>"
      caption="<заголовок>"
      description="<подробное описание>"
      enabled="1|0"
      confirm="<текст запроса на подтверждение>"
      message="<текст сообщения>"

      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>

Подробное описание секции запросов

Секция описания скриптов JavaScript

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

Подробное описание секции скриптов

Секция описания начальных значений данных формы

<data name1="<value1>" ... nameN="<valueN>"/>

Секция описания панелей

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

Подробное описание секции панелей

Секция <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|report|card
waitanimate=«0|1» - отображать ожидание загрузки анимированным gif
noheader - не показывать заголовки 0|1
noselect - не показывать текущую строку 0|1
color.readonly=gray|white
mark.icon=mark|check

дополнительные признаки полей

noscroll - включить поле в непрокручиваемую область слева 0|1
clipboard - возможность выделения текста для переноса в буфер обмена 0|1
align - left|right|center
lightclick - 0|1 обработка легкого нажатия мышки (как для пометки mark), имеет смысл для check и icons

дополнительный тип поля

type=html - содержимое интерпретируется как HTML, реализована CSS поддержка таблиц для таких полей:

<table class="table"> ... </table>
<table class="table hover"> ... </table>

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, означающий необходимость свернуть панель при запуске экранной формы, и развернуть при получении фокуса ввода на панель:

  <panel type="treemenu" rowset="<имя набора строк>" collapse="0|1"/>

Особым образом интерпретируются следующие поля набора строк:

form - поле, содержащие имя запускаемой формы, может быть переопределено в секции fields treemenu.form=«имя поля»
params - поле, содержащие параметры запускаемой формы, может быть переопределено в секции fields treemenu.params=«имя поля»

fields

Панель позволяет совместно разместить несколько полей набора строк

<panel type="fields" rowset="<имя набора строк>" captionup="0|1">
  <field name="<имя поля>" line="<имя строки>" column="<имя колонки>"/>
  ...
  <field/>
</panel>

Дополнительные параметры полей:

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 текст по шаблону с макроподстановками или текст заголовка

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

Макроподстановки

CAPTION - текст параметра caption
LOGIN - элемент с именем текущего пользователя (из параметра login) по клику запрос disconnect
выражение - см Формат данных LSS - как для подстановки в функцию get

Стили

caption - стиль заголовка панели, вариант medium и large позволяет увеличить размер. Внутри стиля caption доступен стиль params для таблицы параметров:

<table class="params">
  <tr>
    <td>Имя параметра</td><td>значение параметра</td>
  </tr>
  <tr>
    <td>Имя параметра</td><td>значение параметра</td>
  </tr>
</table>

htmllist

Панель для отображения списка, сформированного по произвольным HTML шаблонам

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

Примеры

Горизонтально расположенные элементы, вроде закладок панелей:

<panel type="htmllist" style="tab" orientation="horizontal" rowset="<набор строк>">
<template>
<![CDATA[
%%rowset.name%%
]]>
</template>
</panel>

Вертикальный список элементов

<panel type="htmllist" style="list" orientation="vertical" caption="<заголовок>" rowset="<набор строк>">
<template>
<![CDATA[
%%rowset.name%%
]]>
</template>
</panel>

Вертикальный список элементов, визуально похожий на url ссылки

<panel type="htmllist" style="linklist" orientation="vertical" caption="<заголовок>" rowset="<набор строк>">
<template>
<![CDATA[
%%rowset.name%%
]]>
</template>
</panel>

Макроподстановки

выражение - см Формат данных LSS - как для подстановки в функцию get

list

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

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

tablist

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

multi

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

Простое описание, поле должно быть refid

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

Сложное описание, актуально для style=check с изменяющимся составом доступных галочек

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

webbrowser

Эта панель в IFRAME отображает содержимое адреса

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

атрибут 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 - принудительно перечитать

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

extcontrol

Панель позволяет подключить к экранной форме внешний HTML документ, с привязкой к среде разработки. В HTML документе, отображаемом внутри панели должна быть объявлена функция doLssRepaint(params), которая будет автоматически вызываться при перерисовке источника данных. В params передаются: источник данных, значения параметров, режим перерисовки (все, одна строка)

<panel type="extcontrol" url="<url адрес>">
  <params>
    <param name="<имя параметра>" value="<значение параметра>">
    ...
    <param/>
  </params>
</panel>

img

Эта панель отображает картинку, size=«» - исходный размер

<panel type="img" url="<url адрес>" field="<имя поля>" size="contain|cover" onaction="action">
  <params>
    <param name="http.url" value="<url адрес>">
    <param name="<имя параметра>" value="<значение параметра>">
    ...
    <param/>
  </params>
</panel>

memo

Эта панель отображает текстовое memo поле с возможностью редактирования

<panel type="memo" field="<имя поля>" enter="0|1" readonly="0|1|manual">
  <field name="<имя поля>"/>
</panel>

readonly=«manual» - в самом поле править нельзя, но в диалоге просмотра можно

allicons

Эта панель отображает все зарегистрированные в проекте иконки

<panel type="allicons"/>

chart

Эта панель отображает графики и диаграммы

<panel type="chart" chart="bar|line|radar|pie|polarArea|bubble">
  <field name="<имя поля>" mode="label"/>
  <field name="<имя поля>" mode="value"/>
  ...
  <field name="<имя поля>" mode="label"/>
</panel>

separator

Это панель разделитель. Отображается как разделительная линия. Например, можно с помощью ее отделять друг от друга панели fields

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

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

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

form

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

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

Содержание