Mark Goodyear — Front-end developer and designer

Polling with Redux

Mon, 06 Nov 2017 00:00:00 +0000

Using ES6 with gulp

Wed, 24 Jun 2015 00:00:00 +0000

Nov 2nd, 2015

As of node 4, we're now able to use ES2015 without the need for Babel. However modules are not currently supported so you'll need to use `require()` still. Checkout the node docs for more info on what's supported. If you'd like module support and to utilise Babel, read on.
Post updated to use Babel 6.

With gulp 3.9, we are now able to use ES6 (or ES2015 as it's now named) in our gulpfile—thanks to the awesome Babel transpiler.

Firstly make sure you have at least version 3.9 of both the CLI and local version of gulp. To check which version you have, open up terminal and type:

gulp -v

This should return:

CLI version 3.9.0
Local version 3.9.0

If you get any versions lower than 3.9, update gulp in your package.json file, and run the following to update both versions:

npm install gulp && npm install gulp -g

Creating an ES6 gulpfile

To leverage ES6 you will need to install Babel (make sure you have Babel 6) as a dependency to your project, along with the es2015 plugin preset:

npm install babel-core babel-preset-es2015 --save-dev

Once this has finished, we need to create a .babelrc config file to enable the es2015 preset:

touch .babelrc

And add the following to the file:

{
  "presets": ["es2015"]
}

We then need to instruct gulp to use Babel. To do this, we need to rename the gulpfile.js to gulpfile.babel.js:

mv "gulpfile.js" "gulpfile.babel.js"

We can now use ES6 via Babel! An example of a typical gulp task using new ES6 features:

'use strict';

import gulp from 'gulp';
import sass from 'gulp-sass';
import autoprefixer from 'gulp-autoprefixer';
import sourcemaps from 'gulp-sourcemaps';

const dirs = {
  src: 'src',
  dest: 'build'
};

const sassPaths = {
  src: `${dirs.src}/app.scss`,
  dest: `${dirs.dest}/styles/`
};

gulp.task('styles', () => {
  return gulp.src(paths.src)
    .pipe(sourcemaps.init())
    .pipe(sass.sync().on('error', plugins.sass.logError))
    .pipe(autoprefixer())
    .pipe(sourcemaps.write('.'))
    .pipe(gulp.dest(paths.dest));
});

Here we have utilised ES6 import/modules, arrow functions, template strings and constants. If you’d like to check out more ES6 features, es6-features.org is a handy resource.

Introducing the vr unit to create simple vertical rhythm—using PostCSS

Fri, 12 Jun 2015 00:00:00 +0000

With Sass, I use a function to create simple vertical rhyhtm—generated from the base line-height—without the complexity of maintaining a baseline grid. With PostCSS, we can take this further and create a new unit.

Function-able Sass

The Sass (SCSS) function I use is very simple. It essentially returns a multiple of the base line-height to help create vertical rhythm. The function looks a little like this:

$line-height: 32px;

@function vr($amount) {
  @return $line-height * $amount;
}

And we can use it in our stylesheet like this:

.selector { margin-bottom: vr(2); }

This will multiply the line-height by the number passed in, so the result here would be 64px.

Extending with PostCSS

After digging into PostCSS, I decided to re-create the Sass function with a PostCSS plugin. Because PostCSS is a post-processer, we are able to extend CSS. The result was postcss-vertical-rhythm, which replicates the Sass function, but using a custom CSS unit—vr—instead of a function. For example:

.selector { margin-bottom: 2vr; }

This method works more like using plain CSS.

How do I use the vr unit?

Firstly, install postcss-vertical-rhythm via npm:

npm install postcss-vertical-rhythm --save-dev

If you’re using gulp, you can then add it to your project like this:

gulp.task('styles', function () {
  return gulp.src('source.css')
    .pipe(postcss(
      require('postcss-vertical-rhythm')()
    ))
    .pipe(gulp.dest('output.css'));
});

Next, we need to define the base font-size and line-height using the shorthand font property:

body {
  font: 1rem/2 sans-serif;
}

The font-size can be either em, rem, px or % based. postcss-vertical-rhythm will parse the property and calculate the px line-height value automatically—no variable set up required. In the case above, the line-height would be 32px.

Once this is set up, we can now use the vr unit:

p {
  padding-top: 1vr
  margin-bottom: 2vr;
}

And with the line-height at 32px from the above font property, the output is:

p {
  padding-top: 32px;
  margin-bottom: 64px;
}

postcss-vertical-rhythm also supports decimal values so we can easily use half or quarter values, for example: .5vr, .25vr.

Thoughts

If you have any feedback, please leave a comment below or you can find me on Twitter. If you’d like to know more more about PostCSS, I wrote about it here. Happy vertical rhythm-ing!

A look into writing future CSS with PostCSS and cssnext

Tue, 09 Jun 2015 00:00:00 +0000

Retinafy your Craft site with Retinafy plugin

Sat, 14 Mar 2015 00:00:00 +0000

Retinafy is a small plugin for Craft CMS. Its aim is to provide a simple way to generate the required images and markup for a retina screen.

How it works

Retinafy uses the srcset attribute, which lets us define different sized images to display depending what screen the user is browsing with. It uses the common 2x definition which lets us display a higher resolution image for retina screens.

To let Retinafy know which images are intended to be used for retina purposes, they will need to have an @2x suffix, e.g. image-name@2x.png. This signifies the intent of the image, and allows us to still upload non-retina images if a higher resolution isn’t available.

Usage

Once installed, there are two ways to call Retinafy. The first is via a Craft variable, and the second being a Twig filter. Firstly, the Craft Variable:

<img src="{{ craft.retinafy.image(assetFieldName) }}" alt="">

And the Twig filter:

<img src="{{ assetFieldName | reftinafy }}" alt="">

Both ways perform exactly the same function, so it’s a matter of preference for which method to use.

By default, Refinafy will create the 1x non-retina version of the uploaded @2x image. This will be used as the src attribute and the original @2x image will be used as the srcset. For example if we upload a 500 x 500 @2x image, Retinfafy will create a 250 x 250 version, and the markup generated would be:

<img src="[generated-image-250x250]" srcset="[original-image-500x500] 2x">

Any browser supporting scrset will then display the correct image based upon the display. A handy place to find out what browser support for this is at caniuse. Retinafy doesn’t provide any polyfills, however it gracefully degrades as any browser that doesn’t support srcset will get the non-retina version. Polyfills can be added manually if desired.

Using transforms

Transforms are a powerful feature of Craft. Retinafy can utilise existing transforms, and if the image is big enough to display a 2x version of the transform, it will be added to the srcset attribute. To use a transform, we can pass it into the Craft variable, or Twig filter:

<!-- Craft variable -->
<img src="{{ craft.retinafy.image(assetFieldName, 'transformHandle') }}">

<!-- Twig filter -->
<img src="{{ assetFieldName | reftinafy('transformHandle') }}" alt="">

Providing the uploaded image is equal too—or larger than—2x the transform size, it will create the @2x version. As an example, if we have a transform set at 250 x 250, it will create a 500 x 500 image, and the generated markup would be:

<img src="[transform-250x250]" srcset="[transform-2x-500x500] 2x">

Download

You can find the plugin on GitHub, and is also available to install through the Directory plugin. If you have any questions, let me know in the comments below or give me a Tweet.

Enjoy Retinafying!

Create an on-demand sticky header with Headhesive.js

Mon, 07 Apr 2014 00:00:00 +0000

Headhesive.js is a lightweight, fully customisable JavaScript plugin for creating an on-demand sticky header.

For a recent project I needed to create a sticky header that was only visible after a certain point on the page. I found a few plugins available, some relied on jQuery, some had many extra features that weren’t necessary. Whilst jQuery isn’t always a bad thing, I was looking for a lightweight, dependency-free solution. Headhesive.js was created.

What does it do?

Headhesive.js creates an on-demand sticky header that will appear after a specific scroll distance, or at a certain element. No dependancies and no fancy extra frills to get in your way. It works exactly how you tell it.

How to use

First of all you’ll need to include the headhesive.min.js file in your footer, then create an instance using any element:

var header = new Headhesive('.header');

This instantiates Headhesive.js on the .header element, using the default options—see the readme for more info on options. Upon instantiating, the .header element will be cloned with the class .headhesive--clone. In this example, the cloned element will look like this:

<div class="header headhesive--clone">
  <!-- header elements will be cloned inside -->
</div>

No styles are injected via the plugin, keeping the plugin lightweight and as user customisable as possible. To create a basic hide/show effect we need to add some CSS magic to the cloned element:

.headhesive--clone {
  position: fixed;                   /* fix the element */
  top: 0;                            /* make sure it's at the top */
  transform: translateY(-100%);      /* move it off screen */
  transition: all 300ms ease-in-out; /* add animation */
}

We shift the element off-screen by setting the transform: translateY property to -100%. Alternatively, we could use a negative margin to move the element off-screen. I prefer transform as there is no need to define any heights, and it works perfectly in IE9.

When reaching the target scroll distance, the class .headhesive--stick is added. We can use this and create some styles to show the element:

.headhesive--stick {
  transform: translateY(0%); /* move it back on screen */
}

We now have an on-demand sticky header!

Further customisation

Please check out the Headhesive.js project on GitHub for an always up-to-date guide on the options, methods, along with a downloadable demo.

If you have any questions or find an issue, please leave a comment below, or you can find me on Twitter.

Better development environments with Vagrant

Wed, 19 Mar 2014 00:00:00 +0000

Having a properly configured development environment is important to any project; Vagrant does just that.

Before we start, I’m going to assume you are using a Mac for development, but the principles are the same if you’re using Windows. It’s worth noting Linux users may not have the issues I cover in the post.

But MAMP rocks!?

I’m a long term user of MAMP, and still use it if I need to quickly fire up a PHP server to test something, though it’s not without its limitations. One in particular is that everything may seem perfect on your local machine, but as soon as it’s deployed to production, things could break. Why? The main difference here would be the Operating System. As you’ll likely be deploying to a Linux server and not OSX/Windows, there may be some compatability issues to iron out. Software (such as Apache, PHP, MySQL etc.) version differences can also cause big problems. From experience, it’s best to develop on the same versions of everything to avoid any potential hiccups. The last thing you want is to be fixing unexpected bugs that appear in a different version of PHP—especially after a launch.

Mirroring the production environment as much as possible is an important step to ensure as little as possible can go wrong. As they say; if it can go wrong, it will.

Other options

Another route I tried is to use the built-in Apache on OSX, along with installing MySQL and multiple PHP versions. Whilst this freed me from MAMP, it was a fairly complicated process and came across a few issues along the way. Replicating the same process on different machines isn’t an easy task, not to mention time consuming—especially in a team where everyone would need to have the same setup. If you had two projects with two different software requirements, things start to get complicated, too. So how do we solve these issues?

Meet Vagrant

Vagrant solves all these issues by allowing us to create portable virtual development environments. This means you can have as many environments as you need, each configured differently to suite the project requirements. So if you need PHP 5.4 on one project and PHP 5.3 on another, Vagrant makes it easy to manage. Replicating an environment on a different machine is as simple as running $ vagrant up, saving you the hard work and time of installing and configuring everything manually. Awesome!

Vagrant is easy to configure, so whether you need Apache or Nginx with a specific version of PHP, setting it up is a breeze.

Getting started with Vagrant

To get started, you’ll first need to install VirtualBox. Once installed, head over to Vagrant Downloads and grab the latest version.

I won’t go into the depths of setting up a project from scratch as there is a great getting started guide on the Vagrant website. I’d recommend taking a look through the documentation to familiarise yourself with Vagrant and its commands. Rather than learning about dev-ops and creating your own provisioning scripts to provision a Vagrant box, there are many tools out there to get you up and running in minutes. One of my favourites is Vaprobash.

Vaprobash uses a collection of Bash scripts to install everything you need to set up your environment. Choosing what you need with Vaprobash is as simple as uncommenting a few lines in the provided Vagrantfile, then running a $ vagrant up. That’s all there is to it, you’re ready to code.

Another tool is PuPHPet, an online GUI generator providing a wide range of options. Enter some project info, tick a couple of boxes and $ vagrant up. If Vaprobash doesn’t offer everything you need, I recommend giving PuPHPet a try.

Both are great options to get started without needing to learn any more than what you would using MAMP. If you need any more flexibility, you can get your hands dirty with provisionging tools—such as Puppet or Chef—to completely customise your environment.

Vagrant workflow

A typical Vagrant workflow would be something like:

Initiate a project and $ vagrant up. This starts up and configures the virtual machine first time round. Vagrant will take a short while to install everything on this first instance, so grab yourself a coffee while you wait.
When everything has installed, fire up your favourite editor and code like a ninja.
At the end of the day, either $ vagrant [suspend|halt|destroy]. Suspend will effectively pause the machine, halt will shutdown the machine, and destroy will completely remove all traces of the machine like it never existed. Remember to dump the database before destroying so you don’t lose it—I’ve done that far too many times! You can even store it in version control for safe-keeping. Usually you’ll only need to destroy a box when a project is complete. Halting or suspending will be fine for the duration. By doing this, $ vagrant up will be much quicker as everything is already installed in the box.

In summary

Vagrant is a great way to create shareable development environments, avoiding the classic line:

I don’t know what you’re talking about; it works fine on my machine!

Getting started with gulp

Sun, 19 Jan 2014 00:00:00 +0000

Updated Jan 28th, 2014 to reflect the advancement of gulp
Updated Apr 21st, 2014 to utilise updated `gulp-livereload`
Updated Aug 11th, 2014 Using `del` instead of `gulp-clean`, updated `gulp-livereload`
Updated May 20th, 2015 Update `gulp-ruby-sass` syntax
Updated Nov 2nd, 2015 Update `del` syntax
Updated Jan 12th, 2016 `gulp-minify-css` depreciated. Use `gulp-cssnano`

Step aside Grunt, there's a new task runner in town. Gulp is an intuitive, code-over-configuration, streaming build system. It's fast.

Why should I be interested? Good question. Gulp’s code-over-configuration makes it not only easy to write tasks for, but also much easier to read and maintain.

Gulp uses node.js streams, making it faster to build as it doesn’t need to write temporary files/folders to disk. If you want to learn more about streams—although not necessary—this article is a good read. Gulp allows you to input your source file(s), pipe them through a bunch of plugins and get an output at the end, rather than configuring each plugin with an input and output—like in Grunt. Let’s take a look at an example of what a basic Sass build could look like with both Grunt and gulp:

####Grunt:

sass: {
  dist: {
    options: {
      style: 'expanded'
    },
    files: {
      'dist/assets/css/main.css': 'src/styles/main.scss',
    }
  }
},

autoprefixer: {
  dist: {
    options: {
      browsers: [
        'last 2 version', 'safari 5', 'ie 8', 'ie 9', 'opera 12.1', 'ios 6', 'android 4'
      ]
    },
    src: 'dist/assets/css/main.css',
    dest: 'dist/assets/css/main.css'
  }
},

grunt.registerTask('styles', ['sass', 'autoprefixer']);

Grunt requires each plugin to be configured separately, specifying source and destination paths for each plugin. For example, we input one file to the Sass plugin, which then saves the output. We then need to configure Autoprefixer to input Sass’s output, which then outputs another file. Let’s take a look at the same configuration with gulp:

####Gulp:

gulp.task('sass', function() {
  return sass('src/styles/main.scss', { style: 'expanded' })
    .pipe(autoprefixer('last 2 version', 'safari 5', 'ie 8', 'ie 9', 'opera 12.1', 'ios 6', 'android 4'))
    .pipe(gulp.dest('dist/assets/css'))
});

With gulp we only input one file. This gets modified by the Sass plugin, passed to the Autoprefixer plugin and modified, then we get one file out. This process speeds up the build process as we’re not reading and writing unnecessary files to end up with one.

So you’re interested, now what? Let’s install gulp and create a basic gulpfile with some core tasks to get started.

Installing gulp

Before we delve into configuring tasks, we need to install gulp:

$ npm install gulp -g

This installs gulp globally, giving access to gulp’s CLI. We then need to install it locally to the project. cd into your project and run the following (make sure you have an existing package.json file):

$ npm install gulp --save-dev

This installs gulp locally to the project and saves it to the devDependencies in the package.json file.

Installing gulp plugins

We are going to install some plugins to achieve the following tasks:

Sass compile (gulp-ruby-sass)
Autoprefixer (gulp-autoprefixer)
Minify CSS (gulp-cssnano)
JSHint (gulp-jshint)
Concatenation (gulp-concat)
Uglify (gulp-uglify)
Compress images (gulp-imagemin)
LiveReload (gulp-livereload)
Caching of images so only changed images are compressed (gulp-cache)
Notify of changes (gulp-notify)
Clean files for a clean build (del)

To install these plugins, run the following command:

$ npm install gulp-ruby-sass gulp-autoprefixer gulp-cssnano gulp-jshint gulp-concat gulp-uglify gulp-imagemin gulp-notify gulp-rename gulp-livereload gulp-cache del --save-dev

This will install all necessary plugins and save them to devDependencies in package.json. A full list of gulp plugins can be found here.

Load in the plugins

Next, we need to create a gulpfile.js and load in the plugins:

var gulp = require('gulp'),
    sass = require('gulp-ruby-sass'),
    autoprefixer = require('gulp-autoprefixer'),
    cssnano = require('gulp-cssnano'),
    jshint = require('gulp-jshint'),
    uglify = require('gulp-uglify'),
    imagemin = require('gulp-imagemin'),
    rename = require('gulp-rename'),
    concat = require('gulp-concat'),
    notify = require('gulp-notify'),
    cache = require('gulp-cache'),
    livereload = require('gulp-livereload'),
    del = require('del');

Phew! That seems a lot more work than Grunt, right? Gulp plugins are slightly different from Grunt plugins—they are designed to do one thing and one thing well. An example; Grunt’s imagemin uses caching to avoid re-compressing images that are already compressed. With gulp, this would be done with a cache plugin, which can also be used to cache other things too. This adds an extra layer of flexibility to the build process. Pretty cool huh?

We can auto load all installed plugins like in Grunt, but for the purpose of this post we’ll stick to the manual method.

Creating tasks

Compile Sass, Autoprefix and minify

Firstly, we will configure Sass compiling. We’re going to compile Sass as expanded, run it through Autoprefixer and save it to our destination. We’ll then create a minified .min version, auto-refresh the page and notify that the task is complete:

gulp.task('styles', function() {
  return sass('src/styles/main.scss', { style: 'expanded' })
    .pipe(autoprefixer('last 2 version'))
    .pipe(gulp.dest('dist/assets/css'))
    .pipe(rename({suffix: '.min'}))
    .pipe(cssnano())
    .pipe(gulp.dest('dist/assets/css'))
    .pipe(notify({ message: 'Styles task complete' }));
});

A little explanation before moving on.

gulp.task('styles', function() { ... )};

This is the gulp.task API which is used to create tasks. The above can run from Terminal with $ gulp styles.

return sass('src/styles/main.scss', { style: 'expanded' })

This is the new gulp-ruby-sass API where we define the source file(s) and pass in any options. For many other plugins, you would use the gulp.src API which we use later in this post (return gulp.src(...)). It also can be a glob pattern, such as /**/*.scss to match multiple files. By returning the stream it makes it asynchronous, ensuring the task is fully complete before we get a notification to say it’s finished.

.pipe(autoprefixer('last 2 version'))

We use .pipe() to pipe the source file(s) into a plugin. Usually the options for a plugin are found on their respective GitHub page. I’ve linked them above for convenience. Pipes are chainable so you can add as many plugins as you need to the stream.

.pipe(gulp.dest('dist/assets/css'));

The gulp.dest API is where we set the destination path. A task can have multiple destinations, one to output the expanded version and one to output the minifed version. This is demonstrated in the above styles task.

I’d recommend checking out the gulp API documentaiton to get a better understanding of these methods. It’s not as scary as it sounds!

JSHint, concat, and minify JavaScript

Hopefully you’ll now have a good idea of how to create a task for gulp. Next, we’ll set up the scripts task to lint, concat and uglify:

gulp.task('scripts', function() {
  return gulp.src('src/scripts/**/*.js')
    .pipe(jshint('.jshintrc'))
    .pipe(jshint.reporter('default'))
    .pipe(concat('main.js'))
    .pipe(gulp.dest('dist/assets/js'))
    .pipe(rename({suffix: '.min'}))
    .pipe(uglify())
    .pipe(gulp.dest('dist/assets/js'))
    .pipe(notify({ message: 'Scripts task complete' }));
});

Here we use the gulp.src API to specify our input files. One thing to note is that we need to specify a reporter for JSHint. I’m using the default reporter, which should be fine for most people. More on this can be found on the JSHint website.

Compress Images

Next, we’ll set up image compression:

gulp.task('images', function() {
  return gulp.src('src/images/**/*')
    .pipe(imagemin({ optimizationLevel: 3, progressive: true, interlaced: true }))
    .pipe(gulp.dest('dist/assets/img'))
    .pipe(notify({ message: 'Images task complete' }));
});

This will take any source images and run them through the imagemin plugin. We can go a little further and utilise caching to save re-compressing already compressed images each time this task runs. All we need is the gulp-cache plugin—which we installed earlier. To set this up, we need to change this line:

.pipe(imagemin({ optimizationLevel: 3, progressive: true, interlaced: true }))

To this:

.pipe(cache(imagemin({ optimizationLevel: 5, progressive: true, interlaced: true })))

Now only new or changed images will be compressed. Neat!

Clean up!

Before deploying, it’s a good idea to clean out the destination folders and rebuild the files—just in case any have been removed from the source and are left hanging out in the destination folder:

gulp.task('clean', function() {
    return del(['dist/assets/css', 'dist/assets/js', 'dist/assets/img']);
});

We don’t need to use a gulp plugin here as we can take advantage of Node modules directly within gulp. We use a return to ensure the task finishes before exiting.

The default task

We can create a default task, ran by using $ gulp, to run all three tasks we have created:

gulp.task('default', ['clean'], function() {
    gulp.start('styles', 'scripts', 'images');
});

Notice the additional array in gulp.task. This is where we can define task dependencies. In this example, the clean task will run before the tasks in gulp.start. Tasks in Gulp run concurrently together and have no order in which they’ll finish, so we need to make sure the clean task is completed before running additional tasks.

Note: It’s advised against using gulp.start in favour of executing tasks in the dependency arrary, but in this scenario to ensure clean fully completes, it seems the best option.

Watch

To watch our files and perform the necessary task when they change, we firstly need to create a new task, then use the gulp.watch API to begin watching files:

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

  // Watch .scss files
  gulp.watch('src/styles/**/*.scss', ['styles']);

  // Watch .js files
  gulp.watch('src/scripts/**/*.js', ['scripts']);

  // Watch image files
  gulp.watch('src/images/**/*', ['images']);

});

We specify the files we want to watch via the gulp.watch API and define which task(s) to run via the dependency array. We can now run $ gulp watch and any changes to .scss, .js or image files will run their respective tasks.

LiveReload

Gulp can also take care of automatically refreshing the page on file change. We’ll need to modify our watch task, configuring the LiveReload server.

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

  // Create LiveReload server
  livereload.listen();

  // Watch any files in dist/, reload on change
  gulp.watch(['dist/**']).on('change', livereload.changed);

});

To make this work, you’ll need to install and enable the LiveReload browser plugin. You can also place the snippet in manually.

Putting it all together

Here we have the full gulpfile, embedded from this gist:

I’ve also put together a Gruntfile that accomplishes the same tasks, so you have take a look for a comparison, in the same gist.

If you have any questions or issues, please leave a comment below or you can find me on Twitter.

Simplify form testing with Populatr

Mon, 09 Sep 2013 00:00:00 +0000

Populatr is a JavaScript plugin that will populate any form with pre-defined data to help reduce testing time.

What is Populatr?

On a recent project I needed to handle multiple large forms and monitor how the data handled each step of the way. Going through the forms manually is not only tedious, but very time consuming. To overcome this I decided to write a small, lightweight JavaScript plugin which will auto-fill form inputs based on given data.

Getting started

Populatr is very simple to use. We can use CSS selectors to target a form (ID, class, etc) and for inputs—including selects—it targets the name attribute. Take the following form for example:

<form id="demo-form">
  <input name="first-name" type="text">
  <input name="last-name" type="text">
  <input name="email" type="email">
</form>

To populate this form we need to initiate Populatr and then feed in some data:

Populatr.init(true, {
  '#demo-form': {             // CSS selector to select the form
    'first-name': 'Mark',     // 'Input name': 'Input value'
    'last-name': 'Goodyear',
    'email': 'hello@markgoodyear.com'
  }
});

We initialise Populatr with Populatr.init() then pass in if it’s active using either true or false. Following this, we set the data to be used. The data can be passed in as a standard JavaScript object—as above—or we can specify an external JSON file, keeping the form data separate and to prevent bloating template files. Using the example above, initiate Populatr with a file to use:

Populatr.init(true, 'populatr.json');

Then populatr.json would look like:

{
  "#demo-form": {
    "first-name": "Mark",
    "last-name": "Goodyear",
    "email": "hello@markgoodyear.com",
  }
}

Note: double quotes are required for JSON.

Multiple forms

Defining multiple forms is possible by passing in multiple objects:

Populatr.init(true, {
  '#form-one': {
    // Form one data...
  },
  '#form-two': {
    // Form two data...
  },
  '#form-three': {
    // Form three data...
  }
});

Input types

Most input types are supported, including newer HTML5 inputs. See the demo for the full range along with an example on populating them.

Thoughts?

If you have any thoughts, suggestions or issues, please leave a comment below.

Automating your workflow with Grunt

Tue, 30 Jul 2013 00:00:00 +0000

Learn how to automate your workflow with Grunt, reducing all those tedious tasks you repeat multiple times a day.

The need for automation

Recently I’ve been looking to improve my workflow to automate the tasks I repeat on a day-to-day basis. I also wanted to standardise projects across a team, set up a project structure and make sure the necessary tasks are done correctly. CodeKit has served me well, however there remain a few issues I wanted to address; the ability to automate more and be able to work cross-platform without needing to configure different apps to match a project structure. Say hello to Grunt.

What is Grunt?

To sum up Grunt, it’s a task runner built on Node.js—don’t let this put you off! Node.js is simple to install—just visit the site, download the install package and run it. If you’re on Mac, you can also install it with Homebrew. You’ll then want to install the Grunt CLI. I won’t go into great detail as they have a great getting started guide, so to summarise:

Make sure Node.js is installed. This will also install the Node Package Manager (NPM).
Install the Grunt CLI globally. npm install -g grunt-cli.
You’ll then need to create two files in the root of your project, package.json and Gruntfile.js. I’ll explain what these two files do next.

Before I continue, it’s worth noting you may need to run some install commands as admin. For example, Mac users will need to use sudo:

sudo npm install -g grunt-cli

Setting up your project

The package.json file contains all the information about the project, such as the name and version. It also lists the dependancies used by the project. A basic package.json will look like this:

{
  'name': 'project-name',
  'version': '0.1.0',
  'devDependencies': {
    'grunt': '~0.4.1',
  }
}

This is basically telling us the project name, version number (using the Semantic Versioning system) and that grunt is a required dependency. To install dependencies, simply run:

npm install

This installs all dependencies to the node_modules folder.

Configuring Grunt tasks

Now we move onto setting up the Gruntfile.js file. It can become quite a large file if there are lot of tasks, so to start off I’ll demonstrate a basic task which will compile your Sass (.scss) files. Firstly, you will need to install the Sass plugin:

npm install grunt-contrib-sass --save-dev

Adding --save-dev to the command automatically adds it to your package.json file so you don’t need to worry about adding it manually. Below is a basic configuration to compile Sass—including a development config and a distribution config.

// Wrapper function
module.exports = function(grunt) {

  // Read package.json
  grunt.file.readJSON('package.json');

  //Initialize grunt
  grunt.initConfig({

    // Sass task
    sass: {

      // Sass development options
      dev: {
        options: {
          style: 'expanded',
        },
        files: {
          'css/main.css': 'css/sass/global.scss'
        }
      },

      // Sass distribution options
      dist: {
        options: {
          style: 'compressed'
        },
        files: {
          'css/main.css': 'css/sass/main.scss'
        }
      }
    },

  });



  // Load tasks
  grunt.loadNpmTasks('grunt-contrib-sass');


  // Create Default Task
  grunt.registerTask('default', [
    'sass:dev' // Compile Sass with dev settings
  ]);

  // Create Distribution Task
  grunt.registerTask('dist', [
    'sass:dist' // Compile Sass with distribution settings
  ]);
}

If you’re familiar with JavaScript and JSON, it should be simple enough to understand. If not, it’s not as scary as it may look! Let’s take a closer look at what’s going on…

The wrapper function

// Wrapper function
module.exports = function(grunt) {

  // Read package.json
  grunt.file.readJSON('package.json');

  //Initialize grunt
  grunt.initConfig({
    [...]
  });

}

The wrapper function contains two key parts. Firstly to read the project details we specified earlier in package.json and then to initialize the Grunt configuration. This is where we configure Grunt tasks.

Task configuration

So, our Sass task looks a little like this:

// Sass task
sass: {

  // Sass development options
  dev: {
    options: {
      style: 'expanded',
    },
    files: {
      'css/main.css': 'css/sass/global.scss'
    }
  },

  // Sass distribution options
  dist: {
    options: {
      style: 'compressed'
    },
    files: {
      'css/main.css': 'css/sass/global.scss'
    }
  }
},

Here we have two tasks configured within the Sass task, dev and dist. Both these are able to have custom options passed through, meaning it’s possible to compile Sass differently based on its environment. How awesome is that?

Keeping it simple, I’ve only set up one option which is basically telling Grunt how to compile for each environment. Of course, there are many more options available which can be found at the plugins GitHub page. This is the same for all Grunt plugins—be sure to check their respective GitHub pages for a full list of options.

After setting up the options, we tell Grunt the destination file css/main.css and the source file css/sass/global.css. You can use the css/sass/global.scss to import all other Sass files in the project:

files: {
  'css/main.css': 'css/sass/global.scss'
}

Loading the tasks

Before Grunt can run the tasks, we need to load them—each dependency will need to be loaded in the same way. This is simply done by the following:

grunt.loadNpmTasks('grunt-contrib-sass');

Creating the tasks

Next, we create the actual tasks which we run from Terminal. Below is a set up for both development and distribution tasks.

// Create Default Task
grunt.registerTask('default', [
  'sass:dev' // Compile Sass with dev settings
]);

// Create Distribution Task
grunt.registerTask('dist', [
  'sass:dist' // Compile Sass with distribution settings
]);

As the development settings are likely to be used often, I use the default task to run any development settings. The default task is run by typing grunt, which is shorter to type than, say, grunt dev. Saves a few characters!

When your project is ready for deploying, run grunt dist and voila! Your code is now ready to go.

Watch it!

Now we have our tasks set up, we can get Grunt to watch files for changes, execute tasks and then reload the page for us. Firstly, install Grunt watch:

npm install grunt-contrib-watch --save-dev

Configure the task:

// Watch files
watch: {

  // Watch .scss files
  sass: {
    files: ['css/sass/**/*.scss'],
    tasks: ['sass:dev'],
  },

  // Live reload files
  livereload: {
    options: { livereload: true },
    files: [
      'css/**/*.css',
      '**/*.html',
    ]
  }
},

Load the plugin:

grunt.loadNpmTasks('grunt-contrib-watch');

Now we can simply type grunt watch into Terminal and it will watch for changes to any .scss files, then run the sass:dev task automatically. To reload the browser, LiveReload is configured to watch any changes to .css files. I’ve also specified to reload any .html files so you can see how it works. You will need to install the LiveReload extension for either Safari, Chrome or Firefox.

Taking it further

This is only a very small amount of what Grunt is capable of. I’d recommend reading through the documentation and checking out the Grunt plugins available (there are lots!) to see what else Grunt can do.

I’ve set up a Grunt starter project which I use as a base—you can find it on GitHub. Feel free to adapt it, improve it and learn from it. Currently, it includes:

JavaScript linting, concatenation and minification
Sass compiling with development and production options
Sass sourcemaps (requires Sass 3.3.0)
Rasterizing .svg files
Compress .jpg/.jpeg, .png and .svg files
Reload the browser on file changes

What are you waiting for? Get Grunting!