TABLEFORMAT

%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> |"
footer="</table>"

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>"

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. 20 Apr 2024 - 13:44
$isodate	Time stamp of last topic update, e.g. 2024-04-20T13:44Z
$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,

sort="Owner,-Priority"

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,

sort="Owner,#Priority"

or

sort="Owner,-#Priority"

%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.

See also: FormQueryPlugin, %SUMFIELD%, %FORMQUERY%, %QUERYTOCALC%, %TABLEFORMAT%, %SHOWCALC%, %MATCHCOUNT%, %SHOWQUERY%