Dan Reeves

Developer & gamer. I work at fffunction.

Getting Started With Gulp.js

Posted on — 1033 words about gulpjs.

Gulp.js is a build system/task automator written for nodejs. It’s useful for simplifying and speeding up your build process, automating tasks for you such as compiling code, minification, and concatenation.

Gulp differs from Grunt through the use of streams and a code-over-configuration approach. Through the use of streams, it allows you to write very simple scripts in a very similar way that you would to the front end using a library like jQuery while being very efficient and only writing files to the disk when you’re ready.

It’s also very easy to pick up and get running with only 6 methods to worry about. Only some minimal knowledge of the command line and npm is needed and then anyone comfortable writing javascript will get along nicely.

Before you start you’ll need nodejs and npm installed which you can here here.

Getting Started

First, you’ll need to install gulp globally with:

npm install -g gulp

Now you can go into your project directory and install gulp and gulp-util, which are the only two dependencies. You can also install any packages you’d like to use now.

npm install --save-dev gulp gulp-util
npm install --save-dev gulp-concat gulp-csso gulp-sass gulp-uglify

Here, I’ve also installed packages for concatenating files, minifying css, compiling sass, and minifying javascript.

The --save-dev option saves these packages to your devDependencies list in package.json. If you don’t already have this file, I recommend creating one according to the docs or using npm init to create one for you. The benefit of this is that anyone using this project will know exactly what packages they need and npm can automatically install them all.

My dependencies currently looks like this:

 "devDependencies": {
   "gulp": "~3.3.0",
   "gulp-concat": "~2.1.7",
   "gulp-csso": "~0.1.7",
   "gulp-sass": "~0.3.0",
   "gulp-uglify": "~0.1.0",
   "gulp-util": "~2.2.9"
 }

gulpfile.js

The next step is to actually write the script. You should create a file in the root of your project called gulpfile.js and open it up in your favourite text editor.

The first thing you need to do here is require all the modules you just installed. Nodejs uses CommonJS-style require and is very easy to understand:

var gulp = require('gulp'),
    gutil = require('gulp-util'),
    sass = require('gulp-sass'),
    csso = require('gulp-csso'),
    uglify = require('gulp-uglify'),
    concat = require('gulp-concat');

The API

Gulp has 6 methods: gulp.task, gulp.src, gulp.dest, gulp.watch, gulp.run, and gulp.env. The first five are the most important.

gulp.task is used for defining a task. You pass it a name and a function to be run. When you enter gulp to the command line it tries to execute the default task but if you pass anything in it will try to do that task, for example gulp taskone. Using this you can set up different tasks that you might run at different times, such as a testing/dev task, where you keep code unminified and create source maps, or a production task, where you minify and concatenate everything.

This can also be done using gulp.env which allows you to pass in --options.

The next two important methods to know about are gulp.src and gulp.dest. Using these methods you tell gulp where to find the files you want to use, and where to output the new ones.

The last thing you will need to know before you can write a simple gulpfile is about nodejs’ pipe method. This method takes in a text stream and sends it to a passed in function.

Writing A Task

The first thing we’ll write is a task to compile our sass and minify it.

gulp.task('css', function () {
    gulp.src('./pathto/css/*.scss')
        .pipe(sass({includePaths: ['pathto/css']}))
        .pipe(csso())
        .pipe(gulp.dest('./assets/css'));
});

Here we’ve created a task named css which sources all .scss files in the folder /path/to/ from the root of our project. It pipes these files to the sass() function with an option that tells sass where the include files are. This is only necessary if you’re using @include in your sass.

It then gets piped into csso() which minifies it and lastly it is piped ito gulp.dest() which creates the file in the assets/css folder from the root of the project.

This can now be run by using gulp css from the command line while in the root of your project directory.

I created another task for my javascript:

gulp.task('js', function () {
    gulp.src('./pathto/js/*.js')
        .pipe(uglify())
        .pipe(concat('all.js'))
        .pipe(gulp.dest('./assets/js'));
});

The usage and documentation for all packages can be found on their npm registry page and you can find gulp-packages by searching here.

Automation

It’s good so far; we can build our css and js with only two commands:

gulp css
gulp js

but we can make it better.

This is where the gulp.watch and gulp.run methods come in. gulp.watch is a built-in method of telling gulp which files to look at, and to do something when they change. gulp.run is the method for running a task by passing it one or more names.

We can now create a default task that runs both the css and js tasks, like so:

gulp.task('default', function () {
    gulp.run('css', 'js');
});

This now only requires you to type gulp to run.

However, going to the command line and typing gulp every time you’ve made a change isn’t ideal.

We can create watch function which keep and eye on your different types of files and run the necessary tasks when they are changed. This helps keep the build times down by only doing the tasks needed at the time, instead of rebuilding all the files.

Our default task could instead look like this:

gulp.task('default', function () {

    // Run both tasks on first run
    gulp.run('css', 'js');

    // Watch the css folder for changes
    gulp.watch('./pathto/css/*', function () {
    	// Run the css task
        gulp.run('css');
    });

    // Watch the js folder for changes
    gulp.watch('./pathto/js/*', function () {
    	// Run the js task
        gulp.run('js');
    });
});

Now, when we run gulp it will keep running until we close it with Ctrl C.

You now have an almost fully automated built process. It is also possible to use a livereload package which even automates page refreshes for you after you have changed anything.

Click here to see my full gulpfile.js


Search A Jekyll Blog With Typeahead.js

Posted on — 768 words about jekyll and js.

One of my first concerns with starting my blog on GitHub pages was the lack of server-side programming. It means you can’t easily pull off many blog standards, such as search. In this post you’ll see how I did it.

Typeahead.js by Twitter

I don’t believe in reinventing the wheel, so, I went searching for an auto-complete library. Enter Typeahead.js.

Typeahead is a “fast and fully-featured autocomplete library” by Twitter.

The API is very simple and it provides a nice UI to search.

var search = $('#search').typeahead({
    prefetch: '/search.json'
});

This code will turn the targeted input[type="text"] into an autocompleting search box for the prefetched json file, which we’ll come onto later.

Note that typeahead does have a dependency on jQuery 1.9+.

This is great but it doesn’t actually do anything yet. Luckily, typeahead also has built in events to listen for.

search.on('typeahead:selected', function (evt, data) {
    window.location = data.url;
});

Now, when an autocomplete option is selected the reader will be redirected to the page of that post. Simples.

search.json

In order to search, we’ll now need something to actually search.

If you’ve already made a blog in Jekyll you’ll know all about the site.posts array and how to loop through it getting the data about each post. If you need a refresher here are the docs for the simliar paginator.posts array.

The first thing to understand about Jekyll is that anything that contains YAML front-matter will be processed by Jekyll as a special page.

Here’s how my search.json file looks:

[
    {% for post in site.posts %}
    {% assign title = post.title | split:' ' %}
    {% assign date = post.date | date_to_long_string | split:' ' %}
    {
        "value": "{{ post.title }}",
        "tokens": [
            {% for tag in post.tags %}"{{ tag }}",{% endfor %}
            {% for word in title %}"{{ word }}",{% endfor %}
            {% for word in date %}"{{ word }}",{% endfor %}
            false
            ],
        "date": "{{ post.date | date_to_long_string }}",
        "url": "{{ post.url }}"
    },
    {% endfor %}
    false
]

Please note that this following file should start with two lines of three hyphens, as shown on the page linked above. Jekyll is being a pain and rendering them as <hr>s.

The first two lines are empty YAML front-matter, to tell Jekyll to process this file. Next, I open the array and start looping through my posts with {% for post in site.posts %}.

The canonical data structure typeahead expects is an object with value and tokens properties. The value is a string which represents the underlying value. The tokens is an array of single-word strings that typeahead uses to match the value to the search query.

I used the built-in filter split in order to create arrays of single words for both the title and the data:

{% assign title = post.title | split:' ' %}
{% assign date = post.date | date_to_long_string | split:' ' %}

This allowed me to then loop through each word and add it to the array.

{% for tag in post.tags %}"{{ tag }}",{% endfor %}
{% for word in title %}"{{ word }}",{% endfor %}
{% for word in date %}"{{ word }}",{% endfor %}

The post.tags are already an array, defined in the post front-matter.

Typeahead also allows extra properties which will be passed along with the result; I added the date and a url.

If you look at the event listener code again you’ll see I accessed the data.url property of the returned object.

Enhancements

So, that works nicely, however when someone is searching my posts I want them to be able to see what date it was published before they go looking at an outdated post.

By default, typeahead only displays the data.value in the search results but it also allows you to pass in a template and templatating engine to do custom results.

I decided to include Hogan.js, a moustache templating engine also developed by Twitter.

Now my search initialization looks like this:

var search = $('#search').typeahead({
    prefetch: '/search.json',
    template: [
        '<p class="post-name">{{value}}</p>',
        '<p class="post-date">{{date}}</p>'
        ].join(''),
    engine: Hogan
});

As you can see, I passed in two extra properties to typeahead, a template and an engine. This allows me to create custom search results including the publication date.

There we have it: a functional search box on a Jekyll blog. Unfortunately it only works for those with js enabled, but, hey, progressive enhancement!

If you need any help with it or have any suggestions for me feel free to hit me up on Twitter @heydanreeves.


Simple Is Beautiful

Posted on — 486 words about photoshop and simplicity.

I think it took the advent of the smart phone to help us realise that simple, single purpose apps are really good. It probably came from how limited the smartphone was, limited screen real estate; limited memory both in terms of storage and ram, but it had stuck around as phones and tablets became more powerful and it’s a trend that has even made is way onto the desktop.

The reason this design is so popular is because it makes it incredibly easy for the user to do what they want to do.

Today I was attempting to create an image map with photoshop. I knew about the slice tool, so I quickly sliced up my image, added links and exported. Wrong! That’s a <table>; fiddle around a bit and you can make it <div>s. Google didn’t help either. The tutorials I found were years old. Eventually I discover that the feature had been removed and I should use fireworks instead. Ugh! Time to give up.

Here’s what I should have done: - Search for image map app. - Install one. - Create the image map.

The right tool for the job

The reason the feature was removed was probably (hopefully) exactly what I am talking about. Photoshop isn’t the tool for that job, it doesn’t need that functionality and keeping it was extra bloat. It’s still a very feature-full app, I’m not a photoshop pro and in the position to tell you that it’s not all needed, but how many people use photoshop for all of them.

My main use of it, and I think a lot of people might agree, is as a psd viewer for coding up designs. It shouldn’t be like that. Where’s my simple app that let’s me view a psd, how and show layers, and maybe get some details out like dimensions or hex codes?

Single responsibility

To give a coding analogy, photoshop would be a class that is a thousand lines long and has all the apps functionality. We already know this is wrong which is why OOP, encapsulation, and single responsibility are such important aspects to modern programming. The Unix philosophy starts: “Write programs that do one thing and do it well. Write programs that work together.” We’ve been doing this for years with command line tools but it hasn’t really translated over to full GUI apps. I think this is changing but it’s up to us to build these apps.

Go forth and code

So, in conclusion, we should all go and build some really simple but really great apps. Use open formats & play nicely with others.


I wrote this on the bus on the way home from work so if anything is wrong or if you have some suggestions for me on great apps to use (especially a psd viewer) let me know on Twitter - @heydanreeves


A Switch to GitHub Pages

Posted on — 312 words about github and blogging.

When I first built this blog I wanted somewhere I could easily write, publish, and archive my thoughts and things I have learnt. One of my main goals was keeping everyone stored on GitHub where it would be easily accessible in a raw format.

I quickly realised that it was a waste of time to maintain a separate repo for my posts and my site. I also wanted to streamline my publication/deployment process. Keeping an server up to date with multiple git repos via FTP was too much of a chore for me.

GitHub Pages

GitHub Pages is a brilliant (and free!) service provided by GitHub which serves static websites directly from a repository. Best of all, they support websites powered by Jekyll, a blog-aware static site generator. This means that I can publish a new post with a simple git push.

Luckily, the templating syntax is very similar to Pico so my site needed very little reconstructing and it was mostly a file structure change.

This move also highlighted my choice in markdown for my content. All my post easily dropped into the new site and worked, minus a different meta data syntax and file name syntax. However, the Jekyll method does seem more future proof to me; meta data is now written in YAML and the file names contain the publication date.

If you haven’t yet tried a Jekyll site I strongly recommend it. It makes simple static sites very easy to create and maintain.

Other Changes

The site has also had a make over! I went a minimalist style to keep the focus on the content (how adventurous of me).

I’m now using the font Roboto which is the current Android System Font.

I have also implemented a post search using typeahead.js by twitter, but more on that later.


Showing and hiding hidden files in OS X

Posted on — 674 words about bash and osx.

EDIT: 2013-11-09

I recently realised one of my favourite apps for the mac, BetterTouchTools, comes with the ability to create a custom gesture or keyboard shortcut which does this very thing so now I can hide or show dotfiles by simply pressing Command + Caps Lock. Incidentally, I’ve also remapped my caps lock key to F19 using PCKeyboardHack so that I can then use it in custom keyboard shortcuts defines in BetterTouchTools.

If you haven’t already remapped Caps Lock you might want to look into it. Also if you aren’t already using BetterTouchTools, I strongly recommend it!

This kinda makes the rest of the post redundant but if you’re still interested in some command line tips keep reading.


If you work on the web chances are you’ll be using .htaccess files. By default these are hidden in the finder on OS X which is a pain. Luckily making these hidden files visible is pretty easy. Simply open the terminal (or your favourite CLI) and enter:

defaults write com.apple.Finder AppleShowAllFiles TRUE && killall Finder

The first half of the command is writing to the system default settings. The && is a conditional execution. This means that the second command can only run if the first is successful. Next the Finder app is killed off and restarted in order for the new settings to take effect.

You can reverse this and hide the files again by replacing TRUE with FALSE.

defaults write com.apple.Finder AppleShowAllFiles FALSE && killall Finder

As a side note, I have seen people use both com.apple.Finder and com.apple.finder. On my installation I have found it best to use both else the it wouldn’t take effect immediately but your milage my vary.

Power User

This is good, but not very practical. However, once again Bash comes to the rescue. We can create aliases in bash which means we can put that whole command in to a variable of our choice, for example:

alias shf="defaults write com.apple.Finder AppleShowAllFiles TRUE && defaults write com.apple.finder AppleShowAllFiles TRUE && killall Finder"

From then on you can simply type shf (show hidden files. See what I did there?) and it will execute all of that.

To be even more useful we can add this to our .bashrc or .bash_profile so it will load every time you start the bash shell. To complete this effect add the following lines to either your .bashrc or .bash_profile files in your home directory: /user/USERNAME/.

alias shf="defaults write com.apple.Finder AppleShowAllFiles TRUE && defaults write com.apple.finder AppleShowAllFiles TRUE && killall Finder"

alias hhf="defaults write com.apple.Finder AppleShowAllFiles FALSE && defaults write com.apple.finder AppleShowAllFiles FALSE && killall Finder"

Now you can always type shf to show hidden files and hhf to hide them again.

Super Power User

This is great, but you might not always have a CLI open and you may not want to open one.

OS X has a great feature called Spotlight which is easily opened with Cmd + Space. The great thing about this is it can open files, run applications, and even executables.

Create the following two files.

shf:

#!/bin/bash

defaults write com.apple.Finder AppleShowAllFiles TRUE && defaults write com.apple.finder AppleShowAllFiles TRUE && killall Finder

hhf:

#!/bin/bash

defaults write com.apple.Finder AppleShowAllFiles FALSE && defaults write com.apple.finder AppleShowAllFiles FALSE && killall Finder

Next, in your CLI, enter sudo chmod +x myfile substituting ‘myfile’ for the names of the files you have created. This will give them the ability to be executed as scripts.

Now, you can type shf or hhf into the spotlight, hit enter and the script will run. If the terminal stays open then you need to go into Terminal Preferences > Settings > Shell and set the ‘When shell exits’ setting to ‘Close if the shell exited cleanly’. This means that if the script is successful the terminal will close. If you use a different CLI you’ll have to find the appropriate settings yourself.

There you have it, the ability to easily hide or show those pesky hidden files.