Skip to content

Table & Cell Styles

A generated table combines several style layers. Understanding which layer owns a property makes table rendering much easier to debug.

Cell properties

A RichTableCell owns cell geometry and decoration such as:

$cell = new RichTableCell('Value', [
    'background' => '#f2f2f2',
    'border' => '0.5pt solid #999999',
    'padding' => '0.15cm',
]);

These options are mapped to ODF table-cell properties.

Paragraph properties inside a cell

Text alignment belongs to the paragraph inside the cell, not to the characters themselves:

$cell = new RichTableCell('129.90', [
    'text-align' => 'right',
]);

The convenience style splitter routes paragraph-oriented options to the cell's paragraph content.

For more explicit control, construct the paragraph yourself:

$paragraph = new Paragraph(null, [
    'text-align' => 'right',
    'margin-top' => '0cm',
    'margin-bottom' => '0cm',
]);
$paragraph->addText('129.90', ['bold' => true]);

$cell = new RichTableCell($paragraph, [
    'background' => '#f2f2f2',
    'padding' => '0.15cm',
]);

This makes the three responsibilities visible in code:

RichTableCell
├── background / border / padding
└── Paragraph
    ├── alignment / spacing
    └── text
        └── font / bold / color

Mixed convenience styles

For simple cells, a single style array can contain cell, paragraph, and text properties:

$cell = new RichTableCell('Total', [
    'background' => '#12324a',
    'border' => '0.5pt solid #0b1f2d',
    'padding' => '0.15cm',
    'text-align' => 'right',
    'bold' => true,
    'color' => '#ffffff',
]);

The engine separates these options internally. This is convenient, but explicit nested content is preferable when a cell becomes structurally complex.

Spans

Cell spans are structural properties rather than visual styles:

$cell
    ->setColspan(2)
    ->setRowspan(2);

The engine writes native ODF span attributes to the table cell. Relative column-width ratios are a separate table-column concern and do not alter these spans.

Table style names

RichTable::setTableStyleName() can assign a table-level style name:

$table->setTableStyleName('InvoiceTable');

This is a reference to a table style name. Table-level style authoring is not exposed through a generic global registry. For most generated tables, start with table, cell, paragraph, and text options unless the template already provides an appropriate reusable table style.

Style sets for array-built tables

buildTableFromArray() can use predefined or custom style sets containing roles such as:

header
row
row-alt
summary / highlight

Custom style sets are registered on the table instance:

$table->addCustomStyle('report', [
    'header' => [
        'background' => '#333333',
        'color' => '#ffffff',
        'font-weight' => 'bold',
    ],
    'row' => [
        'background' => '#f5f5f5',
    ],
    'row-alt' => [
        'background' => '#ffffff',
    ],
]);

Use these when they simplify application rendering. For a highly designed document, LibreOffice template styles or explicit semantic rendering code may be easier to maintain.

XML placement is an implementation concern

ODF allows style definitions in different package locations. The current table pipeline uses document-local semantic style ownership and may materialize generated table-related structures in styles.xml or content.xml according to their ODF role.

Application code should not depend on the exact XML destination of a generated cell or table-column style. Treat RichTable, RichTableCell, and their documented style options as the public abstraction.

Style ownership and materialization are already document-local. Remaining table work concerns layout and geometry semantics rather than another general style-registry consolidation.

Current limitations

Styling a cell does not solve exact table geometry. RichTable already supports explicit column widths, relative column-width ratios, and row-level min-row-height, but overall table width, exact layout across document contexts, fixed row heights, and more advanced geometry/page-flow semantics remain separate concerns.

Always distinguish:

style problem
vs.
layout/geometry problem

when diagnosing a generated table.

See the Tables guide for the current geometry APIs and their boundaries.

See Style Model for the general styling architecture.