"Format strings" are how RT specifies the layout of tables of data; allowing the user to choose which columns are used, as well as how they are formatted, and optionally linked.
They are used by a number of core options, including:
$DefaultSearchResultFormat
$DefaultSelfServiceSearchResultFormat
$MoreAboutRequestorTicketListFormat
$MoreAboutRequestorExtraInfo
$UserSearchResultFormat
$UserSummaryExtraInfo
$UserSummaryTicketListFormat
%AdminSearchResultFormat
...as well as by all ticket searches.
Format strings are comma-separated lists of single-quoted strings. Since they're quoted strings of quoted strings, to prevent having to escape all of the quotes, they often use the qq{ ... }
operator in Perl, which is just a fancy set of double-quotes. For instance:
Set( $DefaultSearchResultFormat, "'__id__','__Status__');
...is the same as:
Set( $DefaultSearchResultFormat, qq{ '__id__','__Status__' } );
...except that it becomes easier to use double-quote characters.
Pieces that can go inside of each quoted section of a format string include:
__id__
If a property name is surrounded by double-underscores, the property name is used for the title of the column, and each row includes the value of that property.
If the only contents of the element is a double-underscored name, the quotes and underscores can be omitted. That is, the format:
'__id__', '__Subject__'
..can also be written:
id, Subject
HTML formatting can be included, which will by default be included in the column title as well as each row. For instance, the format:
'<i>__Owner__</i>'
...will render as:
Owner |
---|
Alice |
Bob |
Charlie |
__NEWLINE__
Used to wrap the format onto a new line. This means that each result in the list will be formatted on two lines. For example, the format:
'__id__', '__Subject__', '__NEWLINE__', '__Status__', '__QueueName__'
...will render a three-ticket set of results as:
# | Subject |
---|---|
Status | Queue |
1 | Broken laptop |
open | General |
2 | Missing caps lock |
open | General |
3 | Cracked screen |
new | General |
The number of columns shown will be padded to the width of the widest of the rows.
__NBSP__
Renders as an empty cell.
/TITLE:...
Given at the end of a format string, sets the column title to what follows the colon. The following format string:
'__id__', '__Subject__/TITLE:Favorite Color'
...will render as (assuming the tickets have ticket subjects of colors):
# | Favorite Color |
---|---|
1 | Blue |
2 | Green |
3 | Orange |
/SPAN:...
Given at the end of a format string, sets the column span of the given column; this is only of use if __NEWLINE__
is in use. This can be used to merge columns into wider columns for more efficient use of space. The following format string:
'__Subject__/SPAN:2', '__NEWLINE__', '__Status__', '__Queue__'
...will render as:
Subject | |
---|---|
Status | Queue |
Broken laptop | |
open | General |
Missing caps lock | |
open | General |
Cracked screen | |
new | General |
/CLASS:...
Apply an arbitrary CSS class to the column heading and data cells.
/STYLE:...
Apply an arbitrary set of CSS styles to the column heading and data cells.
/ALIGN:...
Sets the alignment of the column heading and data cells.