diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7512d1a..dead767 100644 --- a/CONTRIBUTING.md +++ b/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 - - <% if (locals.product.logo) { %> - - <% } else { %> - <%- product.name %> - <% } %> + + {{ if .Hermes.Product.Logo }} + + {{ else }} + {{ .Hermes.Product.Name }} + {{ end }} ``` @@ -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 %> +

{{if .Email.Body.Title }}{{ .Email.Body.Title }}{{ else }}{{ .Email.Body.Greeting }} {{ .Email.Body.Name }},{{ end }}

``` ## 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) { -%> -

<%- introItem %>

- <% }) -%> -<% } %> +{{ with .Email.Body.Intros }} + {{ if gt (len .) 0 }} + {{ range $line := . }} +

{{ $line }}

+ {{ 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 `
` of key-value pairs into the e-mail: ```html - -<% if (locals.dictionary) { %> -
- <% for (item in dictionary) { -%> -
<%- item.charAt(0).toUpperCase() + item.slice(1) %>:
-
<%- dictionary[item] %>
- <% } -%> -
-<% } %> +{{ with .Email.Body.Dictionary }} + {{ if gt (len .) 0 }} +
+ {{ range $entry := . }} +
{{ $entry.Key }}:
+
{{ $entry.Value }}
+ {{ end }} +
+ {{ 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 -<% if (locals.table) { %> - - - <% for (var column in table.data[0]) {%> - - <% } %> - - <% for (var i in table.data) {%> - - <% for (var column in table.data[i]) {%> - +
- 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] %>" - <% } %> - > -

<%- column.charAt(0).toUpperCase() + column.slice(1) %>

-
- style="text-align:<%= table.columns.customAlignment[column] %>" - <% } %> - > - <%- table.data[i][column] %> +{{ with .Email.Body.Table }} +{{ $data := .Data }} +{{ $columns := .Columns }} + {{ if gt (len $data) 0 }} + + + - <% } %> - - <% } %> -
+ + + {{ $col := index $data 0 }} + {{ range $entry := $col }} + + {{ end }} + + {{ range $row := $data }} + + {{ range $cell := $row }} + + {{ end }} + + {{ end }} +
+

{{ $entry.Key }}

+
+ {{ $cell.Value }} +
-<% } %> +
+ {{ 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 - -<% if (locals.action) { %> - <% action.forEach(function (actionItem) { -%> -

<%- actionItem.instructions %>

- - <%- actionItem.button.text %> - - <% }) -%> -<% } %> +{{ with .Email.Body.Actions }} + {{ if gt (len .) 0 }} + {{ range $action := . }} +

{{ $action.Instructions }}

+ + + + +
+ +
+ {{ 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 }} + + + {{ range $action := . }} + + {{ end }} + + +
+

If you’re having trouble with the button '{{ $action.Button.Text }}', copy and paste the URL below into your web browser.

+

{{ $action.Button.Link }}

+
+{{ 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) { -%> -

<%- outroItem %>

- <% }) -%> -<% } %> +{{ with .Email.Body.Outros }} + {{ if gt (len .) 0 }} + {{ range $line := . }} +

{{ $line }}

+ {{ 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 %>, -
-<%- product.name %> +{{.Email.Body.Signature}}, +
+{{.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 - -<% if (locals.goToAction) { %> - -<% } %> +{{.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 `` tag: ```html - + ``` diff --git a/default.go b/default.go index 60c9005..e6e4218 100644 --- a/default.go +++ b/default.go @@ -331,11 +331,11 @@ func (dt *Default) HTMLTemplate() string { {{ end }} {{ end }} -

- {{.Email.Body.Signature}}, -
- {{.Hermes.Product.Name}} -

+

+ {{.Email.Body.Signature}}, +
+ {{.Hermes.Product.Name}} +

{{ with .Email.Body.Actions }}