`<table>`

The <table> element organizes arbitrarily complex relationships of tabular information. This standard table markup allows column or row spanning and table captions or descriptions. An optional title allowed inside the <table> element provides a caption to describe the table.

The DITA table is based on the OASIS Exchange Table Model, augmented with DITA attributes that enable it for accessibility, specialization, conref, and other DITA processing. In addition, the table includes a <desc> element, which enables table description that is parallel with figure description. See simpletable for a simplified table model that can be specialized to represent more regular relationships of data.

In DITA tables, in place of the @expanse attribute used by other DITA elements, the @pgwide attribute is used in order to conform to the OASIS Exchange Table Model. The @pgwide attribute has a similar semantic (1=page width; 0=resize to galley or column).

Note: The @scale attribute represents a stylistic markup property that is currently maintained in tables for legacy purposes. External stylesheets should enable less dependency on this attribute. Use the @scale attribute judiciously.

Content models

See appendix for information about this element in OASIS document type shells.

Inheritance

- topic/table

Example

Figure 1. DITA source

<table>
<tgroup cols="2">
<colspec colname="COLSPEC0" colwidth="121*"/>
<colspec colname="COLSPEC1" colwidth="76*"/>
<thead>
<row>
<entry colname="COLSPEC0" valign="top">Animal</entry>
<entry colname="COLSPEC1" valign="top">Gestation</entry>
</row>
</thead>
<tbody>
<row>
<entry>Elephant (African and Asian)</entry>
<entry>19-22 months</entry>
</row>
<row>
<entry>Giraffe</entry>
<entry>15 months</entry>
</row>
<row>
<entry>Rhinoceros</entry>
<entry>14-16 months</entry>
</row>
<row>
<entry>Hippopotamus</entry>
<entry>7 1/2 months</entry>
</row>
</tbody>
</tgroup>
</table>

The formatted output might be displayed as follows:


Animal	Gestation
Elephant (African and Asian)	19-22 months
Giraffe	15 months
Rhinoceros	14-16 months
Hippopotamus	7 1/2 months

In this example, the use of the <thead> element for the header allows processors or screen readers to identify a header relationship between any cell in the table body and the matching header cell above that column.

Example: Complex table with implied accessibility markup

In the following example, the table uses <thead> to identify header rows and @rowheader to identify a header column. This header relationship can be used to automatically create renderings of the table in other formats, such as HTML, that can be navigated using a screen reader or other assistive technology.

Figure 2. DITA source

<table frame="all" rowheader="firstcol">
  <title>Sample of automated table accessibility</title>
<desc>Names are listed in the column c1. Points are listed in both data columns, with
expected points in column c2 and actual points in column c3.</desc>
  <tgroup cols="3">
    <colspec colname="c1"/>
    <colspec colname="c2"/>
    <colspec colname="c3"/>
    <thead>
      <row>
        <entry morerows="1">Name</entry>
        <entry namest="c2" nameend="c3">points</entry>
      </row>
      <row>
        <entry>expected</entry>
        <entry>actual</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>Mark</entry>
        <entry>10,000</entry>
        <entry>11,123.45</entry>
      </row>
      <row>
        <entry>Peter</entry>
        <entry>9,000</entry>
        <entry>11,012.34</entry>
      </row>
      <row>
        <entry>Cindy</entry>
        <entry>10,000</entry>
        <entry>10,987.64</entry>
      </row>
     </tbody>
   </tgroup>
</table>

In this sample, navigation information for assistive technology is derived from two sources:

The <thead> element contains two rows, and indicates that each <entry> in those rows is a header cell for that column. This means that each body cell can be associated with the header cell or cells above the column. For example, in the second body row, the entry "Peter" can be associated with the header "Name"; similarly, the entry "9,000" can be associated with the headers "expected" and "points".
The @rowheader attribute implies that the first column plays a similar roll as a header. This means that each body cell in columns two and three can be associated with the header cell in column one. For example, in the second body row, the entry "9,000" can be associated with the header "Peter".

As a result of these two sets of headers, a rendering of the table can associate the entry "9,000" with three headers: "Peter", "expected", and "points", making it fully navigable by a screen reader or other assistive technology.

The formatted output might be displayed as follows:

Table 1. Sample of automated table accessibilityNames are listed in the column c1. Points are listed in both data columns, with expected points in column c2 and actual points in column c3.
Name	points
Name	expected	actual
Mark	10,000	11,123.45
Peter	9,000	11,012.34
Cindy	10,000	10,987.64

Complex table with some manually specified accessibility markup

In some complex tables, the <thead> element and @rowheader attribute might not be enough to support all accessibility needs. Assume that the table above is flipped so that the names are listed across the top row, instead of in the first column, as follows:

Table 2. Sample with two header columns
Name		Mark	Peter	Cindy
points	expected	10,000	9,000	10,000
points	actual	11,123.45	11,012.34	10,987.64

In this case the @rowheader attribute cannot be used, because it is only able to specify the first column as a header column. In this case, the @scope attribute can be used to indicate that entries in the first and second columns function as headers for the entire row (or row group, in the case of a cell that spans more than one row). The following code sample demonstrates the use of @scope to facilitate navigation of these rows by a screen reader or other assistive technology; note that the <thead> element is still used to imply a header relationship with the names at the top of each column.

<table frame="all">
 <title>Sample with two header columns</title>
 <tgroup cols="5">
  <colspec colname="c1"/>
  <colspec colname="c2"/>
  <colspec colname="c3"/>
  <colspec colname="c4"/>
  <colspec colname="c5"/>
  <thead>
   <row>
    <entry namest="c1" nameend="c2">Name</entry>
    <entry>Mark</entry>
    <entry>Peter</entry>
    <entry>Cindy</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry morerows="1" scope="rowgroup"><b>points</b></entry>
    <entry scope="row"><b>expected</b></entry>
    <entry>10,000</entry>
    <entry>9,000</entry>
    <entry>10,000</entry>
   </row>
   <row>
    <entry scope="row"><b>actual</b></entry>
    <entry>11,123.45</entry>
    <entry>11,012.34</entry>
    <entry>10,987.64</entry>
   </row>
  </tbody>
 </tgroup>
</table>

Example: complex table with manual accessibility markup

In extremely complex tables, such as those with a single header cell in the middle of the table, extremely fine grained accessibility controls are available to explicitly associate any content cell with any header cell. This might also be useful for cases where processors do not support the implied accessibility relationships described above.

In the following sample, header cells are identified using the @id attribute, which is referenced using the @headers attribute on appropriate content cells. This makes all header relationships in the table explicit. Note that this sample ignores the @scope attribute, which could be used to exercise manual control without setting as many attribute values; it also ignores the fact that <thead> creates a header relationship even when the @id and @headers attributes are not used.

Figure 3. DITA source

<table frame="all">
  <title>Sample with fully manual accessibility control</title>
<desc>Names are listed in the column c1. Points are listed in both data columns, with
expected points in column c2 and actual points in column c3.</desc>
  <tgroup cols="3">
    <colspec colname="c1"/>
    <colspec colname="c2"/>
    <colspec colname="c3"/>
    <thead>
      <row>
        <entry morerows="1"> </entry>
        <entry namest="c2" nameend="c3" id="pts">points</entry>
      </row>
      <row>
        <entry id="exp" headers="pts">expected</entry>
        <entry id="act" headers="pts">actual</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry id="name1">Mark</entry>
        <entry headers="name1 exp pts">10,000</entry>
        <entry headers="name1 act pts">11,123.45</entry>
      </row>
      <row>
        <entry id="name2">Peter</entry>
        <entry headers="name2 exp pts">9,000</entry>
        <entry headers="name2 act pts">11,012.34</entry>
      </row>
      <row>
        <entry id="name3">Cindy</entry>
        <entry headers="name3 exp pts">10,000</entry>
        <entry headers="name3 act pts">10,987.64</entry>
      </row>
     </tbody>
   </tgroup>
</table>

The formatted output might be displayed as follows:

Table 3. Sample with fully manual accessibility controlNames are listed in the column c1. Points are listed in both data columns, with expected points in column c2 and actual points in column c3.
	points
	expected	actual
Mark	10,000	11,123.45
Peter	9,000	11,012.34
Cindy	10,000	10,987.64

Attributes

The following attributes are available on this element: Universal attribute group, outputclass, @frame and @scale from Display attribute group, and the attributes defined below. This element also uses @colsep, @rowsep, and @rowheader from Complex-table attribute group.

@orient

Specifies the orientation of the table in page-based outputs. This attribute is primarily useful for print-oriented display. Allowable values are:

port: The same orientation as the text flow.
land: 90 degrees counterclockwise from the text flow.
-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

In situations where a stylesheet or other formatting mechanism specifies table orientation based on other criteria, or for non-paginated outputs, the @orient attribute can be ignored.

@pgwide

Determines the horizontal placement of the element. Supported values are 1 and 0, although these are not mandated by the DTD, Schema, or RNG.

For print-oriented display, the value "1" places the element on the left page margin; "0" aligns the element with the left margin of the current text line and takes indention into account.