Putting 4.2.0 on top of 4.0.17
[usit-rt.git] / docs / customizing / templates.pod
index 5733f60..d61542d 100644 (file)
@@ -1,7 +1,14 @@
 =head1 Templates
 
-Each template is split into two sections. A block of headers and a body. These
-sections are separated by a blank line.
+Templates are used in RT to send notifications, typically email. You have
+access to RT data via variables available to you in the scope of the template.
+Templates can also be used for some special actions like creating a new ticket
+as part of the execution of a scrip.
+
+Each template is split into two sections: a block of headers and a body. These
+sections are separated by a blank line. Blank lines are not allowed before
+the headers, but can be included in the body as needed after the headers
+section.
 
 Templates are processed by the L<Text::Template> module. This module
 allows you to embed arbitrary Perl code into your templates. Text wrapped
@@ -28,17 +35,17 @@ readable, while users with clients which can display HTML will receive the full
 experience. Please be aware that HTML support in mail clients varies greatly,
 much more so than different web browsers.
 
-We welcome contributions of HTML-ization of builtin templates.
+Starting in RT 4.2, HTML templates are included along with plain text templates
+for the standard RT notifications.
 
 =back
 
 =head2 Template Types
 
-Templates have a Type which dictates which level of code execution is
-allowed.
+Templates have a Type which dictates the level of code execution allowed.
 
 Templates of type C<Perl> are evaluated using L<Text::Template>
-which allows arbitrary code execution. Only users which have the global
+which allows arbitrary code execution. Only users with the global
 C<ExecuteCode> privilege may write templates of type C<Perl>. Prior to
 RT 4.0, this was the only type of Template available.
 
@@ -82,6 +89,24 @@ A localization function. See L<Locale::Maketext>.
 
 =back
 
+The C<$Transaction> and C<$Ticket> objects are particularly useful. For
+example, here are some values you can get from each:
+
+    $Ticket->Status      # Current status
+    $Ticket->Owner       # Current owner
+    $Ticket->FirstCustomFieldValue('CustomFieldName') # CF value
+    $Ticket->DueAsString # Current due date as a string
+    $Ticket->DueObj      # Due as an RT::Date object
+    $Ticket->QueueObj    # Queue object for this ticket
+
+    $Transaction->Type     # Type of transaction
+    $Transaction->OldValue # Previous value, if type is Set
+    $Transaction->NewValue # New value, if type is Set
+    $Transaction->CreatorObj->EmailAddress # Email address of trans creator
+
+You can see the methods available in the L<RT::Ticket> and L<RT::Transaction>
+documentation.
+
 =head3 Selected Simple template variables
 
 Since method calls are not allowed in simple templates, many common
@@ -128,5 +153,20 @@ For example, C<$TransactionCFLocation>.
 
 =back
 
+=head2 Templates Provided with RT
+
+RT comes with a set of templates for the default notifications. As you start to
+customize your templates, these templates are a good place to look for
+examples. As you customize, it can be helpful to create new templates and
+update your scrips to reference your new templates. This leaves the original RT
+templates in place for easy reference.
+
+Starting in RT 4.2, each template has a plain text version and an HTML
+version. For example, the "Correspondence" template is the plain text version
+of the default template for correspondence (replies) and the "Correspondence in
+HTML" template is the same template formatted in HTML. The 4.2 upgrade provides
+a C<switch-templates-to> script to switch all default templates from plain text
+to HTML or the reverse. See the L<UPGRADING-4.2> notes for details.
+
 =cut