lss

Декларативное описание экранной формы - 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="<имя запроса>" 
      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>

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

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

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

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

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

Содержит описания панелей, из которых собирается экранный интерфейс формы.

• type - тип панели, в настоящий момент реализованы типы: panel, tab, accordion, grid
• align - выравнивание: center, left, right, top, bottom
• rowset - имя набора строк

• panels, panel - внутри панели могут содержаться дочерние панели, их описание может группироваться внутри узла <panels>, а может лежать непосредственно внутри родительского узла <panel>

Панель - контейнер, дочерние панели могут размещаться как:

• align=«top» - должна быть понятна высота панели
• align=«bottom» - должна быть понятна высота панели
• align=«left» - должна быть понятна ширина панели
• align=«right» - должна быть понятна ширина панели
• align=«center» - должны быть понятны ширина и высота панели
• align=«»

Панель - контейнер, все дочерние панели размещаются как при align=«top». Если суммарная высота дочерних панелей превышает высоту родительской панели, появляется прокрутка

Контейнер дочерних панелей, в виде TabFrame

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

Контейнер дочерних панелей в виде аккордеона

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

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

• 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 поддержка таблиц для таких полей:

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

Панель дерева. Источник данных древовидный. Особым образом обрабатываются атрибуты row:

• row.type - тип узла, если дерево состоит из разнородных узлов
• row.icon - иконка, если поля нет, то из id.treetype, иначе стандартная
• row.final - не может быть дочерних элементов
• row.empty - нет дочерних элементов (но могут быть)

Следующие данные берутся из полей, в качестве имен можно использовать стандартные имена, или переопределять их в секции fields набора строк. Если набор строк разнородный, и содержит разные описатели fields для разных типов узлов, то для разных типов узлов можно задать разные имена полей

• name - поле, из которого брать текст метки, можно переопределить в fields как name=«имя поля»
• description - поле, из которого брать всплывающую подсказку, можно переопределить в fields как description=«имя поля»

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

• mark.icon=mark|check

Реализует древовидное меню, умеющее по DblClick запускать экранные формы. Панель аналогична панели tree, но использует дополнительный параметр collapse, означающий необходимость свернуть панель при запуске экранной формы, и развернуть при получении фокуса ввода на панель:

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

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

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

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

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

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

• line - разные поля, имеющие одинаковые значения этого параметра размещаются вместе в одной строке. Поля, для которых параметр не задан, размещаются с новой строки.
• column - поля, размещенные в разных строках, с одинаковым значением параметра column, совместно выравниваются по левому краю. По умолчанию, первые в колонке поля имеют одинаковое значение этого параметра, и соответственно, совместно выравниваются.
• len - длина содержимого поля в символах
• stretch - расширять

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

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

Панель для отображения списка, сформированного по произвольным 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

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

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

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

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

Простое описание, поле должно быть 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>

Эта панель в 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>

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

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

Эта панель отображает картинку, 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 поле с возможностью редактирования

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

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

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

<panel type="allicons"/>

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

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

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

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

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

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

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

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