<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.Content models
See appendix for information about this element in OASIS document type shells.
Inheritance
- topic/table
Example
<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.
<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>
- 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:
Name | points | |
---|---|---|
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:
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>
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.
<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 |
Attributes
The following attributes are available on this element: Universal attribute group, outputclass,
@display
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.