FPReport/ru

This is an old revision of FPReport/ru, edited by Zoltanleo at . The current revision is 150092.

/* Цикл передачи пользовательских данных */

Архитектура

FP Report - это инструмент для создания групповых отчетов.

Он был разработан с нуля, чтобы иметь возможность работать на веб-сервере без интерфейса с минимальными зависимостями. Важным примером использования был сервер Linux, работающий в контейнере без установленных X-библиотек. Создание отчета - это просто размещение квадратиков с содержимым на странице, обычно на основе цикла обработки данных. Это можно сделать полностью в памяти и не требует отображения или графического интерфейса пользователя.

Отчеты могут быть созданы полностью в коде или их можно прочитать из преодпределенного файла. В файле, поставляемом по умолчанию, используется формат JSON для хранения определения отчета. Отчеты также могут быть оформлены визуально с помощью конструктора. Существует автономный конструктор, а также возможность разработки отчета в среде IDE Lazarus.

После создания отчета его можно сохранить на диск или отрисовать. Отрисовка - это процесс создания визуального вывода.

Были реализованы различные средства визуализации:

Части, которые не могут быть отображены в формате HTML и CSS, будут отображены в виде изображения и размещены на странице HTML.

Фактически, это основа предварительного просмотра, конструктора и поддержки печати.

Модули

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).

При каждой печати бэнда печатаются все элементы в нем. Существует несколько типов элементов. Основными из них являются

Текст может содержать заполнители, которые будут вычисляться при каждой печати текста.

Эти элементы имеют некоторые общие черты, такие как возможность обводить их рамкой и иметь цвет фона.

Типы бэндов

Отчет FP содержит различные типы бэндов. У каждого бэнда есть свое назначение. Некоторые бэнды могут отображаться в определении отчета только один раз, другие бэнды могут отображаться несколько раз.

DataBand

Это бэнд (класс TFPReportDataBand), который будет распечатываться один раз для каждой записи в цикле данных отчета. В отчет можно поместить несколько бэндов данных, если они связаны отношением мастер-деталь.

Report title и Summary

Заголовок отчета (TFPReportTitleBand) и краткое содержание (TFPReportSummaryBand) могут отображаться один раз на каждой странице отчета. Они печатаются один раз: при запуске и завершении подготовки отчета.

Верхний колонтитул (TFPReportPageHeaderBand) и нижний колонтитул (TFPReportPageFooterBand) печатаются соответственно вверху и внизу каждой страницы. Такую полосу можно добавить один раз на страницу. Можно не печатать верхний колонтитул на первой странице и нижний колонтитул на последней странице.

Верхний колонтитул данных (TFPReportDataHeaderBand) и нижний колонтитул (TFPReportDataFooterBand) печатаются при запуске и завершении цикла обработки данных. Если отчет содержит несколько страниц и использует несколько циклов, то сводка отчета и заголовок печатаются только один раз, но заголовок данных и сводная информация печатаются для каждого цикла. Эту полосу можно добавить один раз для каждого цикла данных в отчете.

Данные могут быть сгруппированы на основе выражения. При изменении значения выражения запускается новая группа. Группа определяется путем размещения на странице заголовка группы (TFPReportGroupHeaderBand). Итоговые данные по группе могут отображаться в конце группы с помощью нижнего колонтитула группы (TFPReportGroupFooterBand)

Этот диапазон можно добавлять один раз для каждого цикла обработки данных в отчете.

Отчет может содержать несколько столбцов. В начале каждого столбца (на каждой странице) можно напечатать заголовок, используя полосу заголовков столбцов (Column Header) (TFPReportColumnHeaderBand). В нижней части столбца (опять же, на каждой странице) может быть напечатана полоса нижнего колонтитула (Column Footer) (TFPReportColumnFooterBand).

Эту полосу можно добавить один раз для каждой страницы отчета.

Child band

За исключением бэндов нижнего колонтитула страницы и столбца, к каждому бэнду может быть присоединен дочерний бэнд (TFPReportChildBand). Это может быть полезно для выравнивания, например, когда бэнд содержит увеличивающийся memo, и бэнд настроен на растяжение, что позволяет разместить содержимое memo.

Этот бэнд можно размещать в отчете произвольное количество раз.

Элементы, доступные для печати

На бэнд можно поместить один или несколько элементов, доступных для печати. Элементом, доступным для печати, является один из следующих элементов:

Какое из них используется, зависит от значения выражения, которое вычисляется каждый раз при печати флажка.

Циклы обработки данных

Цикл обработки данных является основной концепцией отчета. Его можно рассматривать как абстракцию массива записей: для каждой "записи" в "массиве" будет напечатан бэнд данных. "Поля" каждой записи доступны для использования в выражении, и когда вычисляется выражение, содержащее поле, в выражении будет использоваться значение поля для текущей записи.

Очевидно, что цикл обработки данных определяет количество страниц в подготовленном отчете.

В настоящее время доступно 5 типов циклов обработки данных:

Этот цикл полностью управляется событиями, и для извлечения данных используются различные события.

Этот цикл управляется набором данных: запись - это 1 запись в наборе данных, "поля" в записи - это поля в наборе данных.

При этом используется RTTI объектов для предоставления данных в цикле.

Аналогично циклу TFPObjectList, при этом используется RTTI объектов для предоставления данных в цикле.

Это берет массив JSON (или объект) и выполняет цикл по элементам в массиве.

Структура цикла передачи данных

Циклы данных отображаются на нескольких уровнях, они определяют структуру отчета.

Это основной цикл данных для страницы.

Цикл этих бэндов выполняется каждый раз, когда печатается бэнд 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

FAQ

See the FAQ -> FPReport_FAQ