d61542de1c5214484847c7d106eca912dd8d6b15
[usit-rt.git] / 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>.
133
134 =item $TransactionType
135
136 =item $TransactionField
137
138 =item $TransactionOldValue
139
140 =item $TransactionNewValue
141
142 =item $TransactionData
143
144 =item $TransactionContent
145
146 =item $TransactionDescription
147
148 =item $TransactionBriefDescription
149
150 =item $TransactionCF(Name)
151
152 For example, C<$TransactionCFLocation>.
153
154 =back
155
156 =head2 Templates Provided with RT
157
158 RT comes with a set of templates for the default notifications. As you start to
159 customize your templates, these templates are a good place to look for
160 examples. As you customize, it can be helpful to create new templates and
161 update your scrips to reference your new templates. This leaves the original RT
162 templates in place for easy reference.
163
164 Starting in RT 4.2, each template has a plain text version and an HTML
165 version. For example, the "Correspondence" template is the plain text version
166 of the default template for correspondence (replies) and the "Correspondence in
167 HTML" template is the same template formatted in HTML. The 4.2 upgrade provides
168 a C<switch-templates-to> script to switch all default templates from plain text
169 to HTML or the reverse. See the L<UPGRADING-4.2> notes for details.
170
171 =cut
172