Дизайн отчетов
Дизайн отчетов определяет то, каким образом располагается каждый отчет формы при построении результирующего документа.
Шаблоны
Для каждого из отчетов необходимо задать специальный файл (шаблон), который будет использоваться для построения результирующего документа. В качестве имени шаблона конкретного отчета используется <каноническое имя формы>_<имя первой группы объектов>, где каноническое имя формы включает её пространство имён, причём каждая . заменяется на _. Считается, что у пустой группы объектов нет имени, поэтому если первая группа объектов пустая, имя шаблона просто равняется каноническому имени формы (без постфикса _). Пустая группа объектов всегда является первой группой объектов формы, поэтому у формы всегда есть верхний отчет, называемый по одному только каноническому имени формы, без постфикса. Если подотчеты не нужны, этот шаблон — единственный. Подотчеты возникают только из независимых друг от друга групп объектов: цепочка взаимозависимых групп (каждая фильтруется по объектам предыдущей) остаётся одним плоским отчетом под верхним шаблоном без постфикса, тогда как каждая независимая ветвь иерархии групп выделяется в отдельный подотчет. Каждый подотчет добавляет свой шаблон с постфиксом _<группа> по своей первой (непустой) группе объектов — так, например, форма с двумя независимыми группами объектов даёт три шаблона: верхний без постфикса и по одному на каждый из двух подотчетов.
При разработке шаблона разработчик может использовать в качестве полей свойства групп объектов, которые входят в соответствующий отчет или отчеты-предки. Имя поля — имя свойства на форме, а его класс (атрибут class элемента field) — Java-класс, в котором платформа передаёт значения класса свойства:
| Класс свойства | Класс поля |
|---|---|
INTEGER, YEAR | java.lang.Integer |
LONG | java.lang.Long |
DOUBLE | java.lang.Double |
NUMERIC | java.math.BigDecimal |
BOOLEAN, TBOOLEAN | java.lang.Boolean |
STRING, ISTRING, BPSTRING, BPISTRING, TEXT, RICHTEXT, HTMLTEXT, JSON, JSONTEXT, XML, HTML, TSVECTOR, TSQUERY, LINK и ссылки на файлы конкретного типа | java.lang.String |
DATE | java.time.LocalDate |
TIME | java.time.LocalTime |
DATETIME | java.time.LocalDateTime |
ZDATETIME | java.time.Instant |
INTERVAL[DATE], INTERVAL[DATETIME], INTERVAL[TIME], INTERVAL[ZDATETIME] | lsfusion.interop.form.property.cell.IntervalValue |
COLOR | java.awt.Color |
IMAGEFILE | java.io.InputStream |
FILE | lsfusion.base.file.FileData |
NAMEDFILE | lsfusion.base.file.NamedFileData |
RAWFILE и остальные файлы конкретного типа (PDFFILE, JSONFILE, ...) | lsfusion.base.file.RawFileData |
пользовательский класс, в том числе поле <имя объекта>.object объекта пользовательского класса | java.lang.Long с идентификатором объекта |
поле <имя объекта>.object объекта встроенного класса | класс поля этого класса по строкам выше |
JasperReports форматирует значения java.util.Date по атрибуту pattern текстового поля, но не значения java.time, поэтому автоматический дизайн преобразует поле даты или времени прямо в выражении (java.sql.Date.valueOf($F{date}), java.sql.Timestamp.valueOf($F{dateTime})). Собственный шаблон может вместо этого объявить такое поле как java.util.Date (для любого из четырёх классов), java.sql.Timestamp (для DATETIME и ZDATETIME) или java.sql.Time (для TIME), и значение преобразуется к объявленному классу. Поле изображения, объявленное как java.io.InputStream, получает поток изображения или NULL, когда изображения нет, поэтому элемент изображения использует $F{photo} напрямую. Объявленное как lsfusion.base.file.RawFileData, поле получает сам файловый объект, и поток из него берёт выражение: $F{photo} == null ? null : $F{photo}.getInputStream(). Строковые значения передаются без концевых пробелов.
Если один отчет является непосредственным потомком другого отчета, то он должен быть вставлен в шаблон как подотчет, при этом свойства и фильтры в нем в качестве значений верхних объектов будут использовать текущие значения объектов верхнего отчета. Элемент подотчета берет скомпилированный подотчет, его источник данных и его параметры из параметров <ID подотчета>_report, <ID подотчета>_source и <ID подотчета>_params родительского шаблона (соответственно выражения подотчета, источника данных и карты параметров), где <ID подотчета> — имя первой группы объектов подотчета, то же, что и в постфиксе его шаблона. Эти три параметра должны быть объявлены в родительском шаблоне.
По умолчанию шаблон определяется по своему имени. Также разработчик может явно задать для формы в целом или для отдельного отчета свойство, значение которого задает используемый шаблон — либо имя файла, определяемое тем же образом, либо непосредственно сам файл шаблона. В качестве параметров этого свойства можно использовать объекты формы.
Шаблоны используются только полным набором. Если шаблон хотя бы одного отчета формы не найден — ни по имени, ни через такое свойство, — все найденные шаблоны игнорируются, и для всей формы используется автоматический дизайн. Поэтому форме с подотчетами нужен верхний шаблон, даже если в нем нет ничего, кроме элементов подотчетов. Сама подмена ошибки не дает: если часть шаблонов была найдена, в лог сервера записывается предупреждение с именем ненайденного шаблона, а если не найден ни один — не сообщается ничего.
Свойство, отображаемое в колонках (опция COLUMNS), при построении документа размножается: текстовое поле, расположенное непосредственно в бэнде (не внутри frame), выражение которого ссылается на поле такого свойства, заменяется на копии — по одной на каждое значение колонки, а имя поля в выражениях копий получает суффикс с индексом колонки — $F{price} превращается в $F{price[0]}, $F{price[1]} и так далее. Ограничивающий прямоугольник всех текстовых полей бэнда с тем же атрибутом key, что и у исходного, делится на равные части — по одной на каждое значение колонки, и каждая копия воспроизводит исходное поле в своей части с теми же относительными положением и шириной (так заголовок и ячейка значения с общим ключом размножаются единым блоком). Если значений колонок нет, поле удаляется.
У свойства с опцией HEADER, FOOTER, BACKGROUND, FOREGROUND или IMAGE есть дополнительное поле <имя поля>.header, .footer, .background, .foreground или .image со значением свойства этой опции, класс которого определяется по таблице выше. У свойства с опцией SHOWIF есть дополнительное поле <имя поля>.showif (автоматический дизайн его объявляет, а в собственном шаблоне его нужно объявить, чтобы им пользоваться). Пока включен параметр работы useShowIfInReports (по умолчанию), если в первой строке отчета это поле равно NULL, каждое расположенное непосредственно в бэнде текстовое поле с выражением $F{<имя поля>} удаляется вместе с занимаемой им вертикальной полосой: расположенные непосредственно в бэндах элементы в пределах полосы обрезаются, а элементы правее сдвигаются влево на ее ширину. Для форматов с разбиением на страницы (все, кроме XLS, XLSX и HTML) оставшиеся элементы затем пропорционально растягиваются до исходной ширины.
Автоматический дизайн
В случае, если при формировании отчетов не удается найти хотя бы один из шаблонов, то запускается механизм автоматического формирования шаблонов на основе текущей иерархии, который для каждого отчета создает свой отдельный шаблон, в который выносятся все необходимые свойства и подотчеты. При этом, если в один отчет входит несколько групп объектов, то самая нижняя группа в списке будет использоваться как детализация, а для каждой верхней группы в шаблоне будет создана отдельная группировка с своим блоком, в который будут вынесены все свойства из этой группы.
Формат шаблона
В качестве конкретной реализации механизма формирования документов используется LGPL технология JasperReports. Соответственно шаблонами являются файлы формата jrxml, которые можно редактировать при помощи приложения JasperSoft Studio. В момент формирования отчета выполняется поиск файлов шаблонов с именем <имя шаблона>.jrxml в текущем classpath'е сервера (в том числе во всех подкаталогах). Если хоть один файл шаблона не был найден, платформа сгенерирует некоторый автоматический дизайн. Этот дизайн, при запуске сервера из IDE и формировании отчета в режиме предпросмотра, можно при помощи соответствующих кнопок сохранить в каталог запуска (и каталог исходников), после чего отредактировать в соответствии с требованиями задачи (при этом платформа будет автоматически синхронизировать файлы в каталоге запуска и каталоге исходников).
Язык
То, какой шаблон (файл отчета) используется для формы и ее отдельных отчетов, можно явно задать через инструкцию FORM.