4.9.9. The td element

The td element and its colspan, rowspan, and headers attributes take part in the table model.

User agents, especially in non-visual environments or where displaying the table as a 2D grid is impractical, may give the user context for the cell when rendering the contents of a cell; for instance, giving its position in the table model, or listing the cell's header cells (as determined by the algorithm for assigning header cells). When a cell's header cells are being listed, user agents may use the value of abbr attributes on those header cells, if any, instead of the contents of the header cells themselves.

The th element and its colspan, rowspan, headers, and scope attributes take part in the table model.

The scope IDL attribute must reflect the content attribute of the same name, limited to only known values.

The abbr IDL attribute must reflect the content attribute of the same name.

The colspan, rowspan, and headers attributes take part in the table model.

The colSpan IDL attribute must reflect the colspan content attribute. Its default value is 1.

The rowSpan IDL attribute must reflect the rowspan content attribute. Its default value is 1.

The headers IDL attribute must reflect the content attribute of the same name.

The cellIndex IDL attribute must, if the element has a parent tr element, return the index of the cell's element in the parent element's cells collection. If there is no such parent element, then the attribute must return −1.

4.9.12 Processing model

The various table elements and their content attributes together define the table model.

A table consists of cells aligned on a two-dimensional grid of slots with coordinates (x, y). The grid is finite, and is either empty or has one or more slots. If the grid has one or more slots, then the x coordinates are always in the range 0 ≤ x < x_width, and the y coordinates are always in the range 0 ≤ y < y_height. If one or both of x_width and y_height are zero, then the table is empty (has no slots). Tables correspond to table elements.

A cell is a set of slots anchored at a slot (cell_x, cell_y), and with a particular width and height such that the cell covers all the slots with coordinates (x, y) where cell_x ≤ x < cell_x+width and cell_y ≤ y < cell_y+height. Cells can either be data cells or header cells. Data cells correspond to td elements, and header cells correspond to th elements. Cells of both types can have zero or more associated header cells.

It is possible, in certain error cases, for two cells to occupy the same slot.

A row is a complete set of slots from x=0 to x=x_width-1, for a particular value of y. Rows correspond to tr elements.

A column is a complete set of slots from y=0 to y=y_height-1, for a particular value of x. Columns can correspond to col elements. In the absence of col elements, columns are implied.

A row group is a set of rows anchored at a slot (0, group_y) with a particular height such that the row group covers all the slots with coordinates (x, y) where 0 ≤ x < x_width and group_y ≤ y < group_y+height. Row groups correspond to tbody, thead, and tfoot elements. Not every row is necessarily in a row group.

A column group is a set of columns anchored at a slot (group_x, 0) with a particular width such that the column group covers all the slots with coordinates (x, y) where group_x ≤ x < group_x+width and 0 ≤ y < y_height. Column groups correspond to colgroup elements. Not every column is necessarily in a column group.

Row groups cannot overlap each other. Similarly, column groups cannot overlap each other.

A cell cannot cover slots that are from two or more row groups. It is, however, possible for a cell to be in multiple column groups. All the slots that form part of one cell are part of zero or one row groups and zero or more column groups.

In addition to cells, columns, rows, row groups, and column groups, tables can have a caption element associated with them. This gives the table a heading, or legend.

A table model error is an error with the data represented by table elements and their descendants. Documents must not have table model errors.

4.9.12.1 Forming a table

To determine which elements correspond to which slots in a table associated with a table element, to determine the dimensions of the table (x_width and y_height), and to determine if there are any table model errors, user agents must use the following algorithm:

1. Let x_width be zero.

2. Let y_height be zero.

3. Let pending tfoot elements be a list of tfoot elements, initially empty.

4. Let the table be the table represented by the table element. The x_width and y_height variables give the table's dimensions. The table is initially empty.

5. If the table element has no children elements, then return the table (which will be empty), and abort these steps.

6. Associate the first caption element child of the table element with the table. If there are no such children, then it has no associated caption element.

7. Let the current element be the first element child of the table element.

   If a step in this algorithm ever requires the current element to be advanced to the next child of the table when there is no such next child, then the user agent must jump to the step labeled end, near the end of this algorithm.

8. While the current element is not one of the following elements, advance the current element to the next child of the table:

   • colgroup
   • thead
   • tbody
   • tfoot
   • tr

9. If the current element is a colgroup, follow these substeps:

   1. Column groups: Process the current element according to the appropriate case below:

      If the current element has any col element children

      Follow these steps:

      1. Let x_start have the value of x_width.

      2. Let the current column be the first col element child of the colgroup element.

      3. Columns: If the current column col element has a span attribute, then parse its value using the rules for parsing non-negative integers.

         If the result of parsing the value is not an error or zero, then let span be that value.

         Otherwise, if the col element has no span attribute, or if trying to parse the attribute's value resulted in an error or zero, then let span be 1.

      4. Increase x_width by span.

      5. Let the last span columns in the table correspond to the current column col element.

      6. If current column is not the last col element child of the colgroup element, then let the current column be the next col element child of the colgroup element, and return to the step labeled columns.

      7. Let all the last columns in the table from x=x_start to x=x_width-1 form a new column group, anchored at the slot (x_start, 0), with width x_width-x_start, corresponding to the colgroup element.

      If the current element has no col element children

      1. If the colgroup element has a span attribute, then parse its value using the rules for parsing non-negative integers.

         If the result of parsing the value is not an error or zero, then let span be that value.

         Otherwise, if the colgroup element has no span attribute, or if trying to parse the attribute's value resulted in an error or zero, then let span be 1.

      2. Increase x_width by span.

      3. Let the last span columns in the table form a new column group, anchored at the slot (x_width-span, 0), with width span, corresponding to the colgroup element.

   2. Advance the current element to the next child of the table.

   3. While the current element is not one of the following elements, advance the current element to the next child of the table:

      • colgroup
      • thead
      • tbody
      • tfoot
      • tr

   4. If the current element is a colgroup element, jump to the step labeled column groups above.

10. Let y_current be zero.

11. Let the list of downward-growing cells be an empty list.

12. Rows: While the current element is not one of the following elements, advance the current element to the next child of the table:

    • thead
    • tbody
    • tfoot
    • tr

13. If the current element is a tr, then run the algorithm for processing rows, advance the current element to the next child of the table, and return to the step labeled rows.

14. Run the algorithm for ending a row group.

15. If the current element is a tfoot, then add that element to the list of pending tfoot elements, advance the current element to the next child of the table, and return to the step labeled rows.

16. The current element is either a thead or a tbody.

    Run the algorithm for processing row groups.

17. Advance the current element to the next child of the table.

18. Return to the step labeled rows.

19. End: For each tfoot element in the list of pending tfoot elements, in tree order, run the algorithm for processing row groups.

20. If there exists a row or column in the table containing only slots that do not have a cell anchored to them, then this is a table model error.

21. Return the table.

The algorithm for processing row groups, which is invoked by the set of steps above for processing thead, tbody, and tfoot elements, is:

1. Let y_start have the value of y_height.

2. For each tr element that is a child of the element being processed, in tree order, run the algorithm for processing rows.

3. If y_height > y_start, then let all the last rows in the table from y=y_start to y=y_height-1 form a new row group, anchored at the slot with coordinate (0, y_start), with height y_height-y_start, corresponding to the element being processed.

4. Run the algorithm for ending a row group.

The algorithm for ending a row group, which is invoked by the set of steps above when starting and ending a block of rows, is:

1. While y_current is less than y_height, follow these steps:

   1. Run the algorithm for growing downward-growing cells.

   2. Increase y_current by 1.

2. Empty the list of downward-growing cells.

The algorithm for processing rows, which is invoked by the set of steps above for processing tr elements, is:

1. If y_height is equal to y_current, then increase y_height by 1. (y_current is never greater than y_height.)

2. Let x_current be 0.

3. Run the algorithm for growing downward-growing cells.

4. If the tr element being processed has no td or th element children, then increase y_current by 1, abort this set of steps, and return to the algorithm above.

5. Let current cell be the first td or th element in the tr element being processed.

6. Cells: While x_current is less than x_width and the slot with coordinate (x_current, y_current) already has a cell assigned to it, increase x_current by 1.

7. If x_current is equal to x_width, increase x_width by 1. (x_current is never greater than x_width.)

8. If the current cell has a colspan attribute, then parse that attribute's value, and let colspan be the result.

   If parsing that value failed, or returned zero, or if the attribute is absent, then let colspan be 1, instead.

9. If the current cell has a rowspan attribute, then parse that attribute's value, and let rowspan be the result.

   If parsing that value failed or if the attribute is absent, then let rowspan be 1, instead.

10. If rowspan is zero, then let cell grows downward be true, and set rowspan to 1. Otherwise, let cell grows downward be false.

11. If x_width < x_current+colspan, then let x_width be x_current+colspan.

12. If y_height < y_current+rowspan, then let y_height be y_current+rowspan.

13. Let the slots with coordinates (x, y) such that x_current ≤ x < x_current+colspan and y_current ≤ y < y_current+rowspan be covered by a new cell c, anchored at (x_current, y_current), which has width colspan and height rowspan, corresponding to the current cell element.

    If the current cell element is a th element, let this new cell c be a header cell; otherwise, let it be a data cell.

    To establish which header cells apply to the current cell element, use the algorithm for assigning header cells described in the next section.

    If any of the slots involved already had a cell covering them, then this is a table model error. Those slots now have two cells overlapping.

14. If cell grows downward is true, then add the tuple {c, x_current, colspan} to the list of downward-growing cells.

15. Increase x_current by colspan.

16. If current cell is the last td or th element in the tr element being processed, then increase y_current by 1, abort this set of steps, and return to the algorithm above.

17. Let current cell be the next td or th element in the tr element being processed.

18. Return to the step labelled cells.

When the algorithms above require the user agent to run the algorithm for growing downward-growing cells, the user agent must, for each {cell, cell_x, width} tuple in the list of downward-growing cells, if any, extend the cell cell so that it also covers the slots with coordinates (x, y_current), where cell_x ≤ x < cell_x+width.

4.9.12.2 Forming relationships between data cells and header cells

Each cell can be assigned zero or more header cells. The algorithm for assigning header cells to a cell principal cell is as follows.

1. Let header list be an empty list of cells.

2. Let (principal_x, principal_y) be the coordinate of the slot to which the principal cell is anchored.

3. If the principal cell has a headers attribute specified

   1. Take the value of the principal cell's headers attribute and split it on spaces, letting id list be the list of tokens obtained.

   2. For each token in the id list, if the first element in the Document with an ID equal to the token is a cell in the same table, and that cell is not the principal cell, then add that cell to header list.

   If principal cell does not have a headers attribute specified

   1. Let principal_width be the width of the principal cell.

   2. Let principal_height be the height of the principal cell.

   3. For each value of y from principal_y to principal_y+principal_height-1, run the internal algorithm for scanning and assigning header cells, with the principal cell, the header list, the initial coordinate (principal_x,y), and the increments Δx=−1 and Δy=0.

   4. For each value of x from principal_x to principal_x+principal_width-1, run the internal algorithm for scanning and assigning header cells, with the principal cell, the header list, the initial coordinate (x,principal_y), and the increments Δx=0 and Δy=−1.

   5. If the principal cell is anchored in a row group, then add all header cells that are row group headers and are anchored in the same row group with an x-coordinate less than or equal to principal_x+principal_width-1 and a y-coordinate less than or equal to principal_y+principal_height-1 to header list.

   6. If the principal cell is anchored in a column group, then add all header cells that are column group headers and are anchored in the same column group with an x-coordinate less than or equal to principal_x+principal_width-1 and a y-coordinate less than or equal to principal_y+principal_height-1 to header list.

4. Remove all the empty cells from the header list.

5. Remove any duplicates from the header list.

6. Remove principal cell from the header list if it is there.

7. Assign the headers in the header list to the principal cell.

The internal algorithm for scanning and assigning header cells, given a principal cell, a header list, an initial coordinate (initial_x, initial_y), and Δx and Δy increments, is as follows:

1. Let x equal initial_x.

2. Let y equal initial_y.

3. Let opaque headers be an empty list of cells.

4. If principal cell is a header cell

   Let in header block be true, and let headers from current header block be a list of cells containing just the principal cell.

   Otherwise

   Let in header block be false and let headers from current header block be an empty list of cells.

5. Loop: Increment x by Δx; increment y by Δy.

   For each invocation of this algorithm, one of Δx and Δy will be −1, and the other will be 0.

6. If either x or y is less than 0, then abort this internal algorithm.

7. If there is no cell covering slot (x, y), or if there is more than one cell covering slot (x, y), return to the substep labeled loop.

8. Let current cell be the cell covering slot (x, y).

9. If current cell is a header cell

   1. Set in header block to true.

   2. Add current cell to headers from current header block.

   3. Let blocked be false.

   4. If Δx is 0

      If there are any cells in the opaque headers list anchored with the same x-coordinate as the current cell, and with the same width as current cell, then let blocked be true.

      If the current cell is not a column header, then let blocked be true.

      If Δy is 0

      If there are any cells in the opaque headers list anchored with the same y-coordinate as the current cell, and with the same height as current cell, then let blocked be true.

      If the current cell is not a row header, then let blocked be true.

   5. If blocked is false, then add the current cell to the headers list.

   If current cell is a data cell and in header block is true

   Set in header block to false. Add all the cells in headers from current header block to the opaque headers list, and empty the headers from current header block list.

10. Return to the step labeled loop.

A header cell anchored at the slot with coordinate (x, y) with width width and height height is said to be a column header if any of the following conditions are true:

• The cell's scope attribute is in the column state, or
• The cell's scope attribute is in the auto state, and there are no data cells in any of the cells covering slots with y-coordinates y .. y+height-1.

A header cell anchored at the slot with coordinate (x, y) with width width and height height is said to be a row header if any of the following conditions are true:

• The cell's scope attribute is in the row state, or
• The cell's scope attribute is in the auto state, the cell is not a column header, and there are no data cells in any of the cells covering slots with x-coordinates x .. x+width-1.

A header cell is said to be a column group header if its scope attribute is in the column group state.

A header cell is said to be a row group header if its scope attribute is in the row group state.

A cell is said to be an empty cell if it contains no elements and its text content, if any, consists only of White_Space characters.