Upgrade to 4.0.8 with mod of ExternalAuth + absolute paths to ticket-menu.
[usit-rt.git] / 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