Шаблоны
Добавление шаблона
Вы можете добавлять шаблоны отчетов в экране деталей отчета. Создайте или отредактируйте существующий отчет в экране списка отчетов и перейдите на вкладку Templates:
Один отчет может иметь несколько шаблонов, но один из шаблонов должен быть выбран как шаблон по умолчанию.
Ниже приведена форма для добавления шаблона:
-
Template code - идентификационный код шаблона.
-
Template file - загружается из файловой системы и сохраняется в базе данных вместе с описанием структуры отчета.
-
Output type - тип вывода отчета. Должен соответствовать типу файла шаблона согласно правилам, описанным в соответствии форматов вывода.
-
Output name pattern - необязательный шаблон имени файла, который будет использоваться для генерации имени файла создаваемого отчета. Это может быть как постоянная строка, так и строка, содержащая параметр отчета в качестве переменной, например,
${header.authorName}.xlsx. Также можно создавать более сложные шаблоны с несколькими параметрами и конкатенацией строк в виде скрипта в любом бэнде структуры отчета, например,${Root.title}.xlsx, гдеtitleявляется результатом скрипта:[['title' : ('Report for '+params['author'].firstName+' '+params['author'].lastName)]] -
Is custom - флаг использования пользовательской логики форматирования, не охватываемой ни одним предоставленным форматером. Когда он установлен, необходимо определить два дополнительных поля:
-
Defined by - способ определения пользовательского шаблона: с помощью класса, скрипта или URL.
-
Custom definition - полностью квалифицированное имя Java-класса, содержимое Groovy-скрипта или URL, используемый для создания шаблона. Если выбран Script, то в Groovy-скрипте можно использовать следующие параметры:
-
params- карта параметров доступна по псевдонимуparams. -
rootBand- объект типаBandData, который предоставляет доступ к наборам данных бэндов. -
applicationContext- объект типаApplicationContext, который предоставляет доступ к управляемым бинам.
-
-
-
Is alterable output - флаг, позволяющий пользователю выбирать тип вывода отчета во время выполнения в диалоговом окне.
Если флаг установлен, при запуске отчета будет показан диалог с выбором типа вывода. Если у отчета более одного шаблона, также будет показан выпадающий список выбора шаблона.
-
Is default - когда вы помечаете шаблон как "используемый по умолчанию" для конкретного отчета, этот шаблон автоматически используется в качестве основы для генерации отчета, если пользователь явно не выберет другой шаблон.
Типы шаблонов
XLS(X) шаблоны
Вы можете создавать XLS(X) шаблоны с помощью Microsoft Office или LibreOffice.
Каждый бэнд отчета должен иметь соответствующую область в шаблоне, названную так же, как бэнд. Например, отчет имеет два бэнда - Header и Data. Это означает, что шаблон также должен иметь именованные диапазоны Header и Data. Чтобы создать именованные области, выберите нужные диапазоны ячеек и введите имя в поле в левом верхнем углу приложения. Для редактирования существующих именованных областей используйте команду меню Formulas → Name Manager в Microsoft Office и команду Insert → Names → Manage в LibreOffice. И наоборот, каждая часть листа, которую вы хотите показать, должна иметь бэнд в отчете (хотя бы пустой бэнд).
Бэнды выводятся в порядке, указанном в иерархии бэндов.
Бэнды могут быть ориентированы горизонтально и вертикально. Если бэнд горизонтальный, соответствующая именованная область будет расти вниз, вертикальный - вправо. Горизонтальные бэнды могут быть организованы в древовидную структуру и содержать подбэнды (вложенные или дочерние бэнды). Следовательно, для подбэндов необходимо создавать именованные области непосредственно под областями, соответствующими родительским бэндам.
Форматер XLSX будет отображать дочерние бэнды, используя следующий алгоритм:
-
Записать первую строку родительского бэнда →
-
Записать все дочерние строки первой строки →
-
Записать следующую строку родительского бэнда.
Поля набора данных бэнда размещаются в шаблоне с помощью строк в формате ${имя_поля}, где имя_поля - соответствующее имя поля бэнда. Например:
Вы можете добавлять переменные в шаблон отчета. Переменные должны быть вставлены в имена листов или верхний/нижний колонтитул шаблона XLSX в формате ${<ИмяБэнда>.<имяПеременной>}.
Ячейки могут содержать форматирование, а также несколько полей внутри. Для вывода изображений или формул необходимо разместить их полностью внутри соответствующей именованной области, связанной с бэндом.
Формулы могут ссылаться на ячейки того же бэнда или другого бэнда. Чтобы быть обработанными форматером, формулы должны использовать либо диапазон ячеек в бэнде, либо прямые координаты ячеек, например, (A1*B1) или ($B:$B).
Для обработки данных в виде диаграммы Excel создайте пустой бэнд в структуре отчета и именованную область с тем же именем в шаблоне. Затем создайте диаграмму внутри этой именованной области и ссылайтесь на связанные бэнды с помощью кнопки Select data в контекстном меню диаграммы. Если данные для диаграммы находятся в непрерывном диапазоне ячеек, выберите любую ячейку в этом диапазоне. Ваша диаграмма будет включать все данные в диапазоне. Если ваши данные не находятся в непрерывном диапазоне, выберите несмежные ячейки или диапазоны.
|
Включение авто-высоты строк в шаблонах XLSX Чтобы активировать автоматический расчет высоты строки в созданных вручную шаблонах XLSX, необходимо определить именованный диапазон, который начинается с Для отчетов XLSX, созданных с помощью мастера отчетов, этот именованный диапазон автоматически добавляется для каждого настроенного региона отчета. При выполнении отчета ячейка, содержимое которой превышает доступное пространство для одной строки, автоматически становится многострочной, а высота строки соответствующим образом корректируется для отображения всего содержимого. |
|
Преобразование XLSX в PDF и CSV Отчеты XLSX могут быть автоматически преобразованы в форматы CSV и PDF. Для преобразования в PDF должен быть установлен LibreOffice. |
CSV шаблоны
Вы можете создавать CSV шаблоны с помощью Microsoft Office или LibreOffice.
Бэнды в CSV шаблоне должны быть только горизонтально ориентированы, поэтому соответствующая именованная область будет расти вниз. Также бэнды должны принадлежать первому уровню данных, то есть быть дочерними по отношению к бэнду Root. Во всех остальных отношениях следует использовать те же принципы, что и для XLS(X) шаблонов.
Встроенный редактор
CSV шаблоны поддерживают встроенное редактирование. Вы можете редактировать шаблон непосредственно в диалоговом окне Report template и видеть изменения без необходимости повторной загрузки файла шаблона.
DOC(X) шаблоны
Вы можете создавать DOC(X) шаблоны с помощью Microsoft Office или LibreOffice.
Шаблон типа DOC(X) может включать текст документа и, опционально, одну или несколько таблиц. Текст документа выводит данные из первых строк произвольных бэндов. В то время как в таблице можно выводить произвольное количество строк бэнда.
Чтобы разместить поле в тексте документа, следует использовать строку в формате ${имя_бэнда.имя_поля}, где имя_бэнда - имя бэнда, имя_поля - имя поля бэнда.
Для вывода данных в таблицу следует связать ее с бэндом. Это делается путем указания ##band=имя_бэнда в первой ячейке таблицы, где имя_бэнда - имя бэнда. Поля таблицы размещаются с использованием формата ${имя_поля}, где имя_поля - имя поля бэнда, связанного с таблицей. Можно использовать префикс имени бэнда для доступа к полям других бэндов, так же как в полях текста документа. В одной ячейке таблицы можно выводить несколько полей.
Горизонтальные бэнды в DOC(X) не могут содержать подбэнды. Если нужны подбэнды, используйте формат XLS(X).
|
Таблица должна содержать либо одну, либо две строки. Если таблица имеет две строки, то соответствующие поля бэнда должны находиться во второй строке. Первая строка должна содержать маркер с соответствующим именем бэнда и, при необходимости, статический текст или другие поля бэндов. |
Ниже приведен пример шаблона, который выводит отчет, состоящий из двух бэндов, Book и Authors. Первый бэнд выводит название книги и жанр, а второй выводит список авторов этой книги.
|
Формат данных ячеек не поддерживается в DOC(X) шаблонах. Чтобы избежать проблем с форматированием чисел или дат из-за локали пользователя, таких как ненужные числовые разделители, попробуйте преобразовать ваши данные в строку. Например, замените
на
|
|
Обработка многострочных строк в DOCX шаблонах По умолчанию переносы строк в значениях параметров игнорируются при генерации отчета. Чтобы сохранить переносы строк (например, Эта функция эксклюзивна для формата вывода отчетов DOCX и не влияет на другие форматы, такие как XLSX или PDF. |
HTML шаблон
HTML шаблон определяется в файле .html (кодировка UTF-8 без BOM). Вы можете использовать функции HTML/CSS библиотеки Flying Saucer. Ее основное руководство доступно на странице GitHub.
Для управления размером страницы, верхними и нижними колонтитулами страницы используйте специальные CSS-правила и свойства.
Существует два способа размещения данных в шаблоне:
-
С использованием тегов FreeMarker.
-
С использованием механизма шаблонов Groovy.
По умолчанию Мастер отчетов генерирует HTML шаблон с тегами FreeMarker.
Используйте переключатель Template type в диалоговом окне шаблона отчета для переключения между методами.
HTML шаблоны поддерживают встроенное редактирование. Вы можете редактировать шаблон непосредственно в диалоговом окне Report template и видеть изменения без необходимости повторной загрузки файла шаблона.
- Движок шаблонов Groovy
-
Вы можете предварительно обработать HTML шаблон отчета как шаблон Groovy. Он будет обработан GStringTemplateEngine.
Движок шаблонов использует синтаксис скриптов в стиле JSP
<% %>и выражений<%= %>или выражения в стиле GString. Переменнаяoutпривязывается к писателю, в который записывается шаблон. Таким образом, шаблон может использовать любой код на Groovy, если он правильно определен.GStringTemplateEngineимеет доступ к:-
внешним параметрам:
BandName.fields.ParamName; -
бэндам:
BandName.bands.ChildBandName; -
полям:
BandName.fields.FieldName.
Вы можете использовать переменные для удобства, например:
<% def headerRow = Root.bands.HeaderRow %> <p>Date: ${headerRow.fields.reportDate}</p>Ниже приведен пример шаблона, который выводит отчет для одного пользователя.
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ru"> <head> <title> Report User </title> <style type="text/css"> body {font-family: 'Charis SIL', sans-serif;} tbody tr {height:20px; min-height:20px} </style> </head> <body> <% def user = Root.bands.User %> <p>Login: ${user.fields.login.first()}</p> <p>Active: ${user.fields.active.first()}</p> </body> </html> -
- FreeMarker
-
Документация FreeMarker доступна на freemarker.apache.org.
Модель документа FreeMarker имеет следующую структуру:
Band { bands [ bandName : [ band, .. ], .. ] fields [ fieldName : fieldValue, .. ] }Например, для доступа к полю
nameв строке с индексом 0 бэндаbandследует использовать следующее выражение:Root.bands.band[0].fields.nameВы можете использовать переменные для удобства, например:
<#assign headerRow = Root.bands.Header[0]> <p>Date: ${headerRow.fields.reportDate}</p>Вы также можете использовать
getMessage()для получения локализованных значений:getMessage()принимает один или два аргумента. Если предоставлен только один аргумент, он возвращает значение из пакета сообщений. Если предоставлено два аргумента, он будет получать локализованные сообщения из пакета сообщений, используя аргументы как группу и ключ сообщения.${getMessage(order.status)}Ниже приведен пример шаблона, который выводит отчет, состоящий из двух бэндов,
BookиAuthors. Первый бэнд выводит название книги и жанр, а второй выводит список авторов этой книги.<!doctype html> <html> <head></head> <body> <#assign book = Root.bands.Book[0] /> <#assign authors = Root.bands.Authors /> <p>Name: ${book.fields.name}</p> <p>Genre: ${book.fields.literatureType.name}</p> <table border="1" cellpadding="5" cellspacing="0" width="200"> <thead> <tr> <td>First name</td> <td>Last name</td> </tr> </thead> <tbody> <#list authors as author> <tr> <td>${author.fields.firstName}</td> <td>${author.fields.lastName}</td> </tr> </#list> </tbody> </table> </body> </html>Ниже приведен более сложный пример. Предположим, у нас есть следующая структура бэндов:
Root { HeaderBand { query = return [[ "name" : "Column1" ],[ "name" : "Column2" ]] } Band1 { query = return [ ["field1" : "Value 11", "field2" : "Value 12"], ["field1" : "Value 21" , "field2" : "Value 22"] ] } Band2 { query = return [[ "header" : "Header1" ], [ "header" : "Header2" ]] SubBand1 { query = return [["header" : 'SubHeader1'] , [ "header" : 'SubHeader2' ]] } } }-
Вставка поля:
<!doctype html> <html> <head> <title> Simple template </title> </head> <body> <#assign Tree1 = Root.bands.Band2> <h1> Header </h1> <p> ${Tree1[1].bands.SubBand1[0].fields.header} </p> </body> </html>-
Вставка списка:
<!doctype html> <html> <head> <title> List </title> </head> <body> <#assign Table1Header = Root.bands.HeaderBand> <#if Table1Header?has_content> <ol> <#list Table1Header as header> <li> ${header.fields.name} </li> </#list> </ol> </#if> </body> </html>-
Вставка таблицы:
<!doctype html> <html> <head> <title> Table </title> </head> <body> <#assign Table1Header = Root.bands.HeaderBand> <#assign Table1 = Root.bands.Band1> <table border="1" cellpadding="5" cellspacing="0" width="200"> <thead> <tr> <#list Table1Header as header> <td> ${header.fields.name} </td> </#list> </tr> </thead> <tbody> <#list Table1 as row> <tr> <td> ${row.fields.field1} </td> <td> ${row.fields.field2} </td> </tr> </#list> </tbody> </table> </body> </html>-
Вставка многоуровневого списка:
<!doctype html> <html> <head> <title> Multi-level list </title> </head> <body> <#assign Tree1 = Root.bands.Band2> <ul> <#list Tree1 as item> <li> <h2> ${item.fields.header} </h2> <#if item.bands.SubBand1?has_content> <ul> <#list item.bands.SubBand1 as subitem> <li> <h3> ${subitem.fields.header} </h3> </li> </#list> </ul> </#if> </li> </#list> </ul> </body> </html> -
- Встроенные изображения
-
На данный момент дополнение Jmix Reports не предоставляет средств для вставки изображений в HTML отчеты аналогично отчетам DOCX/XLSX. Изображения все еще можно встраивать с помощью тега
imgи ссылки на изображение в атрибутеsrc. Вы можете добавить изображения в HTML отчет одним из следующих способов.-
по URL
Изображение может обслуживаться приложением статически. Например, изображение, размещенное в папке
build\resources\static\images\, можно вставить так:<img src="http://localhost:8080/images/SomeImage.jpg" height="68" width="199" border="0" align="right"/> -
как Bitmap
Изображение добавляется как массив байтов внутри атрибута
src. Этот подход позволяет использовать переменные для атрибутовFileRefсущностей. Массив байтов можно даже добавить непосредственно в шаблон, хотя этот подход не рекомендуется:<img alt="SomePicture.png" src="data:image/png;base64,iVBORw0K ..... AcEP9PwxD0hNKK1FCAAAAAElFTkSuQmCC"/> -
с помощью пользовательских префиксов:
-
Вы можете использовать префиксы
resource://для ссылки на файлы изображений из директорииconfилиclasspath. Это работает только для HTML шаблонов для вывода в формате PDF. Например, изображениеabc.jpg, размещенное в папкеresource\com\company\app\images, можно вставить так:<img src="resource://com/company/app/images/abc.jpg" height="68" width="199" border="0" align="right"/> -
Префикс
fs://позволяет вставлять изображение, указывая форматFileRef. Например:<img src="fs://2025/07/08/78c65527-9cb7-ee77-940f-86e31b214f49.jpeg?name=filename.jpeg" height="68" width="199" border="0" align="right"/>Параметр запроса ?name={original_filename}.{ext}является обязательным. Система полагается на этот параметр для корректного разбора строки и восстановления объектаFileRef.
-
-
- Преобразование HTML в PDF
-
Отчеты, имеющие шаблон в формате HTML и формат вывода PDF, не всегда корректно отображают шрифты. Чтобы решить эту проблему, добавьте поддиректорию
jmix/fontsс требуемыми шрифтами.ttfв директорию конфигурации Jmix (по умолчанию${user.dir}/.jmix/conf/). Дополнительно можно использовать существующие шрифты операционной системы, указав их путь в свойстве приложения jmix.reports.pdf-fonts-directory.
Для решения проблемы со шрифтами на сервере Ubuntu следует сделать следующее:
-
Установите пакет
ttf-mscorefonts-installer:$ sudo apt-get install ttf-mscorefonts-installer
-
Установите свойство приложения jmix.reports.pdf-fonts-directory:
jmix.reports.pdf-fonts-directory = /usr/share/fonts/truetype/msttcorefonts
-
Явно укажите шрифты в HTML шаблонах, например:
<html> <head> <style type="text/css"> * { font-family: Times New Roman; } </style>
Еще один момент - разбор специальных символов. Чтобы избежать ошибок при преобразовании HTML в PDF, рекомендуется оборачивать ваши поля в конструкцию <![CDATA[ ]]> в файле HTML шаблона:
<tr>
<td> <![CDATA[${(row.fields('book_name'))!?string!}]]> </td>
<td> <![CDATA[${(row.fields('author'))!?string!}]]> </td>
</tr>
Шаблон JasperReports
Форматер JasperReports позволяет использовать шаблоны JasperReports для вывода информации, извлеченной отчетностью Jmix. Шаблон будет обработан движком отчетов, предоставляя вывод определенного типа, смотрите Матрица соответствия форматов вывода.
Вы можете создавать JRXML шаблоны с помощью инструментов JasperReports (например, Jaspersoft Studio) или в простом текстовом редакторе. Каждый бэнд отчета, определенный в структуре отчета, должен иметь соответствующий элемент band в шаблоне, который, в свою очередь, размещается в одном из стандартных разделов отчета JasperReports (которые также называются бэндами в терминологии JasperReports): title, pageHeader, columnHeader, detail и т.д.
Движок отчетов помещает все данные бэндов отчета в один источник данных: JRBandDataDataSource, который содержит данные в виде дерева с бэндом Root в качестве корня, и передает экземпляр CubaJRFunction в шаблон в качестве основного источника данных, к которому можно обращаться с помощью параметра REPORTING. Объявление этого параметра в шаблоне отчета не является обязательным, он будет добавлен автоматически, если пропущен, но если вы хотите компилировать шаблон в IDE JasperReports, вам нужно объявить этот параметр явно.
Параметр REPORTING поддерживает две функции:
-
dataset- получает под-источник данных из основного источника данных, который можно использовать, например, в таблицах или в подотчетах как subDataset. Этот метод ищет среди дочерних элементов корневого бэнда бэнд с указанным именем и создает новый источник данных с данными этого бэнда в качестве нового корня. Например:<subDataset name="Product"> <field name="name" class="java.lang.String"/> <field name="price" class="java.lang.Long"/> </subDataset> ... <dataSourceExpression><![CDATA[$P{REPORTING}.dataset("Product")]]></dataSourceExpression> -
bitmap- преобразует заданный массив байтов вByteArrayInputStreamи может использоваться для встраивания изображений в отчет. Например:
<field name="Main.image" class="java.lang.Object"/> //image from DB as byte array
...
<imageExpression><![CDATA[$P{REPORTING}.bitmap($F{Main.image})]]></imageExpression>
Каждый бэнд отчета может быть использован в шаблоне только один раз, поэтому если вам нужно представить одни и те же данные в разных формах в пределах одного отчета (например, как таблицу и диаграмму), вам нужно создать столько бэндов, сколько элементов band в шаблоне. Вложенные бэнды не поддерживаются, все бэнды должны быть прямыми потомками бэнда Root.
Данные могут быть получены из источника данных с использованием следующего синтаксиса: $F{<имя поля>}. Например:
<textField>
<textFieldExpression><![CDATA[$F{library_department_name}]]></textFieldExpression>
</textField>
Пример отчета с шаблоном JasperReports можно найти в разделе JRXML Template.
Шаблон, определяемый классом
Шаблоны, определяемые классом, используются, когда слишком сложно или невозможно выбрать данные с помощью SQL, JPQL или Groovy. Они используются, например, когда отчет является результатом объединения нескольких других отчетов.
Создайте класс и реализуйте интерфейс io.jmix.reports.yarg.formatters.CustomReport. Определите метод createReport(), который возвращает массив байтов и принимает следующие входные параметры:
-
report- дескриптор отчета типаio.jmix.reports.yarg.structure.Report. -
rootBand- данные корневого бэнда типаio.jmix.reports.yarg.structure.BandData. -
params- карта внешних параметров отчета.
Ниже приведен пример простого шаблона, определяемого классом. Он создает HTML-документ, показывающий название книги, выбранной в качестве параметра отчета:
package com.company.library.reports;
import com.company.library.entity.Book;
import io.jmix.reports.yarg.formatters.CustomReport;
import io.jmix.reports.yarg.structure.BandData;
import io.jmix.reports.yarg.structure.Report;
import java.util.Map;
public class BookReport implements CustomReport {
@Override
public byte[] createReport(Report report, BandData rootBand, Map<String, Object> params) {
Book book = (Book) params.get("book");
String html = "<html><body>";
html += "<p>Name: " + book.getName() + "</p>";
html += "</body></html>";
return html.getBytes();
}
}
В диалоговом окне шаблона отчета установите флажок Is custom, выберите Class в поле Defined by и укажите полностью квалифицированное имя Java-класса в качестве пользовательского определения:
Форматер таблиц
Когда вы выбираете табличный вывод в мастере, система автоматически создает шаблон. При запуске отчета данные будут отображены на специальном экране приложения.
Вы также можете создать шаблон вручную для существующего отчета. Для этого выберите Table в качестве типа вывода в экране деталей шаблона отчета.
В столбце Band добавьте имена бэндов, которые вы хотите отобразить в результирующей таблице. Для каждого бэнда задайте карту ключ-значение, где ключ - это имя свойства набора данных, а значение - его локализованная надпись.
Дополнение Reports получит данные бэнда и нарисует сортируемую таблицу для каждого бэнда с первого уровня иерархии.
Таблица отображает столбцы для всех свойств для SQL и JPQL наборов данных. Если используется набор данных Entity/List of Entities, таблица будет отображать только столбцы для выбранных атрибутов.
Результирующая таблица отображается в экране Reports → Show tables вашего веб-приложения. Кнопка Excel позволяет загрузить отображаемую таблицу как файл Excel.
Выполнение внешних отчетов
Дополнение Reports позволяет запускать отчет внешней службы, такой как Microsoft Reporting Services, и загружать его вывод. Чтобы определить внешний отчет, выполните следующие шаги:
-
В диалоговом окне шаблона отчета установите флажок Is custom.
-
Выберите URL в поле Defined by.
-
В поле Custom definition укажите URL внешнего отчета. Параметры отчета могут передаваться в URL как
${param Alias}. -
Настройте свойство приложения jmix.reports.curl-path, установив в него путь к инструменту командной строки curl.
Матрица соответствия форматов вывода
В таблице ниже показана взаимосвязь между форматом входного шаблона и форматом вывода, например, входной шаблон XLSX может выводить форматы XLSX, CSV, PDF и HTML.
| Шаблон / Вывод | XLSX | XLS | CSV | DOCX | DOC | HTML | |
|---|---|---|---|---|---|---|---|
XLSX |
+ |
+ |
+ 1 |
+ 1 |
|||
XLS |
+ |
+ 1 |
|||||
CSV |
+ |
||||||
DOCX |
+ |
+ 2 |
+ 2 |
||||
DOC |
+ |
+ 1 |
|||||
HTML |
+ |
+ |
|||||
JRXML |
+ |
+ |
+ |
+ |
+ |
+ |
+ |
1 - для вывода должен быть установлен LibreOffice.
2 - в зависимости от свойства приложения jmix.reports.use-office-for-document-conversion вывод может выполняться с LibreOffice или без него. В последнем случае необходимо предоставить требуемые шрифты, как описано в HTML в PDF.