Categories
Development Inspiration Thoughts

Hemingway’s Advice for Coders

I’m an avid reader of Brain Pickings (check it out if you haven’t heard of it), and one thing caught my attention a few weeks ago. In the mid-1930’s a young writer by the name of Arnold Samuelson caught up with his hero, Ernest Hemingway. Rather then cast him away, Hemingway took him on as a sort of protege, and gave him some invaluable writing advice along the way. There was one thing that resonated with me in particular because I find myself in this trap all the time.

The most important thing I’ve learned about writing is never write too much at a time… Never pump yourself dry. Leave a little for the next day. The main thing is to know when to stop. Don’t wait till you’ve written yourself out. When you’re still going good and you come to an interesting place and you know what’s going to happen next, that’s the time to stop. Then leave it alone and don’t think about it; let your subconscious mind do the work.

I mostly write code for a living, not prose. But this rule still applies. I can’t tell you how many times I’ve been coding away when I finally get myself to a good place. Everything’s perfect. The bug is patched, the feature is solid.

Then I go just a little bit further. And that’s when I blow it. I get frustrated and lost. My motivation goes into free-fall and I alternate between my code editor and Twitter every five seconds. And no it’s late. It’s dinner time, or my wife is calling me, or the office is closing.

So don’t be me. Take Hemingway’s advice. It doesn’t matter if you have a little extra time, find that place where you still have some juice left and just stop. If you really need to keep going, go over the code you just wrote and refactor a bit. Or look at the next step enough to get pumped about it, but don’t write any code. When you get up and walk away from your computer, the levers in your brain will keep moving, even when you sleep through the night.

The next morning, when you’ve had a good sleep and you’re feeling fresh, rewrite what you wrote the day before. When you come to the interesting place and you know what is going to happen next, go on from there and stop at another high point of interest. That way, when you get through, your stuff is full of interesting places and when you write a novel you never get stuck and you make it interesting as you go along. Every day go back to the beginning and rewrite the whole thing and when it gets too long, read at least two or three chapters before you start to write and at least once a week go back to the start. That way you make it one piece.

More sound advice. When you start up again fresh, instead of jumping straight into a problem, go back over the work you did the day previous. Take 10 or 15 minutes and tweak little things, just enough to get the ball rolling. When you start developing the next step, you’ll already be in a good place. And by going back over code you’ve written before, you can make sure to keep things fluid and connected.

I’ve started to do this (when possible) and it feels really code. All of this, of course, requires nice blocks of time devoted to your tasks, not distracted by email and social media and meetings. That can be tough, but it is well worth it. You might not write For Whom the Bell Tolls, but your code will be a lot better for it. Give it a go.

Categories
Development JavaScript WordPress

Gulp, LiveReload, SASS and WordPress

For a little while now, I’ve been using Gulp in my WordPress themes to automate my front-end workflow and add some handy helpers along the way. For those unaware, Gulp is a slick JavaScript task runner, which can be used to concatenate JS and CSS files, lint files, and generally automate your front-end workflow.

My goal was to write a short introduction to how this works. It ended up kind of long. But by the end you’ll be compiling SASS, minifying Javascript, working with livereload and implementing a SVG icon system. So not bad.

Setting Things Up

First off, gulp runs on top of NodeJS, and is generally operated from the command line. If you’re not set up with Node yet, I’d recommend following the steps on their website (or better yet, installing Homebrew).

With Node installed, you can install gulp globally on your system by opening up your Terminal and running:

npm install -g gulp

This will ensure that you can use the gulp command from the command line. In the root directory of your theme file, you will also need to install and set up a local version of gulp, and add a package.json file to manage your dependencies. This is basically just a config file that Node uses to figure out which packages it needs to bring down and install (things like a SASS concatenate or a JavaScript linter or any number of other tools). To create this file, just navigate to your theme’s directory in the terminal and run:

npm init

This will step you through the process of creating a package.json file. When that’s finished, the last step is to install gulp locally to your WordPress theme folder.

npm install gulp --save-dev

That last flag, --save-dev will automatically save this to a list of dependencies in your package.json file, so you can easily pass the directory around. But more on that later.

More info at CSS-Tricks.

Folder Structure

I just want to quickly note my folder structure. You’ll notice that a lot of my decisions in gulp are dependent on this, but they can easily be changed. My theme folder looks like this:

screen-of-files

 

In the root directory, we’ve already created the package.json file, and we’ll create the gulpfile.js in just a minute. The other important folder is assets which includes all of my front-end files.

  • assets/js/app – Contains all of my custom Javascript files, which gulp will combine
  • assets/js/vendor – Contains any vendor Javascript files, things like Bootstrap and Modernizr
  • assets/sass/style.scss – My main SASS file, which contains imports for all the other sass files
  • assets/sass/ – All the other SASS files
  • assets/svg/individual – Contains any SVG files I would like to use in my SVG icon system

Hopefully this will be a bit more clear as we step through.

From here, it’s just a matter of installing the packages we need, and creating a gulp task for each one.

Getting Started with SASS

Ok, let’s start out with the SASS setup. The first thing we’ll need to do is install gulp-sass, a library which will compile SASS down into plain old CSS.

npm install gulp-sass --save-dev

With that, we can finally start setting up Gulp. Create a new file in the root directory titled gulpfile.js and at the very top add:

Gulpfile.js
var gulp     = require('gulp'),
    sass    = require('gulp-sass');

Gulp uses the require syntax in order to import dependencies, so all we are doing here is ensuring that the gulp and gulp-sass library are loaded into variables.

Gulp works in what’s known as tasks. Each task performs a simple operation, passing files through and spitting them out in a different format on the other end. We’ll call our first task sass, which will handle the process of processing the style.scss file located in the assets/sass directory of our theme.

Gulpfile.js
gulp.task('sass', function () {
    return gulp.src('./assets/sass/style.scss')
            .pipe(sass.sync({outputStyle: 'compressed'}).on('error', sass.logError))
            .pipe(gulp.dest('./'));
});

Pretty simple actually. We give the initial task a source, and then use pipe, a built in connector for tasks to process sass. You’ll notice on line 3 that we’re actually calling the sass variable in order to process our file. Now, if we run gulp sass in the terminal, a new CSS file will be generated in the root directory of our theme. So far, so good.

Concatenating and Minifying Javascript

In a typical theme, I have two sets of Javascript files. The first are vendor files, and the other are my custom files. As seen above, I keep these in two separate folders helps to manage them better, and later on, I use gulp to combine them all together.

One thing I’ve run into over and over again is loading order for Javascript. If you’re using modules, you may not have to worry about this, but I’ve found that rather then trying weird naming conventions or separating files, I’ve opted to simply list out my Javascript files in the order I would like them to load. That way, gulp will process them one by one and spit them out into one big file. I know there are other methods, but this has worked best for me.

We’ll need to install a few other packages to get this up and running.

npm install gulp-concat gulp-uglify gulp-rename --save-dev

Gulp-concat will combine all of our Javascript files into one big file, gulp-ugilfy will minify them, compressing the file and saving us precious kilobytes, and gulp-rename will allow us to call this outputted file whatever we would like. Once again, at the top of our gulpfile we need to define the packages we just installed.

Gulpfile.js
var concat   = require('gulp-concat'),
    uglify  = require('gulp-uglify'),
   rename   = require('gulp-rename');

Next, we will create a config variable that defines all of the Javascript files we want to concat. This variable will be used by gulp to process the files in order. If you simply want to include all the files from a directory, you can use the /**/*.js syntax, as we will do for our app folder.

Gulpfile.js
var config = {
    scripts: [
                // Bootstrap
        './assets/js/vendor/bootstrap.js',
        // Modernizr
        './assets/js/vendor/modernizr/modernizr.shiv.js',
        // SVG Fallback
        './assets/js/vendor/svg/svg-fallback.js',
        // Any Custom Scripts
        './assets/js/app/**/*.js'
    ]
};

With that all set up, we can add a new task called scripts, which will run the files through concat and uglify and output the file:

Gulpfile.js
gulp.task('scripts', function() {
    return gulp.src(config.scripts)
            .pipe(concat('scripts.js'))
            .pipe(gulp.dest('./assets/js/'))
            .pipe(uglify())
            .pipe(rename({ extname: '.min.js' }))
            .pipe(gulp.dest('./assets/js/'));
});

This time for our source, we pass the variable we creaed, which has an array of the files we want to concat. This will output a file called scripts.js in our assets/js folder. Then uglify will compress this file even further, and output it as scripts.min.js. This will be our production-ready file. However, the scripts.js file can come in handy when debugging your theme.

If you want to see this in action, simply run gulp scripts.

SVG Icons

I won’t go too far into why I prefer SVG icons over any other systems, but if you want a lengthy introduction on how they work, CSS Tricks has a great tutorial. If you find yourself convinced, like I did, just make sure to save all of the individual SVG files you want to use in the assets/svg/individual folder. We will then use the gulp-svg-sprite and gulp-svg2png libraries to automatically create an SVG sprite and image fallbacks of our icons to easily use in our theme.

First step, install the two libraries we will need.

npm install gulp-svg-sprite gulp-svg2png --save-dev

Next, we’ll define our npm packages at the top of our gulpfile.

Gulpfile.js
var svgSprite    = require("gulp-svg-sprite"),
    svg2png     = require('gulp-svg2png');

Now it’s time to set up our SVG icon tasks. I’ve actually broken this up in my gulpfile into two tasks. The first creates the SVG sprite, which we can embed in our theme, and the second creates PNG fallbacks for our icons. The first we’ll call sprites:

Gulpfile.js
gulp.task('sprites', function () {
    return gulp.src('**/*.svg', {cwd: './assets/svg/individual'})
            .pipe(svgSprite({ shape: { transform: ['svgo'] }, mode: { defs: {dest: '.'} } } ) )
            .pipe(gulp.dest('./assets/svg/'));
});

As our source, we are simply looking in the ‘assets/svg/individual’ folder for anything with an .svg extension, and then processing it using the svg-sprite library. You will notice that I passed an svgo transformation, which will automatically optimize the SVG files. The final sprite will be saved to assets/svg as sprites.defs.svg. From there, you can follow the article linked above for how to include this in your theme.

Next up is the SVG fallbacks. For these fallbacks, I use a script from Luke Whitehouse. I had to modify it a bit to point to the proper URL (MyTheme + /assets/svg/png/”), but it works fairly well. You may also want to consider a library like SVG For Everybody. But in order for either method to work, they will need PNG images to fall back to. So we’ll create a gulp task that simply runs through our SVG files, converts them to PNG, and drops them in our assets/svg/png folder.

Gulpfile.js
gulp.task('svg2png', function () {
    return gulp.src('./assets/svg/individual/**/*.svg')
            .pipe(svg2png())
            .pipe(gulp.dest('./assets/svg/pngs/'));
});

This uses the gulp-svg2png library we installed to convert our SVG files on the fly.

Gulp tasks do not simply have to be one-off scripts. In fact, they can simply be an array of tasks to perform, in order. For our SVG workflow to be complete, we’ll want to combine the two tasks we created into a single task called icons. All we need to do is pass the names of these two tasks to a new one.

Gulpfile.js
gulp.task('icons', ['sprites', 'svg2png']);

Now, if you run gulp icons you will see this workflow in action.

Bonus Round: LiveReload

Livereload is an incredible library that can be used to automatically reload your site whenever changes are made. That way you don’t have to do the annoying Ctrl / CMD + R, check changes, switch to editor dance. And for CSS files, it will even inject styles on the fly, with no refresh needed. So you will see your styles change instantly.

The first step is to install the gulp-livereload library.

npm install gulp-livereload --save-dev

Next, we need to make sure that the livereload script is actually running on our site. H/T to Rob & Lauren for pointing me in the right direction with this one. We can add this to the functions.php file in our theme, automatically enqueueing the script on local environments.

functions.php
if (in_array($_SERVER['REMOTE_ADDR'], array('127.0.0.1', '::1'))) {
  wp_register_script('livereload', 'http://localhost:35729/livereload.js?snipver=1', null, false, true);
  wp_enqueue_script('livereload');
}

 

With that added, we can go back our gulpfile.js file. At the top, make sure to define your dependency in a new variable.

Gulpfile.js
var livereload      = require('gulp-livereload');

Next we can add the livereload function to our SASS and JS tasks. This will call livereload at the appropriate times so that your development site is reloaded automatically in the browser whenever one of these tasks is called. So our SASS task will now be:

Gulpfile.js
gulp.task('sass', function () {
    return gulp.src('./assets/sass/style.scss')
            .pipe(sass.sync({outputStyle: 'compressed'}).on('error', sass.logError))
            .pipe(livereload())
            .pipe(gulp.dest('./'));
});

And our scripts task will now be:

Gulpfile.js
gulp.task('scripts', function() {
    return gulp.src(config.scripts)
            .pipe(concat('scripts.js'))
            .pipe(gulp.dest('./assets/js/'))
            .pipe(uglify())
            .pipe(rename({ extname: '.min.js' }))
            .pipe(livereload())
            .pipe(gulp.dest('./assets/js/'));
});

Wrapping It Up With Watch

The last thing we will want to do is use Gulp’s built-in watch feature to automatically watch for any changes to files and call the appropriate task when needed. So, if a SASS file is changed, the SASS task will be called, and if a JS file is changed then the scripts task will be called. We can also set up livereload here so that everything is wired up.

Gulpfile.js
gulp.task('watch', function () {
    livereload.listen(35729);
    gulp.watch('**/*.php').on('change', function(file) {
          livereload.changed(file.path);
      });
    gulp.watch('./assets/sass/**/*.scss', ['sass']);
    gulp.watch('./assets/js/**/*.js', ['scripts']);
});

 

Now all we have to do is add a default task which combines everything from before, calling each of our tasks and ending in watch.

Gulpfile.js
gulp.task('default', ['icons', 'sass', 'scripts', 'watch']);

And that’s that! All we have to do is run gulp and our tasks will be called in order and livereloading will begin. Try changing around some SASS or Javascript files and see what happens.

This is by no means an entirely exhaustive workflow, but it’s more then enough to get started. The trick is to understand how it works, and play around with it when you can. If you want to see what the full gulpfile looks like, well, here it is:

Full Gulpfile.js
var     gulp           = require('gulp'),
    concat         = require('gulp-concat'),
    uglify         = require('gulp-uglify'),
    rename         = require('gulp-rename'),
    sass           = require('gulp-sass'),
    livereload      = require('gulp-livereload'),
    svgSprite     = require("gulp-svg-sprite"),
    svg2png     = require('gulp-svg2png');

var config = {
    scripts: [
        './assets/js/vendor/bootstrap/bootstrap.min.js',
        // Modernizr
        './assets/js/vendor/modernizr/modernizr.shiv.js',
        // SVG Fallback
        './assets/js/vendor/svg/svg_fallback.js',
        // Any Custom Scripts
        './assets/js/app/**/*.js'
    ]
};

gulp.task('scripts', function() {
    return gulp.src(config.scripts)
            .pipe(concat('scripts.js'))
            .pipe(gulp.dest('./assets/js/'))
            .pipe(uglify())
            .pipe(rename({ extname: '.min.js' }))
            .pipe(livereload())
            .pipe(gulp.dest('./assets/js/'));
});

gulp.task('sass', function () {
    return gulp.src('./assets/sass/style.scss')
            .pipe(sass.sync({outputStyle: 'compressed'}).on('error', sass.logError))
            .pipe(livereload())
            .pipe(gulp.dest('./'));
});

gulp.task('sprites', function () {
    return gulp.src('**/*.svg', {cwd: './assets/svg/individual'})
            .pipe(svgSprite({ shape: { transform: ['svgo'] }, mode: { defs: {dest: '.'} } } ) )
            .pipe(gulp.dest('./assets/svg/'));
});

gulp.task('svg2png', function () {
    return gulp.src('./assets/svg/individual/**/*.svg')
            .pipe(svg2png())
            .pipe(gulp.dest('./assets/svg/pngs/'));
});

gulp.task('icons', ['sprites', 'svg2png']);

gulp.task('watch', function () {
    livereload.listen(35729);
    gulp.watch('**/*.php').on('change', function(file) {
          livereload.changed(file.path);
      });
    gulp.watch('./assets/sass/**/*.scss', ['sass']);
    gulp.watch('./assets/js/**/*.js', ['scripts']);
});

gulp.task('default', ['icons', 'sass', 'scripts', 'watch']);
Categories
Development JavaScript

How to Make Text That Writes Itself in Javascript

One of my goals for the new year is to start actually blogging, to share the things that I’m learning, and to keep a better record for myself. To go along with that, I launched a new version of my site with the Fixed Theme from Array Themes. It’s incredibly well balanced, fast as hell, and a pleasure to use.

But I did want to carry over one thing from the last iteration of my site, and that is a sort of typewriter effect on the homepage which has a few messages from me to you. I actually saw this over at Music For Programming, and adapted the code for my own needs. But I thought I’d break down how it works. It’s written in vanilla JavaScript, in about 50 lines of code. The end effect is that text appears to type itself across the screen, delete the words, and then type some more.

Here’s what it looks like in action:

The effect itself is deceptively simple. JavaScript runs through each message, and one by one, pops the last letter off of the a message, and attaches it to the container. When we switch to “delete” mode, the opposite is done. In between running each of these, we add a random delay, then call the function again.

The first part is just about setting some variables. Nothing special here, just getting the value of the initial text with container.innerHTML, creating an array with the messages we want to type out, and setting an initial delay.

Next up, we create a simple updateText function. All this will do will take the value passed to it and update the container div with our new text:

function updateText(txt) {
    container.innerHTML = txt;
}

Now comes the cruft of our code, the “tick” function. The first part of the function checks to see if there is any text in our container div. If it is empty, then we have reached the end of the word. It increments our global variable timer (t), sets the message back to an empty string and switches to “write” mode.

    if(container.innerHTML.length == 0) {
        t++;
        thing = things[t];
        message = '';
        mode = 'write';
    }

Next up we use the JavaScript switch statement to move back and forth between two different modes. Switch simply takes a variable, in this case “mode” and runs code based on which case is set. The first mode is called write, which you’ll notice is what we set our mode to above, when the container is empty.

Our mode uses two crucial JavaScript string functions. The first is slice and the second is substr. Imagine our message is blank, we are starting to type a new line. First, the function uses slice to grab the first word off the beginning of our new message, and adds it to the message variable:

message += thing.slice(0, 1);

Next, it removes the first word off our message. That way, the next time this function is called it will grab the second letter, then third letter, and so on:

thing = thing.substr(1);

The write mode of this function does a few more things. For instance, if we have reached the end of our array, then we clear the window’s timeout function and return. We are done, and we want the last message to simply stay on screen. It also checks if there are any more letters in our message. If there are, it creates a delay that uses Math.rand to generate a random number. By using a random number, the effect has more of a typewriter feel. If you made the delay something static, it would look a lot more robotic. You can play around with the delay a bit to change the effect.

Our “delete” mode is even simpler then write. All we have to do is use slice to grab our message and pull the last word off of it. Then we run updateText() again to update our message, one by one.

  message = message.slice(0, -1);
  updateText(message);

And that’s about it. Our final step is just to kick off the function with an initial setTimeout. This will the delay we declared in our global variable (in this case 1 second), and start the function by deleting the initial message. Keep in mind, that I assigning window.setTimeout to a variable so that when the function is all done, I can use clearTimeout() to remove it altogether.

var timeout = window.setTimeout(tick, delay);

I’m sure there are lots of ways to do this, so I’m definitely open if someone has a different implementation. But I thought it was a cool trick that makes use of pretty common JavaScript string functions. Hopefully, you found it useful.