====== Подробное описание секции наборов строк ======
[[start:|lss]] | [[form-definition]]
===== Введение =====
[[rowset-definition|Наборы строк]] содержат отображаемые [[form-definition|экранной формы]] данные. Эти данные отображаются в визуальных элементах экранного интерфейса - панелях. Именно [[rowset-definition|наборы строк]] манипулируют данными на клиенте - отвечают за правку данных и взаимодействие с сервером.
Используемые в [[form-definition|экранной форме]] [[rowset-definition|наборы строк]] должны быть объявлены в секции **rowsets**.

Тут есть хитрость: у [[rowset-definition|набора строк]] на стороне сервера есть контроллер. Этот контроллер умеет возвращать описание своего [[rowset-definition|набора строк]] по [[request|запросу]] **definition**. А описания в секции **rowsets** позволяют подстроить типовое унифицированное описание [[rowset-definition|набора строк]] под нужды конкретной [[form-definition|экранной формы]].
===== Родительский и дочерние наборы строк =====
На уровне [[form-definition|экранной формы]] [[rowset-definition|наборы строк]] можно выстроить в иерархию: родительский - дочерний. При смене текущей строки в родительском [[rowset-definition|наборе строк]] его дочерние [[rowset-definition|наборы строк]] автоматически перечитываются. Задача программиста описать в дочерних [[rowset-definition|наборах строк]] фильтры так, что бы после перечитки содержимое дочернего [[rowset-definition|набора строк]] соответствовало текущей строке родительского [[rowset-definition|набора строк]].

Пример:
<code>
<rowsets>

  <rowset name="document">
    <rowsets>
      <rowset name="item">
        <param name="filter.documentid" js_value="get('document.id')"/>
      </rowset>
    </rowsets>
  </rowset>
  
</rowsets>
</code>
В этом примере описаны 2 [[rowset-definition|набора строк]]: **document** и **item**. Их подробное описание в секции **rowsets** отсутствует, так как размещенные на сервере контроллеры [[rowset-definition|наборов строк]] вернут [[form-definition|экранной форме]] их унифицированные описания, по [[request|запросу]] **definition**.

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

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

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

===== Набор строк фильтра =====
Есть типовая задача - [[form-definition|экранная форма]] должна отображать не все данные, а только интересующую пользователя часть, причем пользователь может задавать фильтруемые значения. Для хранения и правки данных фильтра в LSS используется специальный [[rowset-definition|набор строк]] - фильтр. Он задается параметром **filter="1"**.

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

Пример:
<code>
<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>
</code>
В этом примере [[rowset-definition|набор строк]] с именем **filter** объявлен как фильтр посредством атрибута **filter="1"**. В секции **fields** описаны его поля. У полей **doctypeid** и **doctype_name** с помощью атрибута **default** заданы начальные значения.
 
[[rowset-definition|Набор строк]] **document** описан как дочерний к нему. Каждое изменение пользователем значения поля [[rowset-definition|набора строк]] фильтра автоматически вызовет перечитку дочернего [[rowset-definition|набора строк]] **document**. Посредством задания параметров **filter.doctypeid**, **filter.ndoc** и **filter.ddoc** введенные пользователем значения [[rowset-definition|набора строк]] фильтра передаются в контроллер [[rowset-definition|набора строк]] **document**. Атрибут **skipempty="1"** означает, что если соответствующее поле фильтра не задано и, следовательно, значение параметра пусто, то параметр передавать на сервер не надо.
===== Корректировка описания набора строк =====
==== Корректировка заголовка ====
Чаще всего, при корректировке заголовка [[rowset-definition|набора строк]] в секции **rowsets**, возникает необходимость настраивать доступность [[rowset-definition|набора строк]] для правки и описывать параметры работы **пагинатра**.

Например:
<code>
<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>

</code>
В этом примере [[rowset-definition|набор строк]] **document** работает в режиме **пагинации**. В каждом [[request|запросе]] серверу на начитку данных добавляются параметры пагинатора: **paginator.from** и **paginator.count**. Контроллер [[rowset-definition|набора строк]] на сервере должен уметь их обрабатывать, и возвращать в ответе только соответствующие параметрам пагинации строки.
А у [[rowset-definition|набора строк]] item задано динамическое условие на доступность [[rowset-definition|набора строк]] только на чтение. 

Другая интересная возможность - можно задать id строки, на которую [[rowset-definition|набор строк]] должен спозиционироваться при открытии [[form-definition|экранной формы]]:
<code>
<rowsets>

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

</code>
В этом примере, при первой перечитке [[rowset-definition|набора строк]], при открытии [[form-definition|экранной формы]], на сервер будет передан дополнительный параметр: 
<code>
<param name="row.focus.id" value="243"/>
</code>
Контроллер [[rowset-definition|набора строк]] на сервере должен этот параметр корректно отработать:
  * если включен режим пагинации, то найти и вернуть в ответе ту порцию данных, в которой размещена строка с заданным **id**
  * пометить эту строку признаком **row.focus="1"**
==== Корректировка полей ====
Описание [[rowset-definition|набора строк]] состоит из описания поддерживаемых им [[request|запросов]] и описаний его полей.
В секции **rowsets** можно вносить изменения в универсальное, не зависящее от [[form-definition|экранной формы]], описание списка полей [[rowset-definition|набора строк]]. Там можно осуществлять привязку описания полей к контексту использования.
Для поля, в секции **rowsets**, можно задавать значения атрибутов **js_readonly**, **js_visible**, **caption**, **len**, **stretch** и т.д. Для справочников можно модифицировать параметры, передаваемые при начитке допустимых строк справочника.

Например:
<code>
<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>
</code>
В этом примере модифицировано описание поля справочника **itemtypeid** [[rowset-definition|набора строк]] **item**. 
Для него:
  * Выписано динамическое выражение, описывающее доступность поля для правки - **js_readonly**.
  * Внесены изменения в начитку строк справочника: при раскрытии диалога выбора строки справочника происходит начитка **itemtype**. При этом контроллеру **itemtype** на сервер отправляется дополнительный параметр **filter.doctypeid**, контроллер должен его корректно обработать, и вернуть только подходящие строки.
  * Группирующий элемент **fields** не обязателен, его можно опустить. Тогда элементы **field** можно размещать непосредственно в узле **rowset**.
==== Корректировка запросов ====
Описание [[rowset-definition|набора строк]] состоит из описания поддерживаемых им [[request|запросов]] и описаний его полей. В описание [[request|запросов]] можно вносить изменения, позволяющие привязать работу 
[[rowset-definition|набора строк]] к [[form-definition|экранной форме]]. Можно:
  * Задавать доступность/запрет выполнения [[request|запроса]] в зависимости от контекста, посредством параметра **js_enable**
  * Подстраивать передаваемые [[request|запросу]] параметры
  * Включать поддержку [[request|запроса]] пометки строки **mark**. Обычно этот [[request|запрос]] отрабатывает на клиенте, без обращения к серверу. А список помеченных строк можно передать на сервер параметром [[request|запроса]], используя функцию **get('rowset.mark')**.
Например:
<code>
<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>
</code>

В этом примере внесены изменения в описания [[request|запросов]] [[rowset-definition|набора строк]] **item**:
  * Добавлен параметр **filter.documentid**. В результате, значение этого параметра передается в каждый [[request|запрос]], отправляемый [[rowset-definition|набором строк]] **item** на сервер.
  * Добавлена поддержка [[request|запроса]] **mark**. Это возможность на клиенте помечать строки.
  * Для поддерживаемых [[rowset-definition|набором строк]] [[request|запросов]] **append** и **delete**, добавлено динамически вычисляемое условие доступности выполнения [[request|запроса]].
  * Для [[request|запроса]] **append** добавлен параметр **documentMode**, передаваемый на сервер только при выполнении этого [[request|запроса]].

Этот пример можно записать компактнее, опустив группирующий элемент **requests**:
<code>
<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>
</code>