ui/niceTables.pl

niceTables.pl

Subroutines for creating tables that:

DataTable() creates a table displaying data. It should not be used for layout, such as displaying an array of graphs.

LayoutTable() creates a "table" without using an HTML table in HTML output. Use LayoutTable() whenever you are simply laying out content for space-saving purposes. Ask yourself if there is any meaningful relation between content cells within a column or within a row. If the answer is no in both cases, it is likely a case for LayoutTable().

Description

Command for a typical table:

DataTable(
    [
        [a,b,c,...],
        [d,e,f,...],
        ...
    ],
    options
);

LayoutTable(
    [
        [a,b,c,...],
        [d,e,f,...],
        ...
    ],
    options
);

The cell entries above like a may be simple cell content, a hash reference with data => cellContent and options, or an array reference where the 0th entry is the cell content and it is followed by option key-value pairs.

As much as possible, options apply to all output formats. Some options only apply to HTML, and some apply only to PDF. Not all options are supported by every output format. For example PreTeXt cannot use color information.

All features described below apply to a DataTable. Most apply to a LayoutTable as well, but not caption, rowheaders, header, colspan, or headerrow.

Options for the WHOLE TABLE

All output formats

center => 0 or 1

center the table (default 1)

caption => string

caption for the table

horizontalrules => 0 or 1

make rules above and below every row (default 0)

texalignment => string

an alignment string like is used in a LaTeX tabular environment: for example 'r|ccp{1in}'

l for left-aligned column

c for center-aligned column

r for right-aligned column

p{width} for a column with left-aligned paragraphs of the given width. The width can be an absolute width or (unlike in LaTeX) a positive decimal number at most 1. If it is a decimal, it will be interpreted as a portion of the available width.

X for a column that expands to fill (see Xratio below), and will have left-aligned paragraphs

| for a vertical rule (n adjacent pipes make one rule that is n times as thick)

!{\vrule width 3pt} for a vertical rule of the indicated width (must be an absolute width; 3pt is just an example)

>{commands} Execute commands at each cell in the column. For example, 'c>{\color{blue}}c' will make the second column have blue text. The following LaTeX commands may be used:

    \color{colorname} for text color

    \color[HTML]{xxxxxx} for text color (xxxxxx is a 6-character hex color code)

    \columncolor{colorname} for background color

    \columncolor[HTML]{xxxxxx} for background color (xxxxxx is a 6-character hex color code)

    \bfseries for bold

    \itshape for italics

    \ttfamily for monospace

Other LaTeX commands apply only to PDF output.

align => string

convenient short version of texalignment

Xratio => number

When X is part of overall alignment, Xratio must be some number between 0 and 1, inclusive of 1. The table as a whole will be Xratio wide, relative to the overall horizontal space. And X columns expand to fill the available space. The default is 0.97.

encase => [ , ]

Encases all table entries in the two entries. For example, use [$BM,$EM] to wrap all cells in math delimiters. See also noencase for individual cells.

rowheaders => 0 or 1

Make the first element of every row a row header. Default is 0.

headerrules => 0 or 1

Make a horizontal rule under a row of column headers and a vertical rule to the right of a column of row headers. Default is 1.

valign => 'top'

Can be 'top', 'middle', or 'bottom'. Applies to all rows. See below to override for an individual row.

padding => [ , ]

An array of two non-negative numbers used to define cell-padding. The first is for top-down padding, the second for left-right padding. In HTML, each padding is the value multiplied by 0.85rem. In LaTeX, the left-right padding is the value multiplied by 10pt, and the top-down padding is implemented by setting \arraystretch to the value. (0.85rem and 10pt are default font sizes at the time of this feature's introduction.) The default for a DataTable is [0,0.5] and the default for a LayoutTable is [1,1]. padding may also be entered as a single nonnegative number to describe both top-down and left-right padding at the same time.

HTML output

Each css property setting should be a hash reference. For example, {'font-family' => 'fantasy', color => 'red'}. If a key has a dash character, it needs to be in quotes. Alternatively, you may uses a javascript flavor of CSS key like {fontFamily => 'fantasy'}

tablecss => css string

css styling commands for the table element

captioncss => css string

css styling commands for the caption element

columnscss => array ref

an array reference to css strings for columns

Note: only four css properties apply to a col element:

  • border (family)

  • background (family)

  • width

  • column-span

datacss => css string

css styling commands for non-header cells

headercss => css string

css styling commands for header cells

allcellcss => css string

css styling commands for all cells

PDF hardcopy output

booktabs => 0 or 1

use the booktabs package for horizontal rules (default 1)

Options for CELLS

Each cell entry can be an array reference where the first entry is the actual cell content, and then key-value pairs follow. For example, in a table with four columns, to make the first cell span two columns, enter the first cell as an array reference:

[[a, colspan => 2], b, c]

Alternatively, using a hash reference with a data key:

[{data => a, colspan => 2}, b, c]

All output formats

halign => string

Similar to the components for texalignment above. However, only l, c, r, p{}, and vertical rule specifications should be used. With vertical rule specifiers, any left vertical rule will only be observed for cells is in the first column. Otherwise, use a right vertical rule on the cell to the left.

header => type,

Declares the scope of the HTML th element. Case-insensitive:

  • th for a generic table header

  • ch for a column header (col and column work too)

  • rh for a row header (row works too)

  • td for overriding a headerrow or rowheaders option (except PTX output cannot honor this)

color => string

color name or 6-character hex color code for text color

bgcolor => string

color name or 6-character hex color code for background color

b=>1

Set the cell to bold font.

i=>1

Set the cell to italics font.

m=>1

Set the cell to monospace font.

noencase => 0 or 1

If you are using encase (see above) use this to opt out.

colspan => positive integer

Makes the cell span more than one column. When using this, you often set halign as well.

top => positive integer or string

Make a top rule for one cell if the cell is in the top row. Thickness is either n pixels or a width like '0.04em'. Has no effect on cells outside of top row.

bottom => positive integer or string

Make a bottom rule for one cell. Thickness is either n pixels or a width like '0.04em'.

HTML output

This option is only for HTML output.

cellcss => string

css styling commands for this cell

PDF hardcopy output

The following apply only to PDF output

texpre => tex code and texpost => tex code

For more fussy cell-by-cell alteration of the tex version of the table, code to place before and after the cell content.

texencase => array ref

Shortcut for entering [texpre,texpost] at once.

Options for ROWS

Some parameters in a cell's options array affect the entire row. When there is a clash, the last non-falsy declaration in the row will be used.

rowcolor => string

Sets the row's background color. Must be a color name, 6-character hex color code.

rowcss => string

css styling commands for the row

headerrow => 0 or 1

Makes an entire row use header cells (with column scope).

rowtop => positive integer or string

When used on the first row, creates a top rule. Has no effect on other rows. Thickness is either n pixels or a width like '0.04em'.

rowbottom => positive integer string

Make a bottom rule. Thickness is either n pixels or a width like '0.04em'.

valign => string

Override table's overall vertical alignment for this row. Can be 'top', 'middle', or 'bottom'.

rows => 2D array reference

If a row contains only one cell with no content or attributes other than 'rows', and if 'rows' is an array reference where each element is itself an array reference that is appropriately formatted to be a niceTables row, then this row will be expanded to those rows. This allows a sequence of rows to be computed algorithmically for example [{rows = [ map {[ $_, $_**2 ]} (1..4)]}]> will expand to [1, 1], [2, 4], [3, 9], [4, 16].

This can also be achieved if the cell is an array reference with (possibly empty) whitespace content followed by the rows attribute, for example: [['', 'rows', [ map {[ $_, $_**2 ]} (1..4)]]]. This form is used by PGML. So for instance when using PGML, [. .]*{rows = $rows}>.

This expansion is not recursive; any 'rows' attribute in the inner rows will not be expanded.

Options for COLUMNS

Column styling is handled indirectly for now, mostly through the texalignment option above.

Deprecations

These features were supported in an earlier version and still work, but are deprecated.