Урок 9. Настройка печатных форм#

Цель данного урока, ознакомить слушателя с принципами создания отчетов.

1.Печатные формы#

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

1.1.Версии печатных форм#

Версия печатной формы позволяет:

Безопасно вернутся к предыдущей реализации;
Запускать реализацию в зависимости от периода;

Версия печатной формы содержит:

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

1.2.Типы шаблонов печатных форм#

Определяют формат в котором задаются шаблоны печатных форм.

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

Jaspersoft Studio#

Шаблоны для построения отчетов пишутся в Jaspersoft Studio Jaspersoft Studio - это программное обеспечение для редактирования JasperReports. Студия помогает:

Разрабатывать и запускать шаблоны отчетов;
Создавать запросы к отчетам;
Писать сложные выражения;
Компоновать визуальные компоненты.

Шаблон представляет из себя zip архив содержащий набор xml файлов сформированных в jasper studio. Jasper studio это специализированное средство построения печатных форм.

1.3. Выходные форматы шаблонов печатных форм#

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

Доступные форматы шаблонов печатных форм#

jasper
- pdf
- png
- txt
- html
- xls
- prt
docx
- docx
- pdf

Внимание

При установке выходного формата pdf шаблона docx на месте тегов в документе будут подставлены изображения. Детально данная функциональность будет описана ниже.

1.4. Загрузка файлов#

Чтобы загрузить файл шаблона печатной формы в Global необходимо:

Создать новую печатную форму в Global.
Чтобы настроить новую печатную форму в Global:
1. Откройте приложение Настройка системы.
2. Откройте перечень печатных форм Отчеты > Печатные формы.
3. Используя операцию Создать добавьте новый отчет.
4. Заполните обязательные атрибуты и нажмите кнопку Редактировать, чтобы перейти в карточку.
Привязать новую печатную форму к типу объекта.
Чтобы настроить новую версию печатной формы необходимо:
1. На вкладке Версии печатной формы создайте новую версию.
2. Для версии выберите Тип шаблона печатной формы.
3. Нажмите на кнопку Загрузить файл в систему.
4. Выберите файл шаблона печатной формы:
  - jasper
    Для шаблона типа «jasper» файлом шаблона будет являться архив, содержащий шаблон с наименованием «main.jrml».
    Внимание
    1. Шаблоныы суботчетов могут иметь любое название
    2. В архиве может быть только один основной отчёт с наименованием main
  - docx
    Файл формата docx
  - xlsx
    Файл формата docx

1.5. Параметры отчета#

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

Пользовательские параметры#

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

Служебные параметры#

Формируются автоматически

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

Програмные параметры#

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

1.6. Вызов печатных форм#

Печатные формы могут вызываться:

из операции выборки;
из запроса к сервису печати;
из rest сервиса;
От произвольного объекта системы;
От интерфейса свободные отчеты.

Вызов печатной формы из операции выборки#

Для вызова отчета из операции выборки используйте функцию ru.bitec.app.gtk.gl.Reports#createReportEx:

  /**
    * Выполняет построение отчёта по системному имени отчёта.
    *
    * @param reportName        Имя отчёта
    * @param reportVersionDate Дата
    * @param postBuildAction   Действие, которое необходимо произвести после заполнения отчёта
    * @param propertyMap       Карта входящих параметров
    */
  @throws[ApplicationException]
  def createReportEx(reportName: String, reportVersionDate: Date, postBuildAction: PostBuildAction, propertyMap: Map[String, Any]): Unit

Данная функция может быть вызвана только в контексте интерактивной бизнес логики(интерфейса пользователя).

Пример:

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:

  /**
    * Выполняет построение отчёта по системному имени отчёта.
    * Если для версии отчета указано несколько доступных для печати форматов,
    * то будет выдана ошибка построения.
    * Требуется явно указать формат построения, указав параметр [[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 сервиса)

Внимание

В случае, если получен поток, его необходимо обязательно закрыть.

Вызов печатной формы от произвольного объекта#

При открытии карточки любого объекта, выводятся стандартные операции печати по которым можно выполнять вызов печатных форм. Для добавления печатной формы к списку печати для типа объекта:

Откройте приложение Настройка системы.
Откройте типы объектов.
Выполните пункт меню Сущности > Типы объектов > Типы объектов.
Перейдите на вкладку Печатные формы.
Добавьте необходимые печатные формы.

Вызов печатной формы в свободных отчетах#

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

Для вызова интерфейса построения свободных отчетов:

Откройте приложение.
Откройте свободные отчеты.
Выполните пункт меню Отчеты > Свободные отчеты.
Выберите нужный отчет.
Заполните параметры.
Напечатайте отчет.
Для этого выполните операцию Печать.

Для того чтобы ПФ могла быть вызвана из свободных отчетов:

Откройте приложение Настройки системы.
Откройте печатные формы.
Пункт меню Отчеты > Печатные формы.
Выберете требуемую печатную форму.
Включите признак Свободный отчет.
Настройте параметры отчета.
Укажите приложение для печати.
Укажите требуемые роли.

Примечание

Если роли не указаны, печатная форма будет доступна всем пользователям

2. Шаблоны отчетов#

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

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

Основным элементом разметки шаблона является

Тэг
Текст окружённый спецсимволами, управляющий формированием отчёта.

Все тэги имеют следующий вид: [#{значение}#]

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

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

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

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

Форматы тегов для печати данных из запроса:

открывающий тэг

[#&{произвольное системное имя}={SQL запрос}#]

закрывающий тэг

[#/{произвольное системное имя}#]

Внимание

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

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

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

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

Настройки вставки изображений в печатную форму типа docx#

Данная настройка производится в коллекции к печатной форме.

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

Для вставки изображений в печатную форму типа docx должны быть выполнены следующие условия:

Печатная форма должна содержать теги вида [SomeTag]

Внимание

Не путать с тегами разметки шаблона!
Тип шаблона печатной формы - docx
Формат печатной формы - pdf
В коллекции к печатной форме(Настройки вставки изображений в печатную форму) настроены необходимые изображения для вставки

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

3. Jaspersoft Studio#

3.1. Основные визуальные элементы#

Основные визуальные элементы Jaspersoft Studio

Repository#

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

Outline#

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

Properties#

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

Editor#

Отображает открытый отчет. Содержит следующие закладки:

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

Project Explorer#

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

3.2. Проект#

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

Совет

Печатные формы проще создавать и редактировать в одном проекте если они не содержат скриплетов.

Для создания проекта отчёта:

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

По завершению на закладке Project Explorer появится новый проект, пока ещё не содержащий шаблонов отчёта.

3.3. Параметры#

Для изучения подробнее смотри: Параметризация шаблонов

Параметры отчета находятся в окне Outline по адресу {Report} \ parameters Параметры отчёта используются для следующих целей:

В SQL-запросах
Для ограничения данных по переданным из вне параметрам
Связи между частями шаблонов
Для связи между движком отчёта и внешним окружением.

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

Например:

REPORT_CONNECTION тип java.sql.Connection
REPORT_PARAMETERS_MAP тип Map<String,Object>

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

Внимание

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

Использовать параметры можно в полях отчёта в запросе данных даже в других параметрах для того чтобы использовать параметр наименование этого параметра нужно обернуть в тэг $P{PARAMETER_NAME}

3.4. Адаптеры данных#

Для создания адаптера

В окне «Repository Explorer» выполните операцию «Create Data Adapter»
В открывшемся диалоге выберите «Data base JDBC connectivity»
Укажите реквизиты подключения к базе Postgres
- name={имя подключения}
- JDBC driver=org.postgresql.Driver
- JDBC url=jdbc:postgresql://{host}/{db}
- Username ={username}

Примечание

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

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. Скриптлеты#

Для изучения подробнее смотри: Скриплеты

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

Дополнительная информация:

Скриптлет наследуется от одного из классов:

net.sf.jasperreports.engine. JRAbstractScriptlet
net.sf.jasperreports.engine.JRDefaultScriptlet

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

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

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

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

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

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

Ручная загрузка отчетов#

В Project Explorer выберите папку содержащую отчеты печатной формы.
В контекстном меню выполните Export.
Выберите тип Archive file.
Выберете фалы для экспорта.
Внимание

Допустимы только следующие расширения:
- jrxml
- class
- jar
Укажите опцию save in zip archive.
Укажите файл куда сохранить шаблон.
Откройте приложение Настройки системы.
Откройте печатные формы.
Пункт меню Отчеты > Печатные формы.
Создайте версию печатной формы.
Загрузите шаблон печатной формы.

Внимание

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

Загрузка отчета на dataInstall#

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

Пример:

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-отчета

Поля для детали отчёта (берём из класса Состав накладной):

Номер - выводим sNumber;
Книга - выводим idBook;
Цена - выводим nPrice;
Кол-во - выводим nQty.

Создание jasper-отчета

Создание docx шаблона#

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

Формирование печатных форм из приложения#

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

Курс разработки по GlobalFramework

Урок 9. Настройка печатных форм

Contents

Урок 9. Настройка печатных форм#

1.Печатные формы#

1.1.Версии печатных форм#

1.2.Типы шаблонов печатных форм#

Jaspersoft Studio#

1.3. Выходные форматы шаблонов печатных форм#

Доступные форматы шаблонов печатных форм#

1.4. Загрузка файлов#

1.5. Параметры отчета#

Пользовательские параметры#

Служебные параметры#

Програмные параметры#

1.6. Вызов печатных форм#

Вызов печатной формы из операции выборки#

Формирования файла с отчетом#

Вызов печатной формы от произвольного объекта#

Вызов печатной формы в свободных отчетах#

2. Шаблоны отчетов#

Настройки вставки изображений в печатную форму типа docx#

3. Jaspersoft Studio#

3.1. Основные визуальные элементы#

Repository#

Outline#

Properties#

Editor#

Project Explorer#

3.2. Проект#

3.3. Параметры#

3.4. Адаптеры данных#

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

3.6. Структура страницы шаблона#

3.7. Скриптлеты#

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

Ручная загрузка отчетов#

Загрузка отчета на dataInstall#

Практики#

Создание jasper-отчета#

Создание docx шаблона#

Формирование печатных форм из приложения#