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

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

Наборы строк содержат отображаемые экранной формы данные. Эти данные отображаются в визуальных элементах экранного интерфейса - панелях. Именно наборы строк манипулируют данными на клиенте - отвечают за правку данных и взаимодействие с сервером. Используемые в экранной форме наборы строк должны быть объявлены в секции rowsets.

Тут есть хитрость: у набора строк на стороне сервера есть контроллер. Этот контроллер умеет возвращать описание своего набора строк по запросу definition. А описания в секции rowsets позволяют подстроить типовое унифицированное описание набора строк под нужды конкретной экранной формы.

На уровне экранной формы наборы строк можно выстроить в иерархию: родительский - дочерний. При смене текущей строки в родительском наборе строк его дочерние наборы строк автоматически перечитываются. Задача программиста описать в дочерних наборах строк фильтры так, что бы после перечитки содержимое дочернего набора строк соответствовало текущей строке родительского набора строк.

Пример:

<rowsets>

  <rowset name="document">
    <rowsets>
      <rowset name="item">
        <param name="filter.documentid" js_value="get('document.id')"/>
      </rowset>
    </rowsets>
  </rowset>
  
</rowsets>

В этом примере описаны 2 набора строк: document и item. Их подробное описание в секции rowsets отсутствует, так как размещенные на сервере контроллеры наборов строк вернут экранной форме их унифицированные описания, по запросу definition.

Набор строк document объявлен родительским. Набор строк item для него описан как дочерний. Предполагается, что на сервере контроллер набора строк item понимает параметр filter.documnentid и воспринимает его как фильтр - возвращает только строки, относящиеся к заданному значению documentid. Соответственно, при смене текущей строки в наборе строк document автоматически произойдет перечитка дочернего к нему набора строк item. А благодаря правильно настроенному фильтру - параметру filter.documentid перечитка вернет только данные, относящиеся к текущей строке набора строк document.

Этот пример можно записать компактнее:

<rowsets>

  <rowset name="document">
    <rowset name="item">
      <param name="filter.documentid" js_value="get('document.id')"/>
    </rowset>
  </rowset>
  
</rowsets>

Есть типовая задача - экранная форма должна отображать не все данные, а только интересующую пользователя часть, причем пользователь может задавать фильтруемые значения. Для хранения и правки данных фильтра в LSS используется специальный набор строк - фильтр. Он задается параметром filter=«1».

У этого набора строк есть несколько особенностей:

• У набора строк фильтра нет контроллера на сервере. У каждой экранной формы фильтры свои, и универсальный контроллер фильтра смысла не имеет. Соответственно, набор строк фильтра полностью описывается в экранной форме, в секции rowsets. Так как нет контроллера, то нет и отправляемых контроллеру запросов. Соответственно, описание набора строк фильтра - это только описание его полей.
• Данные набора строк фильтра всегда одна и только одна строка. У нее нет id, ее нельзя удалить, нельзя добавить новую. Содержимое этой строки нельзя начитать с сервера - нет контроллера. Начальные значения полей фильтра следует задавать посредством атрибута default.
• По умолчанию каждое изменение пользователем значения фильтра приводит к автоматической перечитке дочерних к нему наборов строк.
• Нестандартное поведение набора строк фильтра следует реализовывать в контроллере экранной формы, так как для набора строк фильтра своего контроллера нет.

Пример:

<rowsets>

  <rowset name="filter" filter="1">
    <fields>
      <field name="doctypeid" type="ref" caption="Тип документа" default="25">
        <ref datasource="doctype"/>
      </field>
      <field name="doctype_name" refid="doctypeid" caption="Тип документа" default="Наряд на проведение работ"/>
      <field name="ndoc" caption="Номер документа" type="string" len="15"/>
      <field name="ddoc" caption="Дата документа" type="date"/>
    </fields>
    <rowset name="document">
      <param name="filter.doctypeid" js_value="get('filter.doctypeid')" skipempty="1"/>
      <param name="filter.ndoc" js_value="get('filter.ndoc')" skipempty="1"/>
      <param name="filter.ddoc" js_value="get('filter.ddoc')" skipempty="1"/>

      <rowset name="item">
        <param name="filter.documentid" js_value="get('document.id')"/>
      </rowset>
    </rowset>
  </rowset>
  
</rowsets>

В этом примере набор строк с именем filter объявлен как фильтр посредством атрибута filter=«1». В секции fields описаны его поля. У полей doctypeid и doctype_name с помощью атрибута default заданы начальные значения.

Набор строк document описан как дочерний к нему. Каждое изменение пользователем значения поля набора строк фильтра автоматически вызовет перечитку дочернего набора строк document. Посредством задания параметров filter.doctypeid, filter.ndoc и filter.ddoc введенные пользователем значения набора строк фильтра передаются в контроллер набора строк document. Атрибут skipempty=«1» означает, что если соответствующее поле фильтра не задано и, следовательно, значение параметра пусто, то параметр передавать на сервер не надо.

Чаще всего, при корректировке заголовка набора строк в секции rowsets, возникает необходимость настраивать доступность набора строк для правки и описывать параметры работы пагинатра.

Например:

<rowsets>

  <rowset name="document" paginator.count="300">
    <rowset name="item" js_readonly="get('document.state')!='edit'">
      <param name="filter.documentid" js_value="get('document.id')"/>
    </rowset>
  </rowset>
  
</rowsets>

В этом примере набор строк document работает в режиме пагинации. В каждом запросе серверу на начитку данных добавляются параметры пагинатора: paginator.from и paginator.count. Контроллер набора строк на сервере должен уметь их обрабатывать, и возвращать в ответе только соответствующие параметрам пагинации строки. А у набора строк item задано динамическое условие на доступность набора строк только на чтение.

Другая интересная возможность - можно задать id строки, на которую набор строк должен спозиционироваться при открытии экранной формы:

<rowsets>

  <rowset name="document" paginator.count="300" row.focus.id="243">
  </rowset>
  
</rowsets>

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

<param name="row.focus.id" value="243"/>

Контроллер набора строк на сервере должен этот параметр корректно отработать:

• если включен режим пагинации, то найти и вернуть в ответе ту порцию данных, в которой размещена строка с заданным id
• пометить эту строку признаком row.focus=«1»

Описание набора строк состоит из описания поддерживаемых им запросов и описаний его полей. В секции rowsets можно вносить изменения в универсальное, не зависящее от экранной формы, описание списка полей набора строк. Там можно осуществлять привязку описания полей к контексту использования. Для поля, в секции rowsets, можно задавать значения атрибутов js_readonly, js_visible, caption, len, stretch и т.д. Для справочников можно модифицировать параметры, передаваемые при начитке допустимых строк справочника.

Например:

<rowsets>

  <rowset name="document">
    <rowset name="item">
      <param name="filter.documentid" js_value="get('document.id')"/>
      <fields>
        <field name="itemtypeid" type="ref" js_readonly="get('document.mode')=='specialMode'">
          <ref datasource="itemtype">
            <param name="filter.doctypeid" js_value="get('document.doctypeid')" skipempty="1"/>
          </ref>
        </field>
      </fields>
    </rowset>
  </rowset>
  
</rowsets>

В этом примере модифицировано описание поля справочника itemtypeid набора строк item. Для него:

• Выписано динамическое выражение, описывающее доступность поля для правки - js_readonly.
• Внесены изменения в начитку строк справочника: при раскрытии диалога выбора строки справочника происходит начитка itemtype. При этом контроллеру itemtype на сервер отправляется дополнительный параметр filter.doctypeid, контроллер должен его корректно обработать, и вернуть только подходящие строки.
• Группирующий элемент fields не обязателен, его можно опустить. Тогда элементы field можно размещать непосредственно в узле rowset.

Описание набора строк состоит из описания поддерживаемых им запросов и описаний его полей. В описание запросов можно вносить изменения, позволяющие привязать работу набора строк к экранной форме. Можно:

• Задавать доступность/запрет выполнения запроса в зависимости от контекста, посредством параметра js_enable
• Подстраивать передаваемые запросу параметры
• Включать поддержку запроса пометки строки mark. Обычно этот запрос отрабатывает на клиенте, без обращения к серверу. А список помеченных строк можно передать на сервер параметром запроса, используя функцию get('rowset.mark').

Например:

<rowsets>

  <rowset name="document">
    <rowset name="item">
      <requests>
        <param name="filter.documentid" js_value="get('document.id')"/>
        
        <request name="mark"/>
        <request name="delete" js_enabled="get('document.mode')=='specialMode'"/>
        <request name="append" js_enabled="get('document.mode')=='specialMode'">
          <param name="documentMode" js_value="get('document.mode')" skipempty="1"/>
        </request>
      </requests>
    </rowset>
  </rowset>
  
</rowsets>

В этом примере внесены изменения в описания запросов набора строк item:

• Добавлен параметр filter.documentid. В результате, значение этого параметра передается в каждый запрос, отправляемый набором строк item на сервер.
• Добавлена поддержка запроса mark. Это возможность на клиенте помечать строки.
• Для поддерживаемых набором строк запросов append и delete, добавлено динамически вычисляемое условие доступности выполнения запроса.
• Для запроса append добавлен параметр documentMode, передаваемый на сервер только при выполнении этого запроса.

Этот пример можно записать компактнее, опустив группирующий элемент requests:

<rowsets>

  <rowset name="document">
    <rowset name="item">
      <param name="filter.documentid" js_value="get('document.id')"/>
        
      <request name="mark"/>
      <request name="delete" js_enabled="get('document.mode')=='specialMode'"/>
      <request name="append" js_enabled="get('document.mode')=='specialMode'">
        <param name="documentMode" js_value="get('document.mode')" skipempty="1"/>
      </request>
    </rowset>
  </rowset>
  
</rowsets>