• 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

Custom fields

If you have created custom fields applied to tickets, you can refer to them using CF. . For example, if you have a custom field named Component, you could use a format like:

    '__id__', '__Subject__', 'CF.Component'

or:

    '__id__', '__Subject__', '__CustomField.{Component}__'

Alternatively, you can use the custom field's numeric ID instead of its name. This is mostly useful if you have multiple custom fields with the same name and you need to disambiguate.

    '__id__', '__Subject__', 'CF.3'

    '__id__', '__Subject__', '__CustomField.{3}__'

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.