├── .gitignore ├── .jshintrc ├── gulpfile.js ├── package.json ├── index.js ├── README.md └── test └── test.js /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | .DS_Store -------------------------------------------------------------------------------- /.jshintrc: -------------------------------------------------------------------------------- 1 | { 2 | "curly": true, 3 | "eqeqeq": true, 4 | "expr": true, 5 | "freeze": true, 6 | "indent": 4, 7 | "maxlen": 120, 8 | "newcap": true, 9 | "noarg": true, 10 | "node": true, 11 | "nonbsp": true, 12 | "quotmark": true, 13 | "trailing": true, 14 | "undef": true, 15 | "unused": true 16 | } 17 | -------------------------------------------------------------------------------- /gulpfile.js: -------------------------------------------------------------------------------- 1 | var gulp = require('gulp'); 2 | var jshint = require('gulp-jshint'); 3 | var stylish = require('jshint-stylish'); 4 | var mocha = require('gulp-mocha'); 5 | 6 | gulp.task('lint', function() { 7 | gulp.src(['./index.js', './test/test.js']) 8 | .pipe(jshint()) 9 | .pipe(jshint.reporter(stylish)); 10 | }); 11 | 12 | gulp.task('test', function() { 13 | gulp.src('./test/test.js') 14 | .pipe(mocha({ reporter: 'spec' })); 15 | }); 16 | 17 | gulp.task('cat', function() { 18 | gulp.src('./test/test.js') 19 | .pipe(mocha({ reporter: 'nyan' })); 20 | }); 21 | 22 | gulp.task('default', ['lint', 'test']); 23 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "gulp-build", 3 | "version": "0.5.3", 4 | "description": "Build files for different environments by swapping in variables", 5 | "homepage": "https://github.com/tjeastmond/gulp-build", 6 | "main": "index.js", 7 | "scripts": { 8 | "test": "make test" 9 | }, 10 | "author": { 11 | "name": "TJ Eastmond", 12 | "email": "tj.eastmond@gmail.com", 13 | "url": "http://tjeastmond.com" 14 | }, 15 | "contributors": [ 16 | "Chris Mendis (https://github.com/chrismendis)" 17 | ], 18 | "repository": { 19 | "type": "git", 20 | "url": "git://github.com/tjeastmond/gulp-build.git" 21 | }, 22 | "keywords": [ 23 | "underscore", 24 | "gulpplugin", 25 | "build", 26 | "handlebars", 27 | "partials", 28 | "gulp" 29 | ], 30 | "license": "MIT", 31 | "dependencies": { 32 | "through2": "2.0.0", 33 | "underscore": "1.8.3", 34 | "handlebars": "4.0.5" 35 | }, 36 | "devDependencies": { 37 | "gulp": "3.9.0", 38 | "gulp-util": "3.0.7", 39 | "mocha": "2.3.4", 40 | "should": "8.1.1", 41 | "gulp-jshint": "1.12.0", 42 | "jshint-stylish": "2.1.0", 43 | "gulp-mocha": "2.2.0" 44 | } 45 | } 46 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | var through = require('through2'); 2 | var _ = require('underscore'); 3 | var hbs = require('handlebars'); 4 | 5 | module.exports = function(data, config) { 6 | var options = _.extend({ 7 | layout: null, 8 | partials: [], 9 | helpers: [] 10 | }, config); 11 | 12 | data = data || {}; 13 | 14 | var build = function(file, encoding, callback) { 15 | var fileContents = file.contents.toString(); 16 | var template = ''; 17 | 18 | if (options.helpers.length > 0) { 19 | _.each(options.helpers, function(helper) { 20 | hbs.registerHelper(helper.name, helper.fn); 21 | }); 22 | } 23 | 24 | if (options.partials.length > 0) { 25 | _.each(options.partials, function(partial) { 26 | hbs.registerPartial(partial.name, partial.tpl); 27 | }); 28 | } 29 | 30 | if (_.isString(options.layout) && options.layout.indexOf('{{> body') !== -1) { 31 | hbs.registerPartial('body', fileContents); 32 | template = hbs.compile(options.layout); 33 | } else { 34 | template = hbs.compile(fileContents); 35 | } 36 | 37 | file.contents = new Buffer(template(data)); 38 | 39 | return callback(null, file); 40 | }; 41 | 42 | return through.obj(build); 43 | }; 44 | 45 | module.exports.hbs = hbs; 46 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # gulp-build 2 | 3 | Gulp 3 plugin for building out files for deployment. Good for swapping environmental variables like Google Analytics IDs, or just compiling static HTML files. 4 | 5 | `gulp-build` uses HandleBars for templates, and supports helpers, partials, and layouts. 6 | 7 | **Version `0.5.0` was a big update. I moved away from using Underscore templates, and have added support for partials and layouts. Both partials and layouts must be passed in as strings, but a future update will bring support for file glob'ing.** 8 | 9 | ## Install 10 | 11 | ```shell 12 | npm install --save-dev gulp-build 13 | ``` 14 | 15 | ## Usage 16 | 17 | Basic usage: 18 | 19 | ```javascript 20 | var build = require('gulp-build'); 21 | 22 | gulp.task('build', function() { 23 | gulp.src('scripts/*.js') 24 | .pipe(build({ GA_ID: '123456' })) 25 | .pipe(gulp.dest('dist')) 26 | }); 27 | ``` 28 | 29 | With helpers: 30 | 31 | ```javascript 32 | var build = require('gulp-build'); 33 | 34 | var options = { 35 | helpers: [{ 36 | name: 'addition', 37 | fn: function(a, b) { return a + b; } 38 | }] 39 | }; 40 | 41 | gulp.task('build', function() { 42 | gulp.src('pages/*.html') 43 | .pipe(build({ title: 'Some page' }, options)) 44 | .pipe(gulp.dest('dist')) 45 | }); 46 | 47 | ``` 48 | 49 | Helpers are regular Handlebars helpers or block helpers that your layout, partials, and templates can call. 50 | 51 | For more information on Handlebars helpers, see http://handlebarsjs.com/#helpers and http://handlebarsjs.com/block_helpers.html. 52 | 53 | With partials and a layout: 54 | 55 | ```javascript 56 | var build = require('gulp-build'); 57 | 58 | var options = { 59 | partials: [{ 60 | name: 'footer', 61 | tpl: '

Copyright 2013

' 62 | }], 63 | layout: '{{> body}}' 64 | }; 65 | 66 | gulp.task('build', function() { 67 | gulp.src('pages/*.html') 68 | .pipe(build({ title: 'Some page' }, options)) 69 | .pipe(gulp.dest('dist')) 70 | }); 71 | 72 | ``` 73 | 74 | If your templates want to render partials, you just reference them as: `{{> partialName}}`. 75 | 76 | If you use a layout, you need the `{{> body}}` tag for the plugin to know where to place your content. If you omit it, your compiled file will be missing the main content! 77 | 78 | ## API 79 | 80 | ### gulp-build(data, config) 81 | 82 | #### data 83 | Templates vars passed down to `HandleBars` for compiling 84 | 85 | #### config.layout 86 | Type: `String`
87 | Default: null 88 | 89 | #### config.partials 90 | Type: `Array` containing `Objects`
91 | Default: [] 92 | 93 | A config object with partials would look like: 94 | 95 | ```javascript 96 | var options = { 97 | partials: [ 98 | { name: 'footer', tpl: '

Copyright 2014

' }, 99 | { name: 'header', tpl: '

The Header!

' } 100 | ] 101 | }; 102 | ``` 103 | 104 | Your template could use those partials by using: `{{> footer}}` or `{{> header}}` 105 | 106 | ### gulp-build.hbs 107 | 108 | Access to handlebars instance to extend its own functional. 109 | 110 | ## Contributing 111 | 112 | I'd like to see other template frameworks get integrated. Frameworks like: `ejs`, `Hogan` and `Mustache` but I might not have time to get to these soon. 113 | 114 | If you'd like to help out, just submit a pull request. Before submitting though, be sure to: 115 | 116 | * Update the README 117 | * Write new tests 118 | * Ensure previous tests don't break 119 | * Ensure `jshint` doesn't fail 120 | * Follow code layout/style 121 | 122 | You can run tests and `jshint` with: 123 | 124 | ```shell 125 | gulp lint 126 | gulp test 127 | ``` 128 | 129 | The default `gulp` task will run both of those. 130 | 131 | ## Testing 132 | 133 | Open a terminal in the directory containing `gulp-build` and then: 134 | 135 | ```shell 136 | npm install 137 | gulp 138 | ``` 139 | 140 | ## The License (MIT) 141 | Copyright (c) 2014 TJ Eastmond 142 | 143 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 144 | 145 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 146 | 147 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 148 | 149 | -------------------------------------------------------------------------------- /test/test.js: -------------------------------------------------------------------------------- 1 | /* global describe, it */ 2 | var build = require('../index.js'); 3 | var should = require('should'); 4 | var File = require('gulp-util').File; 5 | var Buffer = require('buffer').Buffer; 6 | 7 | var getFile = function(contents, expected) { 8 | return { 9 | file: new File({ 10 | cwd: '/home/tje', 11 | base: '/home/tje/test', 12 | path: '/home/tje/test/name.html', 13 | contents: contents || new Buffer('

And her name was, {{ name }}.

') 14 | }), 15 | expected: expected || '

And her name was, Melissa.

' 16 | }; 17 | }; 18 | 19 | describe('gulp-build', function() { 20 | it('should compile the template with one variable', function(done) { 21 | var stream = build({ name: 'Melissa' }), 22 | fakeFile = getFile(); 23 | 24 | stream.on('data', function(newFile) { 25 | should.exist(newFile); 26 | should.exist(newFile.path); 27 | should.exist(newFile.relative); 28 | should.exist(newFile.contents); 29 | Buffer.isBuffer(newFile.contents).should.be.true; 30 | newFile.contents.toString().should.equal(fakeFile.expected); 31 | done(); 32 | }); 33 | 34 | stream.write(fakeFile.file); 35 | }); 36 | 37 | it('should compile with partials', function(done) { 38 | var stream = build({ name: 'Figs' }, { partials: [{ name: 'header', tpl: '

Super Bad Ass Cat

' }]}); 39 | var fakeFile = getFile( 40 | new Buffer('{{> header}}

The most bad ass cat ever is easily, {{name}}.

'), 41 | '

Super Bad Ass Cat

The most bad ass cat ever is easily, Figs.

' 42 | ); 43 | 44 | stream.on('data', function(newFile) { 45 | should.exist(newFile); 46 | should.exist(newFile.path); 47 | should.exist(newFile.relative); 48 | should.exist(newFile.contents); 49 | Buffer.isBuffer(newFile.contents).should.be.true; 50 | newFile.contents.toString().should.equal(fakeFile.expected); 51 | done(); 52 | }); 53 | 54 | stream.write(fakeFile.file); 55 | }); 56 | 57 | it('should compile with partials and a layout', function(done) { 58 | var stream = build({ name: 'Jack' }, { 59 | partials: [{ name: 'header', tpl: '

The Tests

' }], 60 | layout: '{{> body}}' 61 | }); 62 | 63 | var fakeFile = getFile( 64 | new Buffer('{{> header}}

Just some tests, {{name}}!

'), 65 | '

The Tests

Just some tests, Jack!

' 66 | ); 67 | 68 | stream.on('data', function(newFile) { 69 | should.exist(newFile); 70 | should.exist(newFile.path); 71 | should.exist(newFile.relative); 72 | should.exist(newFile.contents); 73 | Buffer.isBuffer(newFile.contents).should.be.true; 74 | newFile.contents.toString().should.equal(fakeFile.expected); 75 | done(); 76 | }); 77 | 78 | stream.write(fakeFile.file); 79 | }); 80 | 81 | it('should ignore the layout because of missing {{> body}} tag', function(done) { 82 | var stream = build({ name: 'Jack' }, { layout: '' }); 83 | var fakeFile = getFile(new Buffer('

Just some tests, {{name}}!

'), '

Just some tests, Jack!

'); 84 | 85 | stream.on('data', function(newFile) { 86 | should.exist(newFile); 87 | should.exist(newFile.path); 88 | should.exist(newFile.relative); 89 | should.exist(newFile.contents); 90 | Buffer.isBuffer(newFile.contents).should.be.true; 91 | newFile.contents.toString().should.equal(fakeFile.expected); 92 | done(); 93 | }); 94 | 95 | stream.write(fakeFile.file); 96 | }); 97 | 98 | it('should compile with helpers', function(done) { 99 | var stream = build({ name: 'Jack' }, { 100 | helpers: [ 101 | { 102 | name: 'add', 103 | fn: function (a, b) {return a + b;} 104 | } 105 | ] 106 | }); 107 | 108 | var fakeFile = getFile( 109 | new Buffer('

1 + 2 is definitely equal to {{add 1 2}}.

'), 110 | '

1 + 2 is definitely equal to 3.

' 111 | ); 112 | 113 | stream.on('data', function(newFile) { 114 | should.exist(newFile); 115 | should.exist(newFile.path); 116 | should.exist(newFile.relative); 117 | should.exist(newFile.contents); 118 | Buffer.isBuffer(newFile.contents).should.be.true; 119 | newFile.contents.toString().should.equal(fakeFile.expected); 120 | done(); 121 | }); 122 | 123 | stream.write(fakeFile.file); 124 | }); 125 | 126 | it('should compile with partials that use the provided helpers', function (done) { 127 | var stream = build({ name: 'Jack' }, { 128 | helpers: [ 129 | { 130 | name: 'add', 131 | fn: function (a, b) {return a + b;} 132 | } 133 | ], 134 | partials: [ 135 | { 136 | name: 'addition', 137 | tpl: '

1 + 2 is definitely equal to {{add 1 2}}.

' 138 | } 139 | ] 140 | }); 141 | 142 | var fakeFile = getFile( 143 | new Buffer('
Fact: {{> addition}}
'), 144 | '
Fact:

1 + 2 is definitely equal to 3.

' 145 | ); 146 | 147 | stream.on('data', function(newFile) { 148 | should.exist(newFile); 149 | should.exist(newFile.path); 150 | should.exist(newFile.relative); 151 | should.exist(newFile.contents); 152 | Buffer.isBuffer(newFile.contents).should.be.true; 153 | newFile.contents.toString().should.equal(fakeFile.expected); 154 | done(); 155 | }); 156 | 157 | stream.write(fakeFile.file); 158 | }); 159 | 160 | it('should compile with a layout that use the provided helpers', function(done) { 161 | var stream = build({ name: 'Jack' }, { 162 | layout: '

We know that 1 + 2 is {{add 1 2}}.

{{> body}}
', 163 | helpers: [ 164 | { 165 | name: 'add', 166 | fn: function (a, b) {return a + b;} 167 | } 168 | ] 169 | }); 170 | 171 | var fakeFile = getFile( 172 | new Buffer('

But what is 1 - 2?

'), 173 | '

We know that 1 + 2 is 3.

But what is 1 - 2?

' 174 | ); 175 | 176 | stream.on('data', function(newFile) { 177 | should.exist(newFile); 178 | should.exist(newFile.path); 179 | should.exist(newFile.relative); 180 | should.exist(newFile.contents); 181 | Buffer.isBuffer(newFile.contents).should.be.true; 182 | newFile.contents.toString().should.equal(fakeFile.expected); 183 | done(); 184 | }); 185 | 186 | stream.write(fakeFile.file); 187 | }); 188 | 189 | it('should compile with a layout and partials that use the provided helpers', function(done) { 190 | var stream = build({ name: 'Jack' }, { 191 | layout: '

We know that 1 + 2 is {{add 1 2}}.

{{> body}}
', 192 | helpers: [ 193 | { 194 | name: 'add', 195 | fn: function (a, b) {return a + b;} 196 | }, 197 | { 198 | name: 'subtract', 199 | fn: function (a, b) {return a - b;} 200 | } 201 | ], 202 | partials: [ 203 | { 204 | name: 'subtraction', 205 | tpl: '

Well, it turns out that 1 - 2 is {{subtract 1 2}}.

' 206 | } 207 | ] 208 | }); 209 | 210 | var fakeFile = getFile( 211 | new Buffer('

But what is 1 - 2?

{{> subtraction}}'), 212 | '

We know that 1 + 2 is 3.

But what is 1 - 2?

' + 213 | '

Well, it turns out that 1 - 2 is -1.

' 214 | ); 215 | 216 | stream.on('data', function(newFile) { 217 | should.exist(newFile); 218 | should.exist(newFile.path); 219 | should.exist(newFile.relative); 220 | should.exist(newFile.contents); 221 | Buffer.isBuffer(newFile.contents).should.be.true; 222 | newFile.contents.toString().should.equal(fakeFile.expected); 223 | done(); 224 | }); 225 | 226 | stream.write(fakeFile.file); 227 | }); 228 | 229 | it('should available handlebars instance', function(done) { 230 | var stream = build(); 231 | var fakeFile = getFile( 232 | new Buffer('{{custom}}'), 233 | 'yes!' 234 | ); 235 | 236 | build.hbs.registerHelper('custom', function() { 237 | return 'yes!'; 238 | }); 239 | 240 | stream.on('data', function(newFile) { 241 | should.exist(newFile); 242 | should.exist(newFile.path); 243 | should.exist(newFile.relative); 244 | should.exist(newFile.contents); 245 | Buffer.isBuffer(newFile.contents).should.be.true; 246 | newFile.contents.toString().should.equal(fakeFile.expected); 247 | done(); 248 | }); 249 | 250 | stream.write(fakeFile.file); 251 | }); 252 | }); 253 | --------------------------------------------------------------------------------