Create Formal Tables

A DOM API formal table has header, body, and footer sections. A formal table is useful when a header or footer has multiple rows. The separate header, body, and footer sections facilitate adding rows to and formatting the header, body, or footer independently of the other sections. For information about other types of tables that you can create in reports, see Choose Type of Table to Create. For information about formatting tables, see Format Tables.

A formal table is represented by an mlreportgen.dom.FormalTable object. The header, body, and footer sections are represented by mlreportgen.dom.TableHeader, mlreportgen.dom.TableBody, and mlreportgen.dom.TableFooter objects, respectively. Each section has rows and table entries. The rows are represented by mlreportgen.dom.TableRow objects. Entries in the body and footer sections are represented by mlreportgen.dom.TableEntry objects. Entries in the header are represented by mlreportgen.dom.TableHeaderEntry or mlreportgen.dom.TableEntry objects.

You can create the sections of a formal table from a MATLAB^® array. This approach is the simplest because you do not have to create TableRow and TableEntry or TableHeaderEntry objects. You can also create the sections by building the table from TableRow and TableEntry or TableHeaderEntry objects. This approach is useful for complex formatting requirements, such as an when an entry spans multiple columns or rows. You can combine the approaches. For example, you can create the table body from an array and build the header from rows and entries.

Create Formal Tables from MATLAB Arrays

Create a formal table by using the mlreportgen.dom.FormalTable constructor. The constructor optionally accepts a two-dimensional array or a cell array of MATLAB data for the body, header, and footer sections. See the header, body, and footer arguments on the mlreportgen.dom.FormalTable reference page. For an example that creates a formal table header from a string array and a formal table body from a cell array, see Create a Table from a Cell Array.

Create Formal Tables from Rows and Entries

You can build the header, body, or footer sections of a formal table by appending table entries to table rows and appending the rows to the sections.

To create a header entry, you can use an mlreportgen.dom.TableHeaderEntry or mlreportgen.dom.TableEntry object. If you create a header from an array, the DOM API creates the entries as TableHeaderEntry objects. In an HTML report, the DOM API renders a TableHeaderEntry object as a th (table header cell) element. This rendering relies on the browser to format the table entry. For Word and PDF reports, by default, the DOM API renders the TableHeaderEntry object as an unformatted Word or PDF table entry element. You can use the TableHeaderEntry object properties to format the table entries generated for all output types. For example, you can use these properties to override browser formatting in HTML reports.

To build a section of a formal table from table rows and entries, you can use the FormalTable appendHeaderRow, append, and appendFooterRow methods to append rows to the table header, body, or footer sections. Alternatively, you can access a section by using the Header, Body, or Footer properties of the FormalTable object and then append rows to the section by using the append method.

For an example that builds a header from entries and rows, see Formal Table in Span a Table Entry Across Rows and Columns.