grunt-task-helper
taskHelper helps selecting files for other tasks.
For example, you want to minify only changed JS files. Then taskHelper selects files which are newer than dest
from src
(or newer than the time when this ran last time), and these files are passed to grunt-contrib-uglify task.
And, taskHelper helps you do something small to files (or file's contents).
For example, rename file, replace text, etc...
You can create your custom task to do something easily via grunt.registerTask()
. Or, writing new plugin is easy too. Using taskHelper is more easy.
Getting Started
This plugin requires Grunt ~0.4.1
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-task-helper --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt;
The "taskHelper" task
taskHelper accepts standard Grunt files
components (see Files) and handlers.
The handler is a JavaScript Function which you wrote, or a name of builtin handler. These handlers are called in some timings to select files or do something to files or file's contents. If you want, taskHelper creates standard Grunt files
components which are new for other tasks.
Overview
In your project's Gruntfile, add a section named taskHelper
to the data object passed into grunt.initConfig()
(see Configuring tasks).
You specify the files
and some handlers (e.g. options.handlerByFile
). taskHelper accepts these all files, and some files are selected or done something via handler, and only selected files (filtered files) are passed to other tasks via options.filesArray
.
Example: Copy only CSS files which are needed. This handler works like expanded Custom Filter Function.
Gruntfile.js
grunt;
Example: Minify only changed JS files. (see Builtin handler "newFile".)
Gruntfile.js
grunt;
Example: Insert menu navigation into HTML files.
Gruntfile.js
var htmlMenu = gruntfile;grunt;
Example: Edit HTML files to refer to minified JS files (e.g. file.js
to file.min.js
).
Gruntfile.js
var jsFiles = ;grunt; // taskHelper:getJs must be first.grunt;
Handlers
taskHelper parses files
components, and calls handlers at some timings. The flow may be changed by return value of handlers.
You can specify JavaScript Function which you wrote, or a name of builtin handler. If you want, you can specify multiple handlers into a timing by specifying array of these.
Below are timings which call handlers, and how to specify each handlers.
handlerByTask
The handlers which were specified via options.handlerByTask
are called per a task(target) before files
components are parsed. This may be a handler, or an array which includes multiple handlers. (see Cycle of handlers.)
If JavaScript Function is specified, following arguments are assigned, and return value is the following meaning.
-
options
Type: Object
Copy ofoptions
which is passed togrunt.initConfig()
. -
Return value
If the handler returnsfalse
, exit current task immediately, and the remaining handlers are not called.
NOTE: Any value exceptfalse
(e.g.undefined
or returns with no value) is ignored. i.e. it means the same asreturn true
.
Example:
Gruntfile.js
grunt;
handlerByFileSrc
The handlers which were specified via options.handlerByFileSrc
are called per a src
file in specified files
components (and parsed by Grunt). This may be a handler, or an array which includes multiple handlers. (see Cycle of handlers.)
If JavaScript Function is specified, following arguments are assigned, and return value is the following meaning.
-
src
Type: String
The file path of asrc
file in specifiedfiles
components. This was parsed by Grunt, therefore Globbing patterns (e.g.foo/*.js
) which was specified tosrc
became real path that was found (e.g.foo/file-1.js
).
Ifsrc
includes multiple files (e.g. array of files, or filesfile-1.js
andfile-2.js
which was found via globbing pattern*.js
), all handlers inhandlerByFileSrc
are called with an assigned first file insrc
, and these handlers are called with an assigned second file, and continue next. (see Cycle of handlers.) Note that this flow may be changed by handler. (see Return value below.) -
dest
Type: String
The file path of adest
file in specifiedfiles
components. -
options
Type: Object
Copy ofoptions
which is passed togrunt.initConfig()
. -
Return value
If the handler returnsfalse
, remove current file path fromsrc
, and the remaining handlers inhandlerByFileSrc
are not called. This is like afilter
(see Custom Filter Function). If other tasks will take these selected files (filtered files), an Array must be specified tooptions.filesArray
. taskHelper addsfiles
components to this array, and you let other task refer to this array.
NOTE: Any value exceptfalse
(e.g.undefined
or returns with no value) is ignored. i.e. it means the same asreturn true
.
If the handler returns String, the currentsrc
file path is replaced with this String. Note that other task may ignore thesrc
file which doesn't exist.
Example:
Gruntfile.js
var cssFiles = src: 'theme-base/css/base.css' dest: 'public_html/css/base.css' path = ;grunt;
handlerByFile
The handlers which were specified via options.handlerByFile
are called per an element in specified files
components (and parsed by Grunt, and might have changed by handlerByFileSrc
). This may be a handler, or an array which includes multiple handlers. (see Cycle of handlers.)
If JavaScript Function is specified, following arguments are assigned, and return value is the following meaning.
-
srcArray
Type: Array
The array which includes the file path ofsrc
files in specifiedfiles
components. This was parsed by Grunt, therefore Globbing patterns (e.g.foo/*.js
) which was specified tosrc
became real path that was found (e.g.foo/file-1.js
). And, these might have changed by handlers inhandlerByFileSrc
. (see above.)
Ifsrc
is a file path (e.g. String'foo/file.js'
), this array includes an element (e.g. Array['foo/file.js']
). Ifsrc
files were all not found, array is empty. -
dest
Type: String
The file path of adest
file in specifiedfiles
components. -
options
Type: Object
Copy ofoptions
which is passed togrunt.initConfig()
. -
Return value
If the handler returnsfalse
, remove current element fromfiles
components, and the remaining handlers inhandlerByFile
are not called. If other tasks will take these selected files (filtered files), an Array must be specified tooptions.filesArray
. taskHelper addsfiles
components to this array, and you let other task refer to this array.
NOTE: Any value exceptfalse
(e.g.undefined
or returns with no value) is ignored. i.e. it means the same asreturn true
.
If the handler returns String, the currentdest
file path is replaced with this String.
Example:
Gruntfile.js
var path = ;grunt;
handlerByContent
The handlers which were specified via options.handlerByContent
are called per a dest
file in specified files
components (and parsed by Grunt, and might have changed by handlerByFileSrc
). This may be a handler, or an array which includes multiple handlers. (see Cycle of handlers.)
These are handlers to edit (or check) the content that should be written to dest
file.
If JavaScript Function is specified, following arguments are assigned, and return value is the following meaning.
-
contentSrc
Type: String
The currentsrc
file's contents to first handler. To remaining handlers, the text which returned by previous handler.
All currentsrc
files (which were parsed by Grunt, and might have changed byhandlerByFileSrc
) are loaded, and these concatenated contents is passed to first handler. The text which was returned via the end handler is written todest
file. -
options
Type: Object
Copy ofoptions
which is passed togrunt.initConfig()
. -
Return value
This value is passed to next handler. The end handler returns value to write todest
file.
If the handler returnsfalse
, the remaining handlers inhandlerByContent
are not called, anddest
file is done nothing.
NOTE: Any value exceptfalse
(e.g.undefined
or returns with no value) is content. i.e. if nothing was returned, empty text is written todest
file.
options.separator
All contents of current src
files are concatenated with options.separator
. For example, line-break-character \n
can be specified.
If this option was not specified, taskHelper uses line-break-character which was found first in current src
file's contents. If that was not found, grunt.util.linefeed
is used.
Priority Order:
options.separator
- line-break-character in
src
file's contents (found first) grunt.util.linefeed
NOTE: grunt.util.linefeed
is chosen via operating system which executes this task. Not operating system which uses the generated files. If this task is executed on Windows, \n
for others will be specified to options.separator
or src
files may include this.
Example:
Gruntfile.js
var htmlMenu = gruntfile;grunt;
handlerByAllFiles
The handlers which were specified via options.handlerByAllFiles
are called per a task(target) after files
components are parsed (and might have changed by handlerByFileSrc
and handlerByFile
). This may be a handler, or an array which includes multiple handlers. (see Cycle of handlers.)
If JavaScript Function is specified, following arguments are assigned, and return value is the following meaning.
-
files
Type: Array
This is specifiedfiles
components. This was parsed by Grunt, therefore Globbing patterns (e.g.foo/*.js
) which was specified tosrc
became real path that was found (e.g.foo/file-1.js
). And, these might have changed by handlers inhandlerByFileSrc
andhandlerByFile
. (see above.)
If the files were all not found or these were all removed byhandlerByFileSrc
andhandlerByFile
, array is empty.
This array may be different fromoptions.filesArray
. This array includes only files which were selected in current task(target), but theoptions.filesArray
may include files which were added by other tasks(targets) too. -
options
Type: Object
Copy ofoptions
which is passed togrunt.initConfig()
. -
Return value
If the handler returnsfalse
, exit current task immediately, and the remaining handlers are not called.
NOTE: Any value exceptfalse
(e.g.undefined
or returns with no value) is ignored. i.e. it means the same asreturn true
.
Example:
Gruntfile.js
var path = ;grunt;
Cycle of handlers
The handlers are called at some timings as follows unless it is aborted by returning false.
---------------------------------- <Task 1>
| CALL handlerByTask 1
| CALL handlerByTask 2
| :
|
| ------------------------------- <Element 1 of files>
| |
| | ---------------------------- <src file 1>
| | | CALL handlerByFileSrc 1
| | | CALL handlerByFileSrc 2
| | | :
| | ----------------------------
| |
| | ---------------------------- <src file 2>
| | | CALL handlerByFileSrc 1
| | | CALL handlerByFileSrc 2
| | | :
| | ----------------------------
| | :
| |
| | CALL handlerByFile 1
| | CALL handlerByFile 2
| | :
| |
| | CALL handlerByContent 1
| | CALL handlerByContent 2
| | :
| -------------------------------
|
| ------------------------------- <Element 2 of files>
| | (Same as <Element 1 of files>)
| -------------------------------
| :
|
| CALL handlerByAllFiles 1
| CALL handlerByAllFiles 2
| :
----------------------------------
---------------------------------- <Task 2>
| (Same as <Task 1>)
----------------------------------
:
Builtin handlers
You can specify name of builtin handler instead of JavaScript Function.
Now, taskHelper has following builtin handlers.
newFile
This is a handler for handlerByFile
to select files which are newer than dest
from src
(or newer than the time when this ran last time).
- In the basic case,
srcArray
includes a file path and adest
file path was specified. The modification times of both files are compared, and ifsrc
file is newer thandest
file, return true.
One src file : One dest file
Example: Minify only changed JS files.
Gruntfile.js
grunt;
- When the
srcArray
includes multiple files path and adest
file path was specified, if there is anysrc
file in which is newer thandest
file, return true.
Some src files : One dest file
Example: Concatenate files if one or more source files were updated. (More better way in Tips)
Gruntfile.js
grunt;
- When the file to compare was not specified (e.g.
dest
was not specified, ordest
is same file assrc
), ifsrc
file is newer than the time when this ran last time, return true.
taskHelper saves log file.grunt/grunt-task-helper/fileUpdates.json
for compare.
One or more src files : No dest file
Example: You don't need to keep PNG files that is source of minifying, because you have PSD files which is editable always and outputable to PNG.
Gruntfile.js
grunt;
NOTE: Logging the modification time of the file after task is best way, but current Grunt can't do it. Therefore the time is got via using options.mtimeOffset
. (see source code.)
size
This is a handler for handlerByFileSrc
to select files which match specified size.
You can specify minimum file size to options.minSize
, and maximum file size to options.maxSize
. One or both of these must be specified.
Example: Compress only big files.
Gruntfile.js
grunt;
Tips
Task efficiency
Some grunt plugins are wrapper of something which provide a method. And the method accepts src
file's contents and returns contents to write to dest
file.
If you want to give selected files by taskHelper to the plugin, specifying the method into handlerByContent
instead of the using the plugin is better. Because grunt parses files
components in every tasks(targets). handlerByContent
can be included to one task with other handlers.
Example: Minify CSS files if one or more source files were updated.
clean-css is wrapped by grunt-contrib-cssmin plugin.
Gruntfile.js
grunt;
Example: Minify only changed HTML files.
htmlclean is wrapped by grunt-htmlclean plugin.
Gruntfile.js
grunt;
Example: Concatenate files if one or more source files were updated.
handlerByContent
works like grunt-contrib-concat plugin. (Another plugin or module is unneeded.)
Gruntfile.js
grunt;
Log messages
Grunt outputs log to STDOUT. Handlers can output messages.
Example: When there are a lot of targets, handlers output messages outstanding more than message Running "..." task
by Grunt.
Gruntfile.js
var head = '==================================== ';grunt;grunt;
"Continue?", "Overwrite?" - Wizard style
The handlers work via user's response for interactively running.
Example: Interactively running via readlineSync.
Install readlineSync.
npm install readline-sync
Gruntfile.js
var readlineSync = ;grunt;