rt/docs/customizing/templates.pod

   1 =head1 Templates
   2
   3 Templates are used in RT to send notifications, typically email. You have
   4 access to RT data via variables available to you in the scope of the template.
   5 Templates can also be used for some special actions like creating a new ticket
   6 as part of the execution of a scrip.
   7
   8 Each template is split into two sections: a block of headers and a body. These
   9 sections are separated by a blank line. Blank lines are not allowed before
  10 the headers, but can be included in the body as needed after the headers
  11 section.
  12
  13 Templates are processed by the L<Text::Template> module. This module
  14 allows you to embed arbitrary Perl code into your templates. Text wrapped
  15 in curly braces, C<{...}> is interpreted as Perl. See L<Text::Template>
  16 for more information.
  17
  18 =head2 Headers
  19
  20 Your template may specify arbitrary email headers. Each header is a name, a
  21 colon, then a value. So, for example, to specify a subject, you can use:
  22
  23     Subject: Thanks for your bug report.
  24
  25 =head3 Special Headers
  26
  27 =over
  28
  29 =item RT-Attach-Message: yes
  30
  31 This special header tells RT that any attachments that were added in the
  32 original message should also be included in the email notification going out.
  33
  34 =item Content-Type: text/html
  35
  36 The special header "Content-Type: text/html" tells RT that the template should
  37 be parsed as HTML. RT will automatically make the outgoing message multipart.
  38 That way, recipients who can read only plaintext email will receive something
  39 readable, while users with clients which can display HTML will receive the full
  40 experience. Please be aware that HTML support in mail clients varies greatly,
  41 much more so than different web browsers.
  42
  43 Starting in RT 4.2, HTML templates are included along with plain text templates
  44 for the standard RT notifications.
  45
  46 =back
  47
  48 =head2 Template Types
  49
  50 Templates have a Type which dictates the level of code execution allowed.
  51
  52 Templates of type C<Perl> are evaluated using L<Text::Template>
  53 which allows arbitrary code execution. Only users with the global
  54 C<ExecuteCode> privilege may write templates of type C<Perl>. Prior to
  55 RT 4.0, this was the only type of Template available.
  56
  57 Templates of type C<Simple> permit only simple variable interpolation.
  58 No special privilege beyond C<ModifyTemplate> is needed to write C<Simple>
  59 templates.
  60
  61 For both types of templates, text between curly braces C<{ ... }> is
  62 interpolated. For C<Perl> templates, this text can be any code (see
  63 L<Text::Template/Details>). For C<Simple> templates, only simple variables
  64 are permitted; for example C<{ $TicketSubject }>.
  65
  66 =head2 Variables
  67
  68 =head3 Perl templates
  69
  70 The variables that your templates may use include:
  71
  72 =over 4
  73
  74 =item C<$Transaction>
  75
  76 The transaction object.
  77
  78 =item C<$rtname>
  79
  80 The value of the "rtname" config variable.
  81
  82 =item C<$Ticket>
  83
  84 The ticket object. This is only set during a ticket transaction.
  85
  86 =item C<$Requestor>
  87
  88 This is not an object, but the name of the first requestor on the ticket.
  89 If this is not what you need, inspect C<< $Ticket->Requestors >>.
  90
  91 =item C<loc("text")>
  92
  93 A localization function. See L<Locale::Maketext>.
  94
  95 =back
  96
  97 The C<$Transaction> and C<$Ticket> objects are particularly useful. For
  98 example, here are some values you can get from each:
  99
 100     $Ticket->Status      # Current status
 101     $Ticket->Owner       # Current owner
 102     $Ticket->FirstCustomFieldValue('CustomFieldName') # CF value
 103     $Ticket->DueAsString # Current due date as a string
 104     $Ticket->DueObj      # Due as an RT::Date object
 105     $Ticket->QueueObj    # Queue object for this ticket
 106
 107     $Transaction->Type     # Type of transaction
 108     $Transaction->OldValue # Previous value, if type is Set
 109     $Transaction->NewValue # New value, if type is Set
 110     $Transaction->CreatorObj->EmailAddress # Email address of trans creator
 111
 112 You can see the methods available in the L<RT::Ticket> and L<RT::Transaction>
 113 documentation.
 114
 115 =head3 Selected Simple template variables
 116
 117 Since method calls are not allowed in simple templates, many common
 118 method results have been placed into scalar variables for the template's
 119 use.  Among them:
 120
 121 =over 4
 122
 123 =item $TicketId
 124
 125 =item $TicketSubject
 126
 127 =item $TicketStatus
 128
 129 =item $TicketQueueName
 130
 131 =item $TicketOwnerName
 132
 133 =item $TicketOwnerEmailAddress
 134
 135 =item $TicketCF(Name)
 136
 137 For example, C<$TicketCFDepartment>.  For CFs with more complicated
 138 names, all non-word characters (anything that is not letters, numbers,
 139 or underscores) are stripped to determine the appropriate variable name.
 140
 141 =item $TransactionType
 142
 143 =item $TransactionField
 144
 145 =item $TransactionOldValue
 146
 147 =item $TransactionNewValue
 148
 149 =item $TransactionData
 150
 151 =item $TransactionContent
 152
 153 =item $TransactionDescription
 154
 155 =item $TransactionBriefDescription
 156
 157 =item $TransactionCF(Name)
 158
 159 For example, C<$TransactionCFLocation>.
 160
 161 =back
 162
 163 =head2 Templates Provided with RT
 164
 165 RT comes with a set of templates for the default notifications. As you start to
 166 customize your templates, these templates are a good place to look for
 167 examples. As you customize, it can be helpful to create new templates and
 168 update your scrips to reference your new templates. This leaves the original RT
 169 templates in place for easy reference.
 170
 171 Starting in RT 4.2, each template has a plain text version and an HTML
 172 version. For example, the "Correspondence" template is the plain text version
 173 of the default template for correspondence (replies) and the "Correspondence in
 174 HTML" template is the same template formatted in HTML. The 4.2 upgrade provides
 175 a C<switch-templates-to> script to switch all default templates from plain text
 176 to HTML or the reverse. See the L<UPGRADING-4.2> notes for details.
 177
 178 =cut
 179