Generate Dynamic PDF Reports with Structured Tables
Generating a polished PDF report from changing application data can require much more than placing text on a page. Tables must account for column widths, variable-length content, cell padding, borders, colors, merged cells, images, and page boundaries.
The Add to PDF API Tool simplifies this process with high-level table insertion. Your application supplies a JSON description of the table, and pdfRest handles the layout calculations needed to produce a consistent, readable PDF result.
Describe Tables with High-Level JSON
Instead of calculating the position of every cell and drawing each border individually, describe the table using columns, rows, cells, and style properties. This lets your application focus on its data and presentation rules while pdfRest manages the underlying PDF layout.
[
{
"page": 1,
"x": 54,
"y": 540,
"width": 504,
"repeat_header_on_overflow": true,
"columns": [
{
"width": 210
},
{
"width": 144
},
{
"width": 150
}
],
"style": {
"padding": {
"top": 6,
"right": 8,
"bottom": 6,
"left": 8
},
"text_size": 10,
"border_width": 1,
"border_color_rgb": [
180,
185,
190
]
},
"header_rows": [
{
"cells": [
{
"text": "Description",
"tag_structure_type": "TH",
"style": {
"background_color_rgb": [
26,
72,
112
],
"text_color_rgb": [
255,
255,
255
]
}
},
{
"text": "Quantity",
"tag_structure_type": "TH",
"style": {
"background_color_rgb": [
26,
72,
112
],
"text_color_rgb": [
255,
255,
255
]
}
},
{
"text": "Amount",
"tag_structure_type": "TH",
"style": {
"background_color_rgb": [
26,
72,
112
],
"text_color_rgb": [
255,
255,
255
]
}
}
]
}
],
"rows": [
{
"cells": [
{
"text": "Implementation and configuration services"
},
{
"text": "1"
},
{
"text": "$1,250.00"
}
]
},
{
"cells": [
{
"text": "Additional support and documentation"
},
{
"text": "2"
},
{
"text": "$500.00"
}
]
}
],
"footer_rows": [
{
"cells": [
{
"text": "Total",
"col_span": 2,
"tag_structure_type": "TD"
},
{
"text": "$2,250.00",
"tag_structure_type": "TD"
}
]
}
],
"tag_structure_type": "Table"
}
]
Table properties can be applied at the table, row, column, or cell level, allowing broad defaults and targeted overrides within the same table.
Control Table Structure and Appearance
The table JSON can describe the structure and presentation of each part of the table:
- Columns: Define fixed or relative column widths.
- Headers and footers: Add dedicated header and footer rows to identify columns and summarize results.
- Cells: Insert text or images and customize individual cell behavior.
- Padding: Add space between cell content and its borders.
- Alignment: Control the horizontal and vertical placement of content.
- Typography: Set font, text size, text color, and related text properties.
- Borders: Control border color, thickness, opacity, and placement.
- Backgrounds: Apply fill colors and opacity to tables, rows, columns, or individual cells.
Use table-level styles for consistent defaults, then apply row- or cell-level styles when individual values need to stand out. For example, a report can use a common border and padding style while applying different background colors to status cells or highlighting a final total row.
Handle Merged Cells and Variable Content
Tables often contain section labels, grouped headings, or summary rows that span multiple columns. Specify a cell's col_span or row_span value to represent these relationships in the table description.
Cell content can also vary significantly in length. pdfRest measures and lays out wrapped text within the available cell area, allowing row heights to adjust to the content instead of requiring your application to calculate every line and coordinate.
Build Multi-Page Tables
When a table extends beyond the available space on the starting page, pdfRest can continue the table on additional pages while preserving the defined table structure and styling.
Set repeat_header_on_overflow to repeat the table's header rows on continuation pages. This helps readers understand the meaning of each column when reviewing a long report. Footer rows can be used for totals, summaries, or closing information.
Table layout also accounts for variable row heights, wrapped content, and rows that need to continue across page boundaries. Your application can supply the complete table description while pdfRest manages the available page space and continuation layout.
Add Images to Table Cells
Table cells can include image content as well as text. Upload the image files as multipart image_files fields with the request, then reference each uploaded image from a cell using its zero-based image_index.
For example, the first uploaded image uses image_index 0, the second uses image_index 1, and so on. Image cells can specify their rendered width, height, alternative text, and optional structure metadata.
This makes it possible to create tables containing product images, status icons, approval marks, thumbnails, or other visual indicators alongside ordinary text and numeric values.
Support Different Data and Reading Patterns
Table content can be generated from the data source that best fits your application, including JSON records, database results, CSV files, or service responses. Your application can translate those records into the table JSON structure and use the same layout rules for every generated report.
Tables can also support right-to-left text for workflows involving languages such as Arabic or Hebrew. Combined with explicit alignment, padding, and column settings, this allows the same table-generation approach to support multiple document formats and audiences.
Add Optional Structure Tags
Table insertion supports optional structure tagging for newly inserted table content. When tagging is enabled, the table can include structural elements such as:
- Table: Identifies the inserted table structure.
- TH: Identifies header cells.
- TD: Identifies data cells.
- Figure: Identifies image content within a table cell.
Merged cells can include span information so that the logical table structure reflects the visual layout. Image cells can include alternative text and other metadata to support accessibility-oriented workflows and downstream document processing.
Tagging applies to content inserted by the request. It does not automatically tag pre-existing untagged content in the input PDF, but tagged tables can be added to a PDF that already contains an existing structure tree.
Generate Reports from a Blank PDF
For reports created entirely from application data, combine the Create Blank PDF API Tool with Add to PDF. Create the document canvas first, then add tables along with titles, logos, explanatory text, shapes, and other visual elements.
This workflow supports report generation from scratch while still allowing your application to control the document's content and visual design through structured requests.
Use Tables with Other PDF Workflows
After inserting a table, the resulting PDF can continue through other pdfRest workflows. For example, you can:
- Add text, images, or shapes around the table.
- Combine report sections with the Merge PDFs API Tool.
- Convert the completed report to PDF/A for archival workflows.
- Compress the output for storage or delivery.
- Add attachments or apply document security settings.
This allows table insertion to serve as one step in a broader document-generation workflow rather than requiring a separate PDF layout system.
Start Building Dynamic PDF Reports
Use the Add to PDF API Tool to describe tables in JSON and let pdfRest handle the layout details required for a professional PDF result. You can experiment with table insertion in the pdfRest API Lab and review the complete property reference in the pdfRest API Documentation.