Сервис формирует отчет в формате PDF по HTTP-запросу в формате JSON (XML не поддерживается в текущей версии).
Скрипты генерации PDF хранятся в директории pdf_report_gen
, расположенной в директории приложения сервиса.
Шаблоны страниц в формате PDF хранятся локально в директории templates/pdf
, расположенной в директории приложения сервиса.
Шрифты для использования в генераторе, находятся в директории assets/fonts
, расположенной в директории приложения сервиса. Загружаются при старте сервиса.
Примечание: при добавлении новых файлов шрифтов необходимо сделать рестарт сервиса.
Примеры запросов находятся в директории request_examples/pdf.
См. также “Запросы для формирования отчетов в формате .pdf через Генератор отчетов PDF” в примерах запросов.
Примеры шаблонов: “Шаблоны для формирования отчетов в формате .pdf через Генератор отчетов PDF” в примерах шаблонов.
{
"report-generator":
{
"uri": "local",
"id": "example_1"
},
"input-data":
{
"ORGANIZATION": "Акционерное общество Негосударственный пенсионный фонд «XXXXX»",
"CLINAME": "Петров Петр Петрович"
},
"options":
{
"enable-debug-report-save": true
}
}
Объект report-generator имеет два параметра:
uri
- строка. Задает положение источника команд генератора в зависимости от того, как трактуется параметр id
. Поддерживаемые значения: local
и embedded
.id
- строка. ID генератора.uri
, равному local
, id
- это имя файла в директории сервиса pdf_report_gen
. См. параграф "Генераторы как часть сервиса" ниже.uri
, равному embedded
, id
используется только для диагностических сообщений и идентификации запроса. Генератор должен находится в корневом объекте embedded-report-generator
запроса.Опционально генератор может быть встроен в запрос:
{
"report-generator":
{
"uri": "embedded",
"id": "example_template"
},
"embedded-report-generator":
{
"commands": [...],
},
...
}
Цель - не передавать данные команд внутри запросов, если они не меняются от запроса к запросу.
Директория pdf_report_gen
, расположенная в директории приложения сервиса.
Формат генератора в директории pdf_report_gen
{
"report-generator":
{
"commands": [...]
}
}
Параметры команд примерно соответствуют параметрам в одноименных функциях библиотеки PLPDF, имена без префикса "p_".
Создает новую страницу в документе.
Параметры
orientation
- строка. Поддерживаемые значения:Значение по умолчанию - “P”.
Пример:
{
"name":"NewPage",
"params":{
"orientation":"L"
}
}
Задает трактовку координат и размеров, указываемых в последующих командах. Режим по умолчанию "в миллиметрах”.
Параметры
mode
Поддерживаемые значения: "millimeters", "percents", "normalized".Устанавливает отступы от границ страницы.
Параметры
left
, right
, top
, bottom
- числа с плавающей точкой. Отступы от левого, правого, верхнего, нижнего краев страницы. При достижении нижнего отступа в командах типа Row_Print
автоматически создается новая страница. Команда заменяет plpdf функции setAllMargin
и SetAutoNewPage
.
Пример:
{
"name":"setPageMargins",
"params":{
"left":20,
"right":20,
"top":30,
"bottom":15
}
}
Устанавливает X координату курсора.
Параметры
value
- число с плавающей точкой. Координата X.Устанавливает Y координату курсора.
Параметры
value
- число с плавающей точкой. Координата Y.Устанавливает координаты курсора.
Параметры
x
- число с плавающей точкой. Координата X.y
- число с плавающей точкой. Координата Y.Сохраняет координату X для последующего использования в параметрах координат команд через тег [PDF:savedX]
.
Параметры
value
- опциональный параметр, по умолчанию равен текущей координате X. Может быть числом с плавающей точкой или строкой-выражением со ссылками на встроенные теги. Пример выражения: "[PDF:currentX] - 50"
Сохраняет координату Y для последующего использования в параметрах координат команд через тег [PDF:savedY]
. Внимание: при последующем создании новой страницы значение может оказаться нерелевантным.
Параметры
value
- опциональный параметр, по умолчанию равен текущей координате Y. Может быть числом с плавающей точкой или строкой-выражением со ссылками на встроенные теги. Пример выражения: "[PDF:currentY] - 50"
Сохраняет произвольное значение координат для последующего использования в параметрах координат команд через тег [SAVED:ключ]
. Дополняет команды saveX/saveY
в случаях, когда нужен доступ к нескольким значениям.
Параметры
key
- строка. Произвольный ключ для использования в теге [SAVED:ключ]value
- может быть числом с плавающей точкой или строкой-выражением со ссылками на встроенные теги. Пример выражения: "[PDF:currentY] - 50"
Пример:
{
"name":"saveCoordinate",
"params":{
"key":"x1",
"value":10
}
}
Задает поворот всех последующих объектов.
Параметры
angle
- число с плавающей точкой. Угол вращения в градусах.x
- число с плавающей точкой. X координата точки вращения. Если null, то X координата курсораy
- число с плавающей точкой. Y координата точки вращения. Если null, то Y координата курсораПример:
{
"name":"setRotate",
"params":{
"angle":45,
"x":105,
"y":130,
}
}
Отмена команды:
{
"name":"setRotate",
"params":{
"angle":0
}
}
Указывает степень прозрачности для всех последующих объектов. Действие отменяется командой endOpacity
.
Параметры
val
- число с плавающей точкой. Допустимый диапазон от 0.0 до 1.0, где ноль - полная прозрачность.Отменяет действие команды startOpacity
.
Без параметров.
Задает шрифт и размер шрифта для последующих текстовых команд.
Параметры
font_id
Поддерживаемые значения: имена файлов шрифтов из директории assets/fonts
без расширения. Шрифты загружаются при старте сервиса.size
Размер шрифта в точках в пользовательском пространстве документа pdf. Никаких отличий от PLPDF и других текстовых редакторов.Примечание: единственная поддерживаемая кодовая страница - cp1251.
Задает цвет текста для последующих текстовых команд.
Варианты входных параметров
r
, g
, b
целочисленные десятичные компоненты RGB цвета в диапазоне от 0 до 255. Пример красного цвета: “r”:255, “g”:0, “b”:0.color
строка в формате "#rrggbb", где rgb - шестнадцатеричные компоненты RGB цвета в диапазоне от 0 до ff. Пример красного цвета: "color":“#ff0000”.Задает цвет границ для объектов, выводимых после исполнения данной команды. Примеры объектов: ячейки таблиц, окружности, линии, прямоугольники и т.д.
Параметры: аналогично команде setColor4Text
.
Задает цвет заливки внутренних областей для объектов, выводимых после исполнения данной команды. Примеры объектов: ячейки таблиц, окружности, прямоугольники и т.д.
Параметры: аналогично команде setColor4Text
.
Устанавливает толщину линий, выводимых после исполнения данной команды. Примеры объектов: границы ячеек таблиц, линии, прямоугольники и т.д.
Параметры
width
- число с плавающей точкой. Толщина линии.Устанавливает отступы контента табличной ячейки от левой, верхней, правой и нижней границ.
Параметры
margin
- число с плавающей точкой.Устанавливает отступ контента табличной ячейки от нижней границы.
Параметры
margin
- число с плавающей точкой.Устанавливает отступ контента табличной ячейки от левой границы.
Параметры
margin
- число с плавающей точкой.Устанавливает отступ контента табличной ячейки от верхней границы.
Параметры
margin
- число с плавающей точкой.Устанавливает отступ контента табличной ячейки от правой границы.
Параметры
margin
- число с плавающей точкой.Выводит прямоугольную ячейку с текстом внутри. Можно указать цвет и наличие границ.
Параметры
w
- число с плавающей точкой. Ширина прямоугольника ячейки.h
- число с плавающей точкой. Высота прямоугольника ячейки.txt
- текстborder
- строка. Задает видимые границы ячейки. Допустимые значения: 0 - нет границ, 1 - внешняя граница прямоугольника, L - левая, T - верхняя, R - правая, B - нижняя границы. Допускается комбинация значений L,T,R и B.align
- строка. Горизонтальное выравнивание текста. Значения: L - по левому краю. R - по правому краю, C - по центру, J - равномерно по ширине ячейки.vert_align
- строка. Вертикальное выравнивание текста. Значения: T - по верхнему краю. B - по нижнему краю, С - по центру. Значение по умолчанию: С.fill
- логическое значение. Указывает заполнять ли ячейку текущим цветом для заполнения. См. setColor4Filling
. Значение по умолчанию - false.link
- строка. Ссылка, например, URL или внутренняя ссылка. В текущей версии не поддерживается.clipping
- логическое значение. Указывает обрезать ли текст по границам ячейки. Значение по умолчанию - false.ln
- целое число. Позиция курсора после отрисовки ячейки. Допустимые значения: 0 - рядом с ячейкой, 1 - новая строка, 2 - под ячейкой. Значение по умолчанию - 0.Пример:
{
"name":"PrintCell",
"params":{
"w":120,
"h":7,
"txt":"Персональные данные",
"border":"0",
"align":"L",
"vert_align":"C",
"fill":true,
"clipping":false,
"ln":2
}
}
Выводит многострочную ячейку
Параметры
w
- число с плавающей точкой. Ширина прямоугольника.h
- число с плавающей точкой. Высота прямоугольника ячейки.txt
- текстborder
- строка. Задает видимые границы ячейки. Допустимые значения: 0 - нет границ, 1 - внешняя граница прямоугольника, L - левая, T - верхняя, R - правая, B - нижняя границы. Допускается комбинация значений L,T,R и B.align
- строка. Горизонтальное выравнивание текста. Значения L - по левому краю. R - по правому краю, C - по центру, J - равномерно по ширине ячейки.vert_align
- строка. Вертикальное выравнивание текста. Значения: T - по верхнему краю. B - по нижнему краю, С - по центру. Значение по умолчанию: С.fill
- логическое значение. Указывает заполнять ли ячейку текущим цветом для заполнения. См. setColor4Filling
. Значение по умолчанию - false.maxline
- массив числе с плавающей точкой. Элемент массива задает максимальное количество строк текста в многострочной ячейке.link
- строка. Ссылка, например, URL или внутренняя ссылка. В текущей версии не поддерживается.clipping
- логическое значение. Указывает обрезать ли текст по границам ячейки. Значение по умолчанию - false.indent
- число с плавающей точкой. Отступ для первой строки текста. Значение по умолчанию - 0.ln
- целое число. Позиция курсора после отрисовки ячейки. Допустимые значения: 0 - рядом с ячейкой, 1 - новая строка, 2 - под ячейкой. Значение по умолчанию - 0.Пример:
{
"name":"PrintMultiLineCell",
"params":{
"h":5,
"w":95,
"txt":"Сумма средств пенсионных накоплений, поступивших в фонд (с учетом инвестиционного дохода, полученного от инвестирования средств пенсионных накоплений) при вступлении договора об обязательном пенсионном страховании в силу",
"border":"LTR",
"align":"L",
"vert_align":"T",
"fill":true,
"indent":0,
"clipping":false,
"ln":0
}
}
Выводит строку в PDF документе. Строка состоит из многострочных ячеек(см. PrintMultiLineCell
). Высота строки определяется ячейкой с наибольшей высотой.
Параметры
data
- массив строк. Элемент массива задает текст ячейки в строке.input_data_tag
- альтернатива data, имя массива строк-значений ячеек во входных данных запроса.width
- массив чисел с плавающей точкой. Элемент массива задает ширину ячейки.border
- массив строк. Элемент массива описывает видимые границы ячейки. См. описание команды PrintMultiLineCell
. По умолчанию все границы видимы.maxline
- массив чисел с плавающей точкой. Элемент массива задает максимальное количество строк текста в многострочной ячейке. По умолчанию ограничения нет.align
- массив строк. Элемент массива задает горизонтальное выравнивание в ячейке.vert_align
- массив строк. Элемент массива задает вертикальное выравнивание в ячейке.font
- массив объектов описателей шрифта. Элемент массива задает параметры шрифта в ячейке. Набор полей каждого описателя аналогичен параметрам команды SetPrintFont
. Значение по умолчанию - null, что означает использования настроек шрифта, установленного на предыдущем вызове SetPrintFont
.h
- число с плавающей точкой. Высота ячейки. Значение по умолчанию - 5 единиц.fill
- логическое значение. Указывает заполнять ли ячейку текущим цветом для заполнения. См. setColor4Filling
. Значение по умолчанию - false.min_height
число с плавающей точкой. Минимальная высота строки. Ноль означает, что параметр не используется. Значение по умолчанию - 0.clipping
- логическое значение. Указывает обрезать ли текст по границам ячейки. Значение по умолчанию - false.Пример:
{
"name":"Row_Print",
"params":{
"h":4.5,
"min_height": 27,
"width":[85, 95],
"data":[
"1.4. Средства (часть средств) материнского (семейного) капитала (за вычетом части средств материнского (семейного) капитала, возвращенных в Пенсионный фонд Российской Федерации в случае отказа застрахованного лица от направления их на формирование накопительной пенсии и выбора другого направления использования, включая доход полученный от их инвестирования))",
"0,00"
],
"align":["L", "L"],
"vert_align":["T", "T"],
"border":["0", "0"],
"font": [
{
"size":6,
"font_id":"Arial-Bold"
},
{
"size":6,
"font_id":"Arial"
}
],
"fill":true,
"clipping":false
}
}
Выводит текст по заданным координатам.
Параметры
x
- число с плавающей точкой. X координата начала текстаy
- число с плавающей точкой. Y координата начала текстаtext
- текстПример:
{
"name":"PrintText",
"params":{
"x":10,
"y":40,
"text":"Список документов:"
}
}
Подчеркивает текст, выведенный с помощью команды PrintText
.
Параметры аналогичны PrintText
, значения параметров должны совпадать.
{
"name":"underline",
"params":{
"x":10,
"y":40,
"text":"Список документов:"
}
}
Разрыв строки. Переносит курсор на начало следующей строки.
Параметры
h
- число с плавающей точкой. Отступ от текущей координаты Y курсора.Рисует прямую линию между двумя точками на странице.
Параметры
x1
- число с плавающей точкой. X координата начала линии.y1
- число с плавающей точкой. Y координата начала линии.x2
- число с плавающей точкой. X координата конца линии.y2
- число с плавающей точкой. Y координата конца линии.color
строка в формате "#rrggbb", где rgb - шестнадцатеричные компоненты RGB цвета в диапазоне от 0 до ff. Пример красного цвета: "color":“#ff0000”. По умолчанию используется цвет, предварительно заданный командой setColor4Drawing
.width
- число с плавающей точкой. Толщина линии. По умолчанию используется значение, предварительно заданное командой setLineWidth
.Пример:
{
"name":"Line",
"params":{
"x1":100,
"y1":230,
"x2":150,
"y2":230,
"color":"#000000",
"width":0.2
}
}
Рисует окружность на странице.
Параметры
x
- число с плавающей точкой. X координата центра окружности.y
- число с плавающей точкой. Y координата центра окружности.r
- число с плавающей точкой. Радиус окружности.draw
- логическое значение. Управляет отрисовкой контура окружности. Значение по умолчанию - true.fill
- логическое значение. Управляет заливкой цветом внутренней области окружности. Значение по умолчанию - false.draw_color
цвет контура окружности. Строка в формате "#rrggbb", где rgb - шестнадцатеричные компоненты RGB цвета в диапазоне от 0 до ff. Пример красного цвета: "color":“#ff0000”. По умолчанию используется цвет, предварительно заданный командой setColor4Drawing
.fill_color
цвет контура окружности. строка в формате "#rrggbb", где rgb - шестнадцатеричные компоненты RGB цвета в диапазоне от 0 до ff. Пример красного цвета: "color":“#ff0000”. По умолчанию используется цвет, предварительно заданный командой setColor4Filling
.linewidth
- число с плавающей точкой. Толщина контура окружности. По умолчанию используется значение, предварительно заданное командой setLineWidth
.Пример:
{
"name": "Circle",
"params":
{
"x": 135,
"y": 250,
"r": 15,
"draw": false,
"fill": false,
"draw_color": "#ff0000",
"fill_color": "#ff0000",
"linewidth": 0.1
}
}
Параметры
name
- строка. Имя изображения или ID изображения. Если имя совпадает с указанным на предыдущем вызове, используется изображение, указанное в том же вызове.data
- строка. Закодированный в base64 файл изображения. Если имя name
совпадает с указанным на предыдущем вызове, данный параметр не указывается.x
- число с плавающей точкой. X координата изображения.y
- число с плавающей точкой. Y координата изображения.w
- число с плавающей точкой. Ширина изображения в единицах, заданных командой setCoordinateMode
. Если параметр не указан, изображение выводится в натуральную ширину, которая высчитывается на основе плотности пикселей PDF-документа (72 точки на дюйм) и ширины изображения согласно файлу изображения. Пример: изображение 72x72 точки будет иметь размер 1 дюйм на 1 дюйм в PDF-документе.h
- число с плавающей точкой. Высота изображения. Единицы измерения: аналогично параметру w
.link
- строка. URL или ID внутренней ссылки. В текущей версии не поддерживается.Пример:
{
"name":"putImage",
"params":{
"name":"img",
"data":"base64 encoded image",
"x":100,
"y":205,
"w":50,
"h":37.5
}
}
Параметры
template
- объект в формате{
"uri": "local",
"id": "template_example"
}
где идентификатор шаблона - это путь к документу pdf относительно директории templates/pdf
без расширения.
page
- целое число. Номер страницы шаблона для вывода. Диапазон от единицы до количества страниц в шаблоне.Пример команды для многостраничного шаблона:
{
"name":"setPageTemplate",
"params":{
"template":{
"id":"example_multipage_template",
"uri":"local"
},
"page":1
}
}
Если добавление указанной высоты к текущей координате Y приведет к переполнению страницы (то есть выходу за пределы нижнего отступа страницы), команда добавляет новую страницу и возвращает true (возвращаемое значение имеет значение только в команде if
)
Параметры
h
- число с плавающей точкой. Высота для проверки на переполнение страницы.newpage
- логическое значение. Указывает создавать ли новую страницу в документе при переполнении. Значение по умолчанию - true.Команда позволяет выполнить набор подкоманд при истинности условия непосредственно в момент выполнения команды(в отличие от команды register_auto_new_page_commands
).
Поддерживаемый набор команд для использования в качестве условия: checkPageBreak
.
Параметры
condition
- объект, описывающий команду, возвращающую логическое значение.commands
- массив команд для выполнения в случае, если команда указанная в параметре condition
вернула true.Пример:
{
"name": "if",
"params": {
"condition": {
"name":"checkPageBreak",
"params": {
"h": 4.5,
"newpage": true
}
},
"commands": [
{
"name":"setPageTemplate",
"params":{
"template":{
"id":"example_template",
"uri":"local"
}
}
},
{
"name":"setCurrentXY",
"params":{
"x":10,
"y":30
}
}
]
}
}
Типичный вариант использования: перед попыткой вывода элемента или набора элементов в нижнюю часть страницы, когда есть риск выхода за нижний отступ страницы. Значение параметра h
для проверки обычно берётся из размера элемента, который нужно вывести на экран.
Примечание: команда if
работает непосредственно по месту вызова, с текущей координатой Y. То есть, если ее вызвать в момент, когда на странице есть вертикальное пространство высотой h
, то список подкоманд исполнен не будет.
Примечание: не рекомендуется использовать команду if
для вывода строк таблиц. Она может быть полезна для вывода уникального элемента, когда отрисовка происходит ближе к нижней части страницы. В случае таблиц лучше использовать register_auto_new_page_commands
.
Позволяет зарегистрировать набор подкоманд для выполнения в случае, когда исполнение команд типа Row_Print
приводит к автоматическому созданию новой страницы документа. Может быть полезно для рендера заголовка таблицы. Действует со момента вызова. Отмена возможна вызовом этой же команды с пустым списком подкоманд.
Параметры
commands
- массив команд для выполнения.Пример:
{
"name": "register_auto_new_page_commands",
"params": {
"commands": [
{
"name":"setPageTemplate",
"params":{
"template":{
"id":"example_template",
"uri":"local"
}
}
},
{
"name":"setCurrentXY",
"params":{
"x":10,
"y":30
}
}
]
}
}
Отмена команды:
{
"name": "register_auto_new_page_commands",
"params": {
"commands": []
}
}
Команды, принимающие координаты и размеры в качестве параметров, трактуют значения на основании вызова команды setCoordinateMode
. По умолчанию используются миллиметры.
Все подобные параметры могут быть заданы в числовом или текстовом варианте.
В текстовом виде поддерживаются выражения и специальные теги PDF:currentX/PDF:currentY
Пример:
{
"name": "Line",
"params":
{
"x1": "[PDF:currentX]",
"y1": "[PDF:currentY]",
"x2": "[PDF:currentX] + 50",
"y2": "[PDF:currentY]",
"color": "#ff0000",
"width": 0.1
}
}
Команды, которые работают с текстом (PrintText
, PrintCell
и др.), могут содержать теги, которые будут заменены входными данными из запроса.
Входные данные содержатся в “input-data”: {…}
(см. пример из пункта “Структура запроса”).
Тег задается в квадратных скобках. Например, [ORGANIZATION].
Пример:
{
"name":"PrintMultiLineCell",
"params":{
"h":4,
"w":77,
"ln":2,
"txt":"[ORGANIZATION], именуемый в дальнейшем «Фонд», в лице генерального директора Иванова Ивана Ивановича, действующего на основании доверенности № 11142 от 02.04.2018 г., с одной стороны, и [CLINAME], именуемый в дальнейшем «Участник», с другой стороны, заключили настоящее Соглашение о нижеследующем:",
"fill":false,
"align":"J",
"border":"0",
"indent":15,
"clipping":false
}
}
В запросе скобки не указываются (см. пример из пункта “Структура запроса”).
PDF:currPageNum
, номер текущей страницы.PDF:currentX/PDF:currentY
, X и Y координаты курсора.PDF:savedX/PDF:savedY
, доступно после вызова команд saveX/saveY
.[SAVED:ключ]
, доступно после команды saveCoordinate
.Пример:
{
"name":"Line",
"params":{
"x1":"[PDF:savedX]",
"x2":"[SAVED:endLineX]",
"y1":"[PDF:currentY]",
"y2":"[PDF:currentY]",
"color":"#E8E8E8",
"width":0.8
}
},
{
"name":"PrintText",
"params":{
"x":"[SAVED:pageNumX]",
"y":"[SAVED:pageNumY]",
"text":"Номер страницы: [PDF:currPageNum]"
}
}
setPageTemplate
, когда шрифт полностью совпадает с загруженным командой SetPrintFont
. Может увеличить размер файла отчета.Возможен вывод информации в виде штрихкода посредством использования шрифтов семейства Libre Barcode. Шрифты доступны в репозитории librebarcode. Каждый шрифт представляет собой определенный формат штрихкода. Поддерживаются следующие форматы:
Шрифт может включать оригинальный текст непосредственно под штрихкодом (шрифты с суффиксом Text).
Рассмотрим применение на примере формата Code-128.
Шрифты для помещения в папку assets/fonts
сервиса:
В генераторе команд выбрать нужный шрифт, например:
{
"name": "SetPrintFont",
"params":
{
"font_id": "LibreBarcode128Text-Regular",
"size": 30
}
}
curl --request POST --data-binary "@request_examples/pdf/request_barcode_code-128.json" http://localhost:8085/pdf_report_json
Поддерживаемые опции:
enable-debug-report-save
- логическое значение. Указывает создавать ли копию отчета документа (имя файла - идентификатор шаблона) в локальной директории reports_debug
сервиса. Значение по умолчанию - false
.enable-debug-pdf-log
- логическое значение. Включает расширенный диагностический лог создания PDF. Значение по умолчанию - false
.