# Jasper Reports
Java библиотека для построения печатных отчетов.
Позволяет строить:
- Готовые к печати PDF-файлы в интерактивном динамическом HTML с навигацией внутри или за пределами отчета
- Высококачественные документы PowerPoint, RTF, Word
- Электронные таблицы или необработанные CSV, JSON или XML

```{note}
Данный раздел не является полным руководством к средству построения
отчётов JasperReport. Документ содержит описания базовых принципов
создания шаблонов и способов взаимодействия инфраструктуры Global 3 SE с
построителем отчётов JasperReports.
```

## Дистрибутив

Скачать дистрибутив можно

- с ftp по адресу `ftp://ftp.bitec.ru/pub/#Distrib/JasperStudio`

Для разработки шаблонов отчётов доступны две IDE: 
- Jaspersoft® Studio 
- iReport Designer. 

```{note}
Данный раздел касается только Jaspersoft Studio.
```

## Jaspersoft Studio 
Программное обеспечение, которое позволяет создавать и редактировать шаблоны JasperReports. С помощью Jaspersoft Studio возможно:
- Разрабатывать и запускать шаблоны отчетов
- Создавать запросы к отчетам
- Писать сложные выражения
- Компоновать визуальные компоненты

```{attention}
Перечень шрифтов в дизайнере Jaspersoft Studio может отличатся от перечня шрифтов на сервере приложения.
Используйте стандартные шрифты, к примеру `Arial`
```

## Обучающее видео

Виде выложено на Ftp по адресу `ftp://ftp.bitec.ru/pub/#Global/Video/Обучение/Создание ПФ отчетов в Jasper`

## Документация JasperReports

- [Ресурсы с jaspersoft](https://community.jaspersoft.com/project/jasperreports-library/resources)
- [jaspersoft Wiki](https://community.jaspersoft.com/wiki/jaspersoft-community-wiki-0)
- Руководство пользователя по адресу `ftp://ftp.bitec.ru/pub/#Distrib/JasperStudio`


Для того чтобы открыть примеры Jaspersoft Studio: 
1. Выполните `File > New > Project > JasperReports Samples`. \
    В выбранном рабочем каталоге будет создано множество примеров отчётов.

## Пользовательский интерфейс
![](jasper_report_img/user_interface.png)

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

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

### Properties 
Отображает свойства элемента выбранного в `outline`.


### Editor
Отображает открытый отчет.
Содержит следующие закладки:
- Design
- Source
- Preview

## Колонки
Страницы отчета содержат банды(группы визуальных элементов), независимые от данных (например,
заголовок или нижние колонтитулы страницы), и банды, которые печатаются только при наличии одной или нескольких записей из данных для печати.
Банды с данными можно разделить на вертикальные столбцы, чтобы максимально
использовать доступное пространство на странице.
Количество колонок можно задать в диалоге разметки страницы(`properties\reports\page format` для `outline\{Report}`)

## Bands 
Отчет делится на банды, в которые добавляются визуальные элементы.
Список основных предопределенных бандов:
- `Title` \
  Это первый видимый банд. Он создается только один раз и может быть распечатан на
  отдельной странице
- `Page Header` \
  Позволяет определить заголовок страницы
- `Column Header` \
  Печатается перед началом отрисовки колонки.
  Количество колонок на странице можно задать в 
- `Column Footer` \
  Печатается в конце каждой колонки
- `Page Footer` \
  Появляется в конце каждой страницы 
- `Summary` \
  Содержит итоги по отчету

### Detail band
Печатается для каждой записи данных отчета.
Детальных бандов может быть несколько, поэтому по умолчанию создается детальный банд с именем 'detail 1'

В детальной части можно расположить  «Text Field» и
задать для каждого выражения получения данных.

![](jasper_report_img/band_detail1.png)

## Настройка среды Jaspersoft Studio

Запустите среду разработки отчётов Jaspersort Studio

### Создание подключения к ДБ

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

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

## Проект отчета
Проект отчета создается на группу печатных форм, на усмотрение аналитика. 
```{tip}
Печатные формы проще создавать и редактировать в одном проекте если они не содержат скрипелтов. 
```

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

По завершению на закладке `Project Explorer` появится новый проект, пока ещё не
содержащий шаблонов отчёта.
![](jasper_report_img/project_explorer.png)


## Создание простой печатной формы

Простейший отчёт, выводящий список на основе SQL-запроса.
1. В окне `Project Explorer` выберете требуемы проект
2. Создайте каталог для печатной формы \
   В контекстном меню выполните пункт `New > folder`
3. Создайте отчет \
   В контекстном меню выполните пункт `New > Jasper Report`
4. Задайте имя шаблона отчета `main.jrxml` \
   Файл с этим именем будет искаться при построении отчёта из Global 3 SE.
5. Нажмите кнопку `next`
6. Выберете адаптер базы данных
7. Нажмите кнопку `next` 
8. Введите запрос
9. Нажмите кнопку`next`
10. Добавьте требуемые поля в соответствующие банды
11. Нажмите кнопку `finish`
12. Проверьте корректность отчета на закладке `Preview` в окне `Editor`
13. [Опубликуйте отчет в БД](#публикация-отчётов-в-бд)

Редактирование запроса с данными:
1. Откройте отчет
2. В окне outlet выберете корень
3. Нажмите кнопку `Edit query, filter and sort options` \
   Кнопка находится в окне Properties по адресу  `Report \ DataSet`

Так же запрос можно посмотреть в окне Properties на закладке`Advanced`
![](jasper_report_img/outline.png)


## Двухуровневый отчёт (мастер-деталь)

[Документация в wiki](https://community.jaspersoft.com/wiki/subreports)

1. Создайте файл мастер-шаблона `main.jrxml`(имя обязательно)  \
   Аналогично одноуровнему шаблону.
2. Создайте файл детального-шаблона `subreport.jrxml` \
   В данном шаблоне будут отображать детальные данные.
   Имя может быть любым. 
3. Добавьте в мастер `Subreport` \
   Откройте мастер шаблон и в окне outlet в секцию `Detail 1` добавьте элемент
    `Subreport`, в свойствах которого укажите
    - Имя файла детального шаблона \
      Expression=`"subreport.jrxml"`
    - Подключение к БД \
      Connection Expression = `$P{REPORT_CONNECTION}`
4.  Свяжите запросы двух шаблонов параметрами.
    1.  Создайте в детальном шаблоне параметр `ID_MASTER`
    2.  Параметризуйте детальный запрос \
        Обращение к параметру в детальном запросе `$P{ID_MASTER}`
    3.  Свяжите параметр детального шаблона с мастером \
        1.  Зайдите в раздел "Subreport" свойств мастер-шаблона
        2.  Вызовите диалог редактирования свойства "Edit Parameters"
        3.  Задайте связь \
            Для этого создайте параметр `ID_MASTER` c выражением `$F{id}`

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

## Отчет книга (Report Book)

Отчет книга – это .jrxml, который объединяет несколько отчетов в единый
объект.

[Документация в wiki](https://community.jaspersoft.com/wiki/report-books-jaspersoft-studio)

1. Создайте новый отчет-книгу
   1. Кликните правой кнопкой мыши в `Project Explore` и выполните пункт `New > Jasper Report`
   2. В новом мастере создания отчета выберет `Report Books \ Empty Book`
   3. Укажите имя `main.jrxml` (имя обязательно) 
2. Создайте отчет, который будет отображаться в книге. \
   Отчет может быть как одноуровневым, так и двухуровневым.
3. В отчете-мастере вызовите контекстное меню и выполните пункт "Add new book part"
4. Добавьте отчет, созданный в пункте 2
5. Свяжите отчеты между собой 
    Связь запросов двух отчетов параметрами происходит аналогично
    двухуровневому отчету

```{attention}
Отображение номеров страниц в отчетах, отображаемых в книге
осуществляется через переменную `$V{MASTER_CURRENT_PAGE}`, а общее
количество страниц – через `$V{MASTER_TOTAL_PAGES}`. В настройках
текстового поля должно быть указано `evaluationTime="Master"`
```


## Параметризация шаблонов

[Документация в wiki](https://community.jaspersoft.com/wiki/using-report-parameters)

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

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

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

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

Параметр имеет значение по умолчанию. Его удобно использовать при
разработке и тестировании отчёта, заменяя передачу значения параметра
извне.

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

Флаг `Is For Prompting` означает, что при тестовом построении отчёта из
среды Jaspersoft Studio будет запрошено значение параметра.

```{attention}
Создавайте параметры с именами в верхнем регистре. Это связано с тем,
что имена параметров, переданных извне, приводятся к верхнему регистру
автоматом.
```

### Передача параметров в отчёт

В отчёт можно передать значение параметра с любым типом данных, в том
числе служебных параметров. Так же, через параметры можно передать
значения макросов фильтра, сортировки или весь запрос целиком.
```scala
@Oper(
    caption = "Печать", 
    description = "Печать", 
    imageIndex =17, 
    order = 100
)  
def printReport(): Unit = {  
    createReportEx(
        getVar("sSystemName").asString(), 
        null,
        PostBuildAction.print,  
        Map[String, Any](
            "ParamTestLong" -> 100500.nl,  
            "ParamTestDouble" -> NNumber.fromAny(100500.100500D),  
            "ParamTestString" -> "Тестовая строка",  
            "ParamTestDate" -> NDate.now(),  
            "MacroTestFilter" -> "(1 = 1)"
        )  
    )  
}
```
Карта значений всех переданных извне параметров доступна в служебном
параметре `REPORT_PARAMETERS_MAP`. 

Значение можно получить выражением:
```
$P{REPORT_PARAMETERS_MAP}.get("ИМЯ_ПАРАМЕТРА")
```

Если в шаблоне создать параметр `MY_PARAMETER`, имя которого в верхнем
регистре равно имени переданного в отчёт параметра, значение
`MY_PARAMETER` будет проинициализировано переданным значением. Это
позволяет использовать переданные значения параметров в SQL-запросах.

Пример использования, в отчёте: `Rpt_JasperSimpleQuery`

### Использование параметров в SQL-запросах

#### Подстановка значения

Подстановка значения параметра в запрос выполняется выражением $P{ИМЯ
_ПАРАМЕТРА}. Следите за регистром имён параметров, в случае
несовпадения будет ошибка компиляции.
```
select o.*, $P{MY_ORDER_ID} as idMy 
  from orders o 
 where order_id = $P{MY_ORDER_ID}
```
В данном случае будет выполнен sql запрос:
```sql
select o.*, ? as idMy from orders o where order_id = ?
```
Значение параметра отчёта будет передано как значение sql-параметра.

#### Подстановка выражения (макроса)

Для подстановки в sql-запрос выражения (или полного текста sql-запроса)
необходимо использовать синтаксис `$P!{ИМЯ _ПАРАМЕТРА}`.
```
select * from orders order by $P!{ИМЯ _ПАРАМЕТРА}
select * from orders where $P!{ИМЯ _ПАРАМЕТРА}
$P!{MY_QUERY}
```

### Использование параметров, содержащих список значений

В отчет можно передавать массив значений в одном параметре. 
Для этого в `REPORT_PARAMETERS_MAP` в значении параметра нужно передать массив
`Array[java тип]()`. 

Например: 
```scala
"TEST" -> Array[Long](23553,23552)
```
#### Настройка параметра с множеством в Jasper Studio

В Jasper Studio нужно выбрать тип для параметра, которому будет передаваться
массив значений:
1. Перейдите к параметрам отчета
2. Откройте свойства параметра
3. Задайте "Class" значением `ArrayList`
4. Задайте "Nested type name" \
   К примеру `Long` или `String`


#### Использование параметров с null

Для использования в SQL параметров которые могут быть принимать значение null  
необходимо использовать синтаксис `$X{ИМЯ_ФУНКЦИИ, ИМЯ_КОЛОНКИ, ИМЯ_ПАРАМЕТРА}`.

Где `ИМЯ_ФУНКЦИИ`
- `EQUAL`
- `NOTEQUAL`
- `LESS`
- `GREATER`
- и др.

Для запроса 
```
select * from orders where $X{EQUAL, num_column, num_param}
```
Будут сгенерирован текст:
```
select *  from orders where num_column = 1
```
Или если параметр null 
```
select *  from orders where num_column IS null
```

### Управляющие параметры

На процесс построения и экспорта отчёта могут влиять:
- Служебные параметры отчёта
- Свойства контекста построения отчёта

#### Служебные параметры отчёта.
| Имя | Возможные значения | Описание |
|-|-|-|
| REPORT_LOCALE | Locale.forLanguageTag("ru-RU") | Устанавливает локаль, используемую при построении отчёта |

#### Свойства контекста построения отчёта. 
Имя свойства контекста построения отчета начинается с `net.sf.jasperreports`
Полный список можно найти в [документации JasperReports](http://jasperreports.sourceforge.net/config.reference.html)

Значения по умолчанию определены в ресурсах JasperReports: 
``` 
jasperreports-x.x.x.jar\default.jasperreports.properties
```
Значения могут быть переданы через параметры метода `createReportEx()` или
определены с свойствах шаблона ("Properties \ Advanced \ Misc \ Edit
Properties")

#### Дополнительные управляющие параметры

Параметры, передающиеся в отчет стандартной операцией печати:
- `idSrcObject` \
  id объекта от которого создан отчет
- `idSrcClass` \
  id класса объекта от которого создан отчет
- `idUser` \
  id пользователя
- `signData_dz` \
  json, подписи печатных бланков для отчетов \
  Пример значения:
  ```json
  [
      {
          "sFIO": "Калинин В.М.",
          "sPosition": "Транспортировщик",
          "idEmployee": 25712,
          "idDepartment": 101672,
          "sBasisDocument": "  №036/426-06-2020-ОЛПС           от 01.01.2020",
          "idBlankSignType": 95351,
          "gidBasisDocument": "139800/5433"
      }
  ]
  ```

## Экспорт

По умолчанию, отчёт экспортируется в pdf. Формат, в который будет
выполнен экспорт, определяется параметром `FILENAME`. 

На экспорт влияют [параметры контекста построения](#управляющие-параметры), имена которых начинаются с
`net.sf.jasperreports.export`.

Описание параметров:
- `FILENAME` \
  Определяет имя и формат файла с результатом построения отчёта. 
  Отчёт может быть экспортирован в следующие форматы:
  pdf, xls, docx, xlsx, pptx, xml, json, html, ods, odt, rtf, txt, jpg, jpeg, gif, png. \
  По умолчанию, экспортируется в pdf.
  Возможные значения c AS 1.18: \
  ```
  {name} | {name.} | {name.ext} | {.ext}
  ```
  Возможные значения до AS 1.17: \
  ```
  {name.ext} | {.ext} | {ext}
  ```

### Растровые изображения

Дополнительные параметры контекста, отсутствующие в списке стандартных
свойств контекста JasperReports.
- `net.sf.jasperreports.export.graphics2d.page.index` тип `Integer` \
  Номер экспортируемой страницы.
- `net.sf.jasperreports.export.graphics2d.zoom.ratio` тип Float \
  Коэффициент увеличения. По умолчанию, страница формата A4 имеет размеры 842x595px, 72dpi. 
  При экспорте в растровое изображение с такими параметрами, читаемость текста крайне низка. 
  Параметр позволяет пропорционально увеличить размеры изображения без потери качества.
- `net.sf.jasperreports.export.graphics2d.offset.x` тип `Integer` \
  Сдвиг по оси X
- `net.sf.jasperreports.export.graphics2d.offset.y` тип `Integer` \
  Сдвиг по оси Y

#### GIF и PNG с прозрачностью

Для экспорта страницы отчёта в gif или png с прозрачным фоном
необходимо отключить заливку фона белым цветом.
Параметр:
- `net.sf.jasperreports.export.graphics2d.white.page.background` тип `boolean` \
  Управляет заливкой фона страниц отчёта белым цветом

## Построение отчёта на основе JSON-данных 

[Документация в wiki](http://jasperreports.sourceforge.net/sample.reference/jsondatasource/index.html)

Для построения отчёта на основе JSON-данных:

1. Создайте xxx.json файл содержащий данные в json формате \
   Файл должен находится в каталоге с шаблоном.
   Пример содержимого:
   ```json
    {"Northwind": {
    "Customers": [
        {
        "Phone": "030-0074321",	// nonstandard unquoted field name
        "PostalCode": 12209,	// nonstandard single-quoted field name
        "ContactName": "Maria Anders",	// standard double-quoted field name
        "Fax": "030-0076545",
        "Address": "Obere Str. 57",
        "CustomerID": "ALFKI",
        "CompanyName": "Alfreds Futterkiste",
        "Country": "Germany",
        "City": "Berlin",
        "ContactTitle": "Sales Representative"
        }
    ]
    }}   
   ```
2. В "Repository Explorer" создайте JSON-источник данных
3. Перейдите в свойства "Main DataSet \ Query" шаблона
4. Выберете созданный источник JSON-данных
5. Установите Language = JSON.
6. Заполните выражения запроса \
   Пример:
   ```
   Northwind.Customers(Country == $P{Country})
   ```
   Более подробную информацию по синтаксису смотрите в вики. \
   Для автоматического формирования запроса
   кликните по требуемому узлу JSON дерева(слева от выражения запроса)
7. Нажать "Read Fields" для создания полей на основе JSON-данных


Теперь к полям источника данных можно обращаться как к полям
SQL-запроса `$F{ПОЛЕ}`.

Для передачи данных в функцию `createReportEx()` используйте параметр
`JSON_INPUT_STREAM` c типом `java.io.InputStream` содержащим JSON-данные.

пример:
```scala
val json = """{json-данные}"""
createReportEx(
    getVar("sSystemName").asString,
    null,
    PostBuildAction.print,  
    Map[String, Any](
        "JSON_INPUT_STREAM" -> 
            IOUtils.toInputStream(json, "UTF-8")
    )  
)  
```
Также доступны параметры:  
- `JSON_LOCALE`
- `JSON_TIME_ZONE`
- `net.sf.jasperreports.json.date.pattern`
- `net.sf.jasperreports.json.number.pattern`

## Скриптлет (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» полей, переменных и т.п.

### Создание скриптлета

Для создания скриптлетов необходимо иметь Java-проект, к которому
подключена библиотека:

```scala 
"net.sf.jasperreports" % "jasperreports" % "6.5.1"
```
Перечень действий:
1. Создайте Java-класс \
   ```java 
   public class JRMyExampleScriptlet extends 
        net.sf.jasperreports.engine.JRDefaultScriptlet {
        
   }
   ```
2. Переопределите необходимые методы-обработчики событий
3. Если требуется добавьте необходимые функции

Для создания и компиляции класса скриптлета, можно использовать проект
`Application`. Для этого необходимо подключить к модулю, в котором будет
создан класс скритплета, библиотеку:
```scala
settings(  
    libraryDependencies ++= Seq(  
        "net.sf.jasperreports" % "jasperreports" % "6.5.1" %
        "compile"
        excludeAll(*ExclusionRule*("com.lowagie"),*ExclusionRule*("org.olap4j"))  
    )  
)
```
При этом, если построение отчёта будет запущено из приложения
отлаживаемого в IDEA, будет возможна отладка кода скриптлета.

### Подключение скритплета к шаблону

[Видеоурок](https://www.youtube.com/watch?v=t9Hv6DrwrhQ&list=PLRran9THVx-n7egYAFaW7UdA7IiKvuvsZ&index=2&t=0s)

1. Соберите Jar, содержащий данный класс
2. Скопируйте полученный Jar в каталог проекта версии отчёта \
   Так же допустимо не создавая Jar, скопировать структуру каталогов 
   с class-файлом скриптлета в каталог проекта отчёта
3. Подключите скриплет к дизайнеру JasperReport Studio
   1. Кликните правой кнопкой мыши на каталоге проекта и 
      выберите "Buld path\ Configure Build Path"
   2. Если нужно подключите jar \
      Для этого выполните "Add JARs" и выберете
      jar-файл из каталога проекта версии отчёта
   3. Если нужно подключите каталог \
      Для этого выполните "Add Class Folder..." и выберете каталог 
4. Создайте новый скриплет в отчете \
   Новый скриплет создается из списка скриплетов отчета в окне `outline` по адресу `{Reports} \ Scriptlets`
5. В свойствах скриплета укажите класс созданного скриплета

Теперь при выполнении компиляции и просмотра отчёта в JasperReports
Studio будут вызываться методы созданного скриптлета.

### Пример скриплета для реализации суммы прописью

[Rpt_JRScriptletNumberToStrSample](http://svn.bitec.ru/svn/depot/ASSource/module/rpt/trunk/src/main/reports/Rpt_JRScriptletNumberToStrSample)

Сумма прописью реализована в библиотеке numbertostr:
"ftp://ftp.bitec.ru/pub/%23Global/utils/NumberToStr/numbertostr-all-1.0-SNAPSHOT.jar"

Эта библиотека поставляется с сервером global

Для работы в Jasper Studio необходимо подключить эту библиотеку к
проекту отчета.

#### скриплет – обертка
Создание скриплета:
1. создайте в проекте файл скриплета
   Файл создается в проекте отчета в каталоге `src`
    ```java
    import net.sf.jasperreports.engine.JRDefaultScriptlet;  
    import net.sf.jasperreports.engine.JRScriptletException;  
    import ru.bitec.numbertostr.MoneyToStr;  
    import ru.bitec.numbertostr.settings.Currency;  
    import ru.bitec.numbertostr.settings.PennyShowType;  
    import ru.bitec.numbertostr.settings.Language;  
    
    import java.math.BigDecimal;  
    
    public class JRMoneyToStrScriptlet extends JRDefaultScriptlet {  
        
        public String moneyToStrRu(BigDecimal npSum) throws
        JRScriptletException{  
            return MoneyToStr.spellout(
                npSum, 
                Currency.RUR, 
                Language.RUS,
                PennyShowType.TEXT
            );  
        }  
        
        public String moneyToStrByCurrencyAndLanguageAndPennyShowType(
            BigDecimal
            npSum, 
            String currency, 
            String language,
            String pennyShowType  
        ) throws JRScriptletException {  
            return MoneyToStr.spellout(
                npSum, 
                Currency.valueOf(currency),
                Language.valueOf(language),
                PennyShowType.valueOf(pennyShowType)
            );  
        }  
    }
    ```
3. Добавляем новый скриплет в отчет \
   1. Зайдите в свойства отчета \
      Для этого кликните правой кнопкой мыши по каталогу отчета 
   2. Перейдите в раздел "Java build path"
   3. Перейдите на закладку "source"
   4. Добавьте каталог \
      Нажмите "Add folder" и укажите каталок `src`
4. В свойствах сервлета укажите
   - Name = `JRMoneyToStrScriptlet`
   - Class = `JRMoneyToStrScriptlet`

После этого функции скриплета становятся доступными 
в expression editor в разделе Parameters

Пример выражения:
```
$P{JRMoneyToStrScriptlet_SCRIPTLET}.moneyToStrRu($F{nSum})
```

После завершения редактирования отчета необходимо собрать проекта. 

При экспорте кроме `*.jrxml` файлов надо экспортировать `*.class`
файлы скриптлетов.
```{attention}
Именно файлы, а не папку bin, чтобы они оказались в
корне архива, иначе jasper их не найдет при печати из глобал
```
![](jasper_report_img/export_class.png)


### Скриптлет для скрытия колонок таблицы с сохранением ее ширины

При разработке отчетов возникает необходимость скрывать колонки таблицы в зависимости от определенных условий. Т.к. движок Jasper не позволяет динамически изменять ширину элементов в момент построения отчета, при скрытии колонок с помощью выражения printWhenExpression, оставшиеся видимыми элементы не изменяют свои размеры, из-за чего на месте скрытых элементов появляются пустоты. Скрыть колонки и сохранить ширину таблицы можно с помощью скриптлета ru.bitec.app.rpt.ColumnResizerScriptlet. 

```{note}
Скриптлет позволяет колонки для элемента Таблица, не элементы HeaderColumn и Detail.
```

Для скрытия колонок необходимо создать группу, в Header или Footer которой нужно поместить элемент Таблица. Для того, чтобы указать скриптлету, какие колонки нужно скрыть, необходимо в отчете создать параметр `HIDDEN_COLUMN`, в котором указать нужные колонки в формате строки `"GroupName1_ColumnName1;GroupName2_ColumnName2;...;GroupNameN_ColumnNameM"`, где `GroupNameN` - имя группы, в которой расположена нужная таблица (автоматически группы именуются Group1, Group2 и т.д.), `ColumnNameM` - имя колонки в таблице (автоматические именуются Column1, Column2 и т.д.). Имена групп и колонок таблицы можно поменять в отчете. 

```{attention}
Для корректной работы скриптлета в Header или Footer должна содержаться только таблица и ничего больше.
```

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

Для обеспечения доступа сервера 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.mes.Mes_DataInstallPkg#reportInstall`.

## Отчет с содержанием

[Документация на sourceforge](http://jasperreports.sourceforge.net/sample.reference/tableofcontents/index.html)

Возьмем Report Book, в котором 2 отчета: 
- `TableOfContents` 
- `Content`. 

Для создания содержания с гиперссылками в начале документа

1. Укажите свойства отчета  TableOfConents
   - если отчет стоит перед `Content` то `EvaluationTime` = `Report`
   - `net.sf.jasperreports.bookmarks.data.source.parameter` = `REPORT_DATA_SOURCE`
2. При необходимости установить галочку "Use Cache" 
   Галочка находится на `Pages`
3. Настройте поле для `Anchor` в отчете `Content`
   1. Перейдите на поле которое хотите видеть в содержании 
   2. Задайте свойства на закладке `Hyperlink` 
      - "Anchor name expression" = `$F{sposition}`
        Можно указывать имя в виде `"Позиция: " + $F{sposition}`, но нужно
        учитывать, что если тут будет число – нужно привести его к `.toString`.
      - "Bookmark level" = `1` 
4. Создайте поля в Dataset’e отчета TableOfContents
   - `level` тип `java.lang.Integer`
   - `pageIndex` тип `java.lang.Integer`
   - `label` тип `java.lang.String`
5. Для отображения имени гиперссылки
   1. Создайте или перейдите на соответствующий TextField в TableOfContents
   2. Задайте значением `$F{label}`
   3. Свяжите поле с уровнем anchor \
      Укажите свойство "Appearance \ print when \ print when expression" = `$F{level}==1`
6. Для отображения номера страницы 
   1. Создайте или перейдите на соответствующий TextField в TableOfContents
   2. Задайте значение `$V{PAGE_NUMBER} + $F{pageIndex} + 1`
   3. Задайте свойство "Evaluation Time" = `Auto` 
   4. Свяжите поле с уровнем anchor \
      Укажите свойство "Appearance \ print when \ print when expression" = `$F{level}==1`
7. При необходимости можно сделать поля с именем анкора и номером страницы гиперссылками 
   1. Откройте свойства поля 
   2. Перейдите на закладку Hyperlink 
   3. В разделе HyperLink задайте
      - "Link Target" = `Self` 
      - "Link Type" = `LocalAnchor` 
      - "Hyperlink Anchor Expression" = `$F{lable}`