Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    grunt-file-processpublic

    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

    Keywords

    none

    install

    npm i grunt-file-process

    Downloadsweekly downloads

    95

    version

    0.2.2

    license

    none

    repository

    githubgithub

    last publish

    collaborators

    • avatar