=for html
<style>
table.example { margin-left: auto; margin-right: auto; min-width: 25%; border-collapse: collapse; }
table.example           td,
table.example           th { margin: 0; padding: 0.25em 1em; }
table.example td + td,
table.example th + th      { border-left: 1px dotted black; }
table.example           th { border-bottom: 2px solid black; text-align: left; }
table.example tr.none   th { border-bottom: none; }
table.example tr.bottom td { border-bottom: 1px dotted black; }
</style>

=head1 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:

=over

=item *

C<$DefaultSearchResultFormat>

=item *

C<$DefaultSelfServiceSearchResultFormat>

=item *

C<$MoreAboutRequestorTicketListFormat>

=item *

C<$MoreAboutRequestorExtraInfo>

=item *

C<$UserSearchResultFormat>

=item *

C<$UserSummaryExtraInfo>

=item *

C<$UserSummaryTicketListFormat>

=item *

C<%AdminSearchResultFormat>

=item *

...as well as by all ticket searches.

=back

=head2 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 C<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.

=head2 Elements

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

=over

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

=item Custom fields

If you have created custom fields applied to tickets, you can refer to
them using C< CF. >. For example, if you have a custom field named
C<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}__'

=item 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:

=for html
<table class="example"><tr><th><i>Owner</i></th></tr>
<tr><td><i>Alice</i></td></tr>
<tr><td><i>Bob</i></td></tr>
<tr><td><i>Charlie</i></td></tr>
</table>

=begin text

      /Owner/
    -----------
      /Alice/
      /Bob/
      /Charlie/

=end text

=item C<__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:

=for html
<table class="example"><tr class="none"><th>#</th><th>Subject</th></tr><tr><th>Status</th><th>Queue</th></tr>
<tr><td>1</td><td>Broken laptop</td></tr><tr class="bottom"><td>open</td><td>General</td></tr>
<tr><td>2</td><td>Missing caps lock</td></tr><tr class="bottom"><td>open</td><td>General</td></tr>
<tr><td>3</td><td>Cracked screen</td></tr><tr class="bottom"><td>new</td><td>General</td></tr></table>

=begin text

      #      | Subject
      Status | Queue
    =========+====================
      1      | Broken laptop
      open   | General
    ---------+--------------------
      2      | Missing caps lock
      open   | General
    ---------+--------------------
      3      | Cracked screen
      new    | General

=end text

The number of columns shown will be padded to the width of the widest of
the rows.

=item C<__NBSP__>

Renders as an empty cell.

=item C</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):

=for html
<table class="example"><tr><th>#</th><th>Favorite Color</th></tr>
<tr><td>1</td><td>Blue</td></tr>
<tr><td>2</td><td>Green</td></tr>
<tr><td>3</td><td>Orange</td></tr></table>

=begin text

      #  |  Favorite Color
    -----+------------------
      1  |  Blue
      2  |  Green
      3  |  Orange

=end text

=item C</SPAN:...>

Given at the end of a format string, sets the column span of the given
column; this is only of use if C<__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:

=for html
<table class="example"><tr><th colspan="2">Subject</th></tr><tr><th>Status</th><th>Queue</th></tr>
<tr><td colspan="2">Broken laptop</td></tr><tr class="bottom"><td>open</td><td>General</td></tr>
<tr><td colspan="2">Missing caps lock</td></tr><tr class="bottom"><td>open</td><td>General</td></tr>
<tr><td colspan="2">Cracked screen</td></tr><tr class="bottom"><td>new</td><td>General</td></tr></table>

=begin text

      #      | Subject
      Status | Queue
    =========+===========
      Broken laptop
      open   | General
    ---------+-----------
      Missing caps lock
      open   | General
    ---------+-----------
      Cracked screen
      new    | General

=end text

=item C</CLASS:...>

Apply an arbitrary CSS class to the column heading and data cells.

=item C</STYLE:...>

Apply an arbitrary set of CSS styles to the column heading and data cells.

=item C</ALIGN:...>

Sets the alignment of the column heading and data cells.

=back

=cut
