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:

• Create a Table from a Two-Dimensional Array

• Create a Table Using the Table entry Function

• Create a Table from Scratch

• Format a Table

For details about formal tables, see:

• Create a Formal Table

• Format a Formal Table

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 Object	Format 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.

Formatting	Table 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 Formatting	Format Object	Format 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 Object	Format 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');