<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).
@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.See appendix for information about this element in OASIS document type shells.
- topic/table
<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.
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.
<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><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".@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:
| Name | points | |
|---|---|---|
| expected | actual | |
| Mark | 10,000 | 11,123.45 |
| Peter | 9,000 | 11,012.34 |
| Cindy | 10,000 | 10,987.64 |
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:
| Name | Mark | Peter | Cindy | |
|---|---|---|---|---|
| points | expected | 10,000 | 9,000 | 10,000 |
| 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>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.
<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:
| points | ||
|---|---|---|
| expected | actual | |
| Mark | 10,000 | 11,123.45 |
| Peter | 9,000 | 11,012.34 |
| Cindy | 10,000 | 10,987.64 |
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.
@orientIn 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.
@pgwideFor 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.