• Formats
  • Structure
  • Elements

Formats

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

Structure

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.

Elements

Pieces that can go inside of each quoted section of a format string include:

Column name surrounded by double-underscores: __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

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.