grunt-ejs-static
Grunt EJS Static is a static site generator built with EJS and Grunt. Pages are defined in JSON by declaring the layout file and any additional data needed at render time. The layout file manages EJS Includes, which are partials organized in the components directory.
For examples, please see demo/ and Usage section below.
There is also a project boilerplate available grunt-ejs-static-boilerplate
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:
npm install grunt-ejs-static --save-dev
One the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt;
The "ejs_static" task
Overview
In your project's Gruntfile, add a section named ejs_static
to the data object passed into grunt.initConfig()
.
The required options are dest and path_to_data.
Conditionally required options are path_to_layouts. If options.path_to_layouts is specified, layout can be specified in the controller json (such as routes.json).
If path_to_layout is specified in routes.json, options.path_to_layouts is not necessary. This option does not work well with grunt-usemin, so if you're using it may be better to specify options.path_to_layouts + layout in controller json file.
Important note: to use a layout for multiple pages, there are two methods. One is to specify path_to_layout in routes.json. The other is to specify options.path_to_layouts + layout in controller json file.
If layout paths are not specified, ejs_static falls back to searching the dir specified in options.path_to_layouts.
grunt
Usage
Files to render in routes.json
(this is options.path_to_data in Gruntfile)
Additional data from global.json
Additional data from meta.json
Generates this JSON data model
Layout defined in home.ejs
<% include /templates/global/head %> <% include /templates/global/header %> <% include /templates/home/hero %> <% include /templates/home/body %> <% include /templates/global/footer %>
Which includes templates like head.ejs
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]--><!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]--><!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]--><!--[if gt IE 8]><!--> <!--<![endif]--> <%= global.site_name %> | <%= meta.title %> <!-- css --> <!-- end css --> <!-- modernizr --> <!-- end modernizr --> <!-- google analytics --> <!-- end google analytics -->
Outputs this HTML
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]--><!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]--><!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]--><!--[if gt IE 8]><!--> <!--<![endif]--> Grunt EJS Static | Home <!-- css --> <!-- end css --> <!-- modernizr --> <!-- end modernizr --> <!-- google analytics --> <!-- end google analytics --> <!-- hero here --> <!-- body content here --> <!-- footer --> © Company 2012 <!-- end footer -->
Options
options.dest
Required
Type: String
Files are rendered into this directory
options.path_to_data
Required
Type: String
This is the path to the JSON file that determines what files are rendered
options.path_to_layouts
Optional
Type: String
This is the path to the layout files directory
options.index_page
Optional
Type: String
This sets the index page for the site
options.parent_dirs
Optional
Type: Boolean
This defines how files are output.
If true, files are output as filename.html (for example, about.html)
If false, files are output as filename/index.html (for example, about/index.html)
options.underscores_to_dashes
Optional
Type: Boolean
Filenames are defined in data.json as the key
If true, any underscores in the key are converted to dashes
If false, underscores are not converted
options.file_extension
Optional
Type: String
This defines the file extension of rendered files
Defaults to .html, but could be .php, .aspx, etc
options.helpers
Optional
Type: String
, Object
, or Array
Helper functions can be defined in 3 ways. If a string, indicates the path to a single file containing one or more helper functions. An array indicates multiple paths to files containing one or more helper functions. An object defines one or more helper functions inline (in the Gruntfile). The key is the function name and the value is the function expression.
ejs_static: // single file example string: options: dest: 'dist' path_to_data: 'path/to/data.json' path_to_layouts: 'path/to/layouts' underscore: true helpers: 'demo/dev/js/site/helper_functions3.js' // inline example object: options: dest: 'dist' path_to_data: 'path/to/data.json' path_to_layouts: 'path/to/layouts' underscore: true helpers: { return "<h1 style='color:red;'>" + text + "</h1>"; } { var output = ''; forvar property in obj output += property + ': ' + objproperty+'; \n'; console; } // multiple files example array: options: dest: 'dist' path_to_data: 'path/to/data.json' path_to_layouts: 'path/to/layouts' underscore: true helpers: 'demo/dev/js/site/helper_functions1.js' 'demo/dev/js/site/helper_functions2.js'
If included as a file, needs to be wrapped w/ module.exports
moduleexports = exports = { console; var url = ""; url += scheme; url += "://"; url += hostname; url += path; if querieslength > 0 url += "?"; queries; return url; } { var output = ''; forvar property in obj output += property + ': ' + objproperty+'; \n'; console; } { return "<h1 style='color:red;'>" + text + "</h1>"; } ;
which can then be used in a template like this
<%- highlight('This Text') -%> <%= build_url("https", "www.google.com", "/search", ['q=unicorns', 'oq=unicorns']) %> <% print_object(this); %>
options.underscore
Optional
Type: Boolean
Default: False
Defines whether Underscore is available in the templates at render time.
Examples
To demo how grunt-ejs-static works
git clone https://github.com/shaekuronen/grunt-ejs-static.git cd grunt-ejs-static grunt preview
This builds EJS templates as html into demo/preview/ from layout files in demo/dev/layouts/ (see demo/dev/layouts/home.ejs for an example of layout using EJS includes)
To demo optimizing the site for deployment to production
grunt optimize
This builds static html into demo/production/
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.3.8
- Added support for helper functions.
- Added option to make Underscore JS available in the templates.
0.3.7
- Added dashed_file_name variable to make easier to include page name into CSS.
- Added option to specify layout (vs. path_to_layout) in controller json file. This can be used in combination with path_to_layouts, which is specified in Gruntfile ejs_static options.
0.3.5
- Added file_name variable to allow template extension.
- See discussion on Github.
0.3.2
- Moved logic into modules.
- Improved management of data files. Combine files, or parse for a specific key, prior to rendering.
0.3.0
- Complete rewrite. More flexible, less opinionated.
- Now data-driven. Files to be rendered are defined in JSON file, not in the file structure.
- Backwards compatible, though ejs_static options need to be updated in Gruntfile.
- Added options: parent_dirs, underscores_to_dashes, file_extension, global_data.
0.2.0
- Added a way to get site-wide variables into the models for individual layouts.
- Added logging of debugging information to show what is happening in the task.