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

← Back to index