grunt-ejs-render

> Render ejs templates with custom data and helpers

This plugin provides ejs static rendering to enhance static file development.

Aside from default ejs features it provides:

* Lo-Dash/underscore functions (http://lodash.com/docs)
* Lo-Dash/underscore templates powered view partials (http://lodash.com/docs#template)
* markdown parsing via a custom ejs filter
* an easy way to define custom _per task_ helpers

Getting Started

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

``shell
npm install grunt-ejs-render --save-dev
`

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

`js
grunt.loadNpmTasks('grunt-ejs-render');
`

The "render" task

$3


In your project's Gruntfile, add a section named render to the data object passed into grunt.initConfig().

`js
grunt.initConfig({
render: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
}
}
})
`

$3

#### options._
Type: Object
Default value: _

A reference to a Lo-Dash build. Defaults to the full Lo-Dash from npm integrated with Underscore.string.


`js

//load a Backbone build of Lo-Dash
var bb_ = require('./customlibs/lodash/lodash-backbone.js');

grunt.initConfig({
render: {
options: {
'_' : bb_
}
//...
}
})
`

Inside a template you may access Lo-Dash functions from _:

`


<%= _.first(['orange', 'lemon', 'apple']) %>



`


#### options.data
Type: Object|Array
Default value: null

An object containing dynamic data to be passed to templates.

You may also pass an array of JSON filepaths (any Grunt compatible globbing and template syntax is supported). options.data will be populated with files' contents.

`js
grunt.initConfig({
render: {
first_target: {
options: {
data: ['path/to/my-file.json', 'path/to/my-other-file.json']
}

},
second_target: {
options: {
data: { 'prop': 'my test'}
}

}
}
})
`

To access datas from inside a template use data. namespace:

`


<%= data.prop %>


`

When filepaths are provided, filenames are processed to create new namespaces:

`



<%= data.myFile.whatever %>




<%= data.myOtherFile.whateveragain %>


`


#### options.templates
Type: Mixed
Default value: []

An array of files of Lo-Dash templates to be used inside a main template file. May be useful to reuse client side templates to render a static file.

Compiled templates will be indexed by their filename without extension, and are accessible with the helpers.template helper method

Template configuration

`js
grunt.initConfig({
render: {
options: {
templates: ['templates/*.tpl']
}
}
})
`

Usage

`


<% fruits.forEach(function (fruit) { %>


<%= fruit %>


<% }); %>
`

`


<%= helpers.template('list', {fruits: ['orange', 'lemon', 'apple']}) %>


`

#### options.partialPaths
Type: Array
Default value: []

An array of paths where partials may be stored. Accepts both absolute and relative paths.
Relative paths are resolved from Gruntfile.js location.

This option is used by the getMTime and readPartial helpers.

`js
grunt.initConfig({
render: {
options: {
partialPaths: ['app/includes/']
}
}
});
`

`




`


#### options.helpers
Type: Object
Default value: {}

Hash of custom methods for usage inside a template. Within helpers, this refers to the current tasks' options.

Default helpers are:

* template('templatename', dataObject): executes a precompiled Lo-Dash template (if available) with provided data object
* getMTime('filepath'): returns the last modified time (as unix timestamp) of the passed in file.
* readPartial('filepath'): includes the content of the passed in file.
* renderPartial('filepath', dataObject): renders passed in template, properties of dataObject are available as template local variables.

Helpers configuration

`js
grunt.initConfig({
render: {
options: {
helpers: {
//set a custom helper
timestamp: function () { return new Date().getTime(); },
getName: function () { return this.data.name; }
},
data: {
name: 'John'
}
}
}
})
`

Usage inside templates

`




<%= helpers.template('list', {fruits: ['orange', 'lemon', 'apple']}) %>


build timestamp: <%= helpers.timestamp() %>


Hi <%= helpers.getName() %>
<-- outputs: Hi John -->
`

$3

The plugin adds the md custom filter to ejs, which leverages marked to parse markdown syntax:

`
<%-: markdown rocks! | md %>

`

You may use this filter in conjunction with readPartial helpers to import markdown files

`
<%-: helpers.readPartial('md/about-us.md') | md %>
`

$3

#### Default Options
To process a file with ejs just pass it to the files array:

`js
grunt.initConfig({
render: {
options: {},
html: {
files: {
'dest/index.html': ['src/index.html']
}
}
}
});
`

#### Custom Options
You may provide custom options:

`js
grunt.initConfig({
render: {
options: {
data: ['data/fruits.json']
helpers: {
timestamp: function () { return new Date().getTime(); }
},
templates: ['templates/*.tpl']
},
fruits: {
files: {
'dest/fruits.html': ['src/fruits.html']
}
}
}
});
``

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

0.2.6 - fork from https://github.com/dwightjack/grunt-ejs-render and add i18n support