Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
This module receives configuration to Jade template files, loads them with the Jade engine and also recognizes localization based on language key.
JavaScript Shell
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
resources/en
scripts
test
.gitignore
.nodemonignore
.travis.yml
LICENSE
README.md
main.js
package.json
wercker.yml

README.md

Crafity Templates Dependency status Travis Build Status NPM Module version

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.

Something went wrong with that request. Please try again.