Layout

TerraFluent.Pdf.Reporting provides three layout elements: Column, Row, and Table. They are all accessed through extension methods on IContainer.

For a visual explanation of how Column and Row relate to each other see Row & Column Layout.

Column

Column stacks its children vertically (top → bottom).

container.Column(col =>
{
    col.Spacing(8);          // vertical gap between items in points

    col.Item().Text("First paragraph");
    col.Item().Text("Second paragraph");
    col.Item().Background(Color.Grey.Lighten4).Padding(10).Text("Highlighted box");
});

Column alignment

Each Item() can be aligned independently by calling an AlignItems* method before the Item() call it should affect:

col.AlignItemsLeft();           // default
col.Item().Text("Left");

col.AlignItemsCenter();
col.Item().Text("Centred");

col.AlignItemsRight();
col.Item().Text("Right");

`ColumnDescriptor` API

Method	Description
`Spacing(double)`	Vertical gap between items in points
`AlignItemsLeft()`	Left-align subsequent items (default)
`AlignItemsCenter()`	Centre-align subsequent items
`AlignItemsRight()`	Right-align subsequent items
`Item()`	Adds an item slot; returns `IContainer`
`PageBreak()`	Inserts an explicit page break at this position

Row

Row arranges its children horizontally (left → right).

container.Row(row =>
{
    row.Spacing(6);   // horizontal gap between items in points

    row.RelativeItem(2).Text("Takes 2x the share");
    row.RelativeItem(1).Text("Takes 1x the share");
    row.AutoItem().Text("Natural content width");
    row.ConstantItem(80).Text("Always 80 pt wide");
});

Item sizing

Method	Width
`RelativeItem(weight = 1)`	Proportional share of remaining space after constant/auto items
`AutoItem()`	Measured natural content width
`ConstantItem(points)`	Fixed number of PDF points

Width calculation order:

Subtract spacing from available width.
Measure all ConstantItem widths and AutoItem widths (content measurement pass).
Distribute remaining space among RelativeItem slots proportionally by weight.

`RowDescriptor` API

Method	Returns	Description
`Spacing(double)`	`RowDescriptor`	Horizontal gap in points
`RelativeItem(double weight = 1)`	`IContainer`	Proportional slot
`AutoItem()`	`IContainer`	Auto-sized slot
`ConstantItem(double pts)`	`IContainer`	Fixed-width slot

Table

Table renders a grid with fixed or proportional columns. Header rows are automatically repeated on every continuation page when the table spans multiple pages.

container.Table(table =>
{
    // 1. Define columns
    table.ColumnsDefinition(cols =>
    {
        cols.RelativeColumn(4);    // proportional
        cols.RelativeColumn(1);
        cols.ConstantColumn(70);   // fixed width in points
    });

    // 2. Header row (repeated on continuation pages)
    table.HeaderRow(row =>
    {
        row.Cell().Background("#1a4a8a").Padding(6)
           .Text("Description").Bold().FontColor(Color.White);
        row.Cell().Background("#1a4a8a").Padding(6).AlignCenter()
           .Text("Qty").Bold().FontColor(Color.White);
        row.Cell().Background("#1a4a8a").Padding(6).AlignRight()
           .Text("Price").Bold().FontColor(Color.White);
    });

    // 3. Data rows
    bool shade = false;
    foreach (var item in lineItems)
    {
        string bg = shade ? Color.Grey.Lighten4 : Color.White;
        table.Row(row =>
        {
            row.Cell().Background(bg).Padding(6).Text(item.Name);
            row.Cell().Background(bg).Padding(6).AlignCenter().Text(item.Qty.ToString());
            row.Cell().Background(bg).Padding(6).AlignRight().Text($"${item.Price:N2}");
        });
        shade = !shade;
    }
});

Column definitions

Method	Description
`RelativeColumn(weight = 1)`	Proportional share of available width
`ConstantColumn(points)`	Fixed width in PDF points

`TableDescriptor` API

Method	Description
`ColumnsDefinition(Action<ColumnsDefinitionDescriptor>)`	Define all columns
`HeaderRow(Action<TableRowDescriptor>)`	Add a header row (repeats on new pages)
`Row(Action<TableRowDescriptor>)`	Add a data row

`TableRowDescriptor` API

Method	Returns	Description
`Cell(columnSpan = 1, rowSpan = 1)`	`IContainer`	Next cell slot (left to right, auto-skipping columns reserved by an earlier `columnSpan` in the same row or a `rowSpan` reaching down from a previous row); supports all decorators

Tip: Cells support the full decorator chain: row.Cell().Background(bg).Padding(6).AlignRight().Text("value")

Column and row spans

table.Row(row =>
{
    // rowSpan: add the cell once, on the first row it covers.
    row.Cell(rowSpan: 2).Background("#E8F5F0").Padding(8).AlignMiddle()
       .Text("Laptops").Bold();
    row.Cell().Padding(6).Text("UltraBook Pro 14\"");
    row.Cell().Padding(6).AlignRight().Text("$1,299.00");
});
table.Row(row =>
{
    // Column 1 is already occupied by the rowSpan cell above — Cell()
    // skips it automatically and lands in column 2.
    row.Cell().Padding(6).Text("UltraBook Pro 16\"");
    row.Cell().Padding(6).AlignRight().Text("$1,799.00");
});

// columnSpan merges cells left to right within a single row.
table.Row(row => row.Cell(columnSpan: 3).Background("#0F5C4C").Padding(6)
    .AlignCenter().Text("NEW ARRIVALS").Bold().FontColor(Color.White));

columnSpan merges the cell across that many columns of its own row; the next Cell() call in the same row automatically starts after it.
rowSpan extends the cell down that many rows; call it once, on the first row of the group — every following row’s Cell() calls automatically skip the column it occupies.
Row heights grow to fit a rowSpan cell’s content when it’s taller than the rows it spans (the extra height is split evenly across them).
A rowSpan group is never split across a page break — if it doesn’t fit on the current page, the whole group moves to the next one together.

See 17_TableSpanShowcase.cs in the samples project for a full worked example (category-grouped rows, a banner row, and a rowSpan group crossing a page break).

Header on First Page Only

By default, the page header appears on every page. Use HeaderOnFirstPageOnly() to show the header only on the first page, freeing vertical space for content on continuation pages:

page.Header().Text("Confidential").Bold();
page.HeaderOnFirstPageOnly();  // header only on page 1

This is useful for cover pages or documents where the header should not repeat.

Nesting Layouts

Column, Row, and Table nest freely inside each other.

Two-column page layout

container.Row(row =>
{
    row.RelativeItem().Column(left =>
    {
        left.Spacing(6);
        left.Item().Text("Left heading").Bold();
        left.Item().Text("Left body text.");
    });

    row.ConstantItem(1).Background(Color.Grey.Lighten2);  // divider

    row.RelativeItem().PaddingLeft(12).Column(right =>
    {
        right.Spacing(6);
        right.Item().Text("Right heading").Bold();
        right.Item().Text("Right body text.");
    });
});

Header / body / footer page structure

container.Column(page =>
{
    page.Spacing(10);

    // Header row
    page.Item().Row(header =>
    {
        header.RelativeItem().Text("Logo").Bold();
        header.AutoItem().Text("Page 1").FontColor(Color.Grey.Medium);
    });

    // Body
    page.Item().Text("Main content goes here.");

    // Footer row
    page.Item().Row(footer =>
    {
        footer.RelativeItem().Text("Company Name");
        footer.AutoItem().Text("Confidential").Italic();
    });
});

View this page's source on GitHub →