Create and Format Tables

Two Types of Tables

You can use the DOM API to create two types of tables that differ in structure.

  • An informal table (i.e., a table) consists of rows that contain table entries.

  • A formal table contains a header, a body, and a footer section. Each section contains rows that contain table entries.

Informal tables are useful for most of your reporting needs. Use formal tables for tables whose headers or footers contain multiple rows.

For details about informal tables, see:

For details about formal tables, see:

Create a Table from a Two-Dimensional Array

You can create a table by appending a two-dimensional numeric array or a cell array containing built-in MATLAB® data (text and numbers) and DOM objects (Text, Table, Image, etc.) to a document. The append function converts the array to a Table object, appends it to the document, and returns the Table object, which you can then format. You can also create a Table object directly by including a two-dimensional array in its constructor.

This example shows how to create a table from a numeric array and another table from a cell array of various object types. The cell array contains a magic square, which is rendered as an inner table. The cell array also includes a Text object constructor that uses the AlertLevel template style.

import mlreportgen.dom.*;
doc = Document('test');

table1 = append(doc,magic(5));
table1.Border = 'single';
table1.ColSep = 'single';
table1.RowSep = 'single';

ca = {'text entry',Paragraph('a paragraph entry'); ...
       Text('Danger!','AlertLevel'),magic(4)};
table2 = Table(ca);
append(doc,table2);

close(doc);
rptview(doc.OutputPath);

Create a Table Using the Table entry Function

You can use the entry function with a Table object to add content to a table entry or to format an entry. This approach is useful when you need to format table entries individually. For example:

import mlreportgen.dom.*;
doc = Document('test');

a = magic(5);
[v,i] = max(a);
[v1,i1] = max(max(a));
table = Table(a);

text = table.entry(i(i1),i1).Children(1);
text.Color = 'red';
append(doc,table);

close(doc);
rptview(doc.OutputPath);

Create a Table from Scratch

You can create a table from scratch by creating TableEntry objects, appending them to TableRow objects, and appending the TableRow objects to a Table object. This approach is useful when you need to create table entries that span multiple columns or rows that have a different number of entries. This example shows how to create a table with four columns and two rows. In the first table row, the second entry spans the second and third columns.

import mlreportgen.dom.*;
doc = Document('test');

table = Table(4);
table.Border = 'single';
table.ColSep = 'single';
table.RowSep = 'single';

row = TableRow;
append(row, TableEntry('entry 11'));
te = TableEntry('entry 12-13');
te.ColSpan = 2;
te.Border = 'single';
append(row, te);
append(row, TableEntry('entry 14'));
append(table,row);

row = TableRow;
for c = 1:4
  append(row, TableEntry(sprintf('entry 2%i', c)));
end
append(table,row);

append(doc,table);

close(doc);
rptview(doc.OutputPath);

Format a Table

You can format a table programmatically, using DOM format objects or format properties. You can also use template styles. For information about these formatting techniques and format inheritance, see Report Formatting Approaches.

Format a Table Programmatically

You can use format objects to format tables or use Table format properties to specify commonly used table formats. This example uses:

  • Border, ColSep, and RowSep format objects to specify a red table border and the green column and row separators

  • The Width format property to specify the table width

import mlreportgen.dom.*;
d = Document('test','html');

table = Table(magic(5));
table.Style = {Border('inset','red','3px'), ...
               ColSep('single','green','1px'), ...
               RowSep('single','green','1px')};

table.Width = '50%';

append(d, table);

close(d);
rptview(d.OutputPath);

Use these format objects and format properties to format a table.

Formatting Format ObjectFormat Property

Width of table

Width

Width

Color of table background

BackgroundColor

BackgroundColor

Create border around table

Border

Border

Color of border

Border

BorderColor

Thickness of border

Border

BorderWidth

Create left, right, top, or bottom table border

Border

n/a

Collapse table and table entry borders (HTML)

BorderCollapse

BorderCollapse

Create column separator

ColSep

ColSep

Column separator color

ColSep

ColSepColor

Column separator thickness

ColSep

ColSepWidth

Create row separator

RowSep

RowSep

Row separator color

RowSep

RowSepColor

Row separator thickness

RowSep

RowSepWidth

Indent table from left margin

OuterMargin

OuterLeftMargin

Space before or after table

OuterMargin

n/a

Space to right of table

OuterMargin

n/a

Align table left, right, or center

HAlign

HAlign

Specify table entry flow direction (left-to-right or right-to-left)

FlowDirection

FlowDirection

Resize table columns to fit contents

ResizeToFitContents

n/a

Format Table Entries

A Table object has properties that allow you to specify the same format or set of formats for all its entries.

FormattingTable Object Property

Align entries vertically (top, middle, bottom)

TableEntriesValign

Align entries horizontally (left, right, center)

TableEntriesHalign

Create space (padding) between entry boundary and content

TableEntriesInnerMargin

Apply a set of format objects to all table entries

TableEntriesStyle

You can use a mlreportgen.dom.TextOrientation format object to make the text in a table entry vertical or horizontal.

Keep a Table and Title on the Same Page

Use the KeepLinesTogether and KeepWithNext paragraph formats to keep a table title and the table together on the same page. This example creates a table title, creates table content, and makes the table header row bold, using table entry indexing. To keep the table on the same page, the code specifies KeepLinesTogether and KeepWithNext for all rows except the last row. The last row has only KeepLinesTogether set and not KeepWithNext. This prevents the table from being forced to stay with the paragraph that follows.

import mlreportgen.dom.*
rpt = Document('test','docx');
 
p = Paragraph('Table 1');
p.Style = {Bold,KeepLinesTogether,KeepWithNext};
append(rpt, p);
 
ca = {Paragraph('Col 1'),Paragraph('Col 2'); ...
      Paragraph('data 11'),Paragraph('Data 12'); ...
      Paragraph('data 21'),Paragraph('Data 22')};
 
ca{1,1}.Children(1).Bold = true;
ca{1,2}.Children(1).Bold = true;
 
for r = 1:2
    for c = 1:2
        ca{r, c}.Style = {KeepLinesTogether,KeepWithNext};
    end
end
 
for c = 1:2
    ca{3, c}.Style = {KeepLinesTogether};
end
 
 append(rpt, ca);
 
close(rpt);
rptview(rpt.OutputPath);

Format a Table Using Microsoft Word Style Sheets

You can format tables using an existing Word style in a template or a template style that you modify or add.

To define a table style in a Word template, start by using these steps.

  1. Open the Word template used with the report.

  2. Open the Styles pane.

  3. Click the Manage Styles button .

  4. Click New Style.

  5. In the Create New Style from Formatting dialog box, set Style type to Table.

For more information about using Word styles with DOM objects, see Modify Styles in a Microsoft Word Template.

Format an HTML or PDF Table Using a Style Sheet

You can format HTML and PDF tables using a CSS style defined in a template.

To define a table style in an HTML or PDF template, use a selector on a table style. For example:

table.MyTable {
  border-style: solid;
  border-bottom-color: rgb(128, 128, 128);
  border-bottom-width: thin;
  border-collapse: collapse;
}

Tip

Use the CSS child selector (>) to specify the format of the children of a table. For example, this CSS code specifies the format of the table entries (td elements) of a table whose style is MyTable.

table.MyTable > tbody > tr > td { 
      font-family: Arial, Helvetica, sans-serif; 
      font-size: 11pt; 
      text-align: center; 
   }

Apply a Style to a Table

Once you have defined a table style in a template, you can apply it to a Table object in your report program either as the second argument in the Table object constructor or by setting it to the StyleName property of the Table object. For example, suppose that you defined styles named BodyPara, TableTitle, and RuledTable in the template for your report. This example specifies style names in a Paragraph constructor, in the StyleName property of a Paragraph object, and in a Table constructor.

import mlreportgen.dom.*;
rank = 5;
rpt = Document('MyReport','html','MyTemplate');

p = Paragraph('Here is a magic square or rank 5:','BodyPara');
append(rpt,p);

p = Paragraph(sprintf('Rank %d MagicSquare',rank));
p.StyleName = 'TableTitle';

append(rpt,Table(magic(rank),'RuledTable'));

close(rpt);
rptview(rpt.OutputPath);

You can use programmatic formats to override the styles defined in a template-based table style. For example, suppose that you define a table style named UnruledTable in your template to create tables without any borders or column or row separators. You can then override the style in your report program to draw a frame around a table.

import mlreportgen.dom.*;
rpt = Document('MyReport','html','MyTemplate');

table = Table(magic(5),'UnruledTable');
table.Border = 'single';
append(rpt,table);

close(rpt);
rptview(rpt.OutputPath);

Create a Formal Table

To create a formal table, use the same basic approaches as with an informal table, except that you use an mlreportgen.domlFormalTable constructor to construct a formal table. The constructor optionally accepts a two-dimensional numeric array or a cell array of MATLAB data for the body, header, and footer sections.

If you build a formal table completely or partially from scratch, you can use the FormalTable object functions appendHeaderRow and appendBodyRow to append rows to the table header and footer sections. The FormalTable.append function appends a row to the body section. Alternatively, you can access a section using the Header, Body, or Footer properties of the FormalTable object.

import mlreportgen.dom.*
d = Document('test');

t = FormalTable({'a','b';'c','d'});

r = TableRow();
append(r,TableEntry('Column 1'));
append(r,TableEntry('Column 2'));
append(t.Header,r);

append(d,t);

close(d);
rptview(d.OutputPath);

Format a Formal Table

You can format a formal table programmatically, using DOM format objects or format properties. You can also use template styles. For information about these formatting techniques and format inheritance, see Report Formatting Approaches.

Format a Formal Table Programmatically

You can format a formal table programmatically the same way you format an informal table. The format objects and properties that apply to an informal table also apply to formal tables. In addition, you can format the header, body, and footer sections of an informal table programmatically. If you specify a format for the table and one of its sections, the value you specify for the section overrides the value you specify for the table as a whole. Not all formal table formats apply to formal table sections. For example, you cannot indent a header, body, or footer section independently of the containing table. In other words, the OuterLeftMargin property does not apply to formal table sections.

Apply Table Styles to a Formal Table and Its Sections

Use the same procedure for defining formal table styles in templates as you use for defining informal table styles.

You can apply a table style to a formal table and to each of its sections. If you apply a table style to the table itself and to one of its sections (for example, the header), the section style overrides the table style.

Note

If you apply a table style to one or more sections of a Word formal table, specify the widths of each of the table columns. Otherwise, the columns of the sections might not line up.

Create and Format Table Rows

If you want to build a table from scratch, you can use the TableRow constructor to create the rows. Format the rows and then append the rows to a table that you are building.

Create a Table Row

The mlreportgen.dom.TableRow constructor takes no arguments and returns a TableRow object. You can then create and append TableEntry objects to the object to complete the row construction. Once you construct the row, you can add the row to the table, using the append function. This example creates a two-column table with two rows.

import mlreportgen.dom.*
rpt = Document('test');

table = Table(2); 
 
row = TableRow();
append(row,TableEntry('Col1'));
append(row,TableEntry('Col2'));
append(table,row);
 
row = TableRow();
append(row,TableEntry('data11'));
append(row,TableEntry('data12'));
append(table,row);
 
append(rpt,table);

close(rpt);
rptview(rpt.OutputPath);

Format a Table Row

Use these format objects and format properties to format a table row.

Row Height FormattingFormat ObjectFormat Property

Specify the exact height of a row

RowHeight

Height

Specify the minimum height of row (Word only)

RowHeight

n/a

Cause this row to repeat as header row when a table flows across pages

RepeatAsHeaderRow

n/a

Allow this row to straddle a page boundary

AllowBreakAcrossPages

n/a

Format Table Columns

To format table columns, you can use mlreportgen.dom.TableColSpecGroup objects, either alone or with mlreportgen.dom.TableColSpecGroup objects. Use a TableColSpecGroup object to specify the format of a group of adjacent table columns. Use a TableColSpec object to override, for some table columns, some or all the formats of a column group. In this example, the TableColSpecGroup property specifies a column width of 0.2 inches and green text. The TableColSpec overrides those formats for the first column, specifying a width of 0.5 inches and bold, red text.

import mlreportgen.dom.*
rpt = Document('test');

rank = 5;
table = Table(magic(rank));
table.Border = 'single';
table.BorderWidth = '1px';

grps(1) = TableColSpecGroup;
grps(1).Span = rank;
grps(1).Style = {Width('0.2in'),Color('green')};

specs(1) = TableColSpec;
specs(1).Span = 1;
specs(1).Style = {Width('0.5in'),Bold,Color('red')};

grps(1).ColSpecs = specs;

table.ColSpecGroups = grps;
append(rpt,table);

close(rpt);
rptview(rpt.OutputPath);

To resize columns to fit the widest content of the table entries in a column, include a ResizeToFitContents object in the Style property of the table.

Create and Format Table Entries

If you need to build a table from scratch, you can use the mlreportgen.dom.TableEntry constructor to create table entries. You can then format the table entries and add them to table rows, which you can then add to the table you are building. If you need to format entries in a table that you have created from a cell array, you can use the TableEntry or TableRow function entry to gain access to an entry, which you can then format.

Create a Table Entry

Use a TableEntry constructor to create a table entry. You can optionally use the constructor to specify these kinds of entry content:

  • Char array

  • Any of these kinds of DOM objects:

    • Paragraph

    • Text

    • Image

    • Table

    • OrderedList

    • UnorderedList

    • CustomElement

Format Table Entries Programmatically

You can use format objects or TableEntry format properties to format a table entry programmatically.

Formatting Format ObjectFormat Property

Create border around entry

Border

Border

Color of border

Border

BorderColor

Thickness of border

Border

BorderWidth

Create left, right, top, or bottom entry border

Border

n/a

Align entry content top, bottom, middle

VAlign

VAlign

Space between entry boundary and entry content

InnerMargin

InnerMargin

Space between entry content and its top, bottom, right, or left boundaries

InnerMargin

n/a

Cause entry to span multiple columns

ColSpan

ColSpan

Cause entry to span multiple rows

RowSpan

RowSpan

You can specify formatting for all table entries in a table, use the TableEntriesStyle property of the Table or FormalTable object. For example, you can set border formatting.

import mlreportgen.dom.*
t = Table(magic(5));
t.TableEntriesStyle = {Border('solid','black','1px')};

Properties you set for a TableEntry object take precedence over TableEntriesStyle format objects.

Format Table Entries Using Style Sheets

For HTML reports, you can use styles defined in an HTML template style sheet to format table entries. When defining a table entry style, use a td element selector. For example:

td.TableEntryWithBorder {
  border:5px solid red;
}

To apply a template-defined style to a table entry, set the TableEntry object StyleName property to the name of the style or specify the style name as the second argument to the TableEntry constructor. For example:

te = TableEntry('Hello World','TableEntryWithBorder');

See Also

Classes

Functions

Related Examples

More About

MATLAB Report Generator Documentation
Support

Try MATLAB, Simulink, and Other Products

Get trial now