| Martin Fick | b7f3b2d | 2010-07-23 10:23:03 -0600 | [diff] [blame^] | 1 | Gerrit Code Review - Mail Templates |
| 2 | =================================== |
| 3 | |
| 4 | Gerrit uses velocity templates for the bulk of the standard mails it sends out. |
| 5 | There are builtin default templates which are used if they are not overridden. |
| 6 | These defaults are also provided as examples so that administrators may copy |
| 7 | them and easily modify them to tweak their contents. |
| 8 | |
| 9 | |
| 10 | Template Locations and Extensions: |
| 11 | ---------------------------------- |
| 12 | |
| 13 | The default example templates reside under: `'$site_path'/etc/mail` and are |
| 14 | terminated with the double extension `.vm.example`. Modifying these example |
| 15 | files will have no effect on the behavior of Gerrit. However, copying an |
| 16 | example template to an equivalently named file without the `.example` extension |
| 17 | and modifying it will allow an administrator to customize the template. |
| 18 | |
| 19 | |
| 20 | Supported Mail Templates: |
| 21 | ------------------------- |
| 22 | |
| 23 | Each mail that Gerrit sends out is controlled by at least one template, these |
| 24 | are listed below. Change emails are influenced by two additional templates, |
| 25 | one to set the subject line, and one to set the footer which gets appended to |
| 26 | all the change emails (see `ChangeSubject.vm` and `ChangeFooter.vm` below.) |
| 27 | |
| 28 | ChangeSubject.vm |
| 29 | ~~~~~~~~~~~~~~~~ |
| 30 | |
| 31 | The `ChangeSubject.vm` template will determine the contents of the email |
| 32 | subject line for ALL emails related to changes. |
| 33 | |
| 34 | |
| 35 | Mail Variables and Methods |
| 36 | -------------------------- |
| 37 | |
| 38 | Mail templates can access and display objects currently made available to them |
| 39 | via the velocity context. While the base objects are documented here, it is |
| 40 | possible to call public methods on these objects from templates. Those methods |
| 41 | are not documented here since they could change with every release. As these |
| 42 | templates are meant to be modified only by a qualified sysadmin, it is accepted |
| 43 | that writing templates for Gerrit emails is likely to require some basic |
| 44 | knowledge of the class structure to be useful. Browsing the source code might |
| 45 | be necessary for anything more than a minor formatting change. |
| 46 | |
| 47 | Warning |
| 48 | ~~~~~~~ |
| 49 | |
| 50 | Be aware that modifying templates can cause them to fail to parse and therefor |
| 51 | not send out the actual email, or worse, calling methods on the available |
| 52 | objects could have internal side effects which would adversely affect the |
| 53 | health of your Gerrit server and/or data. |
| 54 | |
| 55 | All OutgoingEmails |
| 56 | ~~~~~~~~~~~~~~~~~~ |
| 57 | |
| 58 | All outgoing emails have the following variables available to them: |
| 59 | |
| 60 | $email:: |
| 61 | + |
| 62 | A reference to the class constructing the current `OutgoingEmail`. With this |
| 63 | reference it is possible to call any public method on the OutgoingEmail class |
| 64 | or the current child class inherited from it. |
| 65 | |
| 66 | $messageClass:: |
| 67 | + |
| 68 | A String containing the messageClass |
| 69 | |
| 70 | $StringUtils:: |
| 71 | + |
| 72 | A reference to the Apache `StringUtils` class. This can be very useful for |
| 73 | formatting strings. |
| 74 | |
| 75 | Change Emails |
| 76 | ~~~~~~~~~~~~~ |
| 77 | |
| 78 | All change related emails have the following additional variables available to them: |
| 79 | |
| 80 | $change:: |
| 81 | + |
| 82 | A reference to the current `Change` object |
| 83 | |
| 84 | $changeId:: |
| 85 | + |
| 86 | Id of the current change (a `Change.Key`) |
| 87 | |
| 88 | $coverLetter:: |
| 89 | + |
| 90 | The text of the `ChangeMessage` |
| 91 | |
| 92 | $branch:: |
| 93 | + |
| 94 | A reference to the branch of this change (a `Branch.NameKey`) |
| 95 | |
| 96 | $fromName:: |
| 97 | + |
| 98 | The name of the from user |
| 99 | |
| 100 | $projectName:: |
| 101 | + |
| 102 | The name of this change's project |
| 103 | |
| 104 | $patchSet:: |
| 105 | + |
| 106 | A reference to the current `PatchSet` |
| 107 | |
| 108 | $patchSetInfo:: |
| 109 | + |
| 110 | A reference to the current `PatchSetInfo` |
| 111 | |
| 112 | |
| 113 | See Also |
| 114 | -------- |
| 115 | |
| 116 | * link:http://velocity.apache.org/[velocity] |
| 117 | |
| 118 | GERRIT |
| 119 | ------ |
| 120 | Part of link:index.html[Gerrit Code Review] |
