docs/customizing/templates.pod

   1 =head1 Templates
   2
   3 Each template is split into two sections. A block of headers and a body. These
   4 sections are separated by a blank line.
   5
   6 Templates are processed by the L<Text::Template> module. This module
   7 allows you to embed arbitrary Perl code into your templates. Text wrapped
   8 in curly braces, C<{...}> is interpreted as Perl. See L<Text::Template>
   9 for more information.
  10
  11 =head2 Headers
  12
  13 Your template may specify arbitrary email headers. Each header is a name, a
  14 colon, then a value. So, for example, to specify a subject, you can use:
  15
  16     Subject: Thanks for your bug report.
  17
  18 =head3 Special Headers
  19
  20 =over
  21
  22 =item Content-Type: text/html
  23
  24 The special header "Content-Type: text/html" tells RT that the template should
  25 be parsed as HTML. RT will automatically make the outgoing message multipart.
  26 That way, recipients who can read only plaintext email will receive something
  27 readable, while users with clients which can display HTML will receive the full
  28 experience. Please be aware that HTML support in mail clients varies greatly,
  29 much more so than different web browsers.
  30
  31 We welcome contributions of HTML-ization of builtin templates.
  32
  33 =back
  34
  35 =head2 Template Types
  36
  37 Templates have a Type which dictates which level of code execution is
  38 allowed.
  39
  40 Templates of type C<Perl> are evaluated using L<Text::Template>
  41 which allows arbitrary code execution. Only users which have the global
  42 C<ExecuteCode> privilege may write templates of type C<Perl>. Prior to
  43 RT 4.0, this was the only type of Template available.
  44
  45 Templates of type C<Simple> permit only simple variable interpolation.
  46 No special privilege beyond C<ModifyTemplate> is needed to write C<Simple>
  47 templates.
  48
  49 For both types of templates, text between curly braces C<{ ... }> is
  50 interpolated. For C<Perl> templates, this text can be any code (see
  51 L<Text::Template/Details>). For C<Simple> templates, only simple variables
  52 are permitted; for example C<{ $TicketSubject }>.
  53
  54 =head2 Variables
  55
  56 =head3 Perl templates
  57
  58 The variables that your templates may use include:
  59
  60 =over 4
  61
  62 =item C<$Transaction>
  63
  64 The transaction object.
  65
  66 =item C<$rtname>
  67
  68 The value of the "rtname" config variable.
  69
  70 =item C<$Ticket>
  71
  72 The ticket object. This is only set during a ticket transaction.
  73
  74 =item C<$Requestor>
  75
  76 This is not an object, but the name of the first requestor on the ticket.
  77 If this is not what you need, inspect C<< $Ticket->Requestors >>.
  78
  79 =item C<loc("text")>
  80
  81 A localization function. See L<Locale::Maketext>.
  82
  83 =back
  84
  85 =head3 Selected Simple template variables
  86
  87 Since method calls are not allowed in simple templates, many common
  88 method results have been placed into scalar variables for the template's
  89 use.  Among them:
  90
  91 =over 4
  92
  93 =item $TicketId
  94
  95 =item $TicketSubject
  96
  97 =item $TicketStatus
  98
  99 =item $TicketQueueName
 100
 101 =item $TicketOwnerName
 102
 103 =item $TicketOwnerEmailAddress
 104
 105 =item $TicketCF(Name)
 106
 107 For example, C<$TicketCFDepartment>.
 108
 109 =item $TransactionType
 110
 111 =item $TransactionField
 112
 113 =item $TransactionOldValue
 114
 115 =item $TransactionNewValue
 116
 117 =item $TransactionData
 118
 119 =item $TransactionContent
 120
 121 =item $TransactionDescription
 122
 123 =item $TransactionBriefDescription
 124
 125 =item $TransactionCF(Name)
 126
 127 For example, C<$TransactionCFLocation>.
 128
 129 =back
 130
 131 =cut
 132