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:
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);
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);
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);
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.
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 |
|
|
Color of table background |
|
|
Create border around table |
|
|
Color of border |
|
|
Thickness of border |
|
|
Create left, right, top, or bottom table border |
| n/a |
Collapse table and table entry borders (HTML) |
|
|
Create column separator |
|
|
Column separator color |
|
|
Column separator thickness |
|
|
Create row separator |
|
|
Row separator color |
|
|
Row separator thickness |
|
|
Indent table from left margin |
|
|
Space before or after table |
| n/a |
Space to right of table |
| n/a |
Align table left, right, or center |
|
|
Specify table entry flow direction (left-to-right or right-to-left) |
|
|
Resize table columns to fit contents |
| n/a |
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) |
|
Align entries horizontally (left, right, center) |
|
Create space (padding) between entry boundary and content |
|
Apply a set of format objects to all table entries |
|
You can use a mlreportgen.dom.TextOrientation
format object to make the text in a table entry vertical or horizontal.
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);
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.
Open the Word template used with the report.
Open the Styles pane.
Click the Manage Styles button .
Click New Style.
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.
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; }
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; }
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);
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);
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.
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.
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.
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.
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.
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);
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 |
|
|
Specify the minimum height of row (Word only) |
| n/a |
Cause this row to repeat as header row when a table flows across pages |
| n/a |
Allow this row to straddle a page boundary |
| n/a |
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.
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.
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
You can use format objects or TableEntry
format properties
to format a table entry programmatically.
Formatting | Format Object | Format Property |
---|---|---|
Create border around entry |
|
|
Color of border |
|
|
Thickness of border |
|
|
Create left, right, top, or bottom entry border |
| n/a |
Align entry content top, bottom, middle |
|
|
Space between entry boundary and entry content |
|
|
Space between entry content and its top, bottom, right, or left boundaries |
| n/a |
Cause entry to span multiple columns |
|
|
Cause entry to span multiple rows |
|
|
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.
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');
mlreportgen.dom.AllowBreakAcrossPages
| mlreportgen.dom.ColSep
| mlreportgen.dom.FlowDirection
| mlreportgen.dom.FormalTable
| mlreportgen.dom.RepeatAsHeaderRow
| mlreportgen.dom.ResizeToFitContents
| mlreportgen.dom.RowHeight
| mlreportgen.dom.RowSep
| mlreportgen.dom.Table
| mlreportgen.dom.TableBody
| mlreportgen.dom.TableColSpec
| mlreportgen.dom.TableColSpecGroup
| mlreportgen.dom.TableEntry
| mlreportgen.dom.TableFooter
| mlreportgen.dom.TableHeader
| mlreportgen.dom.TableHeaderEntry
| mlreportgen.dom.TableRow