%TABLEFORMAT provides a template for the display of values extracted from a FormQueryPlugin query (like the old Fortran 'format' statement).
Parameter Description
name Required, gives the name of the format for use in %SHOWQUERY or another %FORMQUERY
format Required, gives the format of the body rows (or the format to subclass)
header Optional, gives the format of the header row
separator Optional, separate rows with this (default newline)
footer Optional, gives the string to use to terminate the table
sort Optional, defines the sort order
help Optional, if present then a helpful message will be output for undefined fields. So if you see a table entry that is blank and you don;t think it should be, add the help parameter and it should give some guidance.
moan Optional, "on" or "off", if set to "off" disables error output

The header, footer and format parameters are very similar in application to the parameters used in the standard %SEARCH Foswiki command. For the uninitiated, the header is used to define the first row of the results table:

header="| *Topic* | *Summary* |"
header="<table><tr><th>Topic</th><th>Summary</th></tr> |"

The format parameter is overloaded so it can also be used to refer to a table format previously defined using %TABLEFORMAT. This allows you to derive new formats (e.g. with different sort orders) For example,
%TABLEFORMAT{ name=TBLFMT format="|$topic|" sort="Owner,Priority"}%
%TABLEFORMAT{ name=SUBFMT format=TBLFMT sort="Priority,Owner" }%
Any of the header, footer or sort parameters in the referenced table format can be overridden by giving new values in the %SHOWQUERY.

The footer is usually only used for tables generated directly in HTML, in which case it is usually set to footer="</table>"


The format is used to define the rows in the body of the table:

format="| $topic | $Summary |"

Any fields in the form in the topic can be output by putting a $ sign before the name of the field. The two special fields $topic and $form are available for outputting the name of the topic and the type of the form. You can also refer to fields in related topics using the syntax $field.field where $field is the name of the relation and field is a field in the related topic; for example, format="|$Child_of.topic|".

The following special variables can be used in the format string:

Name: Expands To:
$web Name of the web
$topic Topic name
$topic(20) Topic name, "- " hyphenated each 20 characters
$topic(30, -<br />) Topic name, hyphenated each 30 characters with separator "-<br />"
$topic(40, ...) Topic name, shortended to 40 characters with "..." indication
$parent Name of parent topic; empty if not set
$parent(20) Name of parent topic, same hyphenation/shortening like $topic()
$text Formatted topic text.
$locked LOCKED flag (if any)
$date Time stamp of last topic update, e.g. 25 Mar 2023 - 14:37
$isodate Time stamp of last topic update, e.g. 2023-03-25T14:37Z
$rev Number of last topic revision, e.g. 1.4
$username Login name of last topic update, e.g. jsmith
$wikiname Wiki user name of last topic update, e.g. JohnSmith
$wikiusername Wiki user name of last topic update, like Main.JohnSmith
$createdate Time stamp of topic revision 1.1
$createusername Login name of topic revision 1.1, e.g. jsmith
$createwikiname Wiki user name of topic revision 1.1, e.g. JohnSmith
$createwikiusername Wiki user name of topic revision 1.1, e.g. Main.JohnSmith
$summary Topic summary, with 162 characters
$summary(50) Topic summary, with 50 characters
$summary(showvarnames) Topic summary, with %ALLTWIKI{...}% variables shown as ALLTWIKI{...}
$summary(noheader) Topic summary, with leading ---+ headers removed
Note: The tokens can be combined into a comma separated list like $summary(100, showvarnames, noheader)
$formname The name of the form attached to the topic; empty if none
$formfield(name) The field value of a form field; for example, $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a DataForm. An alternative to using the name of the field directly.
$formfield(name, 10) Form field value, "- " hyphenated each 10 characters
$formfield(name, 20, -<br />) Form field value, hyphenated each 20 characters with separator "-<br />"
$formfield(name, 30, ...) Form field value, shortended to 30 characters with "..." indication
$pattern(reg-exp) A regular expression pattern to extract some text from the topic text (does not search meta data; use fields instead).
• Specify a RegularExpression that covers the whole text (topic or line), which typically starts with .*, and must end in .*
• Put text you want to keep in parenthesis, like $pattern(.*?(from here.*?to here).*)
• Example: $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ...
• This example has non-greedy .*? patterns to scan for the first occurance of the Email bullet; use greedy .* patterns to scan for the last occurance
• Limitation: Do not use .*) inside the pattern, e.g. $pattern(.*foo(.*)bar.*) does not work, but $pattern(.*foo(.*?)bar.*) does
• Note: Make sure that the integrity of a web page is not compromised; for example, if you include an HTML table make sure to include everything including the table end tag
$formatTime(<formfield-accessor> [,<format>]) format the datefield pointed to by the <formfield-accessor> using the given <format>; the format can be in any form supported by Foswiki::Func::formatTime() (see Macros).
$n or $n() New line
$nop or $nop() Is a "no operation". This variable gets removed; useful for nested search
$quot Double quote ("). Alternatively, write \" to escape it.
$percnt Percent sign (%)
$dollar Dollar sign ($)

It is also possible to expand the contents of tables embedded in the topic, in two ways:
  • using the syntax $field[format=FORMAT] where $field is the table type, which is named the same as the table topic, and FORMAT is the name of a format previously defined using %TABLEFORMAT and suitable for expanding the sub-table.
  • using the syntax $field.subfield where subfield is a numeric field in the contents of the embedded table (i.e. it contains a number). In this case the result will be the sum of all subfield values over all the rows in the table.

sort is used to define the sort order, and is a list of field names (without $'s) separated by commas. You can reverse the sort order for a column by prepending '-' to the field name. For example,


The default sort method is string comparison. If the field data is numeric, then you can put a '#' in front of the field name to force the sort to be numeric. For example,




%TABLEFORMAT is silent i.e. it produces no output on the page unless there is an error, in which case a descriptive error message is output. This message can be disabled using the moan parameter.

Topic revision: r1 - 17 Nov 2009, CrawfordCurrie
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy