dojo-templater/README.md

Easy HTML emails with variables

ClassDojo Templater
==============================

Author: Chris Frank


What does this module do?
--------------------------

Dojo Templater handles all the nastiness of sending HTML emails.  Include the module, call one of the public methods, and Templater takes care of the rest.


# Features

1.  Translations via Crowdin.  Handlebars syntax:
    `{{ I18n 'dojo-templater.emails:welcome_a.welcome' }}`
2.  Layouts in handlebars:  `{{#extend "main"}}`
3.  Inlines CSS so you can write your CSS in a separate file.
4.  Does NOT inline anything in `<style>` tags.  Use `<style>` tags for mobile clients.
5.  Uses [Zurb's Ink framework](http://zurb.com/ink/).  Ink makes emails easy to maintain and work on many clients.
6.  Uses fixture data for testing and previews.  Update fixtures in `src/fixtures.coffee`.



# Using Dojo Templater in your projects

    # The name of the handlebars file in email_templates
    fileName = "midweekUpdate"

    # Data object
    data =
      firstName: "Rafaelita"
      lastName:  "Rafaelli"

    # Options
    options =
        language: 'en'

    # If you want to use fixture data, say for testing
    options.useFixtures = true


    @templater = new Templater
    @templater.fetchEmail fileName, data, options, (err, result) ->
        # Result is an object with properties:  html, plain, subject
        console.log result.html

    # There is another public method, "get_templates".
    # This was for jade templates, and is being deprecated.
    @template.get_templates(fileName, data, options, callback)


# Testing and viewing templates

If you install Dojo Templater locally, you can run `sh sample.sh` to test a particular template.
Look at `index.test.coffee` to change which template renders.

For viewing all the templates, have a look at `teach.classdojo.com/mailer/index`.
Here, you can see a list of all templates.  Click the link to view a preview of the email in your browser.


IMPORTANT:  When you add a new template, please update the `src/fixtures.coffee` file and add info about your template to the `index' fixture.
This is the only way to keep `teach.classdojo.com/mailer/index` up to date.