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