dsch-emails v0.1.0
DSCH Emails
Powered by:
Take a look at the MJML Guides for markup syntax.
Getting started:
NOTE: You may need to set nvm
to use
version >= 8, eg.
nvm ls
You'll see something like this:
-> v6.x.x
v8.x.x
v10.x.x
system
nvm use v8.x.x
(replace with your specific version, use tab to complete)
git clone git@github.com:distilledmedia/dsch-emails.git
cd dsch-emails
yarn install
Adding a new project
Run:
yarn create-project "newproject"
You will need to add your new project/brands to brands
in config.js
.
This will create the following folder structure:
├── newproject/ * new project
| ├── common * directory to hold partial includes for templates
| ├── COMPILED_TEMPLATES * output folder for this projects templates (.html)
| ├── templates * mjml template files
Commands available:
(See note above re nvm use
)
$ yarn compile-emails
This will prompt you to pick a project that you would like to compile.
$ yarn compile-all-emails
As the name suggests this will compile all of your projects. This is handy if you are integrating with a CI.
$ yarn watch
This will allow you to work on an individual project and it will auto compile your templates on file change/save.
$ yarn create-project "newproject"
This will scaffold out a new project directory.
Project Structure
dsch-emails/
├─ projects/
| └─ brand/
| ├─ common * directory to hold partial includes for templates
| ├─ COMPILED_TEMPLATES * output folder for this projects templates (.html)
| └─ templates * mjml template files
│
├─ scripts/
| ├─ compile.js *
| ├─ create.js *
| ├─ index.js *
│ ├─ inquirer.js *
│ ├─ publish.js *
| └─ watch.js *
│
├─ tools/ * helper tools for running the project
| | index.js * utilities
| └─ logger.js * adds a touch of colour to console logs
|
├─ .babelrc * https://babeljs.io/docs/usage/babelrc/
├─ .editorconfig * http://editorconfig.org/
├─ .env * environment config
├─ .eslintrc * https://eslint.org/docs/user-guide/configuring
├─ .gitignore * https://git-scm.com/docs/gitignore
├─ config.js * global configuration
├─ package.json * https://docs.npmjs.com/files/package.json
└─ projects.config.js * Configuration file for this project
Recommended Development Workflow
Download and Install Visual Studio Code editor
Install these VS Code extensions:
Prettier (Code formatter)
- In VS Code, add the following settings by hitting the
⌘,
keys together to open theSearch settings
input. Enter[json]
, then clickEdit in settings.json
below.
"editor.formatOnSave": true,
"editor.formatOnPaste": true,
"prettier.singleQuote": true,
"prettier.eslintIntegration": true,
"editor.tabSize": 2,
"editor.insertSpaces": true,
"eslint.run": "onSave",
"eslint.autoFixOnSave": true,
"files.insertFinalNewline": true
Coding a template
Code the required email using hard-coded data until happy with the design. Once the FreeMarker templating language is integrated, we can no longer leverage VS Code preview properly
Do a quick check in Litmus to check that everything looks ok
Add FreeMarker code to the template. Note that any missing variables will result in the email not being sent
Prepare the template's code for Knocker (see below)
Publish to Knocker. From here you can send emails by passing through template values
Preparing the code for uploading to Knocker
- Run
$ yarn compile-emails
- You'll be prompted to select the brand you want to compile
Each mjml file in the base of the selected brand folder will be compiled to html, minified and saved to /projects/[BRAND]/COMPILED_TEMPLATES/
For example:
/projects/internal/templates/motor-loan.mjml
=> /projects/internal/COMPILED_TEMPLATES/internal-motor-loan-email.html
internal-motor-loan-email in this case will be the name
associated with the template in Knocker
Publishing to Knocker sandbox
- Run
$ yarn publish-emails
This push all templates to Knocker. It will update them all and create any that are not there.
Create a payload json file
This file is used to send test emails via Postman. This is very valuable when coming back to a tempalte. This is required for each new template.
For each new template, create a similarly-named json file with the expected Freemarker variables in /projects/[BRAND]/payloads
Example of one for Daft Ad Reply email:
{
"channel": "email",
"template_name": "daft-ad-reply-email",
"identifiers": ["some.name@distilled.ie"],
"template_values": {
"subject": "New Enquiry",
"title": "New Enquiry",
"fromName": "Jane Doe",
"fromEmail": "janedoe@test.com",
"fromPhone": "087 1234567",
"message":
"This is a message that you may see from a user enquiring about the property. It can be long sometimes.",
"photoUrl": "https://placeimg.com/600/325/arch",
"berRating": "D1",
"mediaCount": "23",
"hasVirtualTour": true,
"hasVideo": true,
"price": "€850,000",
"address": "Mount Alverno, Sorrento Road, Dalkey, Co.Dublin",
"numBedrooms": "2",
"numBathrooms": "2",
"cdnUrl": "https://dsch-emails-ss-staging.apps.dsch.ninja/email",
"ctaUrl": "https://www.google.ie/"
},
"email_properties": {
"subject": "New Enquiry",
"from": "Daft.ie TEST <noreply@daft.ie>",
"inline_css": false
}
}
This is the reference payload structure that will be used by the backend in template_values
when an email is sent.
Publishing to Staging/Production
Before continuing, ensure that:
- the template in the sandbox environment sends successfully (missing Freemarker variables may result in the email not being sent)
- the template has product & design approval
- the template has been QA approved
- the working branch has been PR approved against master
- any backend changes (if required) are ready for release
Once the above conditions are met:
- Squash and merge your branch to master
- Once you merge it will automatically kick off a pipeline and release to staging and then onto production
- At present, auto promotion to production happens after every merge so please ensure it was tested in sandbox first
- You can view the pipeline here (You must be on the Distilled VPN to view. Log in with Google)