grunt-file-process

0.2.2 • Public • Published

grunt-file-process

Grunt plugin for files (text-based) processing activities.

Getting Started

This plugin requires Grunt ~0.4.0

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-file-process --save-dev

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

grunt.loadNpmTasks('grunt-file-process');

The process task

The main (original) purpose of the task is to inline resources (images, CSS files and fonts) in HTML file to create a portable version - so that the resulting HTML file can be:

  • passed around without additional packaging effort
  • embedded in documentation and other HTML-compoatible resources (like documentation suites, for example)

The process task expects 2 configuration object:

and

  • processors that allows to extend the default capabilities of the process Grunt task

Default capabilities

When no processors configuration option is provided:

simple: {
	files: [
		{
			src: ['test/initial/**/*.html'], 
			dest: 'tmp/output/simple/'
		}
	]
}

or (in accordance to the aforementioned files configuration)

simple_expand: {
	files: [
		{
			expand: true,
			cwd: 'test/initial/',
			src: ['**/*.html'], 
			dest: 'tmp/output/simple_expand/'
		}
	]
}

the process task will parse all files and do the following:

  • TBD replace every local CSS file with <style></style> element that contains the CSS rules

    where CSS file is represented by <link href="path/to/cssfile.ext">

  • replace every local path to image or font with it's base64-encoded string

    where image is represented by

    • <img src="path/to/imagefile.ext"> (single or double quotes), or
    • url(path/to/imagefile.ext) (single, double or no quotes)

    and font is represented by

    • url(path/to/fontfile.ext) (single, double or no quotes)

processors configuration option

The mentioned additional configuration option processors allows one to add more processing power.

processors setting is, with all possible settings, looks like this:

custom: {
	options: {
		processors: [
			{
				pattern: <regex or string to match>,
				setup: function(grunt, filepath) {
					...
				},
				handler: function(context, matchParams) {
					...
				},
				teardown: function(context, handlerOutput) {
					...
				}
			}
		]
	},
	files: [
		{
			src: 'test/initial/simple.html', 
			dest: 'tmp/output/custom/'
		}
	]
}

where:

  • pattern is regexp|substr, as defined by the standard JavaScript String#replace method (with "replace" function):

      var newstring = str.replace(regexp|substr, replaceFunction);
    

    see MDN for more information.

  • setup is a function that is invoked once per file before any of the processors (default or custom) are applied and has the following parameters:

    • grunt - Grunt's environment object
    • filepath - normalized path to the currently processed file

    and may return a context object (empty one will be created by default)

  • handler is the function that works processes the matches (based on pattern) and it receives the following parameters:

    • context - context object that was created by setup function, as well as normalized path to the currently processed file and Grunt's environment object, so at the minimum, it will contain:

        {
        	filepath: <path to file>
        	grunt: <Grunt's environment object>
        }
      
    • matchParams - standard parameters as passed to "replace" function in String#replace (see MDN for more information)

  • teardown is a function that is invoked once per file after all of the processors (default or custom) are applied and has the following parameters:

    • context - as passed to handler function
    • handlerOutput - result of the handler function

For example, the following configuration:

custom: {
	options: {
		processors: [
			{
				pattern: /(img\s+src\s*)=\s*"(\s*.*?)\s*"|=\s*'(\s*.*?)\s*'.*?/gi,
				handler: function(context, matchParams) {
					return 'img="static/path/to/image.png"';
				}
			}
		]
	},
	files: [
		{
			src: 'test/initial/simple.html', 
			dest: 'tmp/output/custom/'
		}
	]
}

will replace every img src="<non empty string>" or img src='<non empty string>' string with path to a static image file: img="static/path/to/image.png".

Disabling default processing

Providing base64: false configuration option in the options hash would disable the base64 translation and run the custom (if any) processors only:

custom_no_default: {
	options: {
		base64: false,
		processors: [
			{
				pattern: /(img\s+src\s*)=\s*"(\s*.*?)\s*"|=\s*'(\s*.*?)\s*'.*?/gi,
				handler: function(context, matchParams) {
					return 'img="static/path/to/image.png"';
				}
			}
		]
	},
	files: [
		{
			src: 'test/initial/simple.html', 
			dest: 'tmp/output/custom_no_default/'
		}
	]
}

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.1.0 12.09.2013

    Initial release

  • 0.2.0 18.09.2013

    • Separated JS
    • Added documentation

Readme

Keywords

none

Package Sidebar

Install

npm i grunt-file-process

Weekly Downloads

3

Version

0.2.2

License

none

Last publish

Collaborators

  • dnutels