# Урок 9. Настройка печатных форм
Цель данного урока, ознакомить слушателя с принципами создания отчетов.

## 1.Печатные формы 
Печатная форма определяет тип шаблона отчёта, формат и правила его построения. 
При выполнении печатной формы формируется отчет в виде файла с заданным форматов.  
Печатная форма может быть подключена к документу с [типа объекта](books/AppGuide/030_class/075_тип_объекта.md) без внесения изменений в программный код.

### 1.1.Версии печатных форм 
Версия печатной формы позволяет:
- Безопасно вернутся к предыдущей реализации;
- Запускать реализацию в зависимости от периода;

Версия печатной формы содержит:
- Тип шаблона печатной формы;
- Бинарный файл для построителя отчетов; 
- Дату версии; 
- Описание;

### 1.2.Типы шаблонов печатных форм
Определяют формат в котором задаются шаблоны печатных форм.
- jasper \
    Java библиотека для построения печатных отчетов.
    Позволяет строить:
    - Готовые к печати PDF-файлы в интерактивном динамическом HTML с навигацией внутри или за пределами отчета
    - Высококачественные документы PowerPoint, RTF, Word
    - Электронные таблицы или необработанные CSV, JSON или XML
    
    Для изучения подробнее смотри:
    - [Руководство разработчика: Jasper Reports](books/AppGuide/060_reports/120_jasper_reports.md)

    #### Jaspersoft Studio 
    Шаблоны для построения отчетов пишутся в `Jaspersoft Studio`
    `Jaspersoft Studio` - это программное обеспечение для редактирования `JasperReports`. 
    Студия помогает:
    - Разрабатывать и запускать шаблоны отчетов;
    - Создавать запросы к отчетам;
    - Писать сложные выражения;
    - Компоновать визуальные компоненты.
   
    Шаблон представляет из себя zip архив содержащий набор xml файлов сформированных в [jasper studio](books/AppGuide/060_reports/120_jasper_reports.md).
    Jasper studio это специализированное средство построения печатных форм.
- xlsx \
    Шаблоном xlxs является документ в формате `xlxs`, размеченный согласно общим правилам разметки шаблонов
    Для изучения подробнее смотри:
    - [Руководство разработчика: Шаблоны отчетов](books/AppGuide/060_reports/125_шаблоны_отчетов.md)
- docx \
    Шаблоном docx является документ в формате `docx`, размеченный согласно общим правилам разметки шаблонов
    Для изучения подробнее смотри:
    - [Руководство разработчика: Шаблоны отчетов](books/AppGuide/060_reports/125_шаблоны_отчетов.md)

### 1.3. Выходные форматы шаблонов печатных форм
Если тип шаблона печатной формы поддерживает конвертацию в другие форматы, можно указать перечень доступных форматов. \
Если указано несколько доступных форматов, при печати печатной формы пользователю будет задан вопрос в каком формате построить отчет. 

#### Доступные форматы шаблонов печатных форм
- jasper
    - pdf
    - png
    - txt
    - html
    - xls
    - prt
- docx
    - docx
    - pdf
```{attention}
При установке выходного формата pdf шаблона docx на месте тегов в документе будут подставлены изображения. Детально данная функциональность будет описана ниже.
```
### 1.4. Загрузка файлов
Чтобы загрузить файл шаблона печатной формы в Global необходимо:
- Создать новую печатную форму в Global. \
    Чтобы настроить новую печатную форму в Global:
    1. Откройте приложение `Настройка системы`.
    2. Откройте перечень печатных форм `Отчеты > Печатные формы`.
    3. Используя операцию `Создать`  добавьте новый отчет.
    4. Заполните обязательные атрибуты и нажмите кнопку `Редактировать`, чтобы перейти в карточку.

- Привязать новую печатную форму к типу объекта. \
    Чтобы настроить новую версию печатной формы необходимо: 
    1. На вкладке `Версии печатной формы` создайте новую версию.
    2. Для версии выберите `Тип шаблона печатной формы`.
    3. Нажмите на кнопку `Загрузить файл в систему`.
    4. Выберите файл шаблона печатной формы:
        - jasper \
        Для шаблона типа "jasper" файлом шаблона будет являться архив, содержащий шаблон с наименованием "main.jrml".
            ```{attention}
            1. Шаблоныы суботчетов могут иметь любое название
            2. В архиве может быть только один основной отчёт с наименованием main
            ```
        - docx \
        Файл формата docx
        - xlsx \
        Файл формата docx

### 1.5. Параметры отчета
Параметры отчета передаются в запрос, формирующий данные для отчета. 

#### Пользовательские параметры
Настраиваются на печатной форме, и значения для таких параметров пользователь может внести  перед выполнением отчета.

#### Служебные параметры
Формируются автоматически

- `SIGNDATA_DZ` - Блок подписи
- `IDUSER` - Пользователь
- `IDSRCOBJECT` - Объект источник \
  Идентификатор объекта от которого выполняется печатная форма.
- `IDSRCCLASS` - Класс источник \
  Идентификатор класса объекта от которого выполняется печатная форма

#### Програмные параметры
Параметры переданные в Map программного метода при построении отчёта.

### 1.6. Вызов печатных форм
Печатные формы могут вызываться:
- из операции выборки;
- [из запроса к сервису печати](books/AppGuide/080_addition/140_сервисы_сервера.md#сервис-отчётов);
- [из rest сервиса](#формирования-файла-с-отчетом);
- От произвольного объекта системы;
- От интерфейса свободные отчеты.

#### Вызов печатной формы из операции выборки
Для вызова отчета из операции выборки используйте функцию `ru.bitec.app.gtk.gl.Reports#createReportEx`:
```scala
  /**
    * Выполняет построение отчёта по системному имени отчёта.
    *
    * @param reportName        Имя отчёта
    * @param reportVersionDate Дата
    * @param postBuildAction   Действие, которое необходимо произвести после заполнения отчёта
    * @param propertyMap       Карта входящих параметров
    */
  @throws[ApplicationException]
  def createReportEx(reportName: String, reportVersionDate: Date, postBuildAction: PostBuildAction, propertyMap: Map[String, Any]): Unit
```
Данная функция может быть вызвана только в контексте интерактивной бизнес логики(интерфейса пользователя).

Пример:
```scala
reports.createReportEx("Mct_OrderSheetMaterials2", null, PostBuildAction.print,
        Map[String, Any]("IDSRCOBJECT" -> getVar("id").asNLong,
          "GIDSRCOBJECT" -> getVar("gid").asNString,
          "SDESIGNATION" -> getVar("sCode").asNString)
      )
```

#### Формирования файла с отчетом
Для формирования файла с отчетом используйте функцию `ru.bitec.app.rpt.Rpt_Pkg#getReportStreamEx`:
```scala
  /**
    * Выполняет построение отчёта по системному имени отчёта.
    * Если для версии отчета указано несколько доступных для печати форматов,
    * то будет выдана ошибка построения.
    * Требуется явно указать формат построения, указав параметр [[Rpt_Pkg.ParamFormatType]]
    *
    * @param reportName        Имя отчёта
    * @param reportVersionDate Дата
    * @param propertyMap       Карта входящих параметров
    * @return InputStream, содержащий результат построения отчёта. ByteArrayInputStream не требует закрытия.
    */
  def getReportStreamEx(reportName: String, reportVersionDate: Date, propertyMap: Map[String, Any]): Option[InputStream]
```
Данная функция может быть вызвана в контексте автономной логики(rest сервиса)
```{attention}
В случае, если получен поток, его необходимо обязательно закрыть.
```

#### Вызов печатной формы от произвольного объекта 
При открытии карточки любого объекта, выводятся стандартные операции печати по которым можно
выполнять вызов печатных форм. 
Для добавления печатной формы к списку печати для типа объекта:
1. Откройте приложение `Настройка системы`.
2. Откройте типы объектов. \
   Выполните пункт меню `Сущности > Типы объектов > Типы объектов`.
3. Перейдите на вкладку `Печатные формы`.
4. Добавьте необходимые печатные формы.

#### Вызов печатной формы в свободных отчетах
Свободные отчеты позволяют настроить для пользователя и приложения перечень отчетов которые можно построить 
без привязки к каким либо типом объектов. 

Для вызова интерфейса построения свободных отчетов:
1. Откройте приложение.
2. Откройте свободные отчеты. \
   Выполните пункт меню `Отчеты > Свободные отчеты`.
3. Выберите нужный отчет.
4. Заполните параметры.
5. Напечатайте отчет. \
   Для этого выполните операцию `Печать`.

Для того чтобы ПФ могла быть вызвана из свободных отчетов:
1. Откройте приложение `Настройки системы`.
2. Откройте печатные формы. \
   Пункт меню `Отчеты > Печатные формы`.
3. Выберете требуемую печатную форму.
4. Включите признак `Свободный отчет`.
5. Настройте параметры отчета.
6. Укажите приложение для печати.
7. Укажите требуемые роли.
   ```{note}
   Если роли не указаны, печатная форма будет доступна всем пользователям
   ```
## 2. Шаблоны отчетов 
Шаблоны документов имеют одинаковую разметку, что позволяет, научившись размечать шаблоны одного типа, создавать отчёты других типов.

Рассмотрим основные положения.

Основным элементом разметки шаблона является 
- `Тэг` \
  Текст окружённый спецсимволами, управляющий формированием отчёта. 
  
Все тэги имеют следующий вид: `[#{значение}#]`

Простейшим случаем является Тэг, возвращающий значение атрибута строки: `[#{имя атрибута}#]`. 

С помощью таких тэгов обозначаются места, которые должны быть заполнены данными. 
Если в данных не будет найден атрибут или параметр с именем `{имя атрибута}`, текст будет заменён на пустоту. 

Для печати в отчете набора данных предназначены переменные части, позволяющие выполнять запросы и выводить в отчёт данные с изменяющимся количеством строк. 

Переменной частью называется область шаблона, ограниченная открывающим и закрывающим тэгами. Переменная часть будет выведена в отчёт столько раз, сколько записей находится в выборке переменной части.

Форматы тегов для печати данных из запроса:
- открывающий тэг
  ```
  [#&{произвольное системное имя}={SQL запрос}#]
  ```
- закрывающий тэг
  ```
  [#/{произвольное системное имя}#]
  ```
```{attention}
Важно понимать, что при построении шаблона отчёта все строчки внутри открывающего и закрывающего тэга будут удалены из документа. Поэтому для корректного построения отчёта они не должны содержать ничего лишнего. 
```

Переменная часть обязательно должна заканчиваться закрывающим тэгом, системное имя которого совпадает с системным именем открывающего тэга. Все системные имена открывающих тэгов начинаются с символа `&`, а все закрывающие тэги начинаются с символа `/`.

При выводе данных в отчет из запроса открывающий тэг переменной части состоит из произвольного уникального в рамках шаблона имени и SQL запроса. В этом случае для данной переменной части также будет создан набор данных с запросом указанным в тэге.

Переменные части могут быть вложенными друг в друга, образовывая связку мастер-деталь.

### Настройки вставки изображений в печатную форму типа docx
Данная настройка производится в коллекции к печатной форме. 

Для изучения подробнее смотри:
[Настройки вставки изображений в печатную форму типа docx](books/AppGuide/115_Отчеты.md#Настройки-вставки-изображений-в-печатную-форму-типа-docx)

Для вставки изображений в печатную форму типа docx должны быть выполнены следующие условия:
1. Печатная форма должна содержать теги вида [SomeTag] 
    ```{attention}
    Не путать с тегами разметки шаблона!
    ```
1. Тип шаблона печатной формы - docx
1. Формат печатной формы - pdf
1. В коллекции к печатной форме(Настройки вставки изображений в печатную форму) настроены необходимые изображения для вставки

Если все требования выполнены корректно, то при печати такой печатной формы будет получен pdf файл с изображениями на месте тегов.


## 3. Jaspersoft Studio

### 3.1. Основные визуальные элементы
![Основные визуальные элементы Jaspersoft Studio](img/l9_1JasperInterface.png)

#### Repository
Содержит перечень подключений к разным базам данных. 
Подключения к базе данных необходимо настраивать для того чтобы была возможность тестировать отчеты из jasper studio.

#### Outline
Отображает структуру открытого отчета. 

#### Properties 
Отображает свойства элемента выбранного в `outline`. Набор закладок, отображемых в данной области, зависит от выбранного эелеметна. 

#### Editor
Отображает открытый отчет.
Содержит следующие закладки:
- Design - используется для редактирования шаблона с использованием визуальных компонентов Jaspersoft Studio.
- Source - на закладке содержиться xml-разметка шаблона, которую при необходимости можно отредактировать.
- Preview - используется для предпросмотра отчёта, сформированнного на основе шаблона.

#### Project Explorer
Обозреватель проектов используется для добавления, удаления новых проектов, папок, отчетов, а также их выбор для модификации.

### 3.2. Проект
Все шаблоны печатных форм в Jaspersoft Studio создаются внутри проекта, который содержит все необходимые для этого библиотеки. При установке в Jaspersoft Studio создается проект по умолчанию «MyReports». Однако при необходимости можно создать новый проект.
```{tip}
Печатные формы проще создавать и редактировать в одном проекте если они не содержат скриплетов. 
```

Для создания проекта отчёта:
1. Выполните `File > New > Project …`
2. Выберите `Jaspersoft Studio / JasperReports Project`
3. Задайте имя отчёта в следующем диалоге.

По завершению на закладке `Project Explorer` появится новый проект, пока ещё не
содержащий шаблонов отчёта.
### 3.3. Параметры
Для изучения подробнее смотри:
[Параметризация шаблонов](books/AppGuide/060_reports/120_jasper_reports.md#Параметризация-шаблонов)

Параметры отчета находятся в окне `Outline` по адресу `{Report} \ parameters`
Параметры отчёта используются для следующих целей:
- В SQL-запросах \
  Для ограничения данных по переданным из вне параметрам
- Связи между частями шаблонов 
- Для связи между движком отчёта и внешним окружением.

Параметры могут быть любого java-типа. 

Например: 
- `REPORT_CONNECTION` тип `java.sql.Connection` 
- `REPORT_PARAMETERS_MAP` тип `Map<String,Object>`

Шаблон отчёта содержит
множество служебных параметров. В дереве элементов шаблона они
отображаются серыми. Их невозможно удалить, или изменить значение из
дизайнера. Их значения могут быть переданы извне или изменены в коде.

```{attention}
Создавайте параметры с именами в верхнем регистре. Это связано с тем,
что имена параметров, переданных извне, приводятся к верхнему регистру
автоматом.
```
Использовать параметры можно в полях отчёта в запросе данных даже в других параметрах для того чтобы использовать параметр наименование этого параметра нужно обернуть в тэг `$P{PARAMETER_NAME}`

### 3.4. Адаптеры данных
Для создания адаптера
1. В окне «Repository Explorer» выполните операцию «Create Data Adapter» \
   ![](img/l9_2reposityry_explorer.png)
1. В открывшемся диалоге выберите "Data base JDBC connectivity"
2. Укажите реквизиты подключения к базе Postgres
   - `name={имя подключения}` 
   - `JDBC driver=org.postgresql.Driver`
   - `JDBC url=jdbc:postgresql://{host}/{db}`
   - `Username ={username}`

```{note}
Подключение к БД необходимо для того, чтобы тестировать отчет из студии.
```

### 3.5. Запрос данных

### 3.6. Структура страницы шаблона
Созданный шаблон разделен на следующие области:
- Title – заголовок шаблона;
- Page Header – верхний колонтитул шаблона;
- Column Header – область для названия столбцов отчета;
- Detail N – область детализации отчета. В отчет могут быть добавлены несколько областей такого типа (Detail 1, Detail 2 и т.п.) в случае, если есть необходимость разделить детализацию отчета.  Например, эта возможность используется, когда необходимо добавить два вложенных отчета;
- Column Footer – нижний колонтитул табличной части шаблона;
- Page Footer – нижний колонтитул шаблона;
- Summary - содержит итоги по отчету. Данные этой области выводятся в конце отчета, построенного по текущему шаблону;
- Background – часть шаблона, на которой размещается фон для печатной формы. 
Так же в отчет можно добавить дополнительные области:
- Last Page Footer – нижний колонтитул, данные которого выводятся в отчете на последней странице отчета, построенного по текущему шаблону;
- No Data – область, которая выводится при построении печатной формы, если отчет не содержит данных (т.е. является пустым).
### 3.7. Скриптлеты
Для изучения подробнее смотри:
[Скриплеты](books/AppGuide/060_reports/120_jasper_reports.md#Скриптлет-(Scriptlet))

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

Дополнительная информация:
- [all-you-want-know-about-scriptlets](https://community.jaspersoft.com/blog/all-you-want-know-about-scriptlets)
- [hello-world-sample-example](https://community.jaspersoft.com/blog/scriptlet-example-jaspersoft-6x-begineers-hello-world-sample-example)
- [sample reference](http://jasperreports.sourceforge.net/sample.reference/scriptlet/)

Скриптлет наследуется от одного из классов:
- `net.sf.jasperreports.engine. JRAbstractScriptlet`
- `net.sf.jasperreports.engine.JRDefaultScriptlet`

Экземпляр данного класса создаётся при заполнении отчёта, и его методы
вызываются на различных этапах в качестве обработчиков. Так же скриптлет
может содержать пользовательские методы, которые можно вызвать через
выражения «Expression» полей, переменных и т.п.

### 3.8. Публикация отчётов в БД

Для обеспечения доступа сервера Global 3 к шаблону отчёта, zip-архив с
шаблоном необходимо загрузить в базу данных через приложение "Настройка
системы", 
пункт меню `Отчёты > Печатные формы > Версии печатной формы > Загрузить в базу`.

Шаблон JasperReports-отчёта может состоять из нескольких файлов
(мастер-деталь, несколько страниц) и содержать различные ресурсы
(картинки, скриптлеты). Поэтому, для сохранения в базу, шаблон
необходимо заархивировать в zip-архив. `Файл main.jrxml` должен находиться
в корне архива, иначе он не будет найден. Остальные файлы могут быть
во вложенных каталогах, главное, что бы в шаблоне были указаны верные
относительные ссылки.

Архив не должен содержать бинарных `*.jasper` файлов.

При построении, zip-архив будет разархивирован во временный каталог.

#### Ручная загрузка отчетов
1. В `Project Explorer` выберите папку содержащую отчеты печатной формы.
2. В контекстном меню выполните `Export`.
3. Выберите тип `Archive file`.
4. Выберете фалы для экспорта.
   ```{attention}
   Допустимы только следующие расширения:
   - `jrxml`
   - `class`
   - `jar`
   ```
5. Укажите опцию `save in zip archive`.
6. Укажите файл куда сохранить шаблон.
7. Откройте приложение `Настройки системы`.
8. Откройте печатные формы. \
   Пункт меню `Отчеты > Печатные формы`.
9. Создайте версию печатной формы.
10. Загрузите шаблон печатной формы.

```{attention}
Убедитесь что файлы экспортируются в корень архива. 
Для этого при экспорте должна быть установлена опция `Create only selected directories`
```

#### Загрузка отчета на dataInstall
Загрузку отчета в базу можно добавить в dataInstall получив blob отчета
с помощью метода `Rpt_ReportVersionApi().compress`.

Пример:
```scala
val blobData = Rpt_ReportVersionApi().compress(
    List((   
        "subreport1.jrxml",
        getClass.getResourceAsStream("/reports/Mes_PlanReport/subreport1.jrxml")
    ),( 
        "subreport2.jrxml",
        getClass.getResourceAsStream("/reports/Mes_PlanReport/subreport2.jrxml")
    ),( 
        "order.jrxml",
        getClass.getResourceAsStream("/reports/Mes_PlanReport/order.jrxml")
    ),(
        "main.jrxml",
        getClass.getResourceAsStream("/reports/Mes_PlanReport/main.jrxml"))  
    )
)
```
Полностью пример можно посмотреть в
`ru.bitec.app.bs.Bs_DataInstallPkg#reportInstall`.



## Практики 
### Создание jasper-отчета
Для документа `Приходная накладная` создать отчёт с деталью(суботчётом) 
Поля отчёта(берём из класса `Приходная накладная`):
- Документ - выводим sNumDoc;
- Владелец - выводим idDepOwner;
- От(Дата) - выводим dDoc;
- Состояние - выводим idState;
- Сумма - выводим nSum;
- Дата - выводим Дата печати отчёта;
- Акт # - выводим Мнемокод документа.

![Создание jasper-отчета `Приходная накладная`](img/l9_3report.png)

Поля для детали отчёта (берём из класса `Состав накладной`):
- Номер - выводим sNumber;
- Книга - выводим idBook;
- Цена - выводим nPrice;
- Кол-во - выводим nQty.

![Создание jasper-отчета `Состав накладной`](img/l9_3reportsub.png)


### Создание docx шаблона
Отчёт из предыдущего задания передалась как шаблон docx.

### Формирование печатных форм из приложения
Загрузить 2 отчёта с помощью метода datainstall класса `Приходная накладная`. Настроить данные отчёта на типе обЪекта для этого класса