grunt-contextualize
This plugin overrides configuration properties based on the current context, in order to re-use a single set of plugin targets for multiple contexts.
This is particularly useful when a plugin is already configured with multiple targets -- for example, to create one JavaScript or CSS file for the whole site, and one for each set of pages on a complex site. In these cases, creating and maintaining a distinct configuration for each combination of components (e.g. site-wide vs. home page) with build configurations (development vs. distribution) is burdensome.
This plugin supports three modes (which can be mixed and matched):
- Contextual properties override the values of properties they're next to.
For example,
options: {pretty: true; pretty$release: false}
in a plugin configuration lets the corresponding plugin task seepretty
astrue
when thecontextualize
task isn't run, but asfalse
when the task follows thecontextualize:release
task. - With local configuration, contexts are specified inside each plugin's configuration, alongside the values that
are being modified. For example,
options: {pretty: true; _release: {pretty: false}}
. - With a global configuration, contexts are specified inside the
contextualize
section of the grunt configuration, and their values are copied into other tasks' configurations.
See the bottom of this README for examples of using each mode to modify SASS and Jade configurations.
Alternatives:
- Grunt templates work great when the configuration property is a string. Unfortunately, templates can't expand into non-string values, such as boolean flags.
- Grunt options are available when
grunt.initConfig
is called, and can therefore be used outside of string interpolation. However, the use of options requires that you specify them as command-line options, in conjunction with the task target(s), in the grunt command line. Unfortunately, command-line options can't be encapsulated in the target definitions. (A target can set option values, but then it's too late for this to affect configuration defined in the initial call togrunt.initConfig
.) - I wanted grunt-context to work, but its author says it's defunct. In time-honored weekend project manner, I decided I'd rather write my own with a different features than understand how to fix it.
- grunt-reconfigure handles the "global configuration" case. I didn't discover that plugin until after I had written this one, and had decided I liked the contextual properties and local configuration by then.
Getting Started
This plugin requires Grunt ~0.4.x
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-contextualize --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt;
The "contextualize" task
Overview
In your project's Gruntfile, do one or more of the following.
With any of these configurations:
- The
contextualize:context1
task will replace the value ofsomePlugin.options.anOption
by1
; and - the
contextualize:context2
task will replace the value ofsomePlugin.options.anOption
by2
.
Contextual Properties
Sprinkle properties named "#{propertyName}$#{context}"
into your grunt configuration.
grunt
Local configuration
Add properties named e.g. '_context1'
('_'
plus a context name) alongside the configuration options for other plugins.
This context property can be inside the object that contains the properties it replaces:
grunt
Or it can be inside a parent of this object:
grunt
Global Configuration
Add a section named contextualize
to the data object passed into grunt.initConfig()
.
grunt
Options
options.infix
Type: String
Default value: '$'
The separator between a contextualized property and its context.
Where contextualize looks for 'name$context1'
in the examples, a value of '_'
for options.prefix
would
cause it to look for 'name_context1'
instead.
'.'
or ':'
would be nice infix values, but using them would require you to quote your property names;
e.g. {'name.context1': ...}
instead of {name.context1: ...}
.
options.prefix
Type: String
Default value: '_'
The values keyed by property names that begin with this prefix are merged into nearby data.
Where contextualize looks for '_context1'
in the examples, a value of '$'
for options.prefix
would
cause it to look for '$context1'
instead.
'.'
or ':'
would be nice prefix values, but using them would require you to quote your property names;
e.g. {':context1': ...}
instead of {_context1: ...}
.
Also, '_
' has the feature that grunt ignores it when used at the top level of a multitask configuration,
where it could otherwise be mistaken for the name of a multitask target.
options.verbose
Type: boolean
Default value: false
Display information about which properties are replaced.
This has the same effect on this plugin as the --verbose
option to grunt
does, but
unlike that option it only affects this plugin.
Usage Examples
Local Configurations
In this example, grunt build
will build jade files with the pretty
option, and uncompressed
sass files with sourcemap
. into the build
directory.
grunt build:release
will build jade files without pretty
, and compressed sass files without
sourcemap
, into the release
directory.
grunt gruntregisterTask 'build' 'jade' 'sass'gruntregisterTask 'build:release' 'context:release' 'build'
Global Configuration
This configuration has the same effect as the preceding example.
grunt gruntregisterTask 'build' 'jade' 'sass'gruntregisterTask 'build:release' 'context:release' 'build'
See this project's Gruntfile for additional (CoffeeScript) examples.
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
- September 24, 20012 -- initial release