L.1.5.4 Table Rows and Cells

A table row is defined using a tr element, which is analogous to the HTML tag. The tr element acts as a container for a row of cells with the table’s content.

A tr element has one formatting child element, trPr, which defines the row properties (such as the row’s width) and whether it can split across a page. Each property is defined by an individual child element under the trPr element. The complete set of table row properties can be found on the definition for the trPr element. As well, a table row can contain two kinds of content: custom markup (custom XML or structured document tags), and table cells.

The cells in a row contain the table’s content and are defined by tc elements, which are analogous to HTML tags.

A tc element has one formatting child element, tcPr, which defines the properties for the cell. Each unique property is specified by a child element of this element. The complete set of table cell properties can be found on the definition for the tcPr element. As well, a table cell can contain any valid block-level content, as defined by the WordprocessingML schema, which allows for the nesting of paragraphs and tables within table cells.

In the example below, the tcW element defines the width of the cell, where the attribute w is the value in twips. Here the width of the cell is 8,856 units, where units are defined by the attribute type. In this case, dxa represents twips.

<w:tr>
  <w:tc>
    <w:tcPr>
      <w:tcW w:w="8856" w:type="dxa"/>
    </w:tcPr>
    <w:p/>
  </w:tc>
</w:tr>

The tc element contains the cell’s content, which, in this case, is an empty p element.

Consider a table having one cell, which contains the text “Hello, world”:

Hello, world

This table’s content is represented by the following XML:

<w:tr>
  <w:tc>
    <w:tcPr>
      <w:tcW w:w="1770" w:type="dxa"/>
    </w:tcPr>
    <w:p>
      <w:r>
        <w:t>Hello, world</w:t>
      </w:r>
    </w:p>
  </w:tc>
</w:tr>

At both the row and cell levels, the properties must also specify how the rows and cells are placed on the table grid.

The trPr element contains information about the number of grid units which should be omitted (‘skipped’) before and after the row is complete using the gridBefore and gridAfter elements, allowing rows to start at different columns on the grid, as well as a preferred width for that leading/trailing space using the wBefore and wAfter elements. The tcPr element also contains grid information pertaining to how many grids a cell spans using the gridSpan element, which determines how many grid units are consumed by the current cell, as well as a preferred width for that cell using the tcW element.

In the earlier complex table having two rows of two differently sized cells, a consumer must represent that table containing three grid columns (one per distinct vertical line). Consider the following XML for the first row of that table:

<w:tr>
  <w:tc>
    <w:tcPr>
      <w:tcW w:w="7368" w:type="dxa" />
      <w:gridSpan w:val="2" />
    </w:tcPr>
    <w:p />
  </w:tc>
  <w:tc>
    <w:tcPr>
      <w:tcW w:w="1488" w:type="dxa" />
    </w:tcPr>
    <w:p/>
  </w:tc>
</w:tr>

Again, the gridSpan element is the number of grid columns that cell spans when being laid out on the table grid. In this example, the first cell of the first row contains two grid columns. As well, the cell specifies its preferred width using the tcW element, which tells the consumer the width desired by that cell at layout time.

It is important to note that every width in a table is a preferred width - because the table must satisfy the grid at all times, conflicting table properties must be resolved by overriding preferred widths in a specific manner, shown below.