From ConTeXt wiki
Jump to: navigation, search

< Tables Overview | XML >



This table mode is called “natural tables” or “automatic tables.” I'd call it “HTML tables,” because it's very similar to them. They're especially suited for XML conversions.

Beware: every element must use \b ... \e!

You find a lot of samples in enattab.pdf

Willi Egger wrote a My Way how he set a typesetter's lead type case: Use of natural tables

To place a table use:

\bTR \bTD One \eTD \bTD two \eTD \eTR
\bTR \bTD One \eTD \bTD two \eTD \eTR

Here is a more elaborate example:

This is our red-coloured table.

\setupTABLE[row][odd][background=color,backgroundcolor=red, width=.2\textwidth]
\bTABLE[split=yes] % allow splitting over page boundaries
  \bTR \bTD[nr=3] 1 \eTD \bTD[nc=2] 2/3     \eTD \bTD[nr=3] 4 \eTD \eTR
  \bTR                   \bTD 2 \eTD \bTD 3 \eTD                   \eTR
  \bTR                   \bTD 2 \eTD \bTD 3 \eTD                   \eTR
  \bTR \bTD[nc=3] 1/2/3                     \eTD \bTD 4 \eTD       \eTR
  \bTR \bTD 1       \eTD \bTD 2 \eTD \bTD 3 \eTD \bTD 4 \eTD       \eTR

Multipage TABLEs

Try to divide your table into...

and \setupTABLE[split=yes] or [split=repeat]

see also tabl-ntb.mkiv

If you must split a natural table over several pages, you can simply do this by adding \setupTABLE[split=yes] to your TABLE definition. Another way is to define it right at the TABLE start by adding the parameter [split=yes] (see example). However, \startlinecorrection can lead to unpredictable vertical spaces between rows [1].

In this case the table head (all between \bTABLEhead and \eTABLEhead) is printed only once at the beginning of the table. But if you use [split=repeat], it is printed on top of every new page, that contains parts of your multipage table. Please take account of the fact, that the head cells are enclosed by \bTH and \eTH (and not \[be]TC).

If you want to use an alternative table header for all following pages, you can do this by defining an additional header. Just add the second header between \bTABLEnext...\eTABLEnext, right after your normal head definition. Now every additional page of the multipage table starts with the next table head.

The table foot is declared between \bTABLEfoot and \eTABLEfoot. It defines the concluding row of your natural table.

Beware: Split tables often begin not on the page (or in the column, if you use them) where they could start, but on/in the next one. This is a known limitation due to the complicated calculation of remaining space on the page. That won't become better before this calculations are newly written in Lua. (Said Hans on 2010-09-24.)

The following standalone example deals with all the mentioned aspects of natural tables. Just copy&paste it as a starting point for further experiments...



% setup for all cells
\setupTABLE[r][each][style=\tfx\it, align=center]

% setup table head
% setup table footer

\bTABLE[split=repeat,option=stretch]% head on every page, stretch columns
% IMPORTANT: use \bTH ... \eTH to enclose the head|next cells
  \bTH  head1 \eTH
  \bTH  head2 \eTH
  \bTH  head3 \eTH
\bTABLEnext % setup for next table head
\bTR [background=color,backgroundcolor=cyan]
  \bTH  next1 \eTH
  \bTH  next2 \eTH
  \bTH  next3 \eTH
% the table body (main part)
\dorecurse{100}{% 100 rows
  \bTC  body body body body body \eTC
  \bTC  body body body body body \eTC
  \bTC  body body body body body \eTC
% the table foot
  \bTC  foot1 \eTC
  \bTC  foot2 \eTC
  \bTC  foot3 \eTC


Tables in multiple columns

... just work (at least in luaTeX and not here...). See the following example.

{\bTR \bTD a\eTD \bTD b \eTD \eTR}

Creating tables from CSV data (Comma Separated Values)

See also the database module!

and Creating Tables using CSV (Comma-separated values) by Mojca Miklavec

An interesting example of creating a table using comma separated values was posted to the mailing list by Christopher Creutzig

The following macros take care of processing CSV data:

% Iterate over all the lines of text captured with \obeylines active
% command to call is first argument, is not called for empty lines


The next lines are an example of transforming the data into a natural table, but can be easily adapted to any type of the table or perhaps (mis)used in even more strange ways:



The following lines will then finally result in a desired table:

% some additional settings for the table may be made as well
\setupTABLE[r][1][style=bold] % how to override the \tt in the second column?


Some remarks: the (tentative) code ignores the fact that

See also \processseparatedlist.

Designing complex TABLEs

Everything is easy when a simple grid is enough. Unfortunately, this is not the case most of the time, tables tend to have information which should flow accross cell boundaries either vertically or horizontally. One of the reasons to use TABLE instead of the table environment is that TABLE provides an easy (relatively speaking, at least) way to make merged cells to both directions.

There are probably as many ways to design TABLEs as there are users, but a simple one to begin with is to start with a grid:

The desired table layout is then drawn onto this grid, and the top left corner cell of each cell in the final layout identified:

The cells are listed from left to right and up to down. Each larger cell is then given it size by using nc=... and nr=... parameters with \bTD. The code producing the table above is:

\bTR \bTD \eTD \bTD \eTD \bTD \eTD \bTD \eTD \bTD \eTD \bTD \eTD \eTR
\bTR \bTD[nc=2,nr=2] r1c1 \eTD \bTD r1c3 \eTD \bTD[nr=2] r1c4 \eTD \bTD[nr=2,nc=2] r1c5 \eTD \eTR
\bTR \bTD[nr=2] r2c3 \eTD \eTR
\bTR \bTD[nc=2] r3c1 \eTD \bTD[nc=2] r3c4 \eTD \bTD r3c6 \eTD \eTR
\bTR \bTD r4c1 \eTD \bTD[nc=2] r4c2 \eTD \bTD[nr=2] r4c4 \eTD \bTD[nc=2] r4c5 \eTD \eTR
\bTR \bTD[nr=2,nc=2] r5c1 \eTD \bTD[nr=2] r5c3 \eTD \bTD[nr=2,nc=2] r5c5 \eTD \eTR
\bTR \bTD r6c4 \eTD \eTR

N.B. There is an ugly hack in the code. An empty first row with zero height and no borders is added. If the row is omitted, then something odd happens to the number of columns. The table should have all cells, so this may be a bug. (Or then I have blundered something with this example, possibly.)

Everything rectangular can be done with TABLE, as long as it can be fit in the grid. The grid does not have to be equidistant, and if its dimensions are omitted, the program will fit the data in. L-shaped or other complex cell shapes are not possible. Using them would be a bit odd, in any case, as alignment and text flow problems would be quite interesting.

Cell Addressing and Frames

The setup commands for TABLE do not seem to be very verbosedly commented. There are, however, a few shorthands, which are useful to understand. First of all, there are several ways to address cells. This is a brief summary of some of them:

\setupTABLE[r][(list of rows)][...]
\setupTABLE[c][(list of columns)][...]
\setupTABLE[(list of columns)][(list of rows)][...]

A list contains one or more numbers separated by commas. Word "last" is equivalent to the number of the last row or column. The complete list can be replaced by the word "each" to address all cells on the row/column.

Let us consider the following table:


In plain language the rows are interpreted as follows:

and vertically in the middle (lohi), and remove all frames (borders)

In this case the table is slightly complicated, there are some split cells, as shown below:

  \bTD \bf r1c1 \eTD
  \bTD \bf r1c2 \eTD
  \bTD \bf r1c3 \eTD
  \bTD \bf r1c4 \eTD
  \bTD r2c1 \eTD
  \bTD r2c2 \eTD
  \bTD[nr=2] r2c3 \eTD
  \bTD r2c4 \eTD
  \bTD r3c1 \eTD
  \bTD r3c2 \eTD
  \bTD r3c4 \eTD
  \bTD r4c1 \eTD
  \bTD r4c2 \eTD
  \bTD[nr=3] r4c3 \eTD
  \bTD[nr=3] r4c4 \eTD
  \bTD r5c1 \eTD
  \bTD r5c2 \eTD
  \bTD r6c1 \eTD
  \bTD r6c2 \eTD

The cell numbering is well worth noting. It is very logical (upper leftmost part of a combined cell), but sometimes the results are surprising in the beginning.

The important point about cell numbering is that there is really a difference between "bottom border of row 3" and "top border of row 4". To illustrate this, let us change the frame setups:


is changed to


At first sight this is exactly the same thing. But...

Where did the horizontal line in column 3 disappear? Nowhere. There is no row 3 in column 3, so there cannot be a frame under it. This problem can be overcome by using topframe and leftframe instead of bottom and right, as the cells below and to the right of a border have to exist.

However, this solution leaves the problem of bottom and rightmost borders. How to draw a line in the bottom of the table? Using \setupTABLE[r][6][bottomframe=on] will leave the gap in columns 3 and 4, and \setupTABLE[r][7][topframe=on] is not possible, as there is no row 7. The clever idea of using "last" instead of the row number (6) will fail, as "last" seems to behave exactly the same way as number 6.

One useful method is to switch on the borders cell by cell by adding \setupTABLE[3,4][4][bottomframe=on], i.e. draw a border under cells r4c3 and r4c4.

Column Offset/Gap

From the mailing list at 2005-11-09 by Vit Zyka, modified by Hans Hagen:


% distance mechanism, per column (H)


   \bTR \bTD test \eTD  \bTD test \eTD  \bTD test \eTD \eTR
   \bTR \bTD[nx=2] test \eTD  \bTD test \eTD \eTR
   \bTR \bTD test \eTD  \bTD[nx=2] test \eTD \eTR

   \bTR \bTD test \eTD  \bTD test \eTD  \bTD test \eTD \eTR
   \bTR \bTD[nx=2] test \eTD  \bTD test \eTD \eTR
   \bTR \bTD test \eTD  \bTD[nx=2] test \eTD \eTR

% distance mechanism, per table (V)

   \bTH[nc=3] Table head\eTH
 \bTR\bTD[nc=2] AB\eTD\bTD C\eTD\eTR
 \bTR\bTD[nc=2,align=left] AB\eTD\bTD C\eTD\eTR
 \bTR\bTD[nc=2,align=middle] AB\eTD\bTD C\eTD\eTR
 \bTR\bTD A\eTD\bTD B\eTD\bTD C\eTD\eTR
 \bTR\bTD Aa\eTD\bTD Bb\eTD\bTD Cccc\eTD\eTR
 \bTR\bTD[nc=3,align=middle] ABC\eTD\eTR


Make a cell bold

Drawing bold lines around a cell is done using the [rulethickness=dim] key on a cell. The thicker rules will offset the text inside the cell both downwards and sideways, so care should be taken that the cell's increased rulethickness is offset by an equal decrease in offset.

\bTR \bTD 1 \eTD \bTD 1 \eTD \bTD 2/3 \eTD \eTR
\bTR \bTD 2 \eTD \bTD 2 \eTD \bTD 3 \eTD \eTR
\bTR \bTD 2 \eTD \bTD[rulethickness=2pt,offset=1mm] 2 \eTD \bTD 3 \eTD \eTR
\bTR \bTD 1 \eTD \bTD 1 \eTD \bTD 4 \eTD \eTR
\bTR \bTD 1 \eTD \bTD 1 \eTD \bTD 2 \eTD \eTR



Example: an invoice with thick rules

{\bfa Invoice}
   \setupTABLE[column][1,2]  [width=20mm,offset=\dimexpr1mm+2pt,align=flushleft]
   \bTR[bottomframe=on, rulethickness=2pt,offset=1mm]
	\bTD\bf Date \eTD
	\bTD\bf Description \eTD
	\bTD\bf Quantity \eTD
	\bTD\bf Price \eTD
	\bTD\bf Total \eTD
	\bTD 05-01-2010 \eTD
	\bTD Element  1 \eTD
	\bTD 10.0 \eTD
	\bTD 6.00 \eTD
	\bTD 60.00 \eTD
	\bTD 05-01-2010 \eTD
	\bTD Element 2 \eTD
	\bTD 2.0 \eTD
	\bTD 3.00 \eTD
	\bTD 6.00 \eTD
	\bTD[nx=3] \eTD
	\bTD[align=flushleft] Subtotal \eTD
	\bTD 66.00 \eTD
	\bTD[nx=3] \eTD
	\bTD[align=flushleft] VAT 19\% \eTD
	\bTD 12.54 \eTD
        \bTD[nx=3] \eTD
	\bTD[align=flushleft] \bf Total \eTD
	\bTD 78.54 \eTD

Rules with different thickness

There is only one value for all four borders. However, MetaPost can be used as a workaround until the separate "rulethickness" values are implemented.

The following example (mkiv only!) by Wolfgang Schuster shows a table using MetaPost for the rules:


draw leftboundary   OverlayBox withpen pensquare scaled \frameddimension  {leftrulethickness} ;
draw rightboundary  OverlayBox withpen pensquare scaled \frameddimension {rightrulethickness} ;
draw topboundary    OverlayBox withpen pensquare scaled \frameddimension   {toprulethickness} ;
draw bottomboundary OverlayBox withpen pensquare scaled \frameddimension{bottomrulethickness} ;

clip currentpicture to OverlayBox
	leftenlarged   (\frameddimension  {leftrulethickness}/2)
	rightenlarged  (\frameddimension {rightrulethickness}/2)
	topenlarged    (\frameddimension   {toprulethickness}/2)
	bottomenlarged (\frameddimension{bottomrulethickness}/2) ;

setbounds currentpicture to OverlayBox ;



\startsetups tableborders

  [         background={color,tableborders},

\setupTABLE[row]  [odd]  [backgroundcolor=lightgray]
\setupTABLE[row]  [first][backgroundcolor=gray,bottomrulethickness=2pt]
\setupTABLE[row]  [last] [toprulethickness=2pt,bottomrulethickness=2pt]
\setupTABLE[first][last] [leftrulethickness=2pt]
\setupTABLE[last] [last] [rightrulethickness=2pt]








See the corresponding thread on the list: rules with different thickness

Thick bottom rules

This is a simplified version of the example above (corresponding mailing thread - TABLE: header with a thick bottom line).

  draw bottomboundary OverlayBox withpen pensquare scaled \frameddimension{bottomrulethickness};
  clip currentpicture to OverlayBox;
  setbounds currentpicture to OverlayBox;




Diagonal rules

Sometimes a diagonal rule is required in the top left corner cell of a table to create two fields, one for the left column and one for the top row.

  rulethickness := \frameddimension{rulethickness};

    withpen pencircle scaled rulethickness
    withcolor \MPcolor{\framedparameter{framecolor}});

  pair leftcorner, rightcorner;
  leftcorner  := (rulethickness, \overlayheight-rulethickness);
  rightcorner := (\overlaywidth-rulethickness, rulethickness);

  draw leftcorner -- rightcorner;


  \setuptabulate [after={\blank[\frameddimension{offset}]}]
  \starttabulate [|p|r|]
    \NC    \NC #2 \NC\NR
    \NC #1 \NC    \NC\NR

  \setupTABLE [row] [1] [width=2cm]
      \bTD [background=DiagonalRule]
      \bTD Second \eTD
      \bTD Third \eTD
      \bTD Alpha \eTD
      \bTD Beta  \eTD
      \bTD Gamma \eTD


This solution has (at least) one caveat: Because the first tabulate column is set in paragraph mode, it will eat up as much space as possible, in contrast to occupying as much space as </em>necessary</em>. That is why the width of the column has to be set explicitly.

Using character alignment

ConTeXt can align columns of numbers on a character (often a decimal point to align accounting data) automatically, removing the need to add fixed spaces into your document. For any such column you need to specify the character on which to align. You use the aligncharacter=yes parameter to set up character alignment, alignmentcharacter={.} to say what the character should be (in this case a full stop) and align=middle to set the overall alignment of the column.

\bTR \bTH Category \eTH \bTH Data entry \eTH \eTR
\bTR \bTD First \eTD \bTD 71.3 \eTD \eTR
\bTR \bTD Second \eTD \bTD 43.7 \eTD \eTR
\bTR \bTD Total \eTD \bTD 115 \eTD \eTR

You'll note that the final line, because it has no . in the number, gets aligned under the right-hand side of the numbers. In most circumstances you would want such a number aligned with the left-hand set of digits. To so do, issue the following command in your preamble:


and now the table above will turn out like this:

If there's no alignmentcharacter in the cell, the content will be aligned in the following way depending on the value of \characteralignmentmode:

1left in before.
2right in before.
3.left in after
4.right in after

Specifying the cell column

When writing a table you can omit empty cells and define only cells for specified columns. To have this feature fully available you need to have a beta or a quite fresh ConTeXt version.

Two methods are available:

Here is an example using the "n" option:

\bTR\bTD d1 \eTD\bTD[n=2] d2 \eTD\bTD[n=5] d5 \eTD\bTD[n=7] d7 \eTD\eTR
\bTR\bTD f1 \eTD\bTD[n=4] f4 \eTD\bTD[n=5] f5 \eTD\bTD[n=7] f7 \eTD\eTR

Here is an example using the "m" option:

\bTR\bTD d1 \eTD\bTD[m=2] d2 \eTD\bTD[m=5] d5 \eTD\bTD[m=7] d7 \eTD\eTR
\bTR\bTD f1 \eTD\bTD[m=4] f4 \eTD\bTD[m=5] f5 \eTD\bTD[m=7] f7 \eTD\eTR

Round corners

For a different approach for round corners and colored background follow the text after this example.

It is possible to round the corners of the table if you turn off the main frame of the table and frame the table in \framed. Compare two different approaches in the first and second example.

You can't color the background of the table with round corners unless the frame rulethickness is not big enough to cover the rectangular corners of the background (second example). Well, you can if you frame the table twice. Once in the thick white frame and then in the thin frame with negative offset and slightly smaller corner radius (third example). Be aware of other complications -- notice that the thick white frame is still visible in the text above it.





   {\setupTABLE[row]   [first][topframe=off]%
    \setupTABLE[row]   [last] [bottomframe=off]%
    \setupTABLE[column][last] [rightframe=off]%


        \bTR \bTD test \eTD \bTD test \eTD \eTR
        \bTR \bTD test \eTD \bTD test \eTD \eTR
        \bTR \bTD test \eTD \bTD test \eTD \eTR



\setupTABLE[row]   [first][topframe=off]
\setupTABLE[row]   [last] [bottomframe=off]
\setupTABLE[column][last] [rightframe=off]
        \bTR \bTD test \eTD \bTD test \eTD \eTR
        \bTR \bTD test \eTD \bTD test \eTD \eTR
        \bTR \bTD test \eTD \bTD test \eTD \eTR



\setupTABLE[row]   [first][topframe=off]
\setupTABLE[row]   [last] [bottomframe=off]
\setupTABLE[column][last] [rightframe=off]
            \bTR \bTD test \eTD \bTD test \eTD \eTR
            \bTR \bTD test \eTD \bTD test \eTD \eTR
            \bTR \bTD test \eTD \bTD test \eTD \eTR



From 2006-10-11 on, ConTeXt contains one more mechanism for round corners. Watch the example:

\setupTABLE [y]    [first][background=color,backgroundcolor=blue,frame=off,bottomframe=on,topframe=on,framecolor=white]
\setupTABLE [first][first][backgroundcorner=2,corner=10,frame=on]
\setupTABLE [last] [first][backgroundcorner=4,corner=12,frame=on]
\setupTABLE [row]  [each] [background=color,backgroundcolor=blue,frame=on,framecolor=white]
\setupTABLE [first][2]    [corner=8]
\setupTABLE [last] [2]    [corner=5]
\setupTABLE [first][last] [corner=7]
\setupTABLE [last] [last] [corner=6]

\bTR \bTD one   \eTD \bTD two    \eTD \bTD three \eTD \eTR
\bTR \bTD first \eTD \bTD second \eTD \bTD third \eTD \eTR
\bTR \bTD alpha \eTD \bTD beta   \eTD \bTD gamma \eTD \eTR

Other options

Some other useful options that were not covered above:

TABLEs with old table syntax

From the mailing list in March 2009, by Wolfgang Schuster and Hans Hagen:







 {\ifx\next\doTABLENR \else


This is now part of the core as the NTE module. Quoting its internal documentation:

This module is suggested by Wolfgang Schuster who also prototyped it and came up with the rationale:

This module provides an easy way to use natural in a similiar way as the older table module (based on the TABLE macros) and the newer tabulate module.

You can see the advantage in the following table, once created with the new macros and once with the normal macros provided with the natural table module.

Let us start with the original macros:

    \bTD Text 1 \eTD
    \bTD Text 2 \eTD
    \bTD Text 3 \pasteeTD
    \bTD Text 4 \eTD

Watch how the new macros use less code:

\NC Text 1 \NC Text 2 \NC\NR
\NC Text 3 \NC Text 4 \NC\NR

The actual code differs from the prototype that it does not need to collect whole rows and parse them but looks ahead instead.

Get current row/column number

See for example here: Command/currentTABLErow tt>\bTD


Personal tools
External Help