Use templates for issue e-mail subject and body (#8329)
* Add template capability for issue mail subject * Remove test string * Fix trim subject length * Add comment to template and run make fmt * Add information for the template * Rename defaultMailSubject() to fallbackMailSubject() * General rewrite of the mail template code * Fix .Doer name * Use text/template for subject instead of html * Fix subject Re: prefix * Fix mail tests * Fix static templates * [skip ci] Updated translations via Crowdin * Expose db.SetMaxOpenConns and allow non MySQL dbs to set conn pool params (#8528) * Expose db.SetMaxOpenConns and allow other dbs to set their connection params * Add note about port exhaustion Co-Authored-By: guillep2k <18600385+guillep2k@users.noreply.github.com> * Prevent .code-view from overriding font on icon fonts (#8614) * Correct some outdated statements in the contributing guidelines (#8612) * More information for drone-cli in CONTRIBUTING.md * Increases the version of drone-cli to 1.2.0 * Adds a note for the Docker Toolbox on Windows Signed-off-by: LukBukkit <luk.bukkit@gmail.com> * Fix the url for the blog repository (now on gitea.com) Signed-off-by: LukBukkit <luk.bukkit@gmail.com> * Remove TrN due to lack of lang context * Redo templates to match previous code * Fix extra character in template * Unify PR & Issue tempaltes, fix format * Remove default subject * Add template tests * Fix template * Remove replaced function * Provide User as models.User for better consistency * Add docs * Fix doc inaccuracies, improve examples * Change mail footer to math AppName * Add test for mail subject/body template separation * Add support for code review comments * Update docs/content/doc/advanced/mail-templates-us.md Co-Authored-By: 6543 <24977596+6543@users.noreply.github.com>tokarchuk/v1.17
guillep2k
5 years ago
committed by
Lunny Xiao
parent
d5b1e6bc51
commit
1f90147f39
@ -0,0 +1,272 @@ |
|||||||
|
--- |
||||||
|
date: "2019-10-23T17:00:00-03:00" |
||||||
|
title: "Mail templates" |
||||||
|
slug: "mail-templates" |
||||||
|
weight: 45 |
||||||
|
toc: true |
||||||
|
draft: false |
||||||
|
menu: |
||||||
|
sidebar: |
||||||
|
parent: "advanced" |
||||||
|
name: "Mail templates" |
||||||
|
weight: 45 |
||||||
|
identifier: "mail-templates" |
||||||
|
--- |
||||||
|
|
||||||
|
# Mail templates |
||||||
|
|
||||||
|
To craft the e-mail subject and contents for certain operations, Gitea can be customized by using templates. The templates |
||||||
|
for these functions are located under the [`custom` directory](https://docs.gitea.io/en-us/customizing-gitea/). |
||||||
|
Gitea has an internal template that serves as default in case there's no custom alternative. |
||||||
|
|
||||||
|
Custom templates are loaded when Gitea starts. Changes made to them are not recognized until Gitea is restarted again. |
||||||
|
|
||||||
|
## Mail notifications supporting templates |
||||||
|
|
||||||
|
Currently, the following notification events make use of templates: |
||||||
|
|
||||||
|
| Action name | Usage | |
||||||
|
|---------------|--------------------------------------------------------------------------------------------------------------| |
||||||
|
| `new` | A new issue or pull request was created. | |
||||||
|
| `comment` | A new comment was created in an existing issue or pull request. | |
||||||
|
| `close` | An issue or pull request was closed. | |
||||||
|
| `reopen` | An issue or pull request was reopened. | |
||||||
|
| `review` | The head comment of a review in a pull request. | |
||||||
|
| `code` | A single comment on the code of a pull request. | |
||||||
|
| `assigned` | Used was assigned to an issue or pull request. | |
||||||
|
| `default` | Any action not included in the above categories, or when the corresponding category template is not present. | |
||||||
|
|
||||||
|
The path for the template of a particular message type is: |
||||||
|
|
||||||
|
``` |
||||||
|
custom/templates/mail/{action type}/{action name}.tmpl |
||||||
|
``` |
||||||
|
|
||||||
|
Where `{action type}` is one of `issue` or `pull` (for pull requests), and `{action name}` is one of the names listed above. |
||||||
|
|
||||||
|
For example, the specific template for a mail regarding a comment in a pull request is: |
||||||
|
``` |
||||||
|
custom/templates/mail/pull/comment.tmpl |
||||||
|
``` |
||||||
|
|
||||||
|
However, creating templates for each and every action type/name combination is not required. |
||||||
|
A fallback system is used to choose the appropriate template for an event. The _first existing_ |
||||||
|
template on this list is used: |
||||||
|
|
||||||
|
* The specific template for the desired **action type** and **action name**. |
||||||
|
* The template for action type `issue` and the desired **action name**. |
||||||
|
* The template for the desired **action type**, action name `default`. |
||||||
|
* The template for action type `issue`, action name `default`. |
||||||
|
|
||||||
|
The only mandatory template is action type `issue`, action name `default`, which is already embedded in Gitea |
||||||
|
unless it's overridden by the user in the `custom` directory. |
||||||
|
|
||||||
|
## Template syntax |
||||||
|
|
||||||
|
Mail templates are UTF-8 encoded text files that need to follow one of the following formats: |
||||||
|
|
||||||
|
``` |
||||||
|
Text and macros for the subject line |
||||||
|
------------ |
||||||
|
Text and macros for the mail body |
||||||
|
``` |
||||||
|
|
||||||
|
or |
||||||
|
|
||||||
|
``` |
||||||
|
Text and macros for the mail body |
||||||
|
``` |
||||||
|
|
||||||
|
Specifying a _subject_ section is optional (and therefore also the dash line separator). When used, the separator between |
||||||
|
_subject_ and _mail body_ templates requires at least three dashes; no other characters are allowed in the separator line. |
||||||
|
|
||||||
|
|
||||||
|
_Subject_ and _mail body_ are parsed by [Golang's template engine](https://golang.org/pkg/text/template/) and |
||||||
|
are provided with a _metadata context_ assembled for each notification. The context contains the following elements: |
||||||
|
|
||||||
|
| Name | Type | Available | Usage | |
||||||
|
|--------------------|----------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
||||||
|
| `.FallbackSubject` | string | Always | A default subject line. See Below. | |
||||||
|
| `.Subject` | string | Only in body | The _subject_, once resolved. | |
||||||
|
| `.Body` | string | Always | The message of the issue, pull request or comment, parsed from Markdown into HTML and sanitized. Do not confuse with the _mail body_ | |
||||||
|
| `.Link` | string | Always | The address of the originating issue, pull request or comment. | |
||||||
|
| `.Issue` | models.Issue | Always | The issue (or pull request) originating the notification. To get data specific to a pull request (e.g. `HasMerged`), `.Issue.PullRequest` can be used, but care should be taken as this field will be `nil` if the issue is *not* a pull request. | |
||||||
|
| `.Comment` | models.Comment | If applicable | If the notification is from a comment added to an issue or pull request, this will contain the information about the comment. | |
||||||
|
| `.IsPull` | bool | Always | `true` if the mail notification is associated with a pull request (i.e. `.Issue.PullRequest` is not `nil`). | |
||||||
|
| `.Repo` | string | Always | Name of the repository, including owner name (e.g. `mike/stuff`) | |
||||||
|
| `.User` | models.User | Always | Owner of the repository from which the event originated. To get the user name (e.g. `mike`),`.User.Name` can be used. | |
||||||
|
| `.Doer` | models.User | Always | User that executed the action triggering the notification event. To get the user name (e.g. `rhonda`), `.Doer.Name` can be used. | |
||||||
|
| `.IsMention` | bool | Always | `true` if this notification was only generated because the user was mentioned in the comment, while not being subscribed to the source. It will be `false` if the recipient was subscribed to the issue or repository. | |
||||||
|
| `.SubjectPrefix` | string | Always | `Re: ` if the notification is about other than issue or pull request creation; otherwise an empty string. | |
||||||
|
| `.ActionType` | string | Always | `"issue"` or `"pull"`. Will correspond to the actual _action type_ independently of which template was selected. | |
||||||
|
| `.ActionName` | string | Always | It will be one of the action types described above (`new`, `comment`, etc.), and will correspond to the actual _action name_ independently of which template was selected. | |
||||||
|
|
||||||
|
All names are case sensitive. |
||||||
|
|
||||||
|
### The _subject_ part of the template |
||||||
|
|
||||||
|
The template engine used for the mail _subject_ is golang's [`text/template`](https://golang.org/pkg/text/template/). |
||||||
|
Please refer to the linked documentation for details about its syntax. |
||||||
|
|
||||||
|
The _subject_ is built using the following steps: |
||||||
|
|
||||||
|
* A template is selected according to the type of notification and to what templates are present. |
||||||
|
* The template is parsed and resolved (e.g. `{{.Issue.Index}}` is converted to the number of the issue |
||||||
|
or pull request). |
||||||
|
* All space-like characters (e.g. `TAB`, `LF`, etc.) are converted to normal spaces. |
||||||
|
* All leading, trailing and redundant spaces are removed. |
||||||
|
* The string is truncated to its first 256 runes (characters). |
||||||
|
|
||||||
|
If the end result is an empty string, **or** no subject template was available (i.e. the selected template |
||||||
|
did not include a subject part), Gitea's **internal default** will be used. |
||||||
|
|
||||||
|
The internal default (fallback) subject is the equivalent of: |
||||||
|
|
||||||
|
``` |
||||||
|
{{.SubjectPrefix}}[{{.Repo}}] {{.Issue.Title}} (#.Issue.Index) |
||||||
|
``` |
||||||
|
|
||||||
|
For example: `Re: [mike/stuff] New color palette (#38)` |
||||||
|
|
||||||
|
Gitea's default subject can also be found in the template _metadata_ as `.FallbackSubject` from any of |
||||||
|
the two templates, even if a valid subject template is present. |
||||||
|
|
||||||
|
### The _mail body_ part of the template |
||||||
|
|
||||||
|
The template engine used for the _mail body_ is golang's [`html/template`](https://golang.org/pkg/html/template/). |
||||||
|
Please refer to the linked documentation for details about its syntax. |
||||||
|
|
||||||
|
The _mail body_ is parsed after the mail subject, so there is an additional _metadata_ field which is |
||||||
|
the actual rendered subject, after all considerations. |
||||||
|
|
||||||
|
The expected result is HTML (including structural elements like`<html>`, `<body>`, etc.). Styling |
||||||
|
through `<style>` blocks, `class` and `style` attributes is possible. However, `html/template` |
||||||
|
does some [automatic escaping](https://golang.org/pkg/html/template/#hdr-Contexts) that should be considered. |
||||||
|
|
||||||
|
Attachments (such as images or external style sheets) are not supported. However, other templates can |
||||||
|
be referenced too, for example to provide the contents of a `<style>` element in a centralized fashion. |
||||||
|
The external template must be placed under `custom/mail` and referenced relative to that directory. |
||||||
|
For example, `custom/mail/styles/base.tmpl` can be included using `{{template styles/base}}`. |
||||||
|
|
||||||
|
The mail is sent with `Content-Type: multipart/alternative`, so the body is sent in both HTML |
||||||
|
and text formats. The latter is obtained by stripping the HTML markup. |
||||||
|
|
||||||
|
## Troubleshooting |
||||||
|
|
||||||
|
How a mail is rendered is directly dependent on the capabilities of the mail application. Many mail |
||||||
|
clients don't even support HTML, so they show the text version included in the generated mail. |
||||||
|
|
||||||
|
If the template fails to render, it will be noticed only at the moment the mail is sent. |
||||||
|
A default subject is used if the subject template fails, and whatever was rendered successfully |
||||||
|
from the the _mail body_ is used, disregarding the rest. |
||||||
|
|
||||||
|
Please check [Gitea's logs](https://docs.gitea.io/en-us/logging-configuration/) for error messages in case of trouble. |
||||||
|
|
||||||
|
## Example |
||||||
|
|
||||||
|
`custom/templates/mail/issue/default.tmpl`: |
||||||
|
|
||||||
|
``` |
||||||
|
[{{.Repo}}] @{{.Doer.Name}} |
||||||
|
{{if eq .ActionName "new"}} |
||||||
|
created |
||||||
|
{{else if eq .ActionName "comment"}} |
||||||
|
commented on |
||||||
|
{{else if eq .ActionName "close"}} |
||||||
|
closed |
||||||
|
{{else if eq .ActionName "reopen"}} |
||||||
|
reopened |
||||||
|
{{else}} |
||||||
|
updated |
||||||
|
{{end}} |
||||||
|
{{if eq .ActionType "issue"}} |
||||||
|
issue |
||||||
|
{{else}} |
||||||
|
pull request |
||||||
|
{{end}} |
||||||
|
#{{.Issue.Index}}: {{.Issue.Title}} |
||||||
|
------------ |
||||||
|
<!DOCTYPE html> |
||||||
|
<html> |
||||||
|
<head> |
||||||
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
||||||
|
<title>{{.Subject}}</title> |
||||||
|
</head> |
||||||
|
|
||||||
|
<body> |
||||||
|
{{if .IsMention}} |
||||||
|
<p> |
||||||
|
You are receiving this because @{{.Doer.Name}} mentioned you. |
||||||
|
</p> |
||||||
|
{{end}} |
||||||
|
<p> |
||||||
|
<p> |
||||||
|
<a href="{{AppURL}}/{{.Doer.LowerName}}">@{{.Doer.Name}}</a> |
||||||
|
{{if not (eq .Doer.FullName "")}} |
||||||
|
({{.Doer.FullName}}) |
||||||
|
{{end}} |
||||||
|
{{if eq .ActionName "new"}} |
||||||
|
created |
||||||
|
{{else if eq .ActionName "close"}} |
||||||
|
closed |
||||||
|
{{else if eq .ActionName "reopen"}} |
||||||
|
reopened |
||||||
|
{{else}} |
||||||
|
updated |
||||||
|
{{end}} |
||||||
|
<a href="{{.Link}}">{{.Repo}}#{{.Issue.Index}}</a>. |
||||||
|
</p> |
||||||
|
{{if not (eq .Body "")}} |
||||||
|
<h3>Message content:</h3> |
||||||
|
<hr> |
||||||
|
{{.Body | Str2html}} |
||||||
|
{{end}} |
||||||
|
</p> |
||||||
|
<hr> |
||||||
|
<p> |
||||||
|
<a href="{{.Link}}">View it on Gitea</a>. |
||||||
|
</p> |
||||||
|
</body> |
||||||
|
</html> |
||||||
|
``` |
||||||
|
|
||||||
|
This template produces something along these lines: |
||||||
|
|
||||||
|
#### Subject |
||||||
|
|
||||||
|
> [mike/stuff] @rhonda commented on pull request #38: New color palette |
||||||
|
|
||||||
|
#### Mail body |
||||||
|
|
||||||
|
> [@rhonda](#) (Rhonda Myers) updated [mike/stuff#38](#). |
||||||
|
> |
||||||
|
> #### Message content: |
||||||
|
> |
||||||
|
> \__________________________________________________________________ |
||||||
|
> |
||||||
|
> Mike, I think we should tone down the blues a little. |
||||||
|
> \__________________________________________________________________ |
||||||
|
> |
||||||
|
> [View it on Gitea](#). |
||||||
|
|
||||||
|
## Advanced |
||||||
|
|
||||||
|
The template system contains several functions that can be used to further process and format |
||||||
|
the messages. Here's a list of some of them: |
||||||
|
|
||||||
|
| Name | Parameters | Available | Usage | |
||||||
|
|----------------------|-------------|-----------|---------------------------------------------------------------------| |
||||||
|
| `AppUrl` | - | Any | Gitea's URL | |
||||||
|
| `AppName` | - | Any | Set from `app.ini`, usually "Gitea" | |
||||||
|
| `AppDomain` | - | Any | Gitea's host name | |
||||||
|
| `EllipsisString` | string, int | Any | Truncates a string to the specified length; adds ellipsis as needed | |
||||||
|
| `Str2html` | string | Body only | Sanitizes text by removing any HTML tags from it. | |
||||||
|
|
||||||
|
These are _functions_, not metadata, so they have to be used: |
||||||
|
|
||||||
|
``` |
||||||
|
Like this: {{Str2html "Escape<my>text"}} |
||||||
|
Or this: {{"Escape<my>text" | Str2html}} |
||||||
|
Or this: {{AppUrl}} |
||||||
|
But not like this: {{.AppUrl}} |
||||||
|
``` |
||||||
@ -0,0 +1,55 @@ |
|||||||
|
// Copyright 2019 The Gitea Authors. All rights reserved.
|
||||||
|
// Use of this source code is governed by a MIT-style
|
||||||
|
// license that can be found in the LICENSE file.
|
||||||
|
|
||||||
|
package templates |
||||||
|
|
||||||
|
import ( |
||||||
|
"testing" |
||||||
|
|
||||||
|
"github.com/stretchr/testify/assert" |
||||||
|
) |
||||||
|
|
||||||
|
func TestSubjectBodySeparator(t *testing.T) { |
||||||
|
test := func(input, subject, body string) { |
||||||
|
loc := mailSubjectSplit.FindIndex([]byte(input)) |
||||||
|
if loc == nil { |
||||||
|
assert.Empty(t, subject, "no subject found, but one expected") |
||||||
|
assert.Equal(t, body, input) |
||||||
|
} else { |
||||||
|
assert.Equal(t, subject, string(input[0:loc[0]])) |
||||||
|
assert.Equal(t, body, string(input[loc[1]:])) |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
test("Simple\n---------------\nCase", |
||||||
|
"Simple\n", |
||||||
|
"\nCase") |
||||||
|
test("Only\nBody", |
||||||
|
"", |
||||||
|
"Only\nBody") |
||||||
|
test("Minimal\n---\nseparator", |
||||||
|
"Minimal\n", |
||||||
|
"\nseparator") |
||||||
|
test("False --- separator", |
||||||
|
"", |
||||||
|
"False --- separator") |
||||||
|
test("False\n--- separator", |
||||||
|
"", |
||||||
|
"False\n--- separator") |
||||||
|
test("False ---\nseparator", |
||||||
|
"", |
||||||
|
"False ---\nseparator") |
||||||
|
test("With extra spaces\n----- \t \nBody", |
||||||
|
"With extra spaces\n", |
||||||
|
"\nBody") |
||||||
|
test("With leading spaces\n -------\nOnly body", |
||||||
|
"", |
||||||
|
"With leading spaces\n -------\nOnly body") |
||||||
|
test("Multiple\n---\n-------\n---\nSeparators", |
||||||
|
"Multiple\n", |
||||||
|
"\n-------\n---\nSeparators") |
||||||
|
test("Insuficient\n--\nSeparators", |
||||||
|
"", |
||||||
|
"Insuficient\n--\nSeparators") |
||||||
|
} |
||||||
@ -1,16 +0,0 @@ |
|||||||
<!DOCTYPE html> |
|
||||||
<html> |
|
||||||
<head> |
|
||||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
|
||||||
<title>{{.Subject}}</title> |
|
||||||
</head> |
|
||||||
|
|
||||||
<body> |
|
||||||
<p>{{.Body | Str2html}}</p> |
|
||||||
<p> |
|
||||||
--- |
|
||||||
<br> |
|
||||||
<a href="{{.Link}}">View it on Gitea</a>. |
|
||||||
</p> |
|
||||||
</body> |
|
||||||
</html> |
|
||||||
@ -0,0 +1,31 @@ |
|||||||
|
<!DOCTYPE html> |
||||||
|
<html> |
||||||
|
<head> |
||||||
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
||||||
|
<title>{{.Subject}}</title> |
||||||
|
</head> |
||||||
|
|
||||||
|
<body> |
||||||
|
{{if .IsMention}}<p>@{{.Doer.Name}} mentioned you:</p>{{end}} |
||||||
|
<p> |
||||||
|
{{- if eq .Body ""}} |
||||||
|
{{if eq .ActionName "new"}} |
||||||
|
Created #{{.Issue.Index}}. |
||||||
|
{{else if eq .ActionName "close"}} |
||||||
|
Closed #{{.Issue.Index}}. |
||||||
|
{{else if eq .ActionName "reopen"}} |
||||||
|
Reopened #{{.Issue.Index}}. |
||||||
|
{{else}} |
||||||
|
Empty comment on #{{.Issue.Index}}. |
||||||
|
{{end}} |
||||||
|
{{else}} |
||||||
|
{{.Body | Str2html}} |
||||||
|
{{end -}} |
||||||
|
</p> |
||||||
|
<p> |
||||||
|
--- |
||||||
|
<br> |
||||||
|
<a href="{{.Link}}">View it on {{AppName}}</a>. |
||||||
|
</p> |
||||||
|
</body> |
||||||
|
</html> |
||||||
@ -1,17 +0,0 @@ |
|||||||
<!DOCTYPE html> |
|
||||||
<html> |
|
||||||
<head> |
|
||||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
|
||||||
<title>{{.Subject}}</title> |
|
||||||
</head> |
|
||||||
|
|
||||||
<body> |
|
||||||
<p>@{{.Doer.Name}} mentioned you:</p> |
|
||||||
<p>{{.Body | Str2html}}</p> |
|
||||||
<p> |
|
||||||
--- |
|
||||||
<br> |
|
||||||
<a href="{{.Link}}">View it on Gitea</a>. |
|
||||||
</p> |
|
||||||
</body> |
|
||||||
</html> |
|
||||||
Loading…
Reference in new issue