Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

# 5.7. Other Table Goodies

## 5.7.1. Column alignment

The colaligns parameter of the table filter can be used to control the alignment of text within columns of a table. For example:

    !block  table; colaligns="LCCR"
    Name    Column2             Column3     Column4
    A       B                   C           1.0
    X       Hello dear world    Y           10.2
    !endblock

The output is:

Name | Column2 | Column3 | Column4
A | B | C | 1.0
X | Hello dear world | Y | 10.2

The value of colaligns is usually a sequence of the letters L, C and R (which mean what one would expect). If you prefer, a comma-separated list of the values Left, Center and Right can be specified. For example:

    !block  table; colaligns="Left,Center,Center,Right"
    Name    Column2             Column3     Column4
    A       B                   C           1.0
    X       Hello dear world    Y           10.2
    !endblock

Likewise, the colvaligns parameter can be used to control the vertical alignment of text within columns of a table. The value is either:

- a comma-separated list of the values Top, Middle, Bottom and Baseline, or
- a sequence of the letters T, M, B (Bottom) and L (baseLine).

Baseline alignment means that the base of the first line of the text in each cell is aligned (HTML only).

Note: For a variety of reasons, the default vertical alignment for cells in a HTML table is Middle, while the default vertical alignment for tables in most other formats is Top. As most tables contain rows which fit on one line, this inconsistency is not usually a problem. However, if you want consistent vertical alignment for a complex table across all formats, you need to use the colvaligns parameter to override the default behaviour.

## 5.7.2. Column tagging

In a similar way, columns can be tagged with a phrase style by using the coltags attribute. For example:

    !block table; coltags="B,EMAIL"
    Purpose         Email
    Information     sdf-users@mincom.com
    Bug reporting   sdf-users@mincom.com
    !endblock

The result is:

Purpose | Email
Information | sdf-users@mincom.com
Bug reporting | sdf-users@mincom.com

## 5.7.3. Table filtering and sorting

Tables can be filtered and sorted by using the where and sort attributes of the table filter. These attributes are also supported by the class filters (e.g. terms, references). In either case, filtering is done before sorting.

The where attribute takes an expression which is evaluated for each record. Special symbols available are:

Symbol | Meaning
$_ | the current record
$o{"xyz"} | the value of column xyz
$var{"abc"} | the value of variable abc

For example:

     !define MODULE_CODE "XYZ"
     ...
     !include "../mydata.tbl"; table; \
       where='$o{"Code"} =~ /$var{"MODULE_CODE"}/'

sort takes a comma-separated list of column names to sort on. If no columns are specified, the data is sorted using all columns in the order in which they appear. All sorting is done alphabetically - numeric sorting is not supported.

## 5.7.4. Deleting and selecting columns

The table filter supports the following parameters for changing the columns actually displayed:

- delete - a comma-separated list of columns to delete
- select - the comma-separated list of columns to display.

These parameters are often used in combination with the where parameter. For example:

      # Display the open bugs, sorted by priority
      H1: Open Defects
      !include 'mybugs.tbl'; table; \
               where='$o{"Status"} eq "Open"'; \
               sort='Priority'; \
               delete='Status'

If both delete and select are specified, select has precedence.

## 5.7.5. Macros inside tables

Macros can be used inside tables. In particular:

- rows can now be conditionally included or excluded
- rows can be marked as changed.

For example:

    !block table
    Code    Description
    BTW     By the way
    !block changed
    RTFM    Read the (fine) manual
    !endblock
    !if ALL_TERMS
    SOS     Save our souls
    !endif
    !endblock

## 5.7.6. Landscape tables

Landscape tables are supported via the landscape parameter of the table filter. The value is the height allocated to the area in which the table is placed. If a unit is not specified, the value is assumed to be a percentage of the text column height. For convenience, a value of 1 implies a full page table. Some examples are given below.

Value | Meaning
landscape="50pt" | height allocated to table is 50 points
landscape="50%" | half page table
landscape=50 | half page table (% is the default units)
landscape=1 | full page table (1 implies 100%)
landscape | full page table (syntactic shorthand for above)

Note: This feature is currently use at your own risk. In particular, long tables and table titles confuse it badly. Furthermore, the align and placement parameters are effectively ignored for landscape tables.

## 5.7.7. Cell attributes

Cells within a table can now be given attributes by preceding the cell value with a semicolon-separated list of name-value pairs enclosed in square brackets. For example:

    !block  table; colaligns="LCCR"
    Name    Column2             Column3     Column4
    A       [align=Left]B       C           [bgcolor=Green]1.0
    X       Hello dear world    Y           [bgcolor=Red]10.2
    !endblock

The output is:

Name | Column2 | Column3 | Column4
A | B | C | 1.0
X | Hello dear world | Y | 10.2

The cell attributes supported are given below.

Name | Value
General: |
align | horizontal alignment (Left, Center, Right)
valign | vertical alignment (Top, Middle, Bottom, Baseline)
cols | the number of columns this cell spans (default is 1)
rows | the number of rows this cell spans (default is 1)
bgcolor | background colour of cell (see below)
PS only: |
fill | background colour fill percentage
truling | ruling setting for top of cell
bruling | ruling setting for bottom of cell
lruling | ruling setting for left of cell
rruling | ruling setting for right of cell
angle | angle of text (0, 90, 180, 270)
HTML only: |
nowrap | disable word wrap for this cell
Special: |
sdf | treat the cell text as SDF (rather than as phrase text)
tag | phrase tag to apply to cell text
paratag | paragraph style to apply to cell text

For PS (i.e. MIF) generation, the supported colour values are Black, White, Red, Green, Blue, Yellow, Cyan and Magenta. If a different colour is specified, it is ignored. The supported fill values are 100, 90, 70, 50, 30, 10 and 3. If a fill value is not specified, 100% fill is used.

For HTML generation, any of the HTML colours names (including those supported for PS generation) or the "#rrggbb" form can be used.

The permitted ruling values are Vthin, Thin, Medium, Thick and Double.

The sdf, tag and paratag attributes control the way in which the cell text is converted to SDF:

1. If sdf is set, the cell text is already SDF.
2. Otherwise if tag is set, the SDF paragraph is paratag:{{tag:text}}.
3. Otherwise, the paragraph is paratag:text.

tag is usually set via the tags or groups parameters of the table filter.

Note: paratag is not yet implemented.