grunt-file-process

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

npm install grunt-file-process
13 downloads in the last day
39 downloads in the last week
327 downloads in the last month

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
npm loves you