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;
process
task
The 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:
files
that follows standard Grunt file configuration options
and
processors
that allows to extend the default capabilities of theprocess
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 ruleswhere CSS file is represented by
<link href="path/to/cssfile.ext">
-
replace every local path to image or font with it's
base64
-encoded stringwhere image is represented by
<img src="path/to/imagefile.ext">
(single or double quotes), orurl(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
isregexp|substr
, as defined by the standard JavaScriptString#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 objectfilepath
- 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 onpattern
) and it receives the following parameters:-
context
- context object that was created bysetup
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 inString#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 tohandler
functionhandlerOutput
- result of thehandler
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