Архитектура
FP Report - это инструмент для создания групповых отчетов.
Он был разработан с нуля, чтобы иметь возможность работать на веб-сервере без интерфейса с минимальными зависимостями. Важным примером использования был сервер Linux, работающий в контейнере без установленных X-библиотек. Создание отчета - это просто размещение квадратиков с содержимым на странице, обычно на основе цикла обработки данных. Это можно сделать полностью в памяти и не требует отображения или графического интерфейса пользователя.
Отчеты могут быть созданы полностью в коде или их можно прочитать из преодпределенного файла. В файле, поставляемом по умолчанию, используется формат JSON для хранения определения отчета. Отчеты также могут быть оформлены визуально с помощью конструктора. Существует автономный конструктор, а также возможность разработки отчета в среде IDE Lazarus.
После создания отчета его можно сохранить на диск или отрисовать. Отрисовка - это процесс создания визуального вывода.
Были реализованы различные средства визуализации:
- Для PDF. Предпочтительным средством визуализации является средство визуализации в формате PDF
- Для серии изображений. Программа визуализации изображений FP создает растровое изображение для каждой страницы, и растровые изображения могут быть сохранены в каталоге в любом из поддерживаемых форматов изображений FP.
- В HTML: каждая страница отображается как HTML-страница с использованием соответствующей CSS-разметки.
Части, которые не могут быть отображены в формате HTML и CSS, будут отображены в виде изображения и размещены на странице HTML.
- В LCL (холст).
Фактически, это основа предварительного просмотра, конструктора и поддержки печати.
- В AggPas canvas. AggPas - это мощная графическая библиотека, и этот инструмент визуализации аналогичен инструменту визуализации изображений FP
- В fpGUI - его можно использовать для предварительного просмотра отчета в отчете FPGUI
Модули
- fpreport
- Для создания отчета в коде достаточно этого модуля.
- Он содержит базовый отчет, страницу, бэнды и элементы.
- fpreportstreamer
- Этот модуль содержит стример, который считывает/записывает определение отчета из/в файл.
- fpjsonreport
- Этот модуль содержит класс отчета, который можно удалить из модуля формы/данных Lazarus:
- определение отчета будет записано в файл формы.
- fpreportdb
- Этот модуль содержит компонент цикла обработки данных Данные набора данных отчета TFP, который основывает цикл на данных из набора данных.
- fpreportpdfexport
- Этот модуль содержит программу экспорта отчетов в формате PDF TFP Report Export PDF.
- Экземпляр этого класса можно использовать для экспорта отчета в формат PDF.
- fpreporthtmlexport
- Этот модуль содержит HTML-экспортер TFP Report Export HTML.
- Экземпляр этого класса можно использовать для экспорта отчета на HTML-страницы.
- fpreportfpimageexport
- Этот модуль содержит программу экспорта изображений TFPReportExportfpImage.
- Экземпляр этого класса можно использовать для экспорта отчета в любой поддерживаемый формат изображений.
Структура отчета
Отчет является экземпляром класса TFP Report. Он состоит из одной или нескольких страниц, каждая страница является экземпляром TFPReportCustomPage. Экземпляры доступны в свойстве массива Pages класса отчетов. Количество страниц указывается в свойстве PageCount.
При создании отчета сначала будет отображена первая страница (в соответствии с циклом обработки данных), затем будет отображена вторая страница и так далее.
Каждая страница может состоять из одного или нескольких бэндов. Некоторые бэнды будут отображаться в выходных данных только один раз, другие - в обычных местах, но большинство бэндов будут отображаться произвольное количество раз, в зависимости от данных, которые передаются в отчет. Обычно для каждой записи в цикле обработки данных один раз печатается бэнд данных.
Каждый бэнд содержит один или несколько элементов (потомков TFPReportElement).
При каждой печати бэнда печатаются все элементы в нем. Существует несколько типов элементов. Основными из них являются
- Memo. Это текстовый элемент, который печатает текст.
Текст может содержать заполнители, которые будут вычисляться при каждой печати текста.
- checkbox. Это графический элемент, который печатает флажок (установленный или нет)
- image. Это графический элемент, на котором печатается изображение.
- shape. Это элемент, который может отображать одну из нескольких геометрических фигур.
Эти элементы имеют некоторые общие черты, такие как возможность обводить их рамкой и иметь цвет фона.
Типы бэндов
Отчет FP содержит различные типы бэндов. У каждого бэнда есть свое назначение. Некоторые бэнды могут отображаться в определении отчета только один раз, другие бэнды могут отображаться несколько раз.
DataBand
Это бэнд (класс TFPReportDataBand), который будет распечатываться один раз для каждой записи в цикле данных отчета. В отчет можно поместить несколько бэндов данных, если они связаны отношением мастер-деталь.
Report title и Summary
Заголовок отчета (TFPReportTitleBand) и краткое содержание (TFPReportSummaryBand) могут отображаться один раз на каждой странице отчета. Они печатаются один раз: при запуске и завершении подготовки отчета.
Page Header и Footer
Верхний колонтитул (TFPReportPageHeaderBand) и нижний колонтитул (TFPReportPageFooterBand) печатаются соответственно вверху и внизу каждой страницы. Такую полосу можно добавить один раз на страницу. Можно не печатать верхний колонтитул на первой странице и нижний колонтитул на последней странице.
Data Header и Footer
Верхний колонтитул данных (TFPReportDataHeaderBand) и нижний колонтитул (TFPReportDataFooterBand) печатаются при запуске и завершении цикла обработки данных. Если отчет содержит несколько страниц и использует несколько циклов, то сводка отчета и заголовок печатаются только один раз, но заголовок данных и сводная информация печатаются для каждого цикла. Эту полосу можно добавить один раз для каждого цикла данных в отчете.
Group Header и Footer
Данные могут быть сгруппированы на основе выражения. При изменении значения выражения запускается новая группа. Группа определяется путем размещения на странице заголовка группы (TFPReportGroupHeaderBand). Итоговые данные по группе могут отображаться в конце группы с помощью нижнего колонтитула группы (TFPReportGroupFooterBand)
Этот диапазон можно добавлять один раз для каждого цикла обработки данных в отчете.
Column Header и Footer
Отчет может содержать несколько столбцов. В начале каждого столбца (на каждой странице) можно напечатать заголовок, используя полосу заголовков столбцов (Column Header) (TFPReportColumnHeaderBand). В нижней части столбца (опять же, на каждой странице) может быть напечатана полоса нижнего колонтитула (Column Footer) (TFPReportColumnFooterBand).
Эту полосу можно добавить один раз для каждой страницы отчета.
Child band
За исключением бэндов нижнего колонтитула страницы и столбца, к каждому бэнду может быть присоединен дочерний бэнд (TFPReportChildBand). Это может быть полезно для выравнивания, например, когда бэнд содержит увеличивающийся memo, и бэнд настроен на растяжение, что позволяет разместить содержимое memo.
Этот бэнд можно размещать в отчете произвольное количество раз.
Элементы, доступные для печати
На бэнд можно поместить один или несколько элементов, доступных для печати. Элементом, доступным для печати, является один из следующих элементов:
- Memo. Это текстовый элемент. Текст может содержать формулы и ограниченный набор HTML-тегов, таких как полужирный шрифт, курсив, подчеркивание и теги шрифта или якоря. Формулы будут обработаны, и результат будет подставлен в текста.
- Shape: это одна из нескольких фигур, таких как круг, квадрат, треугольник или прямые линии различной ориентации.
- Image: Вы можете вставить в свой отчет любое изображение. Можно использовать все форматы изображений, поддерживаемые FPC fcl-image.
- Checkbox. Это особый случай компонента изображения: он использует 2 изображения, одно для значений true, другое для значений false.
Какое из них используется, зависит от значения выражения, которое вычисляется каждый раз при печати флажка.
- элемент Barcode. Этот элемент находится в отдельном блоке (fpreportbarcode) и может использоваться для отображения одного из многих типов штрих-кода.
- элемент QRCode. Этот элемент находится в отдельном блоке (fpreportqrcode) и может использоваться для отображения QR-кода. Он обладает некоторыми свойствами, позволяющими определить тип штрих-кода и способ его позиционирования.
Циклы обработки данных
Цикл обработки данных является основной концепцией отчета. Его можно рассматривать как абстракцию массива записей: для каждой "записи" в "массиве" будет напечатан бэнд данных. "Поля" каждой записи доступны для использования в выражении, и когда вычисляется выражение, содержащее поле, в выражении будет использоваться значение поля для текущей записи.
Очевидно, что цикл обработки данных определяет количество страниц в подготовленном отчете.
В настоящее время доступно 5 типов циклов обработки данных:
- Цикл обработки пользовательских данных (user data loop).
Этот цикл полностью управляется событиями, и для извлечения данных используются различные события.
- Цикл обработки данных базы данных (DB data loop).
Этот цикл управляется набором данных: запись - это 1 запись в наборе данных, "поля" в записи - это поля в наборе данных.
- Цикл, основанный на TFPObjectList.
При этом используется RTTI объектов для предоставления данных в цикле.
- Цикл, основанный на TCollection.
Аналогично циклу TFPObjectList, при этом используется RTTI объектов для предоставления данных в цикле.
- Цикл, основанный на массиве JSON/Object.
Это берет массив JSON (или объект) и выполняет цикл по элементам в массиве.
Структура цикла передачи данных
Циклы данных отображаются на нескольких уровнях, они определяют структуру отчета.
- На странице может быть цикл данных.
- Бэнд Master данных. На странице может существовать только один такой бэнд.
Это основной цикл данных для страницы.
- Бэнды Detail данных.
Цикл этих бэндов выполняется каждый раз, когда печатается бэнд Master данных бэндов Detail данных.
Бэнды Detail данных могут быть вложенными, бэнд Detail данных может быть Master для другого бэнда Detail данных.
Для каждой страницы отчета обработчик определяет основной цикл обработки данных для этой страницы.
Это первый цикл обработки данных для бэнда данных, если у бэнда данных нет master бэнда. Он будет использоваться для запуска отображения бэндов на этой странице.
Обычно Page.Data будут равны Nil.
Но если он установлен и отличается от основного цикла обработки данных на странице, то для каждой записи в цикле Page.Data отображается вся страница (и все циклы на ней).
Если основной цикл обработки данных равен циклу обработки данных страницы, логика такова, как если бы Page.Data был равен Nil (для обратной совместимости).
Для каждого диапазона, у которого есть поддиапазоны, движок выполнит аналогичный цикл по поддиапазонам.
Цикл передачи пользовательских данных
Пользовательский цикл обработки данных полностью управляется событиями и должен использоваться для любого типа данных. Ожидается, что пользователь реализует несколько обработчиков событий для цикла обработки данных, чтобы реализовать его функциональность.
- OnOpen
- Вызывается, когда цикл передачи данных 'открыт'.
- Может быть использовано для настройки фактических данных.
- OnFirst
- Вызывается, когда механизму создания отчетов необходимо поместить цикл обработки данных в первую запись.
- OnGetValue
- Вызывается, когда механизму создания отчетов необходимо получить значение поля.
- OnGetNames
- Вызываемый перед открытием цикла обработки данных, он используется для получения списка полей в цикле обработки данных
- OnNext
- Вызывается для подачи сигнала о том, что цикл передачи данных должен перейти к следующей записи
- OnGetEOF
- Вызывается, чтобы проверить, есть ли еще какие-либо записи в цикле обработки данных.
- OnClose
- Вызывается, когда отчет завершен и цикл обработки данных больше не нужен.
DB Data loop
The dataset data loop (TFPReportDatasetData, unit fpreportdb) has some of the events of the user data loop, but in difference with the user data loop, the events are purely for the user to get feedback. The dataset data loop manages all data by itself. It will open the dataset or navigate through the dataset as the reporting engine calls the various methods.
Collection Data loop
Similar to the DB Data loop, the collection data loop (TFPReportCollectionData, unit fpreportcontnr) has some of the events of the user data loop, but in difference with the user data loop, the events are purely for the user to get feedback. The collection data loop loops over the items in a collection. It exposes the published properties of the collection items as fields.
ObjectList Data loop
Similar to the collection data loop, the objectlist data loop (TFPReportObjectListData, unit fpreportcontnr) has some of the events of the user data loop, but in difference with the user data loop, the events are purely for the user to get feedback.
The object list data loop loops over the items in an object list.
It exposes the published properties of the list items as fields. It assumes all the objects in the list are if the same class, and uses the first object in the list to determine the fields.
JSON Data loop
Similar to the collection data loop, the JSON data loop (TFPReportJSONData, unit fpreportjson) has some of the events of the user data loop, but in difference with the user data loop, the events are purely for the user to get feedback.
The JSON data loop loops over the items in a JSON Array or object.
It exposes the properties of the first item in the array (or object) as fields. If the first item in the array is again an array, then Column1 to ColumnN are used as field names
It assumes all the objects/arrays in the list are identical in structure.
The array can be nested inside a complex object: the Path property can be used to point the JSON Data loop to the correct location of the array (or object)
Loading and Saving to file
By itself, TFPReport has no concept of file formats.
It only knows a streamer class. For this reason, it has no LoadFromFile/SaveToFile methods. The only currently supported streamer class is TFPReportJSONStreamer, which can be used to save and load a report design to/from file.
The FPReport_Usage page explains how to load a report from file.
For the same reason, a TFPReport cannot be used to store information in a lazarus .lfm file.
The TFPJSONReport class (unit fpjsonreport) descends from TFPReport, and combines it with the JSON streamer. If you want to be able to automatically load a design from file, or store it in the lazarus .dfm file, you are better off using this class.
Data management
By itself the TFPReport component does not have knowledge of datasets. It only knows an abstract data loop.
If you design a report using the report designer, the stand-alone designer writes data definitions to the JSON it creates. However, the report itself ignores this information, and no datasets or other data loops will be created.
In order to load and use the information about data in the report design, you can use a TFPReportDataManager component.
Just point the FPJSONReport instance's DataManager property to the instance of the TFPReportDataManager component, and it will instantiate the necessary datasets, and couple them to the report.
The FPReport_Usage page explains how to do this.
More Info
- The FPReport_Usage page explains how to create a basic report.
- The FPReport_Designer page explains how to use the stand-alone report designer.
- The FPReport_Custom_elements page explains how to create custom elements for the reporting engine
- The FPReport_Lazarus_support page gives an overview of how FPReport can be used in Lazarus.
FAQ
See the FAQ -> FPReport_FAQ