grunt-dashboard

Generates a static dashboard based on data parsed within specified files

grunt-dashboard

Generates a static dashboard based on data parsed within specified files

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

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

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

Type: String Default value: dash

A string value that is used to determine your data search pattern.

Type: String Default value: dashboard/generated

A string value that is used to determine where the dashboard html file will be generated.

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.

Type: String Default value: node_modules/grunt-dashboard/dashboard/html-template.hbs

A string value that is used to determine what handlebars template should be used for generating components and other HTML partials.

Type: String Default value: ''

A string value that is used to determine what image should be used in a template as a logo.

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.

Type: Boolean Default value: true

A boolean value that is used to determine if data comments in your HTML files should be removed. This would mostly be used for when you are doing a production build.

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.

In this example, the default options are used to parse JSON data from within an HTML file. So when the task below runs, it will create a index.html file within the dashboard directory built from all the scanned HTML files within the html directory.

html/index.html:

<!--[dash:data]
{
    "status": "development",
    "category": "page",
    "label": "Home",
    "link": "path/to/file/index.html"
}
[/dash] -->

Gruntfile.js

grunt.initConfig({
  dashboard: {
    options: {},
    files: {
      'dashboard/index.html': ['html/*.html'],
    },
  },
})

In this example, you can see that the options.searchTerm property is used to change what pattern to look for. This new pattern i.e. [custom:data] will be used to parse for JSON data from within an HTML file. So when the task below runs, it will create a index.html file within the dashboard directory built from all the scanned HTML files within the html directory. Notice the second set of [custom] comments: This will also build out an HTML partial file using the markup within the [custom:html] comments using the handlebars template specified with options.htmlTemplate.

html/index.html:

<!--[custom:data]
{
    "status": "development",
    "category": "page",
    "label": "Home",
    "link": "path/to/file/index.html"
}
[/custom] -->
<!--[custom:html]
<div>
    <h1>Testing</h1>
    <p>
        This is just a simple test
    <p>
</div>
[/custom] -->

Gruntfile.js

grunt.initConfig({
  dashboard: {
    options: {
      searchTerm: 'custom',
      dashTemplate: 'dashboard/dashboard-template.hbs',
      htmlTemplate: 'dashboard/html-template.hbs',
      generatedDir: 'dashboard/generated'
    },
    files: {
      'dashboard/index.html': ['html/*.html']
    },
  },
})

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.

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

Copyright (c) 2014 Jake Larson. Licensed under the MIT license.