grunt-text-include v0.1.2
grunt-text-include
The best grunt plugin ever.
Include simple text resources such as HTML snippets as strings in your project. I use Handlebars and grunt-contrib-handlebars for my templates, but for parameterless templates you can use this. Read a folder of HTML files and this plugin will output a .js file which contains an object with filenames as keys and contents as values.
Getting Started
If you haven't used grunt before, be sure to check out the Getting Started guide.
From the same directory as your project's Gruntfile and package.json, install this plugin with the following command:
npm install grunt-text-include --save-dev
Once that's done, add this line to your project's Gruntfile:
grunt.loadNpmTasks('grunt-text-include');
If the plugin has been installed correctly, running grunt --help
at the command line should list the newly-installed plugin's task or tasks. In addition, the plugin should be listed in package.json as a devDependency
, which ensures that it will be installed whenever the npm install
command is run.
You may also want to use grunt watch:
watch: {
options: {
atBegin: true
},
text_include: {
files: ['app/templates/*.html'],
tasks: ['text_include']
},
handlebars: {
files: ['app/templates/*.hbs'],
tasks: ['handlebars']
}
}
The "text_include" task
Overview
In your project's Gruntfile, add a section named text_include
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
text_include: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
},
},
})
Options
options.namespace
Type: String
Default value: Templates
Name of the global object which contains the strings. Assigned as this["Templates"] = {...}
options.processName
Type: Function {String -> String}
Default value: identity
A function which takes the filename and returns the key this file should have.
options.processContent
Type: Function {String -> String}
Default value: identity
A function which takes the file content and returns it.
options.header
Type: String
Default value:
Text to include before the object.
options.footer
Type: String
Default value:
Text to include after the object.
Usage Examples
Default Options
In this example, the default options are used to import two text files. So if the testing.html
file has the content Testing
and the 123
file had the content 1 2 3
, the generated result would be the object Templates
:
{
'src/testing.html': 'Testing',
'src/123': '1 2 3'
}
grunt.initConfig({
text_include: {
options: {},
files: {
'dest/default_templates.js': ['src/testing', 'src/123'],
},
},
})
Custom Options
In this example, custom options are used to make the keys friendlier and append something to the content. So if the app/templates folder contains two html files: testing.html
file has the content Testing
and the hello-there.html
file had the content Hello\n\nthere
, the generated result in this case would be the following $T object:
{
testing: 'Testing - app/templates/testing.html',
helloThere: 'Hello\n\nthere - app/templates/hello-there.html'
}
grunt.initConfig({
text_include: {
options: {
namespace: '$T',
processContent: function(fileContent, filePath) {
return fileContent + ' - ' + filePath
},
processName: function (filePath) {
return filePath.replace(/^app\/templates\//, '').replace(/\.html$/, '').replace(/-(\w)/g, function (match, letter) {
return letter.toUpperCase();
});
}
},
files: {
'dest/templates.js': ['app/templates/*.html'],
},
},
})
See the tests for further examples
Header And Footer Options
In this example we will wrap the object with an AMD define. For example, wrap the following object.
{
'src/testing.html': 'Testing',
'src/123': '1 2 3'
}
resulting roughly in the equivalent JS file
define([], function () {
this.Templates = {
'src/testing.html': 'Testing',
'src/123': '1 2 3'
};
return this.Templates;
});
using the following config settings
grunt.initConfig({
text_include: {
options: {
header: "define([], function () {\n",
footer: "\nreturn this.Templates;\n});"
},
files: {
'dest/templates.js': ['app/templates/*.html'],
},
},
})
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
14 April 2014 - First release