ecto

Modern Template Consolidation Engine for EJS, Markdown, Pug, Nunjucks, Mustache, and Handlebars

---

Features

• Zero Config by default.
• Async render and renderFromFile functions for ES6 and Typescript.
• Render via Template File with Automatic Engine Selection. No more selecting which engine to use as it does it for you based on file extension.
• Only the Top Template Engines: EJS, Markdown, Pug, Nunjucks, Mustache, Liquid, and Handlebars
• Maintained with Monthly Updates!

---

Getting Started -- It's that Easy!

Step 1: Add Ecto to your Project

yarn add ecto

Step 2: Declate and Initialize

const Ecto = require("ecto");
let ecto = new Ecto();

Step 3: Render via String for EJS (Default Engine)

let source = "<h1>Hello <%= firstName%> <%= lastName %>!</h1>";
let data = {firstName: "John", lastName: "Doe"}
//async render(source:string, data?:object, engineName?:string, rootTemplatePath?:string, filePathOutput?:string): Promise<string>
let output = await ecto.render(source, data);

Here is how it looks all together after you have added it as a package via yarn add ecto!

const Ecto = require("ecto");
let ecto = new Ecto();

let source = "<h1>Hello <%= firstName%> <%= lastName %>!</h1>";
let data = {firstName: "John", lastName: "Doe"};
//async render(source:string, data?:object, engineName?:string, rootTemplatePath?:string, filePathOutput?:string): Promise<string>
let output = await ecto.render(source, data);

console.log(output);

Next Steps:

• More examples on Render via String
• More examples on Render via Template File
• Examples by Specific Engines
• Check out the entire API / Functions

---

Only the Top Template Engines and Their Extensions

While doing research for enabling other projects to handle multiple template engines we decided to not use other consolidation engines as they were all over the place. Some of the packages were unsupported and most likely hard to validate as working. Some had had limited types and ease of use.

Our goal is to support the top engines which most likely handle the vast majority of use cases and just make it easy. Here are the top engines that we support and make easy:

Engine	Monthly Downloads	Extensions
EJS		.ejs
Markdown		.markdown, .md
Pug		.pug, .jade
Nunjucks		.njk
Mustache		.mustache
Handlebars		.handlebars, .hbs, .hjs
Liquid		.liquid

The Extensions are listed above for when we Render via Template File.

---

Render via String

As we have shown in Getting Started -- It's that Easy! you can do a render in only a couple lines of code:

let ecto = new Ecto();

let source = "<h1>Hello <%= firstName%> <%= lastName %>!</h1>";
let data = {firstName: "John", lastName: "Doe"};
//async render(source:string, data?:object, engineName?:string, rootTemplatePath?:string, filePathOutput?:string): Promise<string>
let output = await ecto.render(source, data);

console.log(output);

Now lets say your engine is not EJS so you want to specify it. You can either set the defaultEngine parameter or simply pass it in the render function. Here we are doing Handlebars:

let ecto = new Ecto();

let source = "<h1>Hello {{firstName}} {{lastName}}!</h1>";
let data = {firstName: "John", lastName: "Doe"};
//async render(source:string, data?:object, engineName?:string, rootTemplatePath?:string, filePathOutput?:string): Promise<string>
let output = await ecto.render(source, data, "handlebars");

console.log(output);

render also can handle partial files for you standard engines (markdown excluded) by just adding the rootTemplatePath:

let ecto = new Ecto();

let source = "<h1>Hello <%= firstName%> <%= lastName %>!</h1><%- include('/relative/path/to/partial'); %>";
let data = {firstName: "John", lastName: "Doe"};
//async render(source:string, data?:object, engineName?:string, rootTemplatePath?:string, filePathOutput?:string): Promise<string>
let output = await ecto.render(source, data, undefined, "./path/to/templates");

console.log(output);

render also can write out the file for you by specifying the filePathOutput parameter like below. It will still return the output via string:

let ecto = new Ecto();

let source = "<h1>Hello <%= firstName%> <%= lastName %>!</h1>";
let data = {firstName: "John", lastName: "Doe"};
//async render(source:string, data?:object, engineName?:string, rootTemplatePath?:string, filePathOutput?:string): Promise<string>
let output = await ecto.render(source, data, undefined, undefined, "./path/to/output/file.html");

console.log(output);

Notice the undefined passed into the engineName parameter. This is done because we already have the defaultEngine set to EJS. If you want you can easily add it in by specifying it.

---

Render via Template File with Automatic Engine Selection

To render via a template file it is as simple as calling the renderFromFile function with a couple simple parameters to be passed in. In this example we are simply passing in the template and it will return a string.

let ecto = new Ecto();
let data = { firstName: "John", lastName: "Doe"};

//async renderFromFile(templatePath:string, data?:object, rootTemplatePath?:string, filePathOutput?:string, engineName?:string): Promise<string>
let output = await ecto.renderFromFile("./path/to/template.ejs", data);

In this example we are now asking it to write the output file for us and it will return the output still as a string:

let ecto = new Ecto();
let data = { firstName: "John", lastName: "Doe"};

//async renderFromFile(templatePath:string, data?:object, rootTemplatePath?:string, filePathOutput?:string, engineName?:string): Promise<string>
let output = await ecto.renderFromFile("./path/to/template.ejs", data, undefined,"./path/to/output/yourname.html");

Notice that in these examples it is using the ./path/to/template.ejs to use the engine EJS for the rendering.

You can override the auto selected engine by adding it on the function as a parameter by passing in pug in this example:

let ecto = new Ecto();
let data = { firstName: "John", lastName: "Doe"};

//async renderFromFile(templatePath:string, data?:object, rootTemplatePath?:string, filePathOutput?:string, engineName?:string): Promise<string>
let output = await ecto.renderFromFile("./path/to/template.ejs", data, undefined, "./path/to/output/yourname.html", "pug");

This will override the auto selection process and render the template using the Pug engine.

---

Examples by Specific Engines

Markdown

Handlebars

---

API

Ecto:

• Constructor
• Functions:
  • render
  • renderFromFile
• Parameters:
  • defaultEngine
  • mappings
  • markdown
  • handlebars
  • ejs
  • pug
  • nunjucks
  • mustache
  • liquid

Constructor:

(opts:object)

The constructor can be initialized with the defaultEngine like so for options:

let ecto = new Ecto({defaultEngine: "pug"});

Parameter: defaultEngine

defaultEngine: String

By default the system is set to EJS but if you are using a different engine no problem as you can easily change the default like so:

let ecto = new Ecto();
ecto.defaultEngine = "pug" //we support ejs, markdown, pug, nunjucks, mustache, handlebars, and liquid

From there you can do the default render and it just works! Now if you want to just pass it on the command line you can by doing the following on render which will overwrite the defaultEngine:

let ecto = new Ecto();
let output = await ecto.render(source, data, "pug", "./path/to/output/file.html");

Function: render

render(source:string, data?:object, engineName?:string, filePathOutput?:string): Promise<string>