Tables

Learn by Example

This page was written in a Mallard extension format called Mallard Sites. Read the source markup for this page to learn Mallard from real-world examples.

Tables are an efficient way to display certain types of information. By arranging data into rows and columns, they allow readers to easily scan and compare data. Mallard supports tables using a simple but powerful syntax based on HTML tables. In this tutorial, you will learn how to:

create a basic table,
control the frame around the table and the rules between rows and columns,
automatically shade alternating rows or columns,
group rows or columns together to have better control over rules and shading, and
make a table cell span multiple rows or columns.

Basic Tables

The basic structure of tables in Mallard resembles that of tables in HTML. The table element wraps an entire table. Each row in a table is wrapped in a tr element, and each column in a row is wrapped in a td element.

<table>
  <tr>
    <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65cm</p></td> <td><p>900-1200g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50cm</p></td>         <td><p>680g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
    <td><p>34-43cm</p></td>     <td><p>360g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76cm</p></td>          <td><p>450-1360g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65cm	900-1200g
Eurasian Wigeon	Anas penelope	45-50cm	680g
Common Teal	Anas crecca	34-43cm	360g
Northern Pintail	Anas acuta	59-76cm	450-1360g

Notice that each td element contains a paragraph, marked up with the p tag. A table cell can contain multiple paragraphs or other block elements. In Mallard, every element contains either block or inline content, so even when you only use a single line of text in a table cell, you must use a paragraph.

Frames and Rules

In the previous example, there were no rules between rows or columns, and no frame around the entire table. Mallard provides a simple method to specify how to draw the table frame and the rules between rows and columns.

You can use the frame attribute on the table element to specify how to draw a frame around the table. Set the frame attribute to a space-separated list of positions where a frame should be drawn: top, bottom, left, or right. The following example draws frames on the top and bottom.

<table frame="top bottom">
  <tr>
    <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65cm</p></td> <td><p>900-1200g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50cm</p></td>         <td><p>680g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65cm	900-1200g
Eurasian Wigeon	Anas penelope	45-50cm	680g

Instead of specifying each position, you can set the frame attribute to all to draw frames on all sides.

<table frame="all">
  <tr>
    <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65cm</p></td> <td><p>900-1200g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50cm</p></td>         <td><p>680g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65cm	900-1200g
Eurasian Wigeon	Anas penelope	45-50cm	680g

Unlike HTML, the frame around the entire table is handled separately from rules between rows and columns. You control where rules are drawn using the rules attribute on the table element. Like the frame attribute, the rules attribute takes a space-separated list of where rules should be drawn. The folloing example draws rules between each row and each column.

<table rules="rows cols">
  <tr>
    <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65cm</p></td> <td><p>900-1200g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50cm</p></td>         <td><p>680g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
    <td><p>34-43cm</p></td>     <td><p>360g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65cm	900-1200g
Eurasian Wigeon	Anas penelope	45-50cm	680g
Common Teal	Anas crecca	34-43cm	360g

You could have also simply set rules to all for the same effect. You can also control which rows and columns have rules using row and column groups. See Grouping below for details.

Shading

A common feature in tables of information is alternate-row shading. With shading, every other row is drawn with a darker background color. This helps readers keep track of which information is in which row. In Mallard, you can easily shade rows or columns in Mallard without manually marking alternate rows or columns.

Use the shade attribute to specify whether to shade rows or columns. Like the rules attribute, the shade attribute takes a space-separated list. The following example shades only alternate rows.

<table shade="rows">
  <tr>
    <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65cm</p></td> <td><p>900-1200g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50cm</p></td>         <td><p>680g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
    <td><p>34-43cm</p></td>     <td><p>360g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76cm</p></td>          <td><p>450-1360g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65cm	900-1200g
Eurasian Wigeon	Anas penelope	45-50cm	680g
Common Teal	Anas crecca	34-43cm	360g
Northern Pintail	Anas acuta	59-76cm	450-1360g

To shade both rows and columns, use both rows and cols in the shade attribute, or simply set the shade attribute to all.

<table shade="all">
  <tr>
    <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65cm</p></td> <td><p>900-1200g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50cm</p></td>         <td><p>680g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
    <td><p>34-43cm</p></td>     <td><p>360g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76cm</p></td>          <td><p>450-1360g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65cm	900-1200g
Eurasian Wigeon	Anas penelope	45-50cm	680g
Common Teal	Anas crecca	34-43cm	360g
Northern Pintail	Anas acuta	59-76cm	450-1360g

Notice that when both rows and columns are shaded, a darker background color is used where shaded rows intersect shaded columns. You can also control which rows and columns are shaded using row and column groups. See Grouping below for details.

Grouping

In the previous examples, you were only able to enable rules and shading for all rows or all columns. You can also group rows and columns to control rules and shading. To group rows together, wrap the tr elements for each row group in a tbody element. You can then use rowgroups instead of rows for either of the rules or shade attributes.

<table rules="rowgroups" shade="rowgroups">
  <tbody>
    <tr>
      <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td>
      <td><p>56-65cm</p></td> <td><p>900-1200g</p></td>
    </tr>
    <tr>
      <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
      <td><p>45-50cm</p></td>         <td><p>680g</p></td>
    </tr>
  </tbody>
  <tbody>
    <tr>
      <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
      <td><p>34-43cm</p></td>     <td><p>360g</p></td>
    </tr>
    <tr>
      <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
      <td><p>59-76cm</p></td>          <td><p>450-1360g</p></td>
    </tr>
  </tbody>
</table>

Mallard	Anas platyrhynchos	56-65cm	900-1200g
Eurasian Wigeon	Anas penelope	45-50cm	680g
Common Teal	Anas crecca	34-43cm	360g
Northern Pintail	Anas acuta	59-76cm	450-1360g

To control column grouping, you have to specify the columns and column groups at the beginning of the table element using the col and colgroup elements. Each col element represents one column, and you should have one for each column that appears in your rows. Wrap the col elements in colgroup elements to indicate grouping.

Once you have specified the columns and column groups, you can use colgroups instead of cols for either of the rules or shade attributes.

<table rules="colgroups" shade="colgroups">
  <colgroup><col/></colgroup>
  <colgroup><col/></colgroup>
  <colgroup><col/><col/></colgroup>
  <tr>
    <td><p>Mallard</p></td> <td><p>Anas platyrhynchos</p></td>
    <td><p>56-65cm</p></td> <td><p>900-1200g</p></td>
  </tr>
  <tr>
    <td><p>Eurasian Wigeon</p></td> <td><p>Anas penelope</p></td>
    <td><p>45-50cm</p></td>         <td><p>680g</p></td>
  </tr>
  <tr>
    <td><p>Common Teal</p></td> <td><p>Anas crecca</p></td>
    <td><p>34-43cm</p></td>     <td><p>360g</p></td>
  </tr>
  <tr>
    <td><p>Northern Pintail</p></td> <td><p>Anas acuta</p></td>
    <td><p>59-76cm</p></td>          <td><p>450-1360g</p></td>
  </tr>
</table>

Mallard	Anas platyrhynchos	56-65cm	900-1200g
Eurasian Wigeon	Anas penelope	45-50cm	680g
Common Teal	Anas crecca	34-43cm	360g
Northern Pintail	Anas acuta	59-76cm	450-1360g

In these examples, you used grouping for both rules and shading, but they aren't required to match. You could have rules between each row, but only shade every other row group, for example. And because both the rules and shade attributes take a space-separated list, you can mix row and column grouping, just as you did for rules and shading for single rows and columns. Try modifying the table yourself to achieve different effects.

Spanning

Sometimes you need to have a table cell that spans across multiple rows or columns. Mallard supports row and column spanning using the rowspan and colspan attributes on td elements, similarly to HTML. Both attributes take a number indicating how many rows or columns the td element should occupy.

When you set the colspan attribute, that td element effectively uses up that many columns, so the enclosing tr element should have fewer td elements. For example, if you normally have five columns, but one of your td elements has colspan="3", then you should only have three td elements.

Similarly, when you set the rowspan attribute, that td element uses up space in that many rows. Any tr elements that come after the current row will have fewer td elements.

<table frame="all" rules="all">
  <tr>
    <td><p>One</p></td>
    <td><p>Two</p></td>
    <td><p>Three</p></td>
    <td><p>Four</p></td>
  </tr>
  <tr>
    <td rowspan="2"><p>Rows</p></td>
    <td><p>Two</p></td>
    <td colspan="2"><p>Columns</p></td>
  </tr>
  <tr>
    <td><p>Two</p></td>
    <td><p>Three</p></td>
    <td><p>Four</p></td>
  </tr>
</table>

One	Two	Three	Four
Rows	Two	Columns
Rows	Two	Three	Four

A table cell can span multiple rows and multiple columns at the same time. When you do this, be careful to use the right number of td elements in the following rows.

<table frame="all" rules="all">
  <tr>
    <td><p>One</p></td>
    <td><p>Two</p></td>
    <td><p>Three</p></td>
    <td><p>Four</p></td>
  </tr>
  <tr>
    <td><p>One</p></td>
    <td rowspan="2" colspan="2"><p>Both</p></td>
    <td><p>Four</p></td>
  </tr>
  <tr>
    <td><p>One</p></td>
    <td><p>Four</p></td>
  </tr>
</table>

One	Two	Three	Four
One	Both		Four
One	Both		Four

When you use shading with spanning, table cells are shaded based on the top-left row and column. That is, they are shaded based on where the td element is, as if it did not span any rows or columns.

<table frame="all" rules="all" shade="all">
  <tr>
    <td><p>One</p></td>
    <td><p>Two</p></td>
    <td><p>Three</p></td>
    <td><p>Four</p></td>
    <td><p>Five</p></td>
  </tr>
  <tr>
    <td rowspan="3"><p>Rows</p></td>
    <td><p>Two</p></td>
    <td colspan="2"><p>Columns</p></td>
    <td><p>Five</p></td>
  </tr>
  <tr>
    <td><p>Two</p></td>
    <td rowspan="3"><p>Rows</p></td>
    <td><p>Four</p></td>
    <td><p>Five</p></td>
  </tr>
  <tr>
    <td><p>Two</p></td>
    <td><p>Four</p></td>
    <td><p>Five</p></td>
  </tr>
  <tr>
    <td><p>One</p></td>
    <td><p>Two</p></td>
    <td><p>Four</p></td>
    <td><p>Five</p></td>
  </tr>
</table>

One	Two	Three	Four	Five
Rows	Two	Columns		Five
	Two	Rows	Four	Five
	Two		Four	Five
One	Two		Four	Five

Learn More

In this tutorial, you learned the basics of the major features of Mallard tables. These features are designed to help you display tabular information in ways that will best help your readers. This tutorial only showed you a few ways you can put these features together. Try changing the examples to acheive different effects.

For more information see Tables in the language specification. The specification pages are full of examples to help you learn more.