grunt-ejs-static

v0.4.3

Published

2 years ago

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 componen

Downloads

139

0High
0Medium
0Low

shaekuronen

gruntplugin ejs static html static site generator templates templating engine template embedded js

grunt-ejs-static

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.loadNpmTasks('grunt-ejs-static');

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.initConfig({

    ejs_static: {
      preview: {
        options: {
          dest: 'preview',
          path_to_data: 'demo/dev/data/data.json',
          path_to_layouts: 'demo/dev/layouts',
          index_page: 'home',
          parent_dirs: false,
          underscores_to_dashes: true,
          file_extension: '.html'
        }
      },
      optimize: {
        options: {
          dest: 'production',
          path_to_data: 'demo/dev/data/data.json',
          path_to_layouts: 'demo/dev/layouts',
          index_page: 'home',
          parent_dirs: true,
          underscores_to_dashes: true,
          file_extension: '.html'
        }
      }
    },

})

Usage

Files to render in routes.json (this is options.path_to_data in Gruntfile)

{
  "home": {
    "path_to_layout": "dev/layouts/home.ejs",
    "path_to_data": [
      "dev/data/global.json",
      {"dev/data/meta.json": "home"}
    ]
  }
}

Additional data from global.json

{
  "site_name": "Grunt EJS Static",
  "google_analytics": "XOXOXO"
}

Additional data from meta.json

{
  "home": {
    "title": "Grunt EJS Static | Home",
    "description": "The demo page for Grunt EJS Static",
    "keywords": "gruntplugin, ejs, static html, static site generator, templates, templating engine, template, embedded js"
  }
}

Generates this JSON data model

{
  "global": {
    "site_name": "Grunt EJS Static",
    "google_analytics": "XOXOXO"
  },
  "meta": {
    "title": "Home",
    "description": "The demo page for Grunt EJS Static",
    "keywords": "gruntplugin, ejs, static html, static site generator, templates, templating engine, template, embedded js"
  }
}

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

<!DOCTYPE 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]><!--> <html class="no-js"> <!--<![endif]-->

  <head>

    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">

    <title><%= global.site_name %> | <%= meta.title %></title>
    <meta name="<%= meta.description %>" content="">
    <meta name="<%= meta.keywords %>" content="" >

    <!-- css -->
    <link rel="stylesheet" href="/css/main.css">
    <!-- end css -->

    <!-- modernizr -->
    <script src="js/vendor/modernizr-2.6.2.min.js"></script>
    <!-- end modernizr -->

    <!-- google analytics -->
    <script>
      var _gaq=[['_setAccount','<%= global.google_analytics %>'],['_trackPageview']];
      (function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
      g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
      s.parentNode.insertBefore(g,s)}(document,'script'));
    </script>
    <!-- end google analytics -->

  </head>

Outputs this HTML

<!DOCTYPE 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]><!--> <html class="no-js"> <!--<![endif]-->

  <head>

    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">

    <title>Grunt EJS Static | Home</title>
    <meta name="The demo page for Grunt EJS Static" content="">
    <meta name="gruntplugin, ejs, static html, static site generator, templates, templating engine, template, embedded js" content="" >

    <!-- css -->
    <link rel="stylesheet" href="/css/main.css">
    <!-- end css -->

    <!-- modernizr -->
    <script src="js/vendor/modernizr-2.6.2.min.js"></script>
    <!-- end modernizr -->

    <!-- google analytics -->
    <script>
      var _gaq=[['_setAccount','XOXOXO'],['_trackPageview']];
      (function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
      g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
      s.parentNode.insertBefore(g,s)}(document,'script'));
    </script>
    <!-- end google analytics -->

  </head>


  <body>

    <!-- hero here -->

    <!-- body content here -->

  <!-- footer -->
  <div class="container">

    <footer>
        <p>&copy; Company 2012</p>
    </footer>

  </div>
  <!-- end footer -->

  <script src="js/main.js"></script>

  </body>
</html>

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: {
        highlight: function(text) {
          return "<h1 style='color:red;'>" + text + "</h1>";
        },
        print_object: function(obj) {
          var output = '';
          for(var property in obj) {
            output += property + ': ' + obj[property]+'; \n';
          }
          console.log(output);
        }
      }
    }
  },
  // 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

module.exports = exports = {

  build_url: function(scheme, hostname, path, queries) {
    console.log('this hnappen ' + queries);
    var url = "";
    url += scheme;
    url += "://";
    url += hostname;
    url += path;
    if (queries.length > 0) {
      url += "?";
      queries.forEach(function(query, index) {
        if (index === 0) {
          url += query;
        } else {
          url += "&" + query;
        }
      });
    }
    return url;
  },

  print_object: function(obj) {
    var output = '';
    for(var property in obj) {
      output += property + ': ' + obj[property]+'; \n';
    }
    console.log(output);
  },

  highlight: function(text) {
    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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

grunt-ejs-static

Getting Started

The "ejs_static" task

Overview

Usage

Options

options.dest

options.path_to_data

options.path_to_layouts

options.index_page

options.parent_dirs

options.underscores_to_dashes

options.file_extension

options.helpers

options.underscore

Examples

Contributing

Release History

0.3.8

0.3.7

0.3.5

0.3.2

0.3.0

0.2.0