##Gulp: Automate and enhance your workflow

####Taskrunner? Gulp? Wha?

Gulp is a javascript task runner that will allow you to compile your Sass, concatenate, hint/lint your javascript, and prefix your CSS all on the fly. While CleanSlate will do some of this functionality for you via the config.yml file, Gulp allows you to go above and beyond what CleanSlate will do for you.

####What does it have to do with Hammer?

Gulp allows you to livereload (as long as you install the gulp-livereload plugin, or browsersync + gulp) your theme as you develop, autoprefix your css so you dont have to worry about vendor prefixes (ie -moz, -webkit) and do the general front end performance tweaks all while previewing your theme with Hammer. This allows for very fast iteration in theme development without the need for a static html mockup.

##Sounds good! How do I get started?

These examples get stale quickly use these only as a base of understanding copying and pasting is at your own risk

1. Install Node
2. Follow the Getting Started Guide over at Gulp's Github page
3. Create a gulpfile.js in your theme with one of the examples below:
4. Win

####Gulpfile example 1: Example includes gulp-sass, gulp-livereload, and gulp-autoprefixer. Make sure to install those plugins first.

npm install {plugin-name} --save-dev in the root of your theme.

var gulp = require('gulp'),
  sass = require('gulp-sass'),
  livereload = require('gulp-livereload'),
  prefix = require('gulp-autoprefixer');
  
// Compile Our Sass
gulp.task('sass', function() {
  gulp.src(
    ['./scss/*.scss',
    './scss/**/*.scss'])
    .pipe(sass())
    .pipe(prefix("last 1 version", "> 1%", "ie 8", "ie 7", { cascade: true }))
    .pipe(gulp.dest('stylesheets'))
    .pipe(livereload());
});

gulp.task('reload', function () {
  gulp.src('views/**/*.html')
    .pipe(livereload());
});

gulp.task('watch', function () {
  gulp.watch(['**/*.html','**/*.yml'],['reload']);
  gulp.watch(
    ['./scss/*.scss',
    './scss/**/*.scss'], 
    ['sass']);
});

gulp.task('default', ['sass','watch']);

####Gulpfile example 2: Example includes gulp-sass, browser-sync, and gulp-autoprefixer. Make sure to install those plugins first.

npm install {plugin-name} --save-dev in the root of your theme.

var gulp = require('gulp'),
  sass = require('gulp-sass'),
  browserSync = require('browser-sync'),
  prefix = require('gulp-autoprefixer');
  
// Compile Our Sass
gulp.task('sass', function() {
  gulp.src(
    ['./scss/*.scss',
    './scss/**/*.scss'])
    .pipe(sass())
    .pipe(prefix("last 1 version", "> 1%", "ie 8", "ie 7", { cascade: true }))
    .pipe(gulp.dest('./stylesheets'))
    .pipe(browserSync.reload({stream:true}));
});

gulp.task('reload', function () {
  gulp.src('views/**/*.html')
    .pipe(browserSync.reload({stream:true}));
});

gulp.task('browser-sync', function() {
  browserSync({
    logConnections: true,
    logSnippet: false
  });
});

gulp.task('watch', function () {
  gulp.watch(['**/*.html','**/*.yml'],['reload']);
  gulp.watch(
    ['./scss/*.scss',
    './scss/**/*.scss'], 
    ['sass']);
});

gulp.task('default', ['sass','browser-sync',,'watch']);

Gulp is all about the tasks. These tasks usually do 3 common things.

1. Read a file from a source destination
2. Process the file in some way
3. Output the file to a "distributable" destination.

Lets dissect a super basic sass() compilation task:

// Compile Our Sass
gulp.task('sass', function() {
  gulp.src([
    './scss/*.scss',
    './scss/**/*.scss'
    ])
    .pipe(sass())
    .pipe(gulp.dest('./stylesheets'));
});

The first line in the above code snippet is the declaration of the task. In this line you are naming the task then passing it an anonymous function. gulp.task('sass'... is the name of the task.

The second line tells the task that it will be reading from some source files. gulp.src.

gulp.src() takes 1 string argument, which can be in the following formats:

1. a path string: ./scss/somefile.scss
2. a path glob: ./scss/**/*.scss
3. or an array of path strings and path globs: ['./scss/randomfile.scss','./otherlocation/**/*.scss']

The next line following the gulp.src() and its arguments is .pipe() which passes the output src to the next function. .pipe() accepts 1 argument usually in the form of another function()

In this case we are passing the file contents into the sass() function. This sass() function is what compresses your *.scss files into css.

Now gulp needs to do something with this newly created css. Again a .pipe() function passes the new css content to a new function gulp.dest()

gulp.dest takes 1 string argument, which is a folder path (ie ./stylesheets)

At this point gulp now "writes" the contents of the sass() compression of the gulp.src() *.scss files into the directory of gulp.dest() of ./stylesheets.

Let's say we have another task that depends on the sass() task we created above.

gulp.task('secondTask', ['sass'], function () {  
  // this "secondTask" task will not start until
  // the sync task is all done... or will it???...
});

Actually the sass task in the above snippet will run synchronously to the secondTask. This may not be what we intended.

So how do we fix this? Stream returning to the rescue:

#####Stream

The example below returns the "stream" after the task is complete.

Note: because the way .pipe() works you will notice the return is placed before the opening gulp.src() that is because the chained functions are effectively one command.

gulp.task('sass', function () {  
    return  gulp.src([
      './scss/*.scss',
      './scss/**/*.scss'
    ])
      .pipe(sass())
      .pipe(gulp.dest('./stylesheets'));
});

Now secondTask will run after sass is complete.

Now that you understand a bit about chaining task the default task may make a bit more sense.

The default task is run when the gulp command is run from the command line. Think of it as the control for all the common task you want to run every time you load up gulp

gulp.task('default', ['sass','watch']);

This task will run both the 'sass' and 'watch' tasks asynchronously.