====== Этап разработки справочников LSS проекта ======
[[start:|lss]]
===== Введение =====
На этом этапе мы разработаем справочники **LSS проекта** - контроллеры источников данных **DataSource**, экранные формы, пункты меню для вызова экранных форм. Для наглядности заполним содержимое справочников тестовыми значениями.
===== Развертывание этапа на площадке =====
  * Скачаем архив **LSS проекта** для текущего этапа.
  * Обновим проект из архива. Надо быть осторожным с конфигурационным файлом площадки **php/config/config-place.php**, он содержит текущие параметры соединения с базой данных, его обновлять не надо.
  * Выполним с помощью утилиты **pgAdmin** скрипт заполнения содержимого таблиц первоначальными значениями, файл **export-import/backup/backup.sql**.
===== Описания =====
==== Создание экранных форм справочников ====
Описатели экранных форм справочников размещены в папке **php/forms/ref**. Имя подпапки **ref** следует воспринимать как пространство имен. 

Экранные формы справочников просты, для них используется стандартный контроллер **FormController**, размещенный в **php/lss-server/lib/form-controller.php**. Соответственно, описание экранных форм задается одним только XML шаблоном.

Подробнее о XML описании экранной формы можно посмотреть в [[form-definition|соответствующем разделе описания LSS протокола]].

Рассмотрим, например, XML шаблон экранной формы **formRepair** - виды ремонта:
<code>
<form name="%form%" caption="Виды ремонта">
  <rowsets>
    <rowset name="repair"/>
  </rowsets>
  
  <panels>
   <panel>
     <panel type="grid" rowset="repair">
       <toolbar menu="1">
         <request rowset="#this" name="undo"/>
         <request rowset="#this" name="save"/>
         <request rowset="#this" name="refresh"/>
         <separator/>
         <request rowset="#this" name="append"/>
         <request rowset="#this" name="delete"/>
       </toolbar>
       <fields>
         <field name="name"/>
       </fields>
     </panel>
   </panel>
  </panels>
</form>
</code>
где:
  * секция **rowsets** описывает подключение единственного источника данных - **repair**.
  * секция **panels** содержит единственную панель табличного редактора **grid** с единственным полем **name**.

Шаблон экранной формы **formDepartment** чуть сложнее:
<code>
<form name="%form%" caption="Структура предприятия">
  <rowsets>
    <rowset name="department">
      <rowset name="sector">
        <param name="filter.departmentid" js_value="get('department.id')"/>
      </rowset>
    </rowset>
  </rowsets>
	
  <panels>
    <panel>
      <panel type="grid" rowset="department" align="top" height="50%" splitter="1">
        <toolbar menu="1">
           <request rowset="#this" name="undo"/>
           <request rowset="#this" name="save"/>
           <request rowset="#this" name="refresh"/>
           <separator/>
           <request rowset="#this" name="append"/>
           <request rowset="#this" name="delete"/>
        </toolbar>
        <fields>
          <field name="name"/>
        </fields>
      </panel>
      <panel type="grid" rowset="sector">
        <toolbar menu="1">
          <request rowset="#this" name="undo"/>
          <request rowset="#this" name="save"/>
          <request rowset="#this" name="refresh"/>
          <separator/>
          <request rowset="#this" name="append"/>
          <request rowset="#this" name="delete"/>
        </toolbar>
        <fields>
          <field name="name"/>
        </fields>
      </panel>
    </panel>
  </panels>
</form>
</code>
где:
  * секция **rowsets** описывает подключение двух связанных источников данных данных - **department** и **sector**. При смене текущей строки в родительском источнике данных **department**, дочерний источник данных **sector** автоматически перечитывается. Параметр **filter.departmentid** задает условие фильтрации для источника данных **sector**
  * секция **panels** содержит 2 панели табличных редакторов **grid**, одну для **department**, другую для **sector**.
==== Создание контроллеров источников данных ====
Контроллеры источников данных **DataSource** размещаются в папке **php/datasources**. В подпапке **autogen** размещаются контроллеры, автоматически сформированные по описанию структуры данных, см [[lssexampl-02-datastru]]. Для автоматического формирования этих контроллеров следует использовать экранную форму **Разработка/Структура базы**, вызвав в ней пункт меню **Пересчет/Генератор классов DataSource**.

В корне папки **php/datasources** можно размещать контроллеры, унаследованные от автоматически сформированных, переопределяя заданные там методы и свойства. Для примера, возьмем контроллер для таблицы типов ремонтов **repair**.
Реализуем в нем проверку на уникальность содержимого поля **name**. Эта проверка и так есть - за счет уникального индекса на сервере PostgreSQL, см файл **sql/tables.sql**:
<code>
alter table "repair" add unique("name") deferrable initially deferred;
</code>
Эта проверка на уникальность происходит при завершении транзакции, но текст сообщения об ошибке выдается SQL сервером автоматически и может быть непонятен пользователю.

Добавим проверку на уникальность, цель которой - выдать наглядное сообщение при возникновении ошибки. Вот содержимое файла контроллера источника данных для таблицы **repair**, файл **php/datasources/repair.php**:
<code>
<?php
class DataSource_Repair_Ext extends DataSource_Repair {
  /// переопределяем проверку после правки строки
  protected function onRowValid(&$row) {
    {  // проверка значения поля name на уникальность - для более понятного пользователю сообщения об ошибке
    $sql_name=$this->str2Sql($row['name']);
    $sql_id=$this->str2Sql($row['id']);
    $sql=<<<SQL
select count(*) as n
from
	"repair"
where
	"repair".name='{$sql_name}' and
	"repair".id<>'{$sql_id}'
SQL;
    $rec=$this->pdoFetch($sql);
    if ($rec['n']) throw new Exception("Вид ремонта '{$row['name']}' уже есть");
  }
  }
}
return new DataSource_Repair_Ext();
</code>
Обратите внимание:
  * класс унаследован от автоматически сформированного контроллера **DataSource_Repair**
  * в конце программного кода создается и возвращается экземпляр описанного в файле контроллера **DataSource_Repair_Ext**
Сравните, в справочнике **Типы оборудования** проверка на уникальность поля **name** выполняется только средствами SQL сервера, а в справочнике **Виды ремонта** - перед завершением транзакции выполняется реализованная в **DataSource** проверка, и сообщение об ошибке оказывается более понятным.
==== Создание пунктов меню, для вызова экранных форм справочников ====
Главное меню проекта описывается в XML файле **php/config/appmenu.xml**. Скорректируем его описателями для вызова экранных форм справочников:
<code>
<node name="Справочники" icon="reffolder">
	<node name="Структура предприятия" icon="ref" form="ref.formDepartment"/>
	<node name="Виды ремонта" icon="ref" form="ref.formRepair"/>
	<node name="Типы оборудования" icon="ref" form="ref.formMachineType"/>
	<node name="Состояния оборудования" icon="ref" form="ref.formMachineStatus"/>
</node>
</code>
где:
  * **name** - наименование пункта меню.
  * **icon** - имя иконки. Имена и внешний вид доступных в проекте иконок можно увидеть с помощью экранной формы **Разработка/Иконки**. Подключение дополнительных иконок было разобрано в [[lssexampl-01-custom]].
  * **form** - имя экранной формы и место размещения ее описателя (в подпапке **php/forms**).
  * описатели, имеющие отношение к системе прав, разберем позже, на соответствующем этапе.
Работу главного меню системы обеспечивает источник данных **systreexmlmenu** расположенный в файле **php/lss-server/datasources/systreexmlmenu.php**. Этот источник задействован в главной экранной форме приложения, расположенной в папке **php/forms/formMain**.

===== Демонстрационные примеры и ссылки =====
Демонстрационные примеры доступны в режиме "**только чтение**". Для входа используйте логин **root**, пароль **1**.

  * демонстрация работы **тестового примера** "Материальные активы" у нас на сайте: [[https://lss.m-cti.ru/storage/example/lss-exampl]]