Unfortunately, not many developers know how to create similar tools for themselves.

This talk will cover what JavaScript Abstract Syntax Trees (ASTs) are, how to use ASTs to create powerful node.js and client-side tools, and why you are smart enough to use them.

Note: If the slide deck does not appear below, or you would like to view the actual presentation, go to: http://gregfranko.com/building-javascript-tools-talk

This talk will review some of the traditional maintainability roadblocks facing JavaScript client-side developers, and introduce a new project workflow with RequireJS and Almond.js/AMDClean.js.

Let’s dive in and see how we can improve code maintainability with AMD and start enjoying the code that we write.

Note: If the slide deck does not appear below, or you would like to view the actual presentation, go to: http://gregfranko.com/requirejs-talk

Use Case

Smart Layers is a product suite that currently includes 6 different UI widgets (including share, follow, recommended content). Although each widget contains unique functionality, there are many similarities between the widgets.

For example, all widgets create and append DOM elements, listen to events, support user-specified options, utilize CSS3 show/hide animations, etc. Once we put our code architect hats on, we realized that:

We needed an inheritance model that could handle both unique widget functionality and common logic without code duplication.

Simple JavaScript Prototypal Inheritance

At this point, it is important to delve into object-oriented JavaScript, and recognize the difference between instance properties and prototype properties.

Instance Properties

Instance properties are properties that are scoped to a particular instance object and are not propagated to other instances (unless you go out of your way to change that). Let’s look at an example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

  // Creates an AddThisEmployee constructor function
  function AddThisEmployee(name) {
    this.name = name;
  };

  // Creates an AddThisEmployee instance object
  // and stores it in the greg local variable
  var greg = new AddThisEmployee('Greg Franko'),
    // Creates an AddThisEmployee instance object
    // and stores it in the sol local variable
    sol = new AddThisEmployee('Sol Chea');

  // Greg doesn't like his name and decides to
  // legally change it to 'Frank The Tank'
  greg.name = 'Frank The Tank';

  // Sol has no idea that Greg has changed his name to
  // 'Frank The Tank' and continues to call him Greg
  // This angers Greg

In the previous example, each instance object contains one instance property (name). Since each instance object’s properties are not propagated to each other, they are not aware of each other’s changes.

Prototype Properties

On the other hand, prototype properties are properties that are propagated to all instances. In JavaScript, an object’s property is looked up at run time, by first checking if there is an instance property. If there is not an instance property, then the object’s prototype is checked next to see if it contains the property.

All prototype properties are kept in sync and visible to each instance.

Let’s demonstrate prototypes by expanding upon our previous code example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

  // Creates a Person constructor function
  function AddThisEmployee(name) {
    this.name = name;
  };

  // Assigns the AddThisEmployee prototype property
  AddThisEmployee.prototype = {
    companyName: 'AddThis'
  };
  // Creates an AddThisEmployee instance object and
  // stores it in the greg local variable
  var greg = new AddThisEmployee('Greg Franko'),
    // Creates an AddThisEmployee instance object and
    // stores it in the sol local variable
    sol = new AddThisEmployee('Sol Chea');

  // Greg doesn't like his name and decides to
  // legally change it to 'Frank The Tank'
  greg.name = 'Frank The Tank';

  // Sol has no idea that Greg has changed his name to
  // 'Frank The Tank' and continues to call him Greg
  // This angers Greg

  // AddThis changes it's company name to 'Team Awesome'
  AddThisEmployee.prototype.companyName = 'Team Awesome';

  // Both Greg and Sol know that AddThis changed it's name
  console.log(greg.companyName);
  console.log(sol.companyName);

For Smart Layers, every widget instance reuses the same object as it’s prototype. This both simplifies the codebase and makes it easy to make changes that need to be propagated to all widgets.

Factory Pattern

Since every widget is created in a similar way, we needed a design pattern to take care of the instance creation process. Smart Layers uses the Factory pattern as a generic interface for creating instance objects.

Here’s a high-level look:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

  var commonObj = {
    exampleProp: 'Each instance will have this property';
  },
    factory = function(name, instanceProps) {
      var Constructor = function() {
        for (var x in instanceProps) {
          if (instanceProps.hasOwnProperty(x)) {
            this[x] = instanceProps[x];
          }
        }
      },
        widget;
      widget.prototype = commonObj;
      widget = new Constructor();
      widget.name = name;
    };

  // Calls the factory method
  factory('share', {
    // Constructor function
    _create: function() {}
  });

The previous example shows a factory() method that can be called by passing a string name and an object literal containing all of the desired instance properties.

The factory pattern abstracts away the JavaScript constructor and prototype assigning ugliness, and provides an easy way to implement a consistent API for each instance.

Note: For similar techniques that work with jQuery plugins, check out the jQueryUI Widget Factory and jqfactory open-source projects.

Module Pattern

Another major design pattern used in Smart Layers is the module pattern. Currently, the Smart Layers JavaScript API only has one public method (destroy) that can be used after Smart Layers is initialized on the page. Under the hood though, the JavaScript API consists of multiple hidden methods that are used internally. To accomplish public/private API methods, we took advantage of JavaScript function scoping to only expose what we wanted to.

Let’s look at a basic example of the module pattern:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

  // Function constructor
  var Person = function(obj) {
    // Local variables that are privately scoped
    var firstName = obj.firstName,
      lastName = obj.lastName,
      occupation = obj.occupation;

    // Public API properties
    return {
      firstName: firstName
    }
  },
  // Instantiating a new Person instance object
  greg = new Person({
    firstName: 'Greg',
    lastName: 'Franko',
    occupation: 'JavaScript Engineer'
  });

  // Prints out "Greg"
  console.log('first name', greg.firstName);

  // Prints out "undefined"
  console.log('last name', greg.lastName);

  // Prints out "undefined"
  console.log('occupation', greg.occupation);

This example demonstrates that all local variables, declared using the var keyword, are only accessible within the declaring function or other nested functions.

In our example, a person’s first name, last name, and occupation are all local variables. An object, that includes the firstName property, is then returned inside of our constructor function. Since the firstName local variable is the only variable returned, it is the only property that can be retrieved from a different scope.

The module pattern is an example of a closure, since a local property is kept alive and can be referenced inside of a different scope.

Here’s a more practical example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

  // Method that will only return functions that do not
  // begin with an underscore
  function publicApi (api) {
    var method,
      currentMethod,
      publicApi = {};
    for(method in api) {
      currentMethod = api[method];
      if(method.charAt(0) !== '_') {
        publicApi[method] = api[method];
      }
    }
    return publicApi;
  }

  // Stores the return value of the publicApi method
  var publicMethods = publicApi({
    publicMethod: function() {},
    _privateMethod: function(){}
  });

  // Should only contain the publicMethod as a property
  console.log('Public API', publicMethods);

This demonstrates the technique that Smart Layers uses to expose public API methods. All methods that start with an underscore are assumed to be private and are not returned as a public method.

Summary

Prototypal inheritance, the factory pattern, and the module pattern are all extremely useful techniques that can be used together to create powerful applications. I’d love to hear your thoughts and the patterns you use in your own JavaScript codebases!

Dynamic Loading

With the increasing number of mobile web users using a 3g/4g connection, it’s more important than ever to only download what you need. To save unnecessary bytes from being downloaded, we dynamically load assets (JavaScript, CSS, etc).

For example, Smart Layers uses the great JSON2.js JavaScript library, created by Douglas Crockford, to provide native JSON support for older browsers (IE6 and IE7). Instead of including JSON2.js for browsers that already support the native JSON methods, we make sure to only include JSON2.js for browsers that need the polyfill.

Dynamic asset loading is becoming popular in the front-end community, and is often a benefit of using a client-side script loader, such as Require.js (which we don’t use).

Animations

The unofficial performance goal for web animations is to perform at around 60 frames per second (fps). If your app is running animations at 60fps, then your users will see smooth and jank-free animations. Smooth animations = happy users.

To achieve ~60fps performance, Smart Layer animations use CSS transitions and transforms. A major performance benefit of using CSS transitions and transforms is hardware acceleration. At a high level, this means that all of the animation hard work can be offloaded to the browser and GPU. Performance benchmarks have shown massive speed and resource consumption improvements for browsers that utilize these techniques (specifically mobile browsers).

Instead of creating our own custom CSS transforms and transitions, we decided to use a few of the CSS-based animations from the popular project, Animate.css. We love open-source technologies and want to thank Dan Eden for all of his hard work on the project.

Memory Management

Proper memory management is crucial for the performance of web applications. A common reason for a web app feeling sluggish and non-responsive to a user is a memory leak.

I thought the browser does automatic JavaScript garbage collection and memory deallocation, so why do I have to worry about this?

You’re right, your browser does automatically clean up and deallocate memory. Unfortunately, the browser does not know your application, and you must make it clear what code is no longer being used and can be freed up for other things.

Memory leaks are so common that your web application most likely has one that you may not have noticed; only the memory leaks which cause performance issues easily draw attention. One of the most performance-intensive operations in JavaScript is interacting with the DOM. If you suspect that your application has a memory leak, then you should first investigate if it is DOM-related.

Since so many web applications these days are single page applications (I know, I’m tired of that buzz word too), and long-lived (meaning they go for a long time without a page refresh), we wanted to make sure to support memory deallocation for Smart Layers. To support this, Smart Layers provides a destroy() method that allows you to remove all DOM nodes and DOM event listeners it creates. This method will trigger the browser to garbage collect and deallocate the memory used by Smart Layers to other parts of your application.

This brings us to another important topic: memory consumption. Smart Layers uses a variety of techniques to make sure that it is taking up as little memory as possible, leaving more for your application. Here are a couple techniques.

Event Delegation

Event delegation promotes binding as few DOM event handlers as possible, since each event handler requires memory. For example, let’s say that we have an HTML unordered list we want to bind event handlers to. Instead of binding a click event handler for each list item (which may be hundreds for all we know), we bind one click handler to the parent unordered list itself.

But how does the unordered list click handler get triggered when a child list item is clicked? That’s where event bubbling comes in.

Event bubbling is the concept that a DOM event is propagated (sent to) to the outer-most elements (parents) all the way up to the root element of the document (e.g. the HTML element). By checking the target property of a JavaScript Event object, we can see what DOM element triggered the current event.

Smart Layers heavily uses event delegation and event bubbling to minimize the number of event handlers that are bound. While testing Smart Layers on mobile devices, there was a noticeable performance improvement when using event delegation instead of direct element binding, since less memory was being used.

DOM Performance

Let’s reiterate; DOM interactions are one of the most memory-expensive actions a web application can complete.

A common performance pitfall is repeatedly appending DOM elements (causing multiple browser reflows) to the page instead of appending once. With Smart Layers, we only append elements to the DOM when absolutely necessary. For each Layer, we construct all of the HTML that we want as a string, and then append that string to the DOM. This prevents unnecessary browser reflows, which force the browser to re-calculate the layout of the page.

Another best practice that Smart Layers uses to improve performance is simplified DOM selectors and DOM caching. If we can select a DOM element using an id, then we do. We also save those elements as instance properties internally, so that we do not need to re-query the DOM again.

For any complicated selectors (not too complicated, mind you), we use qwery, a compact, blazing fast CSS selector engine. We are not using Sizzle (the selector engine used by jQuery) since we are not using jQuery, and we do not need all of the advanced selectors Sizzle provides. A special shout out goes to Dustin Diaz, Jacob Thornton, and Rod Vagg for their amazing work on qwery.

Debouncing High-Rate Events

Certain JavaScript events are notorious for being triggered at a high rate per second. Examples include the scroll and resize events. If you are listening for these DOM events and your event handlers contain performance-intensive actions, you should be debouncing your event handlers.

Debouncing an event handler allows you to specify a time (e.g. 500 milleseconds) where you would only like one call to your event handler to execute. For example, if the window scroll event triggers 100 times every 500 milleseconds, your debounced event handler will only get called once (probably the desired behavior). Remember that JavaScript is single threaded (unless you are using web workers, which do not handle DOM-related activities), so if your event handler had executed 100 times repeatedly, it will most likely prevent other logic from executing.

Smart Layers listens to both the resize and scroll events for different reasons, and we make sure to debounce each event to prevent from blocking the UI thread.

One of the cooler features of Smart Layers is our responsive toolset. If you are on a desktop browser and the viewport is less than the size of a tablet browser, we automatically provide our mobile tools (which look better in a small viewport) using the resize event.

Why don’t you just use CSS3 media queries instead of listening to the JavaScript resize event?

We use CSS3 media queries, in conjunction with the debounced resize event, so that we can allow users to specify which viewport sizes they would like our mobile tools to show up on for desktop browsers. Configurable + good performance = happy users.

If you would like to see example implementations of a debounce method, then check out either Underscore.js or Lodash.js.

Infinite Scrolling

On mobile browsers, we allow you to scroll through all the possible sharing services that we support. There are hundreds of services, and we are using beautiful, retina-ready, SVG icons for each service. To prevent any performance issues, we do not load all of our services at once.

If a user searches for a service, or scrolls to a position on the page where that service should be, then we load the service (and it’s associated icon). This technique allows our users to enjoy beautiful icons, and not get bogged down by any performance issues.

Responsive Mobile Scrolling

When testing Smart Layers on mobile browsers, we noticed that scrolling through a large unordered list with a flick of the finger did not send the webpage scrolling. Since we did not feel this was a great user experience, we started to investigate how we could incorporate this momentum effect.

We found out that you can add this default behavior on iOS 5 using the -webkit-overflow-scrolling: touch; CSS property. This is great, but what about other platforms/browsers? To support other browsers, we incorporated the popular library, iScroll. A big thank you to Matteo Spinelli for all of his hard work on iScroll.

We hope that all of these performance best practices baked into Smart Layers pay dividends for you. If you haven’t already tried Smart Layers, grab and code and let us know what you think!

What Does Modular Mean to You?

The term “modular” has many different definitions in the JavaScript community. In the context of this blog post, let’s establish it as JavaScript logic that is separated from the rest of a codebase, can work independently, and does one thing and does it well.

Why Modular?

Maintainability. It is far easier for developers to understand code that has a limited scope.

Benefits of a Maintainable Codebase

New Contributors - A modular codebase allows new contributors to make improvements/changes straight away, since knowledge of an entire codebase is not required.

Core Maintainer - Looking at code you wrote over three months ago might as well have been written by someone else. You will experience the same learning curve improvement that new contributors experience.

Code Reuse - When different parts of an application are separated into standalone modules, it is easier to plugin and play each part wherever you need it. This drastically decreases the amount of code and code duplication in a codebase. Less bytes = happier developers.

Physical and Emotional Well-Being - Wading through one monolithic file is difficult on the eyes and brain. Looking at logically-grouped small files is not.

jQuery Plugins

Now that we have covered the benefits of a modular codebase, let’s take a high-level look at a typical jQuery plugin codebase.

Let’s assume this is a jQuery Tooltip plugin that has been written in one file:

1
2
3
4
5
6
7
8
9
10
11
12

// Adding the tooltip method to the jQuery prototype
$.fn.tooltip = function ( options ) {
  return this.each(function () {
    // Boilerplate jQuery plugin code goes here
  });
  // Plugin Constructor
  function Tooltip() {};
  // All my plugin logic goes here
  Tooltip.prototype = {};
  //Default Options
  $.fn.tooltip.options = {};
}

For very small plugins, this code structure will work at first. Unfortunately, one of the most common problems in software development, feature creep, will demonstrate that this architecture is not scalable.

As more features are added to a plugin and the codebase grows, it becomes more difficult to maintain.

How to Become Modular?

AMD (e.g. Require.js) and CommonJS (e.g. Node.js) are the two most commonly used module formats that allow you to separate your codebase into small reusable pieces. If you aren’t using a specific module format, then you need to be aware of inner-file dependencies when separating logic into different files and then bringing them together at build time.

Can I use AMD with my jQuery Plugin?

Yes! You can wrap each JavaScript file in an AMD define() method call, that lists all file dependencies, and then use the Require.js optimizer, r.js, and Almond.js to build your library.

This means that you can internally use AMD to build your JavaScript library, while not forcing users to use AMD themselves.

Here is an example Require.js build profile (using Almond.js) to do just that:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

({
  baseUrl: "src/js",
  // Set's the path name of the first file that will be built
  paths: {
  "examplePlugin": "app/begin"
  },
  // Makes sure everthing is wrapped in an IIFE (does not expose any global vars)
  wrap: true,
  // Uses the small AMD shim, Almond.js, instead of Require.js
  name: "../libs/almond",
  // All of your Require.js configurations would go in here
  mainConfigFile: "app/config/config.js",
  include: ["examplePlugin"],
  // Creates a new minified file
  out: "js/dist/examplePlugin.min.js"
})

This works great, but unfortunately, Almond.js needs to be built into your library’s source file. Although Almond.js is a small library (~1kb gzipped and minified), it is not desirable for third-party code to be built inside of your own third-party library.

Recently, jQuery started wrapping all of it’s source files in AMD define() method calls. Instead of including an AMD shim, such as Almond.js, the jQuery team is using regular expression checks, at build time, to convert all define() method calls into local variables. This allows the jQuery team to use the benefits of AMD (e.g. dependency management) during development, while not having to include an AMD shim (such as Almond.js) after the jQuery production source file is built.

This is a great idea, but I am looking forward to someone (potentially me) creating a Grunt plugin that can generically reverse engineer an Almond.js project at build time and removes any AMD trace. When this happens, I believe the majority of JavaScript library authors will start incorporating AMD into their workflows.

How to Make jQuery Plugins Maintainable

Abstract boilerplate code

Make the codebase modular (even without Require.js)

Abstract jQuery Plugin Boilerplate

There are currently two open-source libraries that help abstract away common jQuery plugin boilerplate code; the jQueryUI Widget Factory and jqfactory.

jQueryUI Widget Factory

Provides a consistent foundation and API for building jQuery plugins

Supports widget inheritance using functions

Provides common helper methods

Let’s us create plugins using object literals

Can be used independently of jQueryUI

Example:

1
2
3
4
5
6
7
8
9
10
11
12

// Calling the jQueryUI Widget Factory Method
$.widget("an.example", {
  // These options will be used as defaults
  options: {
    someOption: true
  },
  // Constructor
  _create: function(internal) {}
  // Custom method we added to our plugin instance
  customMethod: function() {}
  // The rest of your plugin goes here
});

jqfactory

Supports widget inheritance using object literals

Provides common helper methods

Supports jQuery prototype namespacing

Includes an elegant, promises-based, solution for asynchronous initializations

Easy event binding support similar to Backbone.js views

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

   // Calling the jqfactory Method
   $.jqfactory('person.greg', {
        // Default plugin options
        options: {
            occupation: 'JavaScript Engineer'
        },
        // Plugin Constructor (called first)
        _create: function() {},
        // Dom manipulation goes here (called second)
        _render: function() {},
        // Plugin event bindings (called third)
        _events: {
            'click': function() {}
        },
        // All event listeners are now bound (called last)
        _postevents: function() {}
    });

Differences Between the jQueryUI Widget Factory and jqfactory

Namespacing

jqfactory supports jQuery prototype namespacing and the jQueryUI Widget Factory does not. This means that with jqfactory, you could create a multiple jQuery plugins under a single jQuery name (reducing the possibility of naming collisions).

Inheritance

jqfactory allows widgets to inherit from object literals when the jQueryUI Widget Factory supports inheritance using functions.

AMD support

jqfactory exports itself as a named AMD module (“jqfactory”) when the jQueryUI Widget Factory does not currently support AMD (although all jQueryUI files will soon be exported as anonymous AMD modules in a future release).

Event Handlers

jqfactory does not support passing event handlers as options when the jQueryUI Widget Factory does support event handler options.

Assumed Environment

jqfactory does not assume that you are using jQueryUI, when the jQueryUI Widget Factory does (e.g. Expects jQueryUI CSS class names).

Syntactic Sugar

jqfactory provides helpful abstractions in places the widget factory does not. Examples include event binding, jQuery deferred object support on intialization, and automatic event firing for certain actions (e.g. setting options)

Separate Our Plugin into Independent Pieces

From here on out, let’s assume we are using jqfactory to abstract away our jQuery plugin boilerplate code and are now ready to split up our plugin into separate files.

Our First jQuery Plugin File

Let’s assume that this file will be the first built file and will contain our default plugin options.

1
2
3
4
5
6

// options.js
// ----------
var example = {};
example.options = {
  someOption: true
};

On to the Next File

Let’s assume that this file will contain our plugin constructor function logic.

1
2
3
4
5

// _create.js
// ----------
example._create = function() {
  // Our constructor logic goes here
};

Can You See the Pattern?

So far, we are creating a new file for each plugin method. The reality is that this is a bit overkill, so try to make logical modular design decisions. In other words, try to put methods/features that depend on each other in the same file. Since we are not using anything that handles dependency management (e.g. Require.js), we are forced to track dependencies ourselves.

Creating Our Plugin

Once we are done decoupling our plugin into different files, we can create our plugin using jqfactory.

1
2
3
4

// _plugin.js
// ----------
// Calling the jqfactory Method
$.jqfactory("an.example", example);

Building Our Plugin with Grunt

Since our plugin has been separated into multiple files, we need a command-line tool to build our plugin into one file (for a user to use). We also want users to be able to exclude certain files from the build to allow custom builds. This is where Grunt comes in.

What is Grunt?

JavaScript (Node.js) Command-Line Task Runner

Perfect for automating repetitive tasks

A huge plugin ecosystem

Example Grunt Tasks?

File Concatenation

Minification

Code Quality Checking (e.g. jsHint)

Unit Testing and Phantom.js

SO MUCH MORE

How Do We Use It?

We need to create a file, called Gruntfile.js, at the root of our project directory.

Creating Our Gruntfile

Step 1

Inside of Gruntfile.js, we first need to wrap all of our Node.js code inside of a module.exports function.

1
2
3
4

// Gruntfile.js
module.exports = function(grunt) {
  // The rest of our Grunt code will go here!
};

Step 2

Add the configurations for any Grunt plugins/custom tasks you would like to use inside of the initConfig() Grunt method and also call the loadNpmTasks Grunt method for each plugin. For this example, we are going to use the grunt-contrib-concat and grunt-wrap plugins.

Note: Any plugins that start with the grunt-contrib naming convention are Grunt plugins that are maintained by the core Grunt team. All other plugins are user plugins.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// Gruntfile.js
module.exports = function(grunt) {
  var baseFilePath = 'src/js/',
  fileToBuild = baseFilePath + 'jquery.customBuild.js';
  // Our Grunt configuration
  grunt.initConfig({
  concat: {
    dist: {
      src: '<%= customBuild.files %>',
      dest: fileToBuild
    }
  },
  wrap: {
    modules: {
      src: [fileToBuild],
      wrapper: [';(function($, undefined) {\n', '\n}(jQuery));']
    }
  }
  });
  grunt.loadNpmTasks('grunt-contrib-concat');
  grunt.loadNpmTasks('grunt-wrap');
  // Our custom task will go here next  
 };

Note: In the previous code example, you will notice that we had to call the loadNpmTasks() Grunt method for each Grunt plugin we were using. This can become annoying to do if you are using many Grunt plugins, so you may want to check out the load-grunt-tasks plugin, which allows you to load all Grunt plugins with one line of code.

Step 3

Create our very own customBuild custom Grunt task. Our custom task will work together with the other Grunt plugins we are already using (concat, wrap) to allow users to create custom builds of our jQuery plugin.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

// Gruntfile.js
module.exports = function(grunt) {
  var baseFilePath = 'src/js/',
  fileToBuild = baseFilePath + 'jquery.customBuild.js';
  // Our Grunt configuration
  grunt.initConfig({
  concat: {
    dist: {
      src: '<%= customBuild.files %>',
      dest: fileToBuild
    }
  },
  wrap: {
    modules: {
      src: [fileToBuild],
      wrapper: [';(function($, undefined) {\n', '\n}(jQuery));']
    }
  }
  });
  grunt.loadNpmTasks('grunt-contrib-concat');
  grunt.loadNpmTasks('grunt-wrap');
  // Our custom task will go here next
  // Registers a default Grunt Task
  grunt.registerTask('customBuild', 'customBuild task', function() {
    var defaultFiles = ['options', '_create', '_plugin', 'customMethod'],
      args = this.args, customFiles = [], index, i = -1;
    // Loops through and excludes any file that was passed
    if(args.length) {
      while(++i < args.length) {
        index = defaultFiles.indexOf(args[i]);
        if(index !== -1) defaultFiles.splice(index, 1);
      }
    }
    // Makes sure that each passed file has the correct file path
    customFiles = defaultFiles.map(function(currentFile) {
      return baseFilePath + currentFile + '.js';
    });
    // Sets a Grunt configuration variable
    grunt.config.set('customBuild.files', customFiles);
    // Run's the Grunt concat plugin
    grunt.task.run('concat', 'wrap');
  });
};

Running Grunt

On the command line, type: grunt customBuild. This will build all of our plugin files into one file.

If you had wanted to exclude a file from the build (let’s assume there is an optional customMethod.js file), then you could type: grunt customBuild:customMethod

Success!

By default, any colon-separated arguments passed to our customBuild Grunt task will be mapped to plugin file names and will be not be included in our build.

Final Thoughts

JavaScript workflow tools are improving every day and will continue to improve. Start using these tools today!

Also, if you would like to learn how to create custom web UI builds for your users, then check out the rest of jQuery Portland Slide Deck that covers my open source library, DownloadBuilder.js

Happy jQuery plugin building!

Topics

Some of the topics covered include Require.js configurations, creating AMD modules, using third-party libraries with Require.js, the mobile web, Lodash templates, Jasmine unit testing, and r.js (the Require.js optimizer).

Free Preview

A free preview and sample chapter are both available. Happy reading!

IIFEs

IIFEs are an ideal solution for locally scoping global variables/properties and protecting your JavaScript codebase from outside interference (e.g. third-party libraries). If you are writing jQuery code that will be run in many different environments (e.g. jQuery plugins), then it is important to use an IIFE to locally scope jQuery.

You can’t assume everyone is using the $ to alias jQuery.

Here is how you would do it:

1
2
3
4
5
6
7
8

   // IIFE - Immediately Invoked Function Expression
  (function($, window, document) {
      // The $ is now locally scoped

      // The rest of your code goes here!

  }(window.jQuery, window, document));
  // The global jQuery object is passed as a parameter

If you don’t like having to scroll to the bottom of your source file to see what global variables/properties you are passing to your IIFE, you can do this:

1
2
3
4
5
6
7
8
9
10
11
12

   // IIFE - Immediately Invoked Function Expression
  (function(yourcode) {

      // The global jQuery object is passed as a parameter
      yourcode(window.jQuery, window, document);

      }(function($, window, document) {

          // The rest of your code goes here!

      }
  ));

To read more about IIFEs, you can read my blog post titled, I Love My IIFE.

Ready Event

Many developers wrap all of their code inside of the jQuery ready event like this:

1
2
3
4

   $("document").ready(function() {
      // The DOM is ready!
      // The rest of your code goes here!
  });

Or developers use a shorter version like this:

1
2
3
4

   $(function() {
      // The DOM is ready!
      // The rest of your code goes here!
  });

If you are doing either of the above patterns, then you should consider moving the pieces of your application (e.g. methods), that don’t depend on the DOM, outside of the ready event handler. Like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

   // IIFE - Immediately Invoked Function Expression
  (function(yourcode) {

      // The global jQuery object is passed as a parameter
      yourcode(window.jQuery, window, document);

      }(function($, window, document) {

          // The $ is now locally scoped 
          $(function() {

              // The DOM is ready!

          });

          // The rest of your code goes here!

      }
  ));

This pattern makes it easier to separate your logic (from a code design perspective) since not everything has to be wrapped inside of a single anonymous function. It will also improve your application’s page load performance, since not everything needs to initialized right away.

Caching DOM selectors

When manipulating elements in the DOM (e.g. animating, setting attributes, changing CSS properties), it is important to consider performance.

Every time you select a DOM element using jQuery, you are instantiating a new jQuery object and forcing jQuery to search the DOM.

Instead of creating multiple jQuery instances and forcing jQuery to re-query the DOM for a particular element, you can cache your jQuery object in a variable and reuse it like this:

1
2
3
4
5
6
7
8
9
10
11
12

   
  // Stores the jQuery instance inside of a variable
  var elem = $("#elem");

  // Set's an element's title attribute using it's current text
  elem.attr("title", elem.text());

  // Set's an element's text color to red
  elem.css("color", "red");

  // Makes the element fade out
  elem.fadeOut();

If you prefer the previous code snippet to be on one line, you can chain multiple jQuery methods together like this:

1
2
3
4
5

   // Stores the live DOM element inside of a variable
  var elem = $("#elem");
  
  // Chaining
  elem.attr("title", elem.text()).css("color", "red").fadeOut();

Adding DOM elements

Adding elements to the DOM is one of the slowest and most common use cases in a web application. To limit the performance hit, make sure you are not unneccessarily adding elements to the DOM.

A common example, that can cause web applications to feel janky (or slow), is building a dynamic HTML unordered list. Since there could potentially be thousands of list items inside of the list, you want to make sure to only append to the DOM once (instead of thousands of times). Like this:

1
2
3
4
5
6
7
8
9
10
11
12

   // Dynamically building an unordered list from an array
  var localArr = ["Greg", "Peter", "Kyle", "Danny", "Mark"],
      list = $("ul.people"),
      dynamicItems = "";

  $.each(localArr, function(index, value) {

      dynamicItems += "<li id=" + index + ">" + value + "</li>";

  });

  list.append(dynamicItems);

The previous example stores the entire HTML of the dynamic list inside of a local string variable. Once all the HTML has been created, the list is appended to the page ONE TIME. Many developers mistakingly append to the DOM each time they create a new list item. DO NOT DO BE THAT DEVELOPER

Event Delegation

DOM event handlers take up a lot of memory and can very easily cause memory leaks (and poor performance) in web applications. We can use an HTML unordered list example to demonstrate how to use event delegation to reduce the number of event handlers that we have and the amount of memory our application uses.

1
2
3
4
5
6
7
8
9
10
11
12
13

   var list = $("#longlist");

  list.on("mouseenter", "li", function(){

      $(this).text("Click me!");

  });

  list.on("click", "li", function() {

      $(this).text("Why did you click me?!");

  });

The previous example uses the jQuery on() method to add mouseenter and click event handlers to an unordered list. The second argument provided to the on() method is the event handler context. This tells jQuery to trigger the associated unordered list event handler if a list item child element has been the targeted DOM element.

To understand event delegation, we have to understand event bubbling. Event Bubbling is a behavior associated with DOM elements where parent DOM elements (all the way up to the document) are notified of child DOM element events. Not all DOM events natively bubble, so jQuery has done the heavy lifting and made the event bubbling behavior consistent for every event and browser.

Because of event bubbling, we only have to add one additional event handler to the unordered list (instead of a new event handler for each child list item). This saves system memory, which allows more memory to be allocated for other intensive operations, such as animations (improving our app’s perceived performance).

Ajax

Since jQuery version 1.5+, the jQuery ajax() method has returned a Promise object. Using Promises with Ajax allows us to bind multiple callback functions to our request, write flexible code where our ajax handling logic is in a different place than our actual request, and wait for multiple requests to complete before starting an action.

Here is an example of separating the handling logic from the actual request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

   function getName(personid) {
      var dynamicData = {};
      dynamicData["id"] = personID;
      // Returns the jQuery ajax method
      return $.ajax({
          url: "getName.php",
          type: "get",
          data: dynamicData
      });
  }

  getName("2342342").done(function(data) {
      // Updates the UI based the ajax result
      $(".person-name").text(data.name);
  });

Our example demonstrates a getName() function that accepts a unique id, sends an ajax request with that unique id, and returns the jQuery ajax() method. Since our function returns the jQuery ajax() method (which returns a Promise by default), we are able to call the done() method and pass a callback function (which will execute once the request has completed).

If we had wanted to wait for two separate ajax requests to our endpoint, we could have done something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

   function getName(personid) {
      var dynamicData = {};
      dynamicData["id"] = personID;
      // Returns the jQuery ajax method
      return $.ajax({
          url: "getName.php",
          type: "get",
          data: dynamicData
      });
  }

  var person1 = getName("2342342"),
      person2 = getName("3712968"),
      people = [person1, person2];

  $.when.apply(this, people).then(function() {
      // Both the ajax requests have completed
  });

We are using the JavaScript apply() method in the previous example to demonstrate how we can pass an array to the $.when method. If you do not want to use an array, then you can very easily pass each promise object (stored in a variable) as regular parameters.

Happy jQuerying!

Unfortunately, AMD script loaders, such as Require.js, are not drop-in solutions. To use an AMD module system, you must make sure every other JavaScript library used in your application is AMD Compatible.

AMD Compatible

For a JavaScript file to be AMD Compatible, the JavaScript content must be wrapped in a define() method and all module (file) dependencies must be listed.

A possible solution is to change the source of each JavaScript file you are using and make sure the content is wrapped inside of a define() method. This is both time-intensive and error-prone, since you will even have to change the source of third-party libraries that your application is using, such as jQuery.

At this point you may be scratching your head and asking yourself a few questions…

Common Questions

Why don’t third-party libraries automatically wrap their code in a define method?

Third-party libraries, such as jQuery, are often used in many different development environments, and the jQuery team cannot assume that jQuery is being used in an AMD environment. If jQuery was not being used in an AMD environment, then a syntax error would be thrown complaining that the define method is undefined.

Luckily for us, jQuery and many other popular libraries have found a way to support the AMD API (with the help of the always awesome James Burke)! When jQuery is executed, it checks to see if an AMD script loader is being used, and then conditionally wraps itself in a define() method and declares itself as a named AMD module.

Is there a better way to load a non-AMD Compatible third-party script with Require.js then upgrading the source of a file? Yes, with the Require.js v2.0 release, the shim configuration option was added to shim third-party libraries that were not AMD compatible and exported a global object. You can read more about the shim configuration here.

Does the shim configuration solve all of the AMD Compatibility problems? No! Although the shim configuration works for the most common uses cases, it is still not the ideal approach. Shimmed third-party scripts cannot be loaded from a CDN after a build, since shimmed files are inlined by the builder and may be executed by Require.js before a CDN asset dependency. The best approach is making sure a file is wrapped in a define() method (this works with CDN assets).

jQuery AMD Support

The first FAQ above mentioned that jQuery supports the AMD API by conditionally wrapping itself in a define() method and declaring itself as named AMD module. Let’s take a look at the jQuery source to see how they are doing it:

1
2
3

if ( typeof define === "function" && define.amd && define.amd.jQuery ) {
    define( "jquery", [], function () { return jQuery; } );
}

The jQuery code is checking to make sure that a global define() method is on the page, that there is an amd property (object) set on the define method (Remember this is JavaScript and functions act as first-class objects and can have properties), and that the amd object contains a jQuery property that is set to true. jQuery is essentially checking that an AMD script loader is on the page and that the AMD loader handles the special case when more than one jQuery version is included on the page (this is unfortunately very common).

If an AMD loader satisfies all of the jQuery AMD checks, then jQuery will wrap itself in the global define() method, register itself as a named module (“jquery”), and return itself (the jQuery object) within the define() method callback function.

Note: Registering named AMD modules is usually not recommended, since it hard codes a module id and does not allow you to change the module name, making it inflexible. The reason most popular third-party libraries register as named AMD modules is because many other libraries depend on them, and desire a common name that they can list as a dependency.

Using jQuery with Require.js

Now that we know jQuery is AMD compatible, we can easily use jQuery with a Require.js configuration like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// Sample Configuration File
// -------------------------
require.config({

  // Sets the js folder as the base directory for all future relative paths
  baseUrl: "./js",

  // 3rd party script alias names (Easier to type "jquery" than "libs/jquery, etc")
  paths: {

      // Core Libraries
      // --------------
      "jquery": "libs/jquery"

  }

});

// Includes Desktop Specific JavaScript files here (or inside of your Desktop router)
require(["jquery"],

  function($) {

    console.log("Hey look, I'm using jQuery with Require.js!");

  }

);

Using jQuery Plugins with Require.js

Although jQuery supports the AMD API, that does not mean that jQuery plugins are also AMD compatible. Here is how we could load a jQuery plugin that does not support the AMD API:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// Sample Configuration File
// -------------------------
require.config({

  // Sets the js folder as the base directory for all future relative paths
  baseUrl: "./js",

  // 3rd party script alias names (Easier to type "jquery" than "libs/jquery, etc")
  paths: {

      // Core Libraries
      // --------------
      "jquery": "libs/jquery",

      "example": "libs/plugins/example"

  },

  shim: {

    "example": ["jquery"]

  }

});

// Includes Desktop Specific JavaScript files here (or inside of your Desktop router)
require(["jquery", "example"],

  function($) {

    console.log("Hey look, I'm using a jQuery plugin that does not support the AMD API with Require.js!");

  }

);

The above code example uses the shim configuration to tell Require.js that the plugin depends on jQuery. Internally, Require.js waits until jQuery is loaded before it loads the jQuery plugin.

Luckily for plugin authors, a jQuery plugin can internally support the AMD API:

1
2
3
4
5
6
7
8
9
10
11
12

// Example plugin
(function (factory) {
    if (typeof define === 'function' && define.amd) {
        // AMD. Register as an anonymous module.
        define(['jquery'], factory);
    } else {
        // Browser globals
        factory(jQuery);
    }
}(function ($) {
    $.fn.jqueryPlugin = function () {};
}));

This jQuery plugin example checks to make sure an AMD loader is on the page and then registers itself as an anonymous AMD module (while also passing the “jquery” module as a dependency). Since jQuery registers itself as a named AMD module, the plugin is able to pass that exact name as a dependency.

Note: You can find other AMD patterns here;

Here is how you would load the AMD Compatible jQuery plugin with Require.js:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// Sample Configuration File
// -------------------------
require.config({

  // Sets the js folder as the base directory for all future relative paths
  baseUrl: "./js",

  // 3rd party script alias names (Easier to type "jquery" than "libs/jquery, etc")
  paths: {

      // Core Libraries
      // --------------
      "jquery": "libs/jquery",

      "example": "libs/plugins/example"

  }

});

// Includes Desktop Specific JavaScript files here (or inside of your Desktop router)
require(["jquery", "example"],

  function($) {

    console.log("Hey look, I'm using a jQuery plugin with Require.js!");

  }

);

jQueryUI Widget Factory Plugins

The above code example is a great solution for jQuery plugins to register themselves as anonymous AMD modules, but let’s next look at jQuery plugins that depend on both jQuery and the jQueryUI Widget Factory.

In case you are not familiar, the jQueryUI Widget Factory provides a flexible base for building complex, stateful plugins with a consistent API. - per the jQueryUI website.

The Widget Factory is designed not only for plugins that are part of jQuery UI, but for general consumption by developers who want to create object-oriented components without reinventing common infrastructure.

Since more and more jQuery plugin authors, including myself, are using the jQueryUI Widget Factory, it is necessary to understand how to use these jQuery plugins with AMD loaders such as Require.js.

Since the jQueryUI Widget Factory does not support the AMD API, here is how you currently have to load jQuery plugins that depend on the jQueryUI Widget Factory:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

// Sample Configuration File
// -------------------------
require.config({

  // Sets the js folder as the base directory for all future relative paths
  baseUrl: "./js",

  // 3rd party script alias names (Easier to type "jquery" than "libs/jquery, etc")
  paths: {

      // Core Libraries
      // --------------
      "jquery": "libs/jquery",

      "jquery.ui.widget": "libs/jquery.ui.widget",

      "jquery.selectBoxIt": "libs/plugins/jquery.selectBoxIt"

  },

  shim: {

    "jquery.ui.widget": ["jquery"],

    "jquery.selectBoxIt": ["jquery.ui.widget"]

  }

});

// Includes Desktop Specific JavaScript files here (or inside of your Desktop router)
require(["jquery", "jquery.ui.widget", "jquery.selectBoxIt"],

  function($) {

    $("select").selectBoxIt();

    console.log("Hey look, I'm using a jQueryUI Widget Factory plugin with Require.js!");

  }

);

The above code uses the shim configuration to shim both the jQueryUI Widget Factory and SelectBoxIt, a jQuery plugin based on the jQueryUI Widget Factory. This works, but requires additional configuration setup and the shim configuration, which prevents the loading of CDN assets after building using the Require.js optimizer.

After experiencing this first hand, I tweeted my desire that the jQueryUI Widget Factory should declare itself as a named AMD module, so that plugins (like SelectBoxIt) could list the Widget factory as a dependency and support the AMD API.

@jrburke You should convince the jQueryUI devs to declare the Widget Factory as a named module, like jQuery.Lot’s of plugins depend on it.

— Greg Franko (@GregFranko) February 6, 2013

Dave Methvin, the President of the jQuery Foundation, and Scott Gonzalez, the jQueryUI Project lead, (both all around good guys), responded by asking me if James Burke’s jqueryui-amd project would suit my needs.

@gregfranko Yes, @scott_gonzalez says you’re taking me on a mandate? Let’s gobowling. Does github.com/jrburke/jquery… work for you? @jrburke

— Dave Methvin (@davemethvin) February 7, 2013

@scott_gonzalez @davemethvin @jrburke I’ll write a blog post and let you know when it is done.

— Greg Franko (@GregFranko) February 7, 2013

If you are not familiar with James Burke’s jqueryui-amd project, it is a Node.js command line project that will automatically wrap jQueryUI modules within define() methods and pass jQuery as a dependency, thus making jQueryUI AMD Compatible:

1
2
3

define(['jquery'], function (jQuery) {
    // jQueryUI code goes here
});

This is a great solution if you are only using jQueryUI plugins (i.e. Calendar widget, etc), but not such a great solution for third-party plugin authors, like myself, who are using the jQueryUI Widget Factory as the base for our plugin structures.

Here is how you would load a jQueryUI Widget Factory plugin with Require.js, when using the jqueryui-amd project:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// Sample Configuration File
// -------------------------
require.config({

  // Sets the js folder as the base directory for all future relative paths
  baseUrl: "./js",

  // 3rd party script alias names (Easier to type "jquery" than "libs/jquery, etc")
  paths: {

      // Core Libraries
      // --------------
      "jquery": "libs/jquery",

      "jquery.ui.widget": "libs/jquery.ui.widget",

      "jquery.selectBoxIt": "libs/plugins/jquery.selectBoxIt"

  },

  shim: {

    // Shimming SelectBoxIt by telling Require.js that the plugin depends on the jQueryUI Widget Factory
    "jquery.selectBoxIt": ["jquery.ui.widget"]

  }

});

// Includes Desktop Specific JavaScript files here (or inside of your Desktop router)
require(["jquery", "jquery.ui.widget", "jquery.selectBoxIt"],

  function($) {

    $("select").selectBoxIt();

    console.log("Hey look I'm using a jQueryUI Widget Factory plugin with Require.js!");

  }

);

In the above code example, you’ll notice that jQueryUI Widget Factory no longer needs to use the shim configuration, since the jqueryui-amd project has wrapped it within a define() method. Unfortunately, the SelectBoxIt plugin still needs to be shimmed, since it is not AMD compatible.

By now you may be thinking, couldn’t you just support the AMD API within SelectBoxIt by doing this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

;(function (selectBoxIt) {

    if (typeof define === "function" && define.amd) {
        // AMD. Register as an anonymous module.
        define(["jquery", "jquery.ui.widget"], function() {

            selectBoxIt(window.jQuery, window, document);

        });
    } else {
        // Browser globals
        selectBoxIt(window.jQuery, window, document);
    }

}
(function ($, window, document, undefined) {

    // SelectBoxIt code goes here

})); // End of all modules

Technically yes, I could conditionally support the AMD API by using the above code. The problem is that it would be a very confusing process for plugin users, since I would have to point them to the jqueryui-amd project, which is not trivial to set up. Or I could maintain an up-to-date AMD Compatible version of the jQueryUI Widget Factory. Not an ideal process.

It would be much easier to tell users to create a Require.js path called, “jquery.ui.widget”, and be done with it!

Upgrading the jQueryUI Widget Factory

Following the lead of jQuery, I believe the jQueryUI Widget Factory should support the AMD API by registering as a named AMD module that Widget Factory plugins can declare as a dependency:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

;(function (widgetFactory) {

    if (typeof define === "function" && define.amd) {
        // AMD. Register as an anonymous module.
        define( "jquery.ui.widget", ["jquery"], function() {

            widgetFactory( window.jQuery );

        } );
    } else {
        // Browser globals
        widgetFactory( window.jQuery );
    }
}
(function( $, undefined ) {

    // jQuery Widget Factory code goes here

}));

I have listed “jquery.ui.widget” to be the default name of the Widget Factory, but that is only my personal opinion and may be subject to change. If this change is put into the jQueryUI Widget Factory, then the thousands of plugins that are based on it (probably more), could easily support the AMD API. This means that no Require.js configurations/extra steps would be necessary for you to use a jQuery plugin based on the Widget Factory.

Note: Check out this gist to see the full source of the AMD Compatible jQueryUI Widget Factory that I am proposing.

Final Thoughts

It only takes a couple lines of code to support the AMD API, so I feel that the jQueryUI Widget Factory should follow in the footsteps of its parent’s favorite child, jQuery, and just do it (I am not sponsored by Nike). I’d love to hear your thoughts! Happy AMD’ing!

In the video, I walk through each boilerplate file, and explain in-depth how the library helps you create more maintainable applications. Enjoy!

If you are also interested in incorporating the Backbone Marionette library into your stack, check out the Marionette-Require-Boilerplate. Happy boilerplating!

In the words of James Padolsey:

An IIFE protects a module’s scope from the environment in which it is placed.

There are more benefits to using IIFE’s than just local scoping, but before we talk about some of the other benefits, let’s take a look at some code to see how to create a basic IIFE:

1
2
3

(function(){
  // my special code
}());

The above IFFE is just an anonymous function (no name attached to it) that is wrapped inside of a set of parentheses and called (invoked) immediately. Let’s break this down step by step.

The Anonymous Function:

1
2
3
4

// Anonymous function
function(){
  // my special code
}(); // The parentheses make sure the anonymous function gets called immediately

A function, without a name, is created and then called (invoked) immediately via the () at the very end.

The Parentheses

You might be wondering why we need to wrap the immediately invoked anonymous function inside of parentheses. Before I explain why, try the above code inside of a console window. Get a syntax error?

By wrapping the anonymous function inside of parentheses, the JavaScript parser knows to treat the anonymous function as a function expression instead of a function declaration. A function expression can be called (invoked) immediately by using a set of parentheses, but a function declaration cannot be.

Note: In case you forget the difference between JavaScript function expressions and function declarations:

Function Expression - var test = function() {};

Function Declaration - function test() {};

Since the anonymous function within our IIFE is a function expression and is not being assigned to a global variable, no global property is being created, and all of the properties created inside of the function expression are scoped locally to the expression itself.

Other Benefits of using an IIFE

Whew, now that we understand the basic concept of an IIFE, let’s determine some other benefits of using them in your code.

Reduce scope lookups

A small performance benefit of using IIFE’s is the ability to pass commonly used global objects (window, document, jQuery, etc) to an IIFE’s anonymous function, and then reference these global objects within the IIFE via a local scope.

Note: JavaScript first looks for a property in the local scope, and then it goes all the way up the chain, last stopping at the global scope. Being able to place global objects in the local scope provides faster internal lookup speeds and performance.

Let’s look at a code example of passing global objects to an IIFE:

1
2
3
4
5
6

// Anonymous function that has three arguments
function(window, document, $) {

  // You can now reference the window, document, and jQuery objects in a local scope

}(window, document, window.jQuery); // The global window, document, and jQuery objects are passed into the anonymous function

Minification Optimization

Another small performance benefit of using IIFE’s is that it helps with minification optimization. Since we are able to pass global objects into the anonymous function as local values (parameters), a minifier is able to reduce the name of each global object to a one letter word (as long as you don’t already have a variable of the same name). Let’s look at the above code sample after minification:

1
2
3
4
5
6

// Anonymous function that has three arguments
function(w, d, $) {

  // You can now reference the window, document, and jQuery objects in a local scope

}(window, document, window.jQuery); // The global window, document, and jQuery objects are passed into the anonymous function

Note: Another added benefit (when using jQuery), is that you can freely use the $ without worrying about other library conflicts, since you passed in the global jQuery object and scoped it to the $ as a local parameter.

Readability

One of the con’s with using IIFE’s is readability. If you have a lot of JavaScript code inside of an IIFE, and you want to find the parameters that you are passing into an IIFE, then you need to scroll all the way to the bottom of the page. Luckily, there is a more readable pattern that I have begun to use:

1
2
3
4
5
6
7
8
9
10
11
12
13

(function (library) {

    // Calls the second IIFE and locally passes in the global jQuery, window, and document objects
    library(window, document, window.jQuery);

}

// Locally scoped parameters 
(function (window, document, $) {

// Library code goes here

}));

This IIFE pattern allows you see what global objects you are passing into your IIFE, without you having to scroll to the very bottom of a potentially very long file. Happy IIFE’ing!

Background

Backbone.validateAll originated from a failed Backbone.js pull request. The original pull request was created because of frustration with using the Backbone.js Model validate method when validating HTML forms.

Backbone.js v0.9.1 Changes

Since Backbone.js v0.9.1 and greater, Backbone Model validation was not made to elegantly handle form validation, since the default validate method will validate all Model attributes, regardless of what particular attribute is being set or saved. For certain use cases, it is necessary to only validate a certain Model property (or form field) without worrying about the validation of any other Model property (or form field).

Performance!

Backbone core contributor, @braddunbar, presented a possible solution for this use case in the above mentioned pull request, but it still involved calling all of the validation methods within the validate() method, which can negatively affect performance.

Here is a jsPerf Test showing the performance benefits when setting Backbone Model attributes with and without Backbone.validateAll.

Who Should Use This

Anyone who wants an option to validate only Model properties that are currently being set/saved instead of the entire Model. An obvious use case for this is form validation.

Note: The plugin does not override the default Backbone.js Model validation behavior (all Model attributes are validated whenever an attribute is saved/set on a Model) by default. You need to pass the validateAll option when setting/saving Model attributes.

Is it easy to use the plugin?

Yes! You just have to pass the validateAll option when setting/saving a Model attribute.

1
2

    // The validateAll option makes sure that only the Model attributes that you are setting get passed to the validate method
    user.set({ "firstname": "Greg" }, {validateAll: false});

Summary

If you have found yourself frustrated about Backbone’s default Model validation behavior, then this plugin is a perfect fit. You can also read more about this plugin in Addy Osmani’s Backbone Fundamentals book under the section titled Better Model Property Validation. Happy Model validating!

These projects realize that users expect their documentation to follow a common format that includes a table of contents that houses, at the very least, a Getting Started guide, a Demos/Examples section, and a forum section to ask questions. Additional sections (ie. annotated source code, Contributor Guide) targeting potential core project contributors may also be included.

All OS developers should take note of these documentation practices and follow them when promoting their own projects. When patrolling Github to find new and interesting projects, I often find myself dismissing a project right away if there is a lack of documentation.

The project could have the most readable, brilliant, and performant code known to man, yet I (and many other developers) would never know

But Documentation Takes Too Long to Write!

It’s true, documenting your project may take longer than writing the project code itself. But there are open source tools that can help expediate the process…

Tocify.js - a jQuery plugin

Tocify is “a jQuery plugin that dynamically generates a table of contents (TOC). Tocify can be optionally styled with Twitter Bootstrap or jQueryUI Themeroller, and optionally animated with jQuery show/hide effects”.

Tocify also optionally provides support for smooth scrolling, scroll highlighting, scroll page extending, and the HTML5 pushstate API via History.js.

Tocify works by looking at all of the header elements on an HTML page and constructing a TOC based on the page structure. Tocify was inspired by the Can.js and jQuery++ documentation created by Bitovi, so it allows you to have complex nested TOC structures along with slick show/hide effects.

Document-Bootstrap - a Boilerplate Project

Document-Bootstrap is “a boilerplate project that incorporates JavaScript libraries, jQuery plugins, and Twitter Bootstrap to save developers time when creating project pages and providing users with custom project builds”.

Document-Bootstrap serves as a great starting point for creating a OS project page. Document-Bootstrap allows you to stop worrying about the design of your project page and instead focus on the content.

Note: Document-Bootstrap includes Tocify

Docco - an Annotated Source Code Generator

Docco “produces HTML that displays your comments alongside your code. Comments are passed through Markdown, and code is passed through Pygments syntax highlighting.”

As long as your codebase adheres to Markdown standards, Docco will automatically create an annotated source code HTML page for your project. Annotated source code is much cleaner and easier to read than regular source code, in my opinion.

Note: Docco can be used to process CoffeeScript, JavaScript, Ruby, Python, or TeX files

Summary

I find that as a developer I read more documentation than I write code. Please help my eyes by creating awesome documentation. Happy documenting!

Examples of popular OS projects that are providing custom build options now include jQuery (recent addition in version 1.8), jQueryUI, Modernizr, Twitter Bootstrap, Can.js, etc.

After reviewing the custom build processes of the above OS projects, it seemed that each project had developed its own custom back-end build process from scratch. This architecture seemed to work well for projects with many contributors/organizational backing, but I wanted an easy solution that I could use for my own OS projects where I was the only main contributor. Since I could not find any existing OS projects that fit the bill, I created DownloadBuilder.js.

DownloadBuilder.js

Description

DownloadBuilder.js is a JavaScript library that uses the HTML5 Filesystem API to create concatenated single file custom builds for front-end projects. Since the project uses the HTML5 Filesystem API, all of its features only currently work in Chrome 21+, although it can still be used in all other modern browsers(Firefox, IE8+) to create a generated concatenated project file.

Getting Started

Note: DownloadBuilder.js expects your project to be decoupled and split into separate files (modular approach).

Download the entire project from Github and look at the examples in the demos folder.

Include DownloadBuilder.js

1
2

    // DownloadBuilder.js
    <script src="DownloadBuilder.js" />

HTML

Create one checkbox for each file in your project that you want to allow users to download. Each checkbox value should be the full file path.

Note: You can use Github or local relative file paths. This example uses Github to download your project files.

1
2

    // A checkbox with the correct Github filepath of testfile.js
    <label class="checkbox"><input checked="checked" type="checkbox" value="src/javascripts/testfile.js">Test File</label>

JavaScript

Using a library (eg. jQuery) or regular JavaScript, create a new DownloadBuilder object instance with custom options when the DOM is ready.

Note: You do not need to use a library, such as jQuery. I am using it here for convenience. Also, all options are optional and more documentation about all of the options can be found in the documentation.

1
2
3
4
5
6
7
8

    //Executes your code when the DOM is ready.  Acts the same as $(document).ready().
    $(function() {

        // All options passed to the DownloadBuilder object constructor are optional
        // This example is a sample Github setup
        var builder = new DownloadBuilder({ "location": "github", "author": "gfranko", "repo": "jquery.selectboxit.js", "branch": "dev" });

    });

Next, create an event handler for when you want to create your custom built file, call the buildURL() method to construct a file url (if supported), and then create custom logic once your custom built file has been created (the file is passed into the buildURL callback function).

Note: More documentation about the buildURL method and other methods can be found in the documentation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

    // Whenever an element with an id of javascript-generate is clicked, the buildURL() method is called
    $("#javascript-generate").on("click", function() {

        // Pass in all of the checkboxes that should be used to download files, the desired name of the file to be created,
        // the type of file to be created, and a callback function
        builder.buildURL($("#javascript-downloads input[type='checkbox']:checked"), "example.js", "javascript", function(data) {

            // An object is passed to the callback function which contains a file url
            // (if the current browser supports the HTML5 Filesystem API), file content (the text of the file),
            // the name of the file that was created, and the type of file that was created.

            // Put any custom logic here

        });

    });

Below is the full DownloadBuilder.js example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

    //Executes your code when the DOM is ready.  Acts the same as $(document).ready().
    $(function() {

        // All options passed to the DownloadBuilder object constructor are optional
        // This example is a sample Github setup
        var builder = new DownloadBuilder({ "location": "github", "author": "gfranko", "repo": "jquery.selectboxit.js", "branch": "dev" });

        // Whenever an element with an id of javascript-generate is clicked, the buildURL() method is called
        $("#javascript-generate").on("click", function() {

            // Pass in all of the checkboxes that should be used to download files, the desired name of the file to be created,
            // the type of file to be created, and a callback function
            builder.buildURL($("#javascript-downloads input[type='checkbox']:checked"), "example.js", "javascript", function(data) {

                // An object is passed to the callback function which contains a file url
                // (if the current browser supports the HTML5 Filesystem API), file content (the text of the file),
                // the name of the file that was created, and the type of file that was created.

                // Put any custom logic here

            });

        });

    });

Summary

DownloadBuilder.js is a great fit for small OS projects that are only worried about creating a single file custom build. If there is a feature that you would like to see added to DownloadBuilder.js, feel free to create an issue or fork the project the project on Github. Happy custom building!

The influx of JavaScript MV* frameworks has created new design patterns that have promoted JavaScript as a language that you should care about. JavaScript codebase consistency, maintainability, and performance have never been scrutinized more. This intensified focus is helping the web become an even better place to spend your time.

Although 2012 has been a big win for the JavaScript community, there is still much work to be done. Much of that work consists of educating developers, who may not be JavaScript wizards (seriously not everyone can be Paul Irish, Addy Osmani, etc), that organizing their front-end codebases deserves their full time and attention.

A common argument against using JavaScript MV* frameworks by non-JavaScript wizards is that most “apps” are not complex enough to warrent using these “bloated MV Whatever frameworks” (their words not mine). Before you start screaming at your computer, let’s look at this argument in more detail using Backbone.js, one of the most popular JavaScript MV* frameworks, and custom Backbone.js builds.

Backbone.js

Backbone.js is a great client-side MV* JavaScript framework that provides structure to JavaScript applications by providing View, Model, Collection, Router, and Event class objects. Although your application may not need all of the functionality that Backbone.js provides you, 99% of all applications could use the functionality provided by one or more Backbone.js class objects. Let’s take a look at each Backbone.js class object and determine if a “simple” application needs the functionality provided.

Backbone.js View

Backbone Views allow you to organize all of your JavaScript event handlers while also providing a mechanism for adding dynamic HTML to your page through the optional use of JavaScript templates.

Here is an example Backbone View class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

   var View = Backbone.View.extend({

        // Represents the actual DOM element that corresponds to your View
        el: 'body',

        // Constructor
        initialize: function() {

        },

        // Event Handlers
        events: {

            "click #example": "doSomething"

        },

        render: function() {

            // Updates the text of the element with an ID attribute of example            
            this.$el.find("#example").text("This is an example");

        },

        doSomething: function() {

            // Do something

        }

    });

Backbone.js View Conclusion

The basic functionality that a Backbone View class object provides is organizing your JavaScript event handlers and organizing how you update your applications UI. 99.9% of all applications (simple or complex) will include JavaScript event handlers that respond to user interactions and then add content to a page.

A common problem with most applications is that their JavaScript code is filled with inconsistent event handlers. You could very well see a “legacy” application with DOM Level 0 (event handlers inside HTML code), DOM Level 1 (event handlers inside JavaScript code that limit the amount of event handlers that can be bound to each HTML element) , and DOM Level 2 event handlers (event handlers inside JavaScript code that allows an unlimited amount of event handlers to be bound to each HTML element). This inconsistency makes it extremely difficult to maintain an app, especially if a new team member is added to the project.

If you are using a library, such as jQuery, you most likely have many DOM Level 2 events in your codebase (ie. $(“body”).click(function() {})). Although jQuery helps with the consistency of your event handlers, it does not help you structure how to organize all of your event handlers. With just jQuery, an application could consist of spaghetti code that binds event handlers all over the place. I have worked in this environment, and have found that more bugs are created because of this inconsistency.

No matter the complexity of your application, Backbone Views could very easily help promote best practices and improve maintainability of your JavaScript event handlers.

Backbone Model

Backbone Models store all of your applications business logic and data. This allows you to organize all of your application’s data validation inside of your Models.

Here is an example Backbone Model class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

    var Model = Backbone.Model.extend({

        // Default properties
        defaults: {

            example: "I love having my data separated from the DOM"

        }

        // Constructor
        initialize: function() {

        },

        // Any time a Model attribute is set, this method is called
        validate: function(attrs) {

        }

    });

Backbone.js Model Conclusion

The basic functionality that a Backbone Model class object provides is a place for your application to store and validate client-side information. 99.9% of applications will include validation of data.

A common problem with most applications is that they use the DOM (Document Object Model) as a database (Backbone.js creator, Jeremy Ashkenas, has talked about this at length). Any time an application needs to find the current “state” of an application, that data is retrieved from the DOM. This can severely hurt performance, since DOM related activities are one of the most memory intensive actions your JavaScript can take.

A common misconception is that the DOM is a part of the JavaScript language. It isn’t. In fact, it is a completely separate API that JavaScript interacts with. Having the ability to query the current “state” of your application without always resorting to querying the DOM is a HUGE WIN.

No matter the complexity of your application, Backbone Models could very easily promote decoupling your code and standardizing where your application performs business logic validation.

Backbone.js Collection

If your application is complex, it is also helpful to use Backbone Collections, which provides a mechanism to interact with many different Model instances. Since Backbone has a hard dependency on Underscore.js, you are able to utilize many Underscore.js methods to interact with Collections.

Here is an example Backbone Collection class:

1
2
3
4
5
6

var Collection = Backbone.Collection.extend({

    //Allows the Collection to work with User models
    model: User

});

Backbone.js Collection Conclusion

The basic functionality that a Backbone Collection class object provides is a mechanism for your application to interact with one or more Backbone Models.

The Backbone Collection class object may not be necessary for all applications, since the true benefit of collections shines through when your application contains more than one Backbone Model instance, and very simple applications may only contain one model instance.

Backbone.js Router

Backbone Routers are typically used to define “routes” in your application. Routes are essentially a unique page in a traditional web application, but in a one page JavaScript application, they help organize your client-side logic without requiring a page refresh (traditionally appending a route as a hash tag to a browser’s url or using the new HTML5 push state api to silently track page state).

Here is an example Backbone Router class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

    var Router = Backbone.Router.extend({

        // Constructor
        initialize: function(){

        //Required for Backbone to start listening to hashchange events
        Backbone.history.start();

        },

        routes: {

            // Calls the home method when there is no hashtag on the url
            '': 'home'

        },

        'home': function(){

            // Gets called when there is no hashtag on the url
            console.log("My very first Backbone route");

        }
    });

Backbone.js Router Conclusion

The basic functionality that a Backbone Router class object provides is a mechanism for your application to utlize a “single page” structure. This is particularly useful if you do not want page refreshes in your application when a user navigates between “pages” or different sections of your app’s functionality.

The Backbone Router class object may not be necessary for all applications, since not all applications may want the “single page” feel or care about refreshing the page.

Backbone.js Event

Backbone Events are an important concept in Backbone, since they provide you with an easy mechanism to use the pub sub pattern and decouple your code. Backbone triggers certain events by default (eg. a Model change event is triggered after a Model property has been validated and saved), but Backbone also allows you to trigger and bind to custom events. This is an extremely useful pattern, since it allows many different classes to listen to one class, without that one class knowing about any of its listeners.

Here is an example Event being triggered by a Backbone Model class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

    var Model = Backbone.Model.extend({

        // Default properties
        defaults: {

            example: "I love having my data separated from the DOM"

        }

        // Constructor
        initialize: function() {

        },

        // Any time a Model attribute is set, this method is called
        validate: function(attrs) {

        },

        triggerEvent: function() {

            // Triggers an test event and passes data that can be accessed in the event handler
            this.trigger("test", { someData: "data" });

        }

    });

Here is an example Event being bound by a Backbone View class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

   var view = Backbone.View.extend({

        // Represents the actual DOM element that corresponds to your View (There is a one to one relationship between View Objects and DOM elements)
        el: 'body',

        // Constructor
        initialize: function() {

            //Setting the view's model property.  This assumes you have created a model class and stored it in the Model variable
            this.model = new Model();

            //Event handler that calls the initHandler method when the init Model Event is triggered
            this.model.on("test", this.test);

        },

        // Event Handlers
        events: {

            "click #example": "testModelEvent"

        },

        render: function() {

            // Updates the text of the element with an ID attribute of example            
            this.$el.find("#example").text("This is an example");

        },

        promptUser: function() {

            prompt("Isn't this great?", "Yes, yes it is");

        },

        testModelEvent: function() {
            this.model.triggerEvent();
        },

        test: function(obj) {

            console.log("Just got " + obj.someData + " from my model!");

        }

    });

Backbone.js Event Conclusion

The basic functionality that a Backbone Event class object provides is a mechanism for using the pub/sub pattern to decouple an application’s codebase. 99.9% of applications could benefit from a design pattern that promotes decouplization (not sure if that is a real word).

A common jQuery design pattern is triggering and binding to jQuery special events on the HTML body element. This pattern is extremely useful, but Backbone improves on this pattern, since it does not rely on the DOM for its pub/sub implementation. This improves performance and flexibility, since it allows you to bind to custom events on a generic JavaScript object instead of just a jQuery object.

No matter the complexity of your application, the Backbone Events class object could very easily promote decoupling your code and consistent special event binding.

Backbone.js Custom Builds

Backbone.js does not support custom builds by default, so I looked at the Backbone codebase and split up all of the Backbone Class Objects into their own files. Since Backbone.js is not set up in a modular way and instead heavily uses local variables all scoped under one Immediately Invoked Function Expression (IIFE) like most libraries, I had to make a few changes to remove these local property dependencies so that they could be split into several files.

With Backbone.js custom builds, you can now use the Backbone Events class object as a standalone pub/sub solution, or only use Backbone Views to organize all of your app’s event handlers, or use Backbone Models to store all of your applications data client-side, etc (all while minimizing your file size).

Backbone.js is incredible, so I wanted to make it even easier for people who aren’t completely sold on using it, to only take what they want/need. Start making Backbone.js Custom Builds now!

The Shim configuration is a much needed upgrade to the Require.js core that allows Require.js to load non-AMD compatible scripts. In my previous post Using Backbone.js with Require.js, I covered how Use.js, a Require.js plugin created by Backbone.js core contributor Tim Branyen, was necessary to load Backbone.js and Underscore.js (both AMD incompatible) with Require.js. This was a good solution for integrating these two wonderful projects together, but it was still another project dependency that you needed to keep track of.

James Burke mentions Use.js as one of his inspirations for including the new Shim configuration. Now, instead of including the Use.js plugin to load Backbone and Underscore, you can have a shim configuration in your main file like this:

1
2
3
4
5
6
7
8
9

  // Sets the configuration for your third party scripts that are not AMD compatible
  shim: {

      "backbone": {
          deps: ["underscore", "jquery"],
          exports: "Backbone"  //attaches "Backbone" to the window object
      }

  } // end Shim Configuration

The Shim configuration is also a replacement for the order plugin, which made sure certain scripts executed in a particular order. Example use cases for this include loading jQuery and Backbone plugins, since Backbone must be executed before Backbone plugins are executed, and jQuery must be executed before jQuery plugins are executed. Below is how you can load jQuery and Backbone plugins using Require.js 2.0 or greater:

1
2
3
4
5
6
7

  // Sets the configuration for your third party scripts that are not AMD compatible
  shim: {

        'jquery.selectBoxIt': ['jquery'],
        'backbone.Validation': ['backbone']

  } // end Shim Configuration

For more documentation on all the new changes in Require.js 2.0, head over to the Require.js Github Wiki. Happy AMD’ing!

Backbone Views act as a combination of traditional MVC Views and Controllers, since they allow you to organize all of your JavaScript event handlers while also providing a mechanism for adding dynamic HTML to your page through the optional use of JavaScript templates. Views will also often be where you set data on your Models.

Here is an example Backbone View class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

   var View = Backbone.View.extend({

        // Represents the actual DOM element that corresponds to your View (There is a one to one relationship between View Objects and DOM elements)
        el: 'body',

        // Constructor
        initialize: function() {

            //Setting the view's model property.  This assumes you have created a model class and stored it in the Model variable
            this.model = new Model();

        },

        // Event Handlers
        events: {

            "click #example": "promptUser"

        },

        render: function() {

            // Updates the text of the element with an ID attribute of example            
            this.$el.find("#example").text("This is an example");

        },

        promptUser: function() {

            prompt("Isn't this great?", "Yes, yes it is");

        }

    });

Backbone Models store all of your applications business logic and data. This allows you to organize all of your application’s data validation inside of your Models. In most cases, Models should not know about any of your Views, or the DOM. There are certain design patterns (eg. modelbinding) where Models are aware of the DOM and set data on it, but most patterns do not implement this strategy since it is beneficial for Model’s to be completely decoupled from other pieces of the application.

Here is an example Backbone Model class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

    var Model = Backbone.Model.extend({

        // Default properties
        defaults: {

            example: "I love having my data separated from the DOM"

        }

        // Constructor
        initialize: function() {

        },

        // Any time a Model attribute is set, this method is called
        validate: function(attrs) {

        }

    });

If your application is complex, it is also helpful to use Backbone Collections, which provides a mechanism to interact with many different Model instances. Since Backbone has a hard dependency on Underscore.js, you are able to utilize many Underscore.js methods to interact with Collections. Keep in mind that you may alternatively use lodash, a drop-in replacement library for Underscore.js that provides cross browser bug fixes and performance improvements for Underscore.js. Lodash also allows custom builds, so you can only use a minimum number of Underscore.js functions if you like (reducing file size).

Here is an example Backbone Collection class:

1
2
3
4
5
6

var Collection = Backbone.Collection.extend({

    //Allows the Collection to work with User models
    model: User

});

Backbone Routers are typically used to define “routes” in your application. Routes are essentially a unique page in a traditional web application, but in a one page JavaScript application, they help organize your client-side logic without requiring a page refresh (traditionally appending a route as a hash tag to a browser’s url or using the new HTML5 push state api to silently track page state).

Here is an example Backbone Router class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

    var Router = Backbone.Router.extend({

        // Constructor
        initialize: function(){

        //Required for Backbone to start listening to hashchange events
        Backbone.history.start();

        },

        routes: {

            // Calls the home method when there is no hashtag on the url
            '': 'home'

        },

        'home': function(){

            // Gets called when there is no hashtag on the url
            console.log("My very first Backbone route");

        }
    });

Backbone Events are an important concept in Backbone, since they provide you with an easy mechanism to use the pub sub pattern and decouple your code. Backbone triggers certain events by default (eg. a Model change event is triggered after a Model property has been validated and saved), but Backbone also allows you to trigger and bind to custom events. This is an extremely useful pattern, since it allows many different classes to listen to one class, without that one class knowing about any of its listeners.

Here is an example Event being triggered by a Backbone Model class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

    var Model = Backbone.Model.extend({

        // Default properties
        defaults: {

            example: "I love having my data separated from the DOM"

        }

        // Constructor
        initialize: function() {

        },

        // Any time a Model attribute is set, this method is called
        validate: function(attrs) {

        },

        triggerEvent: function() {

            // Triggers an test event and passes data that can be accessed in the event handler
            this.trigger("test", { someData: "data" });

        }

    });

Here is an example Event being bound by a Backbone View class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

   var view = Backbone.View.extend({

        // Represents the actual DOM element that corresponds to your View (There is a one to one relationship between View Objects and DOM elements)
        el: 'body',

        // Constructor
        initialize: function() {

            //Setting the view's model property.  This assumes you have created a model class and stored it in the Model variable
            this.model = new Model();

            //Event handler that calls the initHandler method when the init Model Event is triggered
            this.model.on("test", this.test);

        },

        // Event Handlers
        events: {

            "click #example": "testModelEvent"

        },

        render: function() {

            // Updates the text of the element with an ID attribute of example            
            this.$el.find("#example").text("This is an example");

        },

        promptUser: function() {

            prompt("Isn't this great?", "Yes, yes it is");

        },

        testModelEvent: function() {
            this.model.triggerEvent();
        },

        test: function(obj) {

            console.log("Just got " + obj.someData + " from my model!");

        }

    });

Require.js serves two different purposes than Backbone.js. Require.js is an AMD (Asynchronous Module Definition) script loader that asynchronously loads your JavaScript to improve page load performance, while also providing you the ability to organize your JavaScript into self contained modules. Each JavaScript file represents a module.

Each module is enclosed in a define tag that lists the module’s file dependencies, and keeps the global namespace free (essentially acting as a JavaScript closure). Since none of your modules are global, inside of each module, you need to declare which other modules are dependencies and pass them to your current module. This provides a solution for limiting global variables and dependency management. This solution is much better then having many script tags in a single page, which can be cumbersome to keep track of which files depend on which other files. It also encourages you to decouple your JavaScript logic (instead of the traditionally hard to read one page JavaScript application).

Here is a more advanced example of a Backbone View class used with Require.js:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

define(['jquery', 'use!backbone','models/model'], function($, Backbone, Model){

    var self,

  View = Backbone.View.extend({

        // Represents the actual DOM element that corresponds to your View (There is a one to one relationship between View Objects and DOM elements)
        el: 'body',

        // View constructor
        initialize: function() {

            // Storing the View context
            self = this;

            // Setting the View's model property to the passed in Model
            this.model = new Model({
                message: "You are now using Backbone, Require, and jQuery!"
            });

        },

        events: {
            "click #example": "promptUser"
      },

        render: function() {

            // Updates the text of the element with an ID attribute of example
            self.$el.find("#example").text("This is an example");

        },

        promptUser: function() {
            prompt("Isn't this amazing?", "Yes, yes it is");
        }

    });
  
    // Returns the entire view (allows you to reuse your View class in a different module)
    return new View();
});

Backbone.js and Require.js perfectly complement each other, but there is one problem… Backbone.js is not AMD compatible. To be AMD compatible, a script must declare itself as a module by calling the define() method if it exists and list it’s dependencies. Backbone decided to not natively support AMD/Require.js, because it’s creater, Jeremy Ashkenas, felt it was unnatural to have to change Backbone’s source code so that it would work in Require.js and other AMD loaders. Luckily for us, Backbone contributor, Tim Branyen, created Use.js for this exact reason.

Looking at the previous code example, you will notice that I am using the Use.js plugin to include Backbone as a dependency to my View class. Use.js allows you to use (no pun intended) scripts that are not AMD compatible, by setting a one time configuration (typically in a main.js file or initialization file), and then prefixing dependencies with use!.

Here is a typical Use.js configuration with Backbone.js and Underscore.js:

1
2
3
4
5
6
7
8
9
10
11
12
13

  // Sets the use.js configuration for your application
  use: {

    backbone: {
      deps: ["use!underscore", "jquery"],
      attach: "Backbone"  //attaches "Backbone" to the window object
    },

    underscore: {
      attach: "_" //attaches "_" to the window object
    }

  } // end Use.js Configuration

Note: Require.js 2.0 added support for loading non-AMD compatible scripts by using the Shim configuration. You can find a more detailed explanation of the Shim configuration in my next blog post. If you want more in-depth explanations and examples of how to setup Backbone.js, Require.js, and the Shim configuration, check out the Backbone-Require-Boilerplate I recently created on Github.

An additional benefit of using Require.js is you can optimize (concat, minifiy) your entire project or single JavaScript files (depending on your preference) using r.js, a library written by James Burke that allows you to use the Require.js Optimizer. All you need to do is install either node.js or rhino (both can be used as command line tools but node.js is recommended) and create a build file.

Here is an example of an app.build.js configuration file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

//Install node.js, navigate to the js folder, and then run this command: "node r.js -o app.build.js"
({

  // Creates a js-optimized folder at the same folder level as your "js" folder and places the optimized project there
  dir: "../js-optimized",

  // 3rd party script alias names
  paths: {

    // Core Libraries
    modernizr: "libs/modernizr-2.5.3.min",
    jquery: "libs/jquery-1.7.2.min",
    underscore: "libs/lodash-0.2.0.min",
    backbone: "libs/backbone-0.9.2.min",

    // Require.js Plugins
    use: "plugins/use-0.3.0.min",
    text: "plugins/text-1.0.8.min"

  },

  // Sets the use.js configuration for your application
  use: {

    backbone: {
      deps: ["use!underscore", "jquery"],
      attach: "Backbone"  //attaches "Backbone" to the window object
    },

    underscore: {
      attach: "_" //attaches "_" to the window object
    }

  }, // end Use.js Configuration

  // Modules to be optimized:
  modules: [

    {
      name: "mobile"
    },

    {
      name: "desktop"
    }
  ]

})

Obviously your app.build.js file will most likely be different, but hopefully this helps get you on the right track (note: I took this directly from my Backbone-Require-Boilerplate project).

Considering the many advantages of using Backbone.js and Require.js together, I hope I have convinced you to try out these great open source projects. Happy coding!

1
2
3
4
5
6
7
8

var something;

if(somethingElse === true) {
    something = true;
}
else if(somethingElse === false) {
    something = false;
}

If you have, then you need to be using JavaScript logical operators. The previous code can be rewritten like this:

1

var something = somethingElse || false;

Logical OR Operator

The logical OR operator returns the first true value it finds (looking from left to right). If nothing is true in the statement, then it defaults to the last value (false in the previous code example). This makes it perfect for setting default values.

It is also important to understand that JavaScript evaluates other variable types to boolean (true or false). Below are examples of other JavaScript variable types that are evaluated to true or false:

"" - An empty string in JavaScript returns false. All other string values return true.

undefined - Returns false.

null - Returns false

0 - Returns false. All other numbers return true.

Here is a more advanced (and more common) use case for the logical OR operator. You want to check if a certain string value is empty, and if it is, you want to set a variable to a default value of “test”

1

var something = (typeof somethingElse === "string" && somethingElse) || "test";

Here is the breakdown of how the above code works:

1. If the somethingElse value is both a string and is true (is not empty), then set the something variable equal to the somethingElse value. It is important to check that the somethingElse value typeof evaluates to string, because we want to make sure we are dealing with a string (and not an integer such as 0 which will evaluate to true).

2. If the somethingElse value is not a string and is false (is empty), then set the something variable equal to “test”.

Logical AND Operator

The JavaScript logical AND operator can also be used to set default values. Instead of returning the first true value, the logical AND operator returns the first false value it finds (looking from left to right). If there is no false value, then the last value is returned. Let’s look at the first code example again, but instead with the logical AND operator.

1

var something = somethingElse && "something";

If the somethingElse value evaluates to false, then the something variable gets set to the somethingElse value. If the somethingElse variable evaluates to true, then the something variable gets set to “something”. The logical AND operator uses the exact opposite logic of the logical OR operator.

JavaScript logical operators are an often misunderstood but powerful feature of the language. Start using them today!