grunt-dashboard
Generates a static dashboard based on data parsed within specified files
Getting Started
This plugin requires Grunt.
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-dashboard --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt;
The "dashboard" task
Overview
In your project's Gruntfile, add a section named dashboard
to the data object passed into grunt.initConfig()
.
grunt
Options
options.compiler
Type: Object
Default value: undefined
Compiler you would like to use for rendering templates. The compiler you use must have a render
method in order to work (ex. Jade, Swig, etc)
NOTE: You will need to install your desired template compiler and require it as the value of the compile key
Example:
options: compiler:
options.compilerOptions
Type: Object
Default value: {}
Compiler options you would like to pass into your desired compiler.
Example:
options: compiler: compilerOptions: pretty: true filename: true
options.generatedDir
Type: String
Default value: dashboard/generated
A string value that is used to determine where the dashboard html file will be generated.
options.dashTemplate
Type: String
Default value: node_modules/grunt-dashboard/dashboard/dashboard-template.hbs
A string value that is used to determine what handlebars template should be used for generating the dashboard.
options.moduleTemplate
Type: String
Default value: node_modules/grunt-dashboard/dashboard/module-template.hbs
A string value that is used to determine what handlebars template should be used for generating components and other HTML partials.
options.logo
Type: String
Default value: ''
A string value that is used to determine what image should be used in a template as a logo.
options.data
Type: Object
Default value: {}
An object of custom variables that will be passed to the Handlebars template. Useful if you want to pass things like version information or other custom variables from your Grunt build process.
options.includes
Type: Array
Default value:
[{
cwd: 'node_modules/grunt-dashboard/dashboard/assets/',
src: [
'**/*'
]
}]
An array of file objects that will be copied over with the dashboard html file to the same output directory. The file object properties available to you are: cwd directory assets are located in.
src file search pattern, (*) is a wildcard that matches everything
This would mostly be used for including external stylesheets or scripts you want to use within a custom dashboard template.
Usage Examples
Default Options
In this example, the default options are used to parse JSON data from within a *.dash.json
. So when the task below runs, it will create a index.html
file within the dashboard
directory built from all the scanned JSON files within the index
directory.
index/index.dash.json
:
Gruntfile.js
grunt
Custom Compiler Options
In this example, you can see that the options.compiler
property is used to control which compiler to use for rendering module templates.
So when the task below runs, it will create a index.html
file within the dashboard
directory built from all the scanned Jade files within the index
directory.
Notice the index/index.dash.jade
example: This will build out an HTML partial file using the markup within that file using the jade compiler.
It's compiled source will then be rendered out to the handlebars template specified with options.moduleTemplate
.
index/index.dash.json
:
index/index.dash.jade
div h1 Testing p This is just a simple test
Gruntfile.js
grunt
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
v1.0.3 - Fixed incorrect Jade dependency issue.
v1.0.2 - Added options.data to module handlebars templates.
v1.0.1 - Updated Underscore to 1.8.2. Updated Underscore.string to 3.0.3.
v1.0.0 - Updated Less to 2.5.1. Updated jQuery to 2.1.4. Switched to eslint from jshint. Removed support for IE8. No longer parses source files, uses *.dash files for defining data and module templates. Added compiler and compilerOptions options.
v0.3.1 - Updated Swig, Jade, and Handlbars to their latest versions.
v0.3.0 - Added data
option so that custom variables can be passed from the Grunt task to the Handlebars template. API break: data
inside handlbars templates has changed to generated
. Update your custom templates accordingly.
v0.2.1 - Added assets
option back into the task and acts as an array of file objects that refer to external assets to be loaded within a custom dashboard template. Also added less and jquery to default template.
v0.2.0 - Removed assets
option from task. Imports will now be handled by author within the :swig
or :jade
dash comments
v0.1.9 - Updated jade and swig dependencies
v0.1.8 - Added swig.setDefaults({ cache: false }); to disable caching problems with Swig modules.
v0.1.7 - Removed EJS support. Removed extra console.logs. Added more test compile tasks.
v0.1.6 - Removed unneeded console.logs
v0.1.5 - Fixed issue with rendering swig asset files
v0.1.4 - Added support for .swig
files
v0.1.3 - Made the default dashboard template responsive with a mobile menu for filters.
v0.1.2 - Updated logic for generated filenames, they now all get the .html extention without their preprocessor added (ex: index.jade.html - > index.html). This should make things less confusing.
v0.1.1 - Updated logic to better handle the rendering of EJS and Jade Templates. Now jade and ejs templates can be directly passed in the files
property of the grunt task
v0.1.0 - Added support for EJS and Jade data comments ([dash:ejs]
or [dash:jade]
). Also added assests
option to allow for including mixins and html partials from other files to your Jade or EJS data comments
v0.0.9 - Added htmlTemplate
option to allow for [dash:html]
comments to create HTML partials within the 'generatedDir' option.
v0.0.8 - HOTFIX: fixed debug
option regex search pattern
v0.0.7 - HOTFIX: debug
option was not working
v0.0.6 - Added ability to remove data comments using debug
option (mostly for production build purposes).
v0.0.5 - Fixed dependencies to underscore and handlebars.
v0.0.4 - Updated ending pattern search regex to be more leinient to better handle HTML rendered by preprocessors (ie Jade).
v0.0.3 - Added logo
option. Updated dashboard template styles and logic.
v0.0.2 - Major Changes: No longer requires jade, now only depends on HTML. Default dashboard template is not also written in HTML + Handlebars. Search pattern has changed to something more readable (ie <!--[custom:data] [/custom] -->
). More options have been added/changed: symbol
is now searchTerm
, added 'generatedDir', and added 'dashTemplate'.
v0.0.1 - Initial alpha release
License
Copyright (c) 2014-2015 Jake Larson. Licensed under the MIT license.