[Rt-commit] rt branch, 4.0/format-strings, created. rt-4.0.23-23-g574830a
Alex Vandiver
alexmv at bestpractical.com
Fri Apr 17 13:59:48 EDT 2015
The branch, 4.0/format-strings has been created
at 574830a4690af7c5881282f9753442f85b572fa2 (commit)
- Log -----------------------------------------------------------------
commit 574830a4690af7c5881282f9753442f85b572fa2
Author: Alex Vandiver <alexmv at bestpractical.com>
Date: Fri Apr 17 13:56:32 2015 -0400
Document format strings
diff --git a/docs/format-strings.pod b/docs/format-strings.pod
new file mode 100644
index 0000000..1757a87
--- /dev/null
+++ b/docs/format-strings.pod
@@ -0,0 +1,233 @@
+=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__' } );
+
+
+=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 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
-----------------------------------------------------------------------
More information about the rt-commit
mailing list