Параметры отчета и форматтеры полей

Параметры внешних отчетов

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

Внешние параметры могут быть переданы вызывающим кодом при запуске отчета через API. Кроме того, генератор отчетов может отображать диалоговое окно для ввода параметров, когда пользователь запускает отчет. В последнем случае вам следует описать внешние параметры на вкладке Parameters and Formats редактора отчетов.

Форма для определения параметра показана ниже:

Figure 1. Внешние параметры отчета

Свойства входных параметров

На вкладке Properties вы можете определить свойства параметра:

Caption – название параметра, как оно будет отображаться в форме ввода параметра при запуске отчета.
Parameter alias – псевдоним параметра, используемый для доступа к нему в наборах данных.
Parameter type – тип параметра.
Hidden – флажок, определяющий, должен ли запрос параметра быть скрыт от пользователей.
Required parameter? – флажок, определяющий, является ли параметр обязательным.
Default value – определяет значение параметра, которое будет использоваться по умолчанию, если пользователь не выберет никакого другого значения.

Типом параметра могут быть примитивные типы String, Number, Boolean или временные, кроме того, в качестве типа можно выбрать Enumeration, Entity или List of entities. В зависимости от выбранного типа требуются дополнительные поля:

Если выбран тип параметра Entity или List of entities:

Entity – объект, который будет использоваться в качестве параметра.
Entity selection screen – необязательный идентификатор экрана, который будет использоваться для выбора экземпляров сущности. Если экран не указан, выбор будет произведен из специального экрана, общего для всех сущностей.

Если выбран тип параметра Enumeration:

Enumeration – перечисление для использования в качестве параметра.

Если выбран тип временного параметра (Date, Time или Date and time):

Default date(time) is current – флажок определяет, будет ли текущая отметка времени использоваться в качестве значения параметра по умолчанию.

Локализация входных параметров

На вкладке Localization вы можете определить имя параметра для разных языков. Для этого нужно ввести пары locale_name = parameter_name, например:

ru = Книга

Преобразование входных параметров

На вкладке Transformation вы можете применить скрипт Groovy к параметру, прежде чем использовать его в отчете.

Скрипт Groovy должен возвращать новое значение параметра. В скрипт передаются следующие переменные:

params – сопоставление параметров доступно под псевдонимом params.
paramValue – текущее значение параметра доступно в скрипте по `paramValue'.
dataManager – объект типа DataManager, который обеспечивает функциональность CRUD.
metadata – объект типа Metadata, который предоставляет доступ к метаданным приложения.
applicationContext – типа org.springframework.context.ApplicationContext, который предоставляет доступ к управляемым компонентам.

Например:

return "%" + paramValue + "%"

Вы также можете использовать предопределенные преобразования, которые добавляют подстановочные знаки для текстовых (строковых) параметров:

Starts with,
Ends with,
Contains.

Figure 2. Преобразование входных параметров

На вкладке Validation вы можете определить скрипт Groovy с некоторыми условиями для валидации параметров, подпробнее см. ниже.

Валидация входных параметров

Вы можете провести валидацию входной параметр и/или настроить валидацию перекрестных параметров.

Установите флажок Validate на вкладке Validation редактора параметров, чтобы включить валидацию каждого параметра. Логика валидации задается скриптом Groovy. Скрипт должен проверить значение параметра и вызвать метод invalid(), если значение недопустимо. Этот метод покажет пользователю предупреждение с заданным сообщением об ошибках валидации отчета.

В скрипт передаются следующие переменные:
- value – значение параметра, введенное пользователем.
- applicationContext – объект типа org.springframework.context.ApplicationContext, который предоставляет доступ к управляемым компонентам.
- currentAuthentication – объект типа io.jmix.core.security.CurrentAuthentication, связанный с текущим аутентифицированным пользователем.
- dataManager – объект типа DataManager, который предоставляет функциональность CRUD.
- metadata – объект типа Metadata, который предоставляет доступ к метаданным приложения.
- invalid – замыкание Groovy, которое фактически не проходит валидацию, если вызывается изнутри скрипта.
  
  Figure 3. Валидация входных параметров
Можно включить перекрестную валидацию параметров, установив флажок Validate в разделе Cross parameters validation на вкладке Parameters and Formats. Логика валидации задается скриптом Groovy. Скрипт должен проверить, имеют ли значения параметров смысл по отношению друг к другу, и вызвать метод invalid(), если это не так. Этот метод покажет пользователю предупреждение с заданным сообщением об ошибках валидации отчета.

В дополнение к переменным, перечисленным выше, переменная params передается в скрипт для доступа к сопоставлению параметров внешнего отчета.

Figure 4. Перекрестная валидация параметров

Форматы значений полей

Вы можете определить форматирование для любого поля, выводимого отчетом, на вкладке Parameters and Formats редактора отчетов. Ниже приведена форма для добавления формата:

Figure 5. Форматы значений полей

Value name – имя поля отчета с префиксом полосы, например, Book.year.
Format string – формат поля. Для числовых значений укажите формат в соответствии с правилами java.text.DecimalFormat, для дат – java.text.SimpleDateFormat.
Флажок Groovy script – позволяет указать скрипт Groovy для форматирования параметра. Используя псевдоним value, текущее значение параметра передается скрипту, который может быть отформатирован или преобразован в нужный формат. Скрипт Groovy должен возвращать новое значение в виде строки.

С помощью форматов в документ можно вставлять изображения и HTML-блоки.

Чтобы вставить изображение, укажите его URL-адрес в качестве значения поля, а также следующую строку формата: ${image:<Width>x<Height>}, например, ${image:200x300}.

Для работы с FileRef используйте форматтер значений ${imageFileId:WxH}, который принимает экземпляр FileRef или URI файла в виде строки.
Чтобы вставить HTML-блок, необходимо вернуть HTML-разметку в поле и выбрать ${html} в качестве строки формата. В выходном значении можете опустить теги верхнего уровня вплоть до <body> включительно. При необходимости все отсутствующие теги верхнего уровня будут добавлены автоматически. Все блоки должны быть закодированы в UTF-8. CSS и атрибут style не поддерживаются.

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