Crafity Templates

Supported templates

Whenever you want to communicate a well formatted message to the user of your application you will be thinking of generating such a message on the fly. Imagine you have a couple of different situations in which generating messages is suitable: one user sends invitation to another, the system sends emails to user(s) on some subject.

Also, the application is multilingual, so versions of a single message will be available in different human languages. English is the default language in crafity-templates module.

This module supports generating messages that are templated with the following HTML preprocessors:

• Jade
• Haml

Preparation

Install crafity-templates module via NPM installer or by cloning this repository from GitHub:

via NPM

$ npm install

via GitHub

$ git clone https://github.com/Crafity/crafity-templates.git
$ cd crafity-templates

Before you start using crafity-templates you must install all its dependencies. They are listed in package.json file under key dependencies. Install them first by running command on the terminal from crafity-templates as current directory:

$ npm install

After the dependencies have been installed, run the unit tests to check the sanity of the module. From the command line and current directory crafity-templates type the command:

$ npm test

Things you need to prepare before calling the crafity-templates module:

1. Create folder resources under you application root folder.

2. Think of the human languages you want to support and create a new folder for each language, e.g. to support English, Bulgarian and Dutch you crate en, bg and nl under resources folder. If you think it is a better organization to put another folder between resources and the language folder, just do so. Make sure you specify the path "/resources/myFolderName/" in the configuration of the module.

    NB! Make also sure the *en* folder is always present as this is considered 
    the default and compulsory one.
   

3. Put your template files under the relevant language folder.

Upon initialization crafity-templates module assumes the following defaults:

• there is a folder resources under the application root folder

• there is one default folder en under resources

• template files to be generated have extensions either ".jade" or ".haml"

• the custom configuration has one or more of the following properties:

  config = { resourcePath: process.cwd() + "/resources" // current directory , defaultLanguage: "en" // English , preprocessor: "jade" }

• there is only one current preprocessor set at a time

• will use the file extentions that correspond with the configured preprocessor

Now, let's assume a scenario where you want your templates in Jade to reside in three different languages under your [appRootFolder]/resources/email_templates/ :

You create the following structure:

[appRootFolder]/resources/email_templates/en
	letter.jade
	letter.haml
[appRootFolder]/resources/email_templates/nl
	letter.jade
[appRootFolder]/resources/email_templates/bg
	letter.jade

Public API

Require crafity-templates module and pass a configuragion in the init method:

var templatesModule = require('crafity-templates')
        , newConfiguration = 
            { 
                resourcePath: "~/resources/email_templates"
                , defaultLanguage: "nl"
                , preprocessor: "jade"
            }
        ;
 
templatesModule
    .init(newConfiguration)
    .get("letter", function(err, template) {
        // TODO: handle error ...
        
        // merge template in Ditch with the data
        if (template) {
        
            var html = template.merge(viewModel);
            
            // TODO: send an email with this html body
        }
    });

templatesModule.get([language], templateName, callback);

• language String - language (folder)
• templateName String - the name of the template
• callback Function

Setting a custom configuration in the beginnning means you don't intend to repeat the defaults on every call of the get method. But should you wish to call the get with a language that is switching on the fly then use the language argument. If not passed the default configuration language will be used. One such call is:

var templatesModule = require('crafity-templates')
        , newConfiguration = 
            { 
                resourcePath: "~/resources/email_templates"
                , defaultLanguage: "nl"
                , preprocessor: "jade"
            }
        ;
 
templatesModule
    .init(newConfiguration)
    .get("bg", "letter", function(err, template) {
        // TODO: handle error ...
        
        // merge template in Bulgarian with the data
        if (template) {
        
            var html = template.merge(viewModel);
            
            // TODO: send an email with this html body
        }
    });

Assume another scenario: configure Haml to be the default preprocessor and then call get for a fileName "letter" which is available on disk as letter.jade and letter.haml:

var templatesModule = require('crafity-templates')
            , newConfiguration = 
                { 
                    resourcePath: "~/resources/email_templates"
                    , preprocessor: "haml"
                }
            ;
 
templatesModule
    .init(newConfiguration)
    .get("letter", function(err, template) {
        // TODO: handle error ...
        
        // merge template from the Haml file in English with the data
        if (template) {
        
            var html = template.merge(viewModel);
            
            // TODO: send an email with this html body
        }
    });

Alternatively if you call for a file the extension of which does not match with the configured preprocessor then an exception will be thrown.