Add last steps of contributing guide
This commit is contained in:
matcornic
parent
a70fb3bcbd
commit
20fa1b38bb
213
CONTRIBUTING.md
213
CONTRIBUTING.md
|
|
@ -20,12 +20,15 @@ This file contains instructions on adding themes to Mailgen:
|
|||
* [Creating a Built-In Theme](#creating-a-built-in-theme)
|
||||
|
||||
> We use Golang templates under the hood to inject the e-mail body into themes.
|
||||
> - [Official guide](https://golang.org/pkg/text/template/)
|
||||
> - [Tutorial](https://astaxie.gitbooks.io/build-web-application-with-golang/en/07.4.html)
|
||||
> - [Hugo guide](https://gohugo.io/templates/go-templates/)
|
||||
|
||||
### Using a Custom Theme
|
||||
|
||||
If you want to supply your own **custom theme** for Hermes to use (but don't want it included with Mailgen):
|
||||
|
||||
1. Create a new struct implementing `Theme` interface ([hermes.go](hermes.go)). An real-life example is in [default.go](default.go)
|
||||
1. Create a new struct implementing `Theme` interface ([hermes.go](hermes.go)). A real-life example is in [default.go](default.go)
|
||||
2. Supply your new theme at hermes creation
|
||||
|
||||
```go
|
||||
|
|
@ -70,11 +73,11 @@ If you want to create a new **built-in** Mailgen theme:
|
|||
1. Fork the repository to your GitHub account and clone it to your computer
|
||||
2. Create a new Go file named after your new theme
|
||||
3. Copy content of [default.go](default.go) file in new file and make any necessary changes
|
||||
6. Scroll down to the [injection snippets](#injection-snippets) and copy and paste each code snippet into the relevant area of your template markup
|
||||
7. Test the theme by running the `examples/*.js` scripts (insert your theme name in each script) and observing the template output in `preview.html`
|
||||
8. Take a screenshot of your theme portraying each example and place it in `screenshots/{theme}/{example}.png`
|
||||
9. Add the theme name, credit, and screenshots to the `README.md` file's [Supported Themes](README.md#supported-themes) section (copy one of the existing themes' markup and modify it accordingly)
|
||||
7. Submit a pull request with your changes and we'll let you know if anything's missing!
|
||||
4. Scroll down to the [injection snippets](#injection-snippets) and copy and paste each code snippet into the relevant area of your template markup
|
||||
5. Test the theme by adding the theme to slice of tested themes (see [hermes_test.go](hermes_test.go)). A set of tests will be run to check that your theme follows features of Hermes.
|
||||
6. Create examples in new folder for your theme in `examples` folder and run `go run *.go`. It will generate the different `html` and `plaintext` emails for your different examples. Follow the same examples as default theme (3 examples: Welcome, Reset and Receipt)
|
||||
7. Add the theme name, credit, and screenshots to the `README.md` file's [Supported Themes](README.md#supported-themes) section (copy one of the existing themes' markup and modify it accordingly)
|
||||
8. Submit a pull request with your changes and we'll let you know if anything's missing!
|
||||
|
||||
Thanks again for your contribution!
|
||||
|
||||
|
|
@ -85,12 +88,12 @@ Thanks again for your contribution!
|
|||
The following will inject either the product logo or name into the template.
|
||||
|
||||
```html
|
||||
<a href="<%- product.link %>" target="_blank">
|
||||
<% if (locals.product.logo) { %>
|
||||
<img src="<%- product.logo %>" class="email-logo" />
|
||||
<% } else { %>
|
||||
<%- product.name %>
|
||||
<% } %>
|
||||
<a href="{{.Hermes.Product.Link}}" target="_blank">
|
||||
{{ if .Hermes.Product.Logo }}
|
||||
<img src="{{.Hermes.Product.Logo}}" class="email-logo" />
|
||||
{{ else }}
|
||||
{{ .Hermes.Product.Name }}
|
||||
{{ end }}
|
||||
</a>
|
||||
```
|
||||
|
||||
|
|
@ -107,7 +110,7 @@ It's a good idea to add the following CSS declaration to set `max-height: 50px`
|
|||
The following will inject the e-mail title (Hi John Appleseed,) or a custom title provided by the user:
|
||||
|
||||
```html
|
||||
<%- title %>
|
||||
<h1>{{if .Email.Body.Title }}{{ .Email.Body.Title }}{{ else }}{{ .Email.Body.Greeting }} {{ .Email.Body.Name }},{{ end }}</h1>
|
||||
```
|
||||
|
||||
## Intro Injection
|
||||
|
|
@ -115,11 +118,13 @@ The following will inject the e-mail title (Hi John Appleseed,) or a custom titl
|
|||
The following will inject the intro text (string or array) into the e-mail:
|
||||
|
||||
```html
|
||||
<% if (locals.intro) { %>
|
||||
<% intro.forEach(function (introItem) { -%>
|
||||
<p><%- introItem %></p>
|
||||
<% }) -%>
|
||||
<% } %>
|
||||
{{ with .Email.Body.Intros }}
|
||||
{{ if gt (len .) 0 }}
|
||||
{{ range $line := . }}
|
||||
<p>{{ $line }}</p>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Dictionary Injection
|
||||
|
|
@ -127,15 +132,16 @@ The following will inject the intro text (string or array) into the e-mail:
|
|||
The following will inject a `<dl>` of key-value pairs into the e-mail:
|
||||
|
||||
```html
|
||||
<!-- Dictionary -->
|
||||
<% if (locals.dictionary) { %>
|
||||
<dl class="dictionary">
|
||||
<% for (item in dictionary) { -%>
|
||||
<dt><%- item.charAt(0).toUpperCase() + item.slice(1) %>:</dt>
|
||||
<dd><%- dictionary[item] %></dd>
|
||||
<% } -%>
|
||||
{{ with .Email.Body.Dictionary }}
|
||||
{{ if gt (len .) 0 }}
|
||||
<dl class="body-dictionary">
|
||||
{{ range $entry := . }}
|
||||
<dt>{{ $entry.Key }}:</dt>
|
||||
<dd>{{ $entry.Value }}</dd>
|
||||
{{ end }}
|
||||
</dl>
|
||||
<% } %>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
It's a good idea to add this to the top of the template to improve the styling of the dictionary:
|
||||
|
|
@ -165,37 +171,55 @@ The following will inject the table into the e-mail:
|
|||
|
||||
```html
|
||||
<!-- Table -->
|
||||
<% if (locals.table) { %>
|
||||
<table class="data-table" width="100%" cellpadding="0" cellspacing="0">
|
||||
{{ with .Email.Body.Table }}
|
||||
{{ $data := .Data }}
|
||||
{{ $columns := .Columns }}
|
||||
{{ if gt (len $data) 0 }}
|
||||
<table class="data-wrapper" width="100%" cellpadding="0" cellspacing="0">
|
||||
<tr>
|
||||
<% for (var column in table.data[0]) {%>
|
||||
<td colspan="2">
|
||||
<table class="data-table" width="100%" cellpadding="0" cellspacing="0">
|
||||
<tr>
|
||||
{{ $col := index $data 0 }}
|
||||
{{ range $entry := $col }}
|
||||
<th
|
||||
<% if(locals.table.columns && locals.table.columns.customWidth && locals.table.columns.customWidth[column]) { %>
|
||||
width="<%= table.columns.customWidth[column] %>"
|
||||
<% } %>
|
||||
<% if(locals.table.columns && locals.table.columns.customAlignment && locals.table.columns.customAlignment[column]) { %>
|
||||
style="text-align:<%= table.columns.customAlignment[column] %>"
|
||||
<% } %>
|
||||
{{ with $columns }}
|
||||
{{ $width := index .CustomWidth $entry.Key }}
|
||||
{{ with $width }}
|
||||
width="{{ . }}"
|
||||
{{ end }}
|
||||
{{ $align := index .CustomAlignement $entry.Key }}
|
||||
{{ with $align }}
|
||||
style="text-align:{{ . }}"
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
>
|
||||
<p><%- column.charAt(0).toUpperCase() + column.slice(1) %></p>
|
||||
<p>{{ $entry.Key }}</p>
|
||||
</th>
|
||||
<% } %>
|
||||
{{ end }}
|
||||
</tr>
|
||||
<% for (var i in table.data) {%>
|
||||
{{ range $row := $data }}
|
||||
<tr>
|
||||
<% for (var column in table.data[i]) {%>
|
||||
{{ range $cell := $row }}
|
||||
<td
|
||||
<% if(locals.table.columns && locals.table.columns.customAlignment && locals.table.columns.customAlignment[column]) { %>
|
||||
style="text-align:<%= table.columns.customAlignment[column] %>"
|
||||
<% } %>
|
||||
{{ with $columns }}
|
||||
{{ $align := index .CustomAlignement $cell.Key }}
|
||||
{{ with $align }}
|
||||
style="text-align:{{ . }}"
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
>
|
||||
<%- table.data[i][column] %>
|
||||
{{ $cell.Value }}
|
||||
</td>
|
||||
<% } %>
|
||||
{{ end }}
|
||||
</tr>
|
||||
<% } %>
|
||||
</table>
|
||||
<% } %>
|
||||
{{ end }}
|
||||
</table>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
It's a good idea to add this to the top of the template to improve the styling of the table:
|
||||
|
|
@ -234,30 +258,40 @@ It's a good idea to add this to the top of the template to improve the styling o
|
|||
The following will inject the action link (or button) into the e-mail:
|
||||
|
||||
```html
|
||||
<!-- Action -->
|
||||
<% if (locals.action) { %>
|
||||
<% action.forEach(function (actionItem) { -%>
|
||||
<p><%- actionItem.instructions %></p>
|
||||
<a href="<%- actionItem.button.link %>" style="color:<%- actionItem.button.color %>" target="_blank">
|
||||
<%- actionItem.button.text %>
|
||||
</a>
|
||||
<% }) -%>
|
||||
<% } %>
|
||||
{{ with .Email.Body.Actions }}
|
||||
{{ if gt (len .) 0 }}
|
||||
{{ range $action := . }}
|
||||
<p>{{ $action.Instructions }}</p>
|
||||
<table class="body-action" align="center" width="100%" cellpadding="0" cellspacing="0">
|
||||
<tr>
|
||||
<td align="center">
|
||||
<div>
|
||||
<a href="{{ $action.Button.Link }}" class="button" style="background-color: {{ $action.Button.Color }}" target="_blank">{{ $action.Button.Text }}</a>
|
||||
</div>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
It's a good idea to add this to the top of the template to specify a fallback color for the action buttons in case it wasn't provided by the user:
|
||||
A good practice is to describe action in footer in case of problem when displaying button and CSS
|
||||
|
||||
```html
|
||||
<%
|
||||
if (locals.action) {
|
||||
// Make it possible to override action button color (specify fallback color if no color specified)
|
||||
locals.action.forEach(function(actionItem) {
|
||||
if (!actionItem.button.color) {
|
||||
actionItem.button.color = '#48CFAD';
|
||||
}
|
||||
});
|
||||
}
|
||||
%>
|
||||
{{ with .Email.Body.Actions }}
|
||||
<table class="body-sub">
|
||||
<tbody><tr>
|
||||
{{ range $action := . }}
|
||||
<td>
|
||||
<p class="sub">If you’re having trouble with the button '{{ $action.Button.Text }}', copy and paste the URL below into your web browser.</p>
|
||||
<p class="sub"><a href="{{ $action.Button.Link }}">{{ $action.Button.Link }}</a></p>
|
||||
</td>
|
||||
{{ end }}
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Outro Injection
|
||||
|
|
@ -265,11 +299,13 @@ if (locals.action) {
|
|||
The following will inject the outro text (string or array) into the e-mail:
|
||||
|
||||
```html
|
||||
<% if (locals.outro) { %>
|
||||
<% outro.forEach(function (outroItem) { -%>
|
||||
<p><%- outroItem %></p>
|
||||
<% }) -%>
|
||||
<% } %>
|
||||
{{ with .Email.Body.Outros }}
|
||||
{{ if gt (len .) 0 }}
|
||||
{{ range $line := . }}
|
||||
<p>{{ $line }}</p>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Signature Injection
|
||||
|
|
@ -277,9 +313,9 @@ The following will inject the outro text (string or array) into the e-mail:
|
|||
The following will inject the signature phrase (e.g. Yours truly) along with the product name into the e-mail:
|
||||
|
||||
```html
|
||||
<%- signature %>,
|
||||
<br />
|
||||
<%- product.name %>
|
||||
{{.Email.Body.Signature}},
|
||||
<br>
|
||||
{{.Hermes.Product.Name}}
|
||||
```
|
||||
|
||||
## Copyright Injection
|
||||
|
|
@ -287,30 +323,7 @@ The following will inject the signature phrase (e.g. Yours truly) along with the
|
|||
The following will inject the copyright notice into the e-mail:
|
||||
|
||||
```html
|
||||
<%- product.copyright %>
|
||||
```
|
||||
|
||||
## Go-To Action Injection
|
||||
|
||||
In order to support Gmail's [Go-To Actions](https://developers.google.com/gmail/markup/reference/go-to-action), add the following anywhere within the template:
|
||||
|
||||
```html
|
||||
<!-- Support for Gmail Go-To Actions -->
|
||||
<% if (locals.goToAction) { %>
|
||||
<script type="application/ld+json">
|
||||
{
|
||||
"@context": "http://schema.org",
|
||||
"@type": "EmailMessage",
|
||||
"potentialAction": {
|
||||
"@type": "ViewAction",
|
||||
"url": "<%- goToAction.link %>",
|
||||
"target": "<%- goToAction.link %>",
|
||||
"name": "<%- goToAction.text %>"
|
||||
},
|
||||
"description": "<%- goToAction.description %>"
|
||||
}
|
||||
</script>
|
||||
<% } %>
|
||||
{{.Hermes.Product.Copyright}}
|
||||
```
|
||||
|
||||
## Text Direction Injection
|
||||
|
|
@ -318,6 +331,6 @@ In order to support Gmail's [Go-To Actions](https://developers.google.com/gmail/
|
|||
In order to support generating RTL e-mails, inject the `textDirection` variable into the `<body>` tag:
|
||||
|
||||
```html
|
||||
<body dir="<%- textDirection %>">
|
||||
<body dir="{{.Hermes.TextDirection}}">
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue