FPReport/ru

Архитектура

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: Вызывается, когда отчет завершен и цикл обработки данных больше не нужен.

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

Цикл обработки данных набора данных (TFPReportDatasetData, модуль fpreportdb) содержит некоторые события цикла обработки пользовательских данных, но, в отличие от цикла обработки пользовательских данных, события предназначены исключительно для получения обратной связи пользователем. Цикл обработки данных набора данных управляет всеми данными самостоятельно. Он открывает набор данных или выполняет навигацию по набору данных, когда механизм создания отчетов вызывает различные методы.

Цикл данных Collection

Подобно циклу обработки данных базы данных, цикл сбора данных (TFPReportCollectionData, модуль fpreportcontnr) содержит некоторые события цикла обработки пользовательских данных, но, в отличие от цикла обработки пользовательских данных, события предназначены исключительно для получения обратной связи пользователем. Цикл сбора данных выполняет циклическую обработку элементов коллекции. Он предоставляет опубликованные свойства элементов Collection в виде полей.

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

Подобно циклу сбора данных collection, цикл обработки данных ObjectList (TFPReportObjectListData, модуль fpreportcontnr) содержит некоторые события цикла обработки пользовательских данных, но, в отличие от цикла обработки пользовательских данных, события предназначены исключительно для получения обратной связи от пользователя.

Цикл обработки данных ObjectList выполняет циклическую обработку элементов списка объектов.

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

Цикл передачи данных в формате JSON

Подобно циклу данных collection, цикл обработки данных в формате JSON (TFPReportJSONData, модуль fpreportjson) содержит некоторые события цикла обработки пользовательских данных, но, в отличие от цикла обработки пользовательских данных, события предназначены исключительно для получения обратной связи пользователем.

Цикл обработки данных в формате JSON повторяет элементы массива или объекта в формате JSON.

Он отображает свойства первого элемента в массиве (или объекте) в виде полей. Если первый элемент в массиве снова является массивом, то в качестве имен полей используются Column1 по ColumnN

Предполагается, что все объекты/массивы в списке идентичны по структуре.

Массив может быть вложен в сложный объект: свойство Path может использоваться для указания циклу обработки данных JSON правильного местоположения массива (или объекта).

Загрузка и сохранение в файл

Сам по себе TFPReport не имеет представления о форматах файлов.

Ему известен только класс streamer. По этой причине у него нет методов LoadFromFile/SaveToFile. Единственным поддерживаемым в настоящее время классом streamer является TFPReportJSONStreamer, который можно использовать для сохранения и загрузки дизайна отчета в файл/из файла из другого файла.

На странице FPReport_Usage объясняется, как загрузить отчет из файла.

По той же причине TFPReport нельзя использовать для хранения информации в файле lazarus.lfm.

Класс TFPJSONReport (модуль fpjsonreport) наследуется от TFPReport и объединяет его со стримером JSON. Если вы хотите иметь возможность автоматически загружать дизайн из файла или сохранять его в файле lazarus.dfm, вам лучше использовать этот класс.

Управление данными

Сам по себе компонент TFPReport не обладает знаниями о наборах данных. Ему известен только абстрактный цикл обработки данных.

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

Чтобы загрузить и использовать информацию о данных в структуре отчета, вы можете использовать компонент TFPReportDataManager.

Просто укажите в свойстве DataManager экземпляра FPJSONReport экземпляр компонента TFPReportDataManager, и он создаст необходимые наборы данных и свяжет их с отчетом.

На странице FPReport_Usage объясняется, как это сделать.

Дополнительная информация

На странице FPReport_Usage объясняется, как создать базовый отчет.
На странице FPReport_Designer объясняется, как использовать автономный конструктор отчетов.
На странице FPReport_Custom_elements объясняется, как создавать пользовательские элементы для механизма создания отчетов
На странице FPReport_Lazarus_support представлен обзор того, как можно использовать FPReport в Lazarus.

FAQ

См. FAQ -> FPReport_FAQ