The video is around 35 minutes long and there’s a slide deck available on Github that has clickable links and whatnot. Enjoy!

Slidedeck on Github

So, what are Custom Elements?

The W3C Introduction to Web Components defines Custom Elements as follows:

custom elements let authors define their own elements, including new presentation and API, that can be used in HTML documents

To translate that a little bit, consider that every HTML tag inherits from HTMLElement. Often in the W3C specs they’ll shorthand that and refer to items in the DOM as just “element” or “elements”. So what this is basically saying is that the custom elements spec lets you define new HTMLElements, which is kind of like saying you get to define new HTML tags. Technically it has always been possible to create your own HTML tags by shimming the browser, this is in fact how HTML5shim makes legacy browsers recognize HTML5 tags, but these tags weren’t really first class citizens. Which is to say, they could work as containers but if they needed to do anything else like spit out some custom DOM (think the <video> tag or an <input> field) then that wasn’t going to just magically happen. You’d have to write some custom javascript for that and somehow trigger it on the page.

Custom elements solves these issues by letting you define new markup which can then have a whole lifecycle of events, unique styles that are only scope to the element and additional (hidden) HTML markup.

Defining a new Custom Element

It’s probably easier to grok all of this if you just see some example code. Let’s look at the proposed markup for defining a new custom element.

1
2
3

<element extends="button" name="x-dropdown-button">
  …
</element>

The W3C definition of this is painfully muddled:

“The element element defines a custom element. It specifies the type of element it’s a refinement of using the extends attribute.”

To translate, you create an element tag, give it a unique identifier with name and specify which tag you’re extending. All custom elements must extend an existing tag and ideally it should be a tag that they closely relate to. In this case we’re creating a new custom element called x-dropdown-button which extends <button>. The docs suggest that if you don’t have a closely related tag that you should just extend <div> or <span> since (at a minimum) you know that your element is related to a container of some sort. As a fallback legacy browsers will then use the original tag and at least render something that is close to your intent. Maybe IE8 won’t get a x-dropdown-button but at least it’ll get a button.

Defining Custom Elements with Templates

If you recall I said that Custom Elements can define additional markup, similar to the <video> tag or an <input> field. This markup is specified through the use of a <template> tag. For example:

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

<element extends="button" name="x-dropdown-button">
  <template>
    <content></content>
    <div class="dropdown">
      <ul class="dropdown-menu">
        <li><a tabindex="-1" href="#">Action</a></li>
        <li><a tabindex="-1" href="#">Another action</a></li>
        <li><a tabindex="-1" href="#">Something else here</a></li>
      </ul>
    </div>
  </template>
</element>

If a custom element includes a template then it will be cloned into that element’s shadow DOM when the browser parses the tag. We haven’t talked much about shadow DOM yet but for now just think of it as markup that’s rendered on the page but not inspectable by the client.

Any content that would normally live inside of the extended tag ends up inside of the <content> tag in the template. For instance if we extended <button>Hello World</button> then “Hello World” would end up in the <content> tag.

In addition to markup the template can include styles that are scoped only to the custom element. Here’s the same example from above with the addition of a scoped style tag.

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

<element extends="button" name="x-dropdown-button">
  <template>
    <style scoped>
      .dropdown-menu {
        font-size: 12px;
        color: #CCC;
      }
    </style>
    <content></content>
    <div class="dropdown">
      <ul class="dropdown-menu">
        <li><a tabindex="-1" href="#">Action</a></li>
        <li><a tabindex="-1" href="#">Another action</a></li>
        <li><a tabindex="-1" href="#">Something else here</a></li>
      </ul>
    </div>
  </template>
</element>

The CSS used in the scoped style tag will not affect anything else on the page so you can have your own .dropdown-menu classes and they won’t conflict with the component. The component author can expose style hooks for the consumer to alter the appearance of the element through the use of the new pseudo attribute.

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

<element extends="button" name="x-dropdown-button">
  <template>
    <style scoped>
      .dropdown-menu {
        font-size: 12px;
        color: #CCC;
      }
    </style>
    <content></content>
    <div class="dropdown">
      <ul class="dropdown-menu">
        <li pseudo="x-dropdown-item"><a tabindex="-1" href="#">Action</a></li>
        <li pseudo="x-dropdown-item"><a tabindex="-1" href="#">Another action</a></li>
        <li pseudo="x-dropdown-item"><a tabindex="-1" href="#">Something else here</a></li>
      </ul>
    </div>
  </template>
</element>

elsewhere in a style.css you could say:

1
2
3
4

x-dropdown-button::x-dropdown-item {
  background-color: blue;
  height: 40px;
}

Using Custom Elements in Markup

Using a custom element is really straightforward thanks to the new is attribute. To use our new dropdown-button from above would just be:

1

<button is="x-dropdown-button">Hey I'm a dropdown!</button>

Easy, right?

You can also create custom element in script like so:

1
2

var btn = document.createElement("x-dropdown-button");
alert(btn.outerHTML); // will display '<button is="x-dropdown-button"></button>'

Also you can specify a constructor attribute and then use it to create new instances of your element.

1
2
3
4
5
6

<element extends="button" name="x-dropdown-button" constructor="DropdownButton">
  …
</element>

var btn = new DropdownButton();
document.body.appendChild(b);

Additionally you can add methods and properties to this constructor and call them later:

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

<element extends="button" name="x-dropdown-button" constructor="DropdownButton">
  <script>
  DropdownButton.prototype.open = function () {
    alert("Hey I'm open!");
  };
  DropdownButton.prototype.close = function () {
    alert("Aw dang I'm closed...");
  };
  </script>
</element>

…

<script>
    var btn = new DropdownButton();
    document.body.appendChild(btn);
    b.open(); // alerts "Hey I'm open!"
</script>

Constructors are attached to the window object, but if you don’t want to pollute that scope you can use the generatedConstructor property:

1
2
3
4
5
6
7
8

<element extends="table" name="x-chart">
  <script>
    // …
    var DropdownButton = this.generatedConstructor;
    DropdownButton.prototype.open = function() { /* … */ };
    // …
  </script>
</element>

Support

Unfortunately, at least to my knowledge, custom elements are not currently supported in any major browsers. However Chrome has added support for 2 of the 4 Web Components standards in their last two releases so I can’t help but think that custom elements are right around the corner. One thing I didn’t touch on very much in this post was shadow DOM which currently is supported in Chrome so tomorrow I’ll talk about that technology. Till then!

You should follow me on Twitter here.

So, what are Web Components?

Web Components are actually a group of standards which all fall under the same umbrella. The W3C does a good job of giving a high level overview in their Introduction to Web Components article. Here’s a quote from the introduction (emphasis is mine):

**

“The component model for the Web (also known as Web Components) consists of four pieces designed to be used together to let web application authors define widgets with a level of visual richness not possible with CSS alone, and ease of composition and reuse not possible with script libraries today.

These pieces are:

• templates, which define chunks of markup that are inert but can be activated for use later;

• decorators, which apply templates to let CSS affect rich visual and behavioral changes to documents;

• custom elements, which let authors define their own elements, including new presentation and API, that can be used in HTML documents; and

• shadow DOM which defines how presentation and behavior of decorators and custom elements fit together in the DOM tree.

Both decorators and custom elements are called components.”

– Introduction to Web Components

**

In summary there are two kinds of “components”: custom elements and decorators.

Custom elements let you define new HTMLElements, kind of like creating new tags, and decorators let you augment existing tags by injecting additional markup and styles via CSS selectors. Both custom elements and decorators leverage templates and shadow DOM to encapsulate their markup and styles.

To visualize this process think about the iframe that holds a Facebook Like button. The Like button encapsulates all of its markup and styles inside the iframe so it doesn’t mess up anything on your page. Unfortunately there are a few downsides to this approach. For starters you have to make an http request to load the content of the iframe, so you would never want to build your entire site out of iframe’d components. Also, the Like button doesn’t expose much of an API for you to change its appearance. While that’s not a huge deal for a Facebook Like button, it is if you’re using a more generic component like a slider or dropdown.

In an ideal world you could have a framework of components which hide their markup but expose an API to alter their appearance. Imagine if this:

1
2
3
4
5
6
7
8

<!-- Bootstrap Dropdown -->
<div class="dropdown">
  <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
    <li><a tabindex="-1" href="#">Action</a></li>
    <li><a tabindex="-1" href="#">Another action</a></li>
    <li><a tabindex="-1" href="#">Something else here</a></li>
  </ul>
</div>

was just this:

1

<div is="x-dropdown" class="fancy"></div>

and you’re most of the way there.

It’s (probably) not for apps. It’s for frameworks.

Unless you’re trying to write a UI Framework like the next Bootstrap, you can probably ignore the underpinnings of how Web Components are produced. At present we have the <video> tag which basically uses all of the technologies listed above. Do you care what its template and shadow DOM look like? Not really. You just want to say:

1

<video autoplay="true" controls src="path/to/video">

to spit out your awesome player. Think of the cognitive load that you could unburden yourself of if all UI Frameworks had the same abilities as <video>!

A page might look like this:

1
2
3
4
5
6
7
8

<nav is="x-bootstrap-navbar" sticky></nav>
<section class="container" role="main">
  <!-- mixing Foundation and Bootstrap! -->
  <div is="x-foundation-alert" class="success">Hey you succeeded!</div>
  <table is="x-datatables" ascending src="path/to/data.json"></table>
  <div is="x-bootstrap-pagination"></div>
</section>
<footer is="x-bootstrap-footer"></footer>

instead of hundreds of lines of markup rubber stamped over and over again. Even if you take the repetative markup and place it inside a template engine like handlebars you still can’t mix and match UI Frameworks like Bootstrap and Foundation without running into some serious risks. Web Components hope to solve both of these problems and open up a much more declarative authoring process.

Hopefully tomorrow I can dig into Custom Elements more and provide some concrete examples knitting all of these concepts together. Thanks for reading!

You should follow me on Twitter here.

Feature Detection

The <template> tag is currently only supported in Chrome 26 so you’ll need to either run these examples in Chrome Canary or (if it’s the future) a version of Chrome/FF/Whatever that supports <template>. Here’s a little feature dection script I stole from the HTML5Rocks article on <template>.

1
2
3
4
5
6
7
8
9

<h3 class="template-detection">Does your browser support &lt;template&gt;: </h3>

<script>
  function supportsTemplate() {
    return 'content' in document.createElement('template');
  }

  $('.template-detection').append(supportsTemplate().toString().toUpperCase());
</script>

Does your browser support <template>:

Our first template

There’s a great HTML5Rocks article on the subject of the template tag and I’m going to steal some of their examples. Let’s start by making a template for an image placeholder. We’re going to use the hhhhold image service which will load in a random image from ffffound.com. The markup for our template will be pretty simple:

1
2
3
4
5
6
7
8
9
10
11

<template id="hhhhold-template">
  <img src="" alt="random hhhhold image">
  <h3 class="title"></h3>
</template>

<script>
  var template = document.querySelector('#hhhhold-template');
  template.content.querySelector('img').src = 'http://hhhhold.com/350x200';
  template.content.querySelector('.title').textContent = 'Random image from hhhhold.com'
  document.body.appendChild(template.content.cloneNode(true));
</script>

Which would render something like this (remember to view in a browser that supports template):

If you’ve worked with client-side template libraries like underscore or handelbars the above should look familiar to you. Where underscore and handelbars take advantage of putting their templates inside of <script> tags and changing the type to something like text/x-handlebars-template, the <template> tag doesn’t need to because it’s actually part of the HTML5 spec. There are pros and cons to this approach.

Pros

• The content of the template is inert, scripts won’t run, images won’t load, audio won’t play, etc. This means you can have <img> and <script> tags whose src attributes haven’t been defined yet.
• The child nodes of a template are hidden from selectors like document.getElementById() and querySelector() so you won’t accidentally select them.
• You can place the <template> pretty much anywhere on the page and grab it later.

Cons

• You can’t precompile the template into a JS function like you can with other libraries like handlebars.
• You can’t preload the assets referenced by a template (images, sounds, css, js).
• You can’t nest templates inside of one another and have it automagically work. If a template contains another template you’ll have to activate the child, then activate the parent.
• Very little browser support (only Chrome 26 at the time of this writing).

Given that list of cons you might say “Well why would I ever bother with the <template> tag if something like handlebars gives me way more power?” That’s a great question because by itself the <template> tag isn’t so impressive. Its saving grace lies in the fact that it is intended to be used along side the Shadow DOM and Custom Elements to generate a Web Component.

Think back to the story about Bootstrap that I told at the beginning of this post. If all the markup for a Bootstrap button lived inside a template tag then we’d be one step closer to having a nice encapsulated widget. The next step would be to isolate the styles associated with the button. But I’ll save that for tomorrow’s post :)

You should follow me on Twitter here.

One of the most exciting projects is play, a combination iTunes remote and streaming music player. Play lets you broadcast music to everyone on your team and allows anyone in the chatroom to dictate what goes into the queue. Personally, I don’t use iTunes all that much, opting instead to use rdio for all my music needs. I figured, wouldn’t it be cool if hubot could do all the same stuff he does for play…but with rdio! So that’s what I set out to build.

A call for help!

Let me start by saying that this project is extremely rough. I didn’t intend to release it in this state but I figure the best (and fastest) way to improve it is by opening it up for others to use. The Backbone code is grizzly, the Express code is gnarly, and the things I’m doing with OAuth might be downright illegal (I’m an OAuth newb). But—and this is extremely important—it is super stable (much to my amazement). My team and I have run it for about 2 weeks and never once managed to crash it. Never needed a reboot or any kind of reset. So while the code might make your face melt, just think of it kinda like the walking dead. The unstoppable, bloodthirsty walking dead. You can hit it with a shovel, poke it in the eye, whatever! It’ll keep on truckin’

Grab the project

OK let’s get started. This is going to be a bulleted list kind of thing cuz I’m sleepy and there’s about a million steps. Brevity, people!

• Find the project here.
• git clone https://github.com/robdodson/hubot-rdio.git

Register with rdio

• Go here
• Register
• Get a consumer key and consumer secret
• Add the secret and key to app.js
• Go here
• Read the instructions
• Use rdio-python to generate a playback token (I’ve found this to be a little flaky. If it doesn’t work for you let me know).
• Add playback token to public/js/modules/rdio.js in the flashvars object.

Create your site on Heroku

• Follow the Heroku quickstart if you’ve never used Heroku before.
• Create a new site on Heroku with heroku create
• Copy the path to your new heroku site, it will look like: zen-jargon-1234.herokuapp.com
• Add the path to your site in app.js where it says HEROKU_URL
• Add just the domain to public/js/modules/rdio.js in the flashvars object.
• Push your site up to Heroku git push heroku master
• Scale the process heroku ps:scale web=1

Add the script to hubot

• Copy the hubot/scripts/rdio.coffee file into your hubot’s scripts folder. Normally you would just install the script from the catalog but I haven’t submitted yet because it’s still very rough.
• You’ll need to add 3 environment variables to your hubot
  • HUBOT_RDIO_URL
  • HUBOT_RDIO_TOKEN
  • HUBOT_RDIO_SECRET
• HUBOT_RDIO_URL is just the path address of your app on heroku (http://zen-jargon-1234.herokuapp.com)
• HUBOT_RDIO_TOKEN and HUBOT_RDIO_SECRET are the two parts of your OAuth token. I’ve left two console.logs for you in app.js at lines 341 and 342. If you go to your app on Heroku and login the console should spit out your OAuth token and secret. Add those to hubot and then remove the logs from app.js.
• Push everything to your hubot server

To test that everything is working open up your heroku app in Chrome and login. You should see an empty player. From Campfire, tell hubot: hubot play artist deadmau5. Wait a few seconds and the player should fire up. If not, check your terminal or your browser console to see if there are any errors.

Fire up Nicecast

• You’ll need to purchase Nicecast in order to stream, you can buy it here.
• Click on Source and choose Chrome or whatever browser you’re running.
• Depending on your machine you’ll probably want to click on Quality and turn it down. On my Macbook Air I have it set to the 3rd lowest tick.
• Click Start Broadcast and Nicecast will tell you it has to restart your browser (lame). Restart the browser, login again and instruct hubot to start playing some music.
• Click the Share tab
• Copy the link to the .m3u file.
• Pass around the .m3u link to your officemates. The easiest way to tune in is with iTunes. Just do File > Open Stream or Advanced > Open Stream and paste in the link.
• Dance

Holy shit that’s a lot of steps! Hopefully it all worked, if not please log an issue. kthnxbye

You should follow me on Twitter here.

Just to whet your appetite here’s a teaser shot of what we’re going to accomplish.

You’ll notice over on the right instead of your typical style.css: 7 it says modules.less: 7. That’s right, the developer tools are looking at the generated CSS and source mapping it back to the LESS files.

Clicking on the line number will actual dive into the LESS file where we can see the nesting, variables and mixins.

“Awesome!” you say, but how do we do it?

Well SASS has a debugging feature which will output media-queries above each style. It looks like this:

1
2
3
4

@media -sass-debug-info{filename{font-family:file\:\/\/\/Users\/Rob\/Desktop\/less-debug\/less\/base\.less}line{font-family:\000035}}
h1 {
  color: #999999;
}

This is known as a source map and it basically tells a debugging tool how to find its way from the generated output back to the correct source file. Thankfully the current version of Chrome (26, as of this writing) supports source maps for SASS and the current version of LESS (1.3.3, as of this writing) outputs source maps that look like SASS source maps to take advantage of this.

Important: If you use less.js to compile your LESS in the browser the techniques we’ll be covering will not work for you. Unfortunately less.js generates all its output in a big style block at the top of the page and that seems to confuse the dev tools. I wanted to point that out before you spend too much time setting things up.

Setting Up Chrome

Before we begin make sure you’re running a version of Chrome that’s 24 or above. At present Chrome Canary 28 does not work with this technique so you need to use regular Chrome 24 - 26. I’m pinging the Chrome dev team to see what’s up..

In the address bar type chrome://flags/ and hit enter. You should be transported to a magical place.

Here we’ll search for “Enable Developer Tools experiments”. When you find it click “Enable”. Then restart Chrome. Don’t just close the window, actually quit the program and restart it. Once it’s reopened fire up the developer tools and click the gear in the bottom right.

In the left hand sidebar click General. Scroll down to where it says Sources and click “Enable source maps”. Again in the sidebar click Experiments, scroll down and enable “Support for Sass”.

Now if you’re just working with SASS then all you have to do is make sure your SASS files generate the proper source maps and you’re done. Here’s a great article to walk you through the last couple of steps. But if you’re like me and your codebase is in LESS there is more work to be done. Onward!

Processors

There are a quite a few ways to convert your LESS into properly source mapped CSS code. You can use the lessc command line tool, a GUI such as CodeKit or have the server do it with something like less-middleware for connect/express. As I mentioned previously, you can also compile less on the client-side using less.js but unfortunately our debugging technique does not seem to work with that approach so you’ll need to use an alternative.

One quick warning, which I’ll emphasize again later, make sure you turn off all minification otherwise it will break our source maps!

lessc

If you’ve installed LESS using npm check that you’ve got the latest version.

1
2

$ lessc --version
lessc 1.3.3 (LESS Compiler) [JavaScript]

If your version is not 1.3.3 or greater you should run npm install -g less to update to the latest version.

To compile your less with baked in source maps pass the --line-numbers flag a value of mediaquery. For example:

1

lessc --line-numbers=mediaquery theme.less theme.css

Your generated LESS should now be inspectable in Chrome. Yay! Make sure you’re not running any kind of minification step further along in your build or it will break the source maps.

CodeKit

In CodeKit use the Debug Info in CSS dropdown and set it to Media Query at Top of CSS File. Make sure you set Output Style to Regular otherwise the minification will break our source maps.

After that you should be good to go :)

less-middleware

You might need to update your version of the middleware to whatever’s the latest, which looks like 0.1.9 as of this writing.

In your app you’ll need to add the dumpLineNumbers options to the middleware’s config.

1
2
3
4
5

app.use(lessMiddleware({
  src: __dirname + 'path/to/src',
  dest: __dirname + 'path/to/dest',
  dumpLineNumbers: 'mediaquery'
}));

After that you should be all set. Make sure any minification is turned off or it will screw up the source maps.

Warnings

The above techniques work for regular Chrome 24 - 26 but appear to be broken in Chrome Canary 28.

Minification of any kind seems to screw up the source maps so make sure your code is not minified or YUI compressed. Remember this is for debugging your code so it’s ok if it’s not minified.

One more thing, make sure before you send your code into production that you remember to turn off debugging otherwise you’ll be needlessly bloating your CSS files by quite a lot.

Conclusion

Personally I’ve found this trick extremely useful when working with large LESS codebases. I’ve seen some chatter that Stylus might also support this trick so if you have first-hand experience debugging Stylus with Chrome please drop me a comment. Otherwise I might do a follow up showing how to achieve similar results in that language.

Any questions or comments hit me up in the discussion area below.

– Rob

You should follow me on Twitter here.

Grab the Example Source

I’ve provided a simple grunt project at the link above. Take a look at the tasks folder and you should see two custom tasks, grunt-read-write-local.js and grunt-read-write-web.js. The former will read a local file and write its contents to a new file. The latter will request a webpage and write its contents to a static file.

There are two asynchronous APIs at play here (Node’s and Grunt’s) and it’s important to understand both.

In Node an async operation will usually provide a callback, such is the case for fs.readFile, or it will use an event dispatch, for instance in an http request we listen for the data event.

Grunt, on the other hand, uses a token or a kind of promise. You grab a reference to grunt’s done function and you wait till your node process has finished before calling it. If you take a look at grunt-read-write-local.js you can see that we first call the async method to let grunt know it needs to wait:

1

var done = this.async();

and as we finish writing our file we tell grunt that everything completed succesfully and it’s ok to carry on:

1
2
3
4
5
6
7

// Write the contents of the target file to the new location
fs.writeFile(pathToWrite, data, function (err) {
  if (err) throw err;
  console.log(pathToWrite + ' saved!');
  // Tell grunt the async task is complete
  done();
});

We do something similar in our grunt-read-write-web task but this time we work with Stream events.

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

// Tell grunt this task is asynchronous.
var done = this.async();

http.get(pathToRead, function(res) {
  // Pipe the data from the response stream to
  // a static file.
  res.pipe(fs.createWriteStream(pathToWrite));
  // Tell grunt the async task is complete
  res.on('end', function() {
    console.log(pathToWrite + ' saved!');
    done();
  });
}).on('error', function(e) {
  console.log("Got error: " + e.message);
  // Tell grunt the async task failed
  done(false);
});

The response returned by an http request implements the ReadableStream interface so it will emit data and end events. Node Streams have a great feature called pipes which handle the work of consuming data events and writing them to a destination. Sexy :) We still listen for the end event coming from our request so we can notify grunt that the process has finished and it can move on.

Grab the Example Source

If you want to test it all out make sure you run npm install first to pull down any dependencies. Then kick things off by running grunt. I’m thinking my next post might be all about Streams in node since they’re such a cool concept. Thanks to @maxogden and @dominictarr for their great posts on the subject of streams.

• Node Streams: How do they work? – Max Ogden
• High Level Style in JavaScript – Dominic Tarr

Any questions or comments hit me up in the discussion area below.

You should follow me on Twitter here.

Overview

Note: This tutorial assumes you’re already familiar with require.js and its configuration options. If not I recommend you checkout the docs before proceeding – Rob

Grab the Example Source

Typically when you work with require.js you’re building a single-page app. You usually have one main file which kicks off the app and pulls in dependencies as needed. When you’re developing you leave these dependencies in separate files but when you move to production you need to combine them. In a production setting you want to cut down the number of http requests to the bare minimum. To assist you, require.js provides a build tool called r.js which minifies and concatenates all of your dependencies into one file.

When working with a multi-page site compiling everything into one file is probably not a good idea because you have no guarantee that the user will visit every page. Thus the ideal scenario is one in which each page has its own main file that contains page-specific instructions and then a separate (hopefully cached) file which contains all of the commonly used js libs. For example if you have a page called About and a page called Contact you would have main-about.js and main-contact.js. Let’s say main-about.js and main-contact.js both require 'jquery' and 'underscore'. We wouldn’t want to compile jquery and underscore into each main file because then we’re creating unnecessary bloat. Instead we should create a common.js file which contains jquery and underscore and we’ll make sure that this file loads before any of our main files. Take a look at this diagram to help it sink in:

BEFORE OPTIMIZATION

1
2
3
4
5
6
7
8
9
10
11

About
----------------
js/vendor/jquery.js
js/vendor/underscore.js
js/app/main-about.js

Contact
----------------
js/vendor/jquery.js
js/vendor/underscore.js
js/app/main-contact.js

AFTER OPTIMIZATION

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

common.js
----------------
js/vendor/jquery.js
js/vendor/underscore.js

About
----------------
js/common.js
js/app/main-about.js

Contact
----------------
js/common.js
js/app/main-contact.js

By compiling all of those libaries into common.js we’re reducing the number of http requests per page. Also, after the first page has loaded, common.js should be available from the browser’s cache. Now that you get the general concept let’s take a look at an example.

Examples!

James Burke, author of require.js, has done a great job putting together some example projects which show how to effectively structure your project so it can be run through the r.js optimization tool when you’re ready to deploy. The one I typically refer to is the example-multipage-shim. There’s also an example-multipage but I tend to use the shim version because it seems like there’s always a few non-AMD scripts that end up in a project.

I’ve put together my own boilerplate which you guys are free to grab here. The rest of this post will walk through this boilerplate.

Learn you a boilerplate!

If you’ve worked with require.js on a single page site you’re probably used to defining a script tag that looks like this:

1
2
3

<!--This sets the baseUrl to the "scripts" directory, and
    loads a script that will have a module ID of 'main'-->
<script data-main="scripts/main.js" src="scripts/require.js"></script>

The data-main attribute is a convenience feature of require.js which sets require’s baseUrl property. You usually put some configuration options in the main file as well, for instance, if you’re loading a 3rd party library you might create a path so you can easily reference it. Since our boilerplate has different main files for each page we’re going to put that configuration data into our common.js file instead.

Hold on, I thought you said common.js was where we were going to compile all of our libraries?

Indeed you are correct astute reader. But since common.js is going to be loaded before any other required modules, why not put our configuration options in it as well? Here’s what the common.js file from our boilerplate looks like:

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

//The build will inline common dependencies into this file.

requirejs.config({
  baseUrl: './js',
  paths: {
    'jquery': 'vendor/require-jquery',
    'bootstrap': 'vendor/bootstrap'
  },
  shim: {
    'bootstrap': [ 'jquery' ]
  }
});

To smooth over possible weird module shimming situations I tend to use the combined jQuery-require.js bundle available here. Then in my paths option I map jquery to this file. The file will already be loaded on the page so it doesn’t actually request anything new, it just makes sure that $ is available in my modules.

You’ll also note that we’re using Twitter Bootstrap which is not AMD compliant out of the box so we have to shim it. In this case it depends on jquery so we list that as its only dependency and we’re good.

Aside from common.js you should probably take a look in the app/models directory. I’ve created two models which extend a base model in order to illustrate that the common.js file isn’t only for 3rd party code, it’s really for any code that’s going to be used over and over on your site. We’ll toss the basicModel into common.js during the build process.

Just hit build already…

OK ok. I can tell you’re ready to see some fireworks. Before we hit build I want to point out the options.js file. This is where we tell r.js which modules to compile and what each module should include or exclude.

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

module.exports = {
  appDir: 'www',
  baseUrl: 'js/',
  mainConfigFile: 'www/js/common.js',
  dir: 'www-release',
  modules: [
    {
      name: 'common',
      include: [
        'app/models/basicModel',
        'bootstrap'
      ],
      exclude: ['jquery']
    },

    {
      name: 'app/main-about',
      exclude: ['common', 'jquery']
    },

    {
      name: 'app/main-contact',
      exclude: ['common', 'jquery']
    }
  ]
};

You’ll note that first we put together our common module, then we tell the subsequent modules to exclude it. When you tell r.js to exclude a module it will find all of the nested dependencies in that module and exclude those as well. This is why we don’t need to tell about and contact to exclude bootstrap. It sees that bootstrap is already in common so it knows to exclude it.

If you haven’t already now is a good time to do an npm install. That should pull down all of the grunt dependencies. Speaking of grunt, you’ll need to install that as well if you’ve never used it npm install -g grunt. You might noticed in our gruntfile, grunt.js, we are using a number of tasks from the grunt-contrib library. Grunt-contrib is a great resource for and I encourage you to spend some time looking through all of the tasks that fall under its umbrella.

OK. Ready to rock. Just type grunt to build, or grunt.cmd if you’re on Windows (thanks @stevensacks). When you’re finished you should have a new folder called www-release. Take a look at the build.txt file to see where everything ended up.

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

css/bootstrap-responsive.css
----------------
css/bootstrap-responsive.css

css/bootstrap.css
----------------
css/bootstrap.css

css/style.css
----------------
css/style.css

js/common.js
----------------
js/common.js
js/app/models/basicModel.js
js/vendor/bootstrap.js

js/app/main-about.js
----------------
js/app/models/aboutModel.js
js/app/main-about.js

js/app/main-contact.js
----------------
js/app/models/contactModel.js
js/app/main-contact.js

If you take a look at the common.js file in www-release it should look like a big blob of minified code. That’s what we want to see. In this case it contains our basicModel, twitter bootstrap and our original configuration code. If you refer to about.html you can see how we control the load order:

1
2
3
4
5
6
7
8
9
10
11

<script src="./js/vendor/require-jquery.js"></script>
<script type="text/javascript">
// Load common code that includes config,
// then load the app logic for this page.
require(['./js/common'], function (common) {
  // ./js/common.js sets the baseUrl to be ./js/
  // You can ask for 'app/main-about' here instead
  // of './js/app/main-about'
  require(['app/main-about']);
});
</script>

First we bring in our combined require.js/jquery script. Then we load common.js and only after common.js is loaded do we load the page specific code in main-about. If you stick to this structure you should be able to layer your code so it’s easy to manage throughout your site.

Grab the Example Source

Hope you learned something new today. Feedback and suggestions always welcome in the comments below. Thanks!

You should follow me on Twitter here.

Command Line Fu!

Ok we’re going to pretty much do everything in Terminal so if that scares you now might be a good time to install MAMP instead ;)

Step 1: Enable httpd-vhosts.conf

OK first thing to do is navigate to your apache installation and open it up in your text editor of choice.

1
2

cd /etc/apache2
mate httpd.conf // you can use anything to open it up: vim, nano, etc.

You’re looking for the line:

1

#Include /private/etc/apache2/extra/httpd-vhosts.conf

Remove the # to uncomment it.

It might be wrapped in a block that looks like this:

1
2
3

<IfDefine WEBSHARING_ON>
...
</IfDefine>

Comment out those lines using #. We want our httpd-vhosts file to always be loaded. It should look kind of like this:

1
2
3
4
5
6
7
8
9

#<IfDefine WEBSHARING_ON>

... a bunch of stuff ...

Include /private/etc/apache2/extra/httpd-vhosts.conf

... a buncha other stuff ...

#</IfDefine>

Step 2: Enable PHP

In the httpd.conf file search for this line:

1

#LoadModule php5_module libexec/apache2/libphp5.so

Remove the # so PHP will be enabled.

Step 3: Add a vhost

OK let’s add our first vhost.

1

mate /etc/apache2/extra/httpd-vhosts.conf

This is your list of virtual hosts. There should be some example vhosts in here. Let’s create a new one:

1
2
3
4
5
6
7
8
9
10
11

<VirtualHost *:80>
    ServerName mysite.dev
    DocumentRoot "/Users/Rob/Developer/mysite"
    <Directory "/Users/Rob/Developer/mysite">
        DirectoryIndex index.php index.html
        AllowOverride all
        Options -MultiViews
        Order allow,deny
        Allow from all
    </Directory>
</VirtualHost>

There are a few other options you can use but I’m ignoring them for now. ServerName is what we’ll be typing into our browser address bar. DocumentRoot and Directory point to the location of the project files on our hard drive. Note that DirectoryIndex will check for index.php first and then check for index.html. If you want to just use .html you can remove the bit about index.php

Step 4: Add the vhost to your hosts file

Next let’s add our new host to our hosts file.

1

mate /etc/hosts

You should see a line that looks like this:

1

127.0.0.1 localhost

Add this line underneath so it looks like this:

1
2

127.0.0.1 localhost
127.0.0.1 mysite.dev

Step 5: Restart Apache

OK let’s reboot apache!

1

sudo apachectl restart

Step 6: Cross your fingers!

Head over to your browser and try it out. Make sure you use http:// at the beginning or it will just try to google your hostname.

1

http://mysite.dev

With any luck you should see your site! If everything worked go back to terminal and paste in this line:

1

sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist

That will tell apache to start whenever the system starts. A word of warning: Whenever you change anything in httpd.conf, httpd-vhosts.conf or your hosts file you’ll have to restart apache with sudo apachectl restart otherwise your changes won’t show up in the browser.

Good Luck!

Factories encapsulate and separate object creation from the rest of your code. In situations where the creation of an object can be complex or subject to change a factory can act as a nice buffer to help keep things tidy. Without proper planning Factories can lead to class explosions; as a result the pattern can be both a blessing and a curse depending on how it’s used.

Formal Definition

Factory Method

Define an interface for creating an object, but let subclasses decide which class to instantiate. Factory Method lets a class defer instantiation to subclasses.

Abstract Factory

Provide an interface for creating families of related or dependent objects without specifying their concrete classes.

Also Known As

• Virtual Constructor (Factory Method)
• Kit (Abstract Factory)

Simple Factory vs Factory Method vs Abstract Factory

The phrase “Factory Pattern” is rather overloaded so I’m going to give you a quick crash course in the three main types of factories.

A simple factory is an object which encapsulates the creation of another object, shielding that code from the rest of your application.

1

var user = UserFactory.createUser();

It’s common to parameterize simple factory methods to increase the number of products they’re able to return.

1
2

var admin = UserFactory.createUser('admin');
var customer = UserFactory.createUser('customer');

The actual implementaiton of createUser might look something like this:

1
2
3
4
5
6
7

UserFactory.createUser = function(type) {
    if (type == 'admin') {
        return new Admin();
    } else if (type == 'customer') {
        return new Customer();
    }
};

Typically the return value from a factory is known as the Product. In the case of our UserFactory there are two Products: Admin and Customer. It’s important for these products to maintain a consistent interface so the client can use any product from our factory without needing to do elaborate checks to see if a particular method exists.

Factory Method

While the Simple Factory is a nice start and good for many situations it’s possible to extend this even further through the use of the Factory Method pattern.

The Factory Method Pattern defines an interface
for creating an object, but lets subclasses decide which
class to instantiate. Factory Method lets a class defer
instantiation to subclasses.

Factory Method defines one method, createThing for instance, which is overriden by subclasses who decide what to return. The Factories and Products must conform to interfaces for clients to be able to use them.

In Head First Design Patterns a Factory Method pattern is used to allow a PizzaStore to define many subclasses such as ChicagoPizzaStore, CaliforniaPizzaStore, NewYorkPizzaStore. Each subclass overrides createPizza and returns its own particular style of pizza (ie: a ChicagoPizza or a CaliforniaPizza). The main take away is that there is only one method, createPizza, that does anything. By subclassing and overriding this method we can offer aditional flexibility beyond what’s possible with the Simple Factory.

Abstract Factory

Unlike the Factory Method pattern, Abstract Factory defines any number of methods which return Products.

The Abstract Factory Pattern provides an interface
for creating families of related or dependent objects
without specifying their concrete classes.

Again in Head First Design Patterns, an Abstract Factory pattern is used to provide different Pizza ingredients depending on the type of Pizza. For instance, a ChicagoPizza would be given a ChicagoPizzaIngredients factory with methods like createDough, createSauce, createCheese, etc. A CaliforniaPizzaIngredients factory would also implement createDough, createSauce and createCheese. In this way the factories would be interchangeable.

The authors are keen to point out that the methods of the Abstract Factory (createDough, createSauce, etc) look very similar to the Factory Method (createPizza). One way of thinking about things is that an Abstract Factory can be composed of Factory Methods.

The Factory Method in JavaScript

Since I’ve already shown a basic Simple Factory let’s take a stab at doing the Factory Method in JS. We’ll continue with the PizzaStore theme since I’ve already spelled out how each pattern applies to it. We’re going to do this without the use of the new keyword and instead we’ll take advantage of JavaScript’s prototypes. How you ask?

The very awesome Object.create

ECMAScript 5 introduced a new method of the Object prototype called create. You can read up on it in full detail on MDN. In a nutshell it lets you pass in a prototype and receive a new object which points to that prototype. Object.create is actually a simple Factory Method! Here’s an example:

1
2

var firstPizzaStore = Object.create(PizzaStore);
firstPizzaStore.createPizza(); // returns 'Generic pizza created'

One very cool feature of Object.create is that it accepts a properties object which is then mixed in to the returned object. The code can get a little verbose since it uses defineProperty syntax so instead let’s steal a function from Yehuda Katz which lets us do something very similar.

1
2
3
4
5
6
7
8
9

var fromPrototype = function(prototype, object) {
    var newObject = Object.create(prototype);
    for (var prop in object) {
        if (object.hasOwnProperty(prop)) {
            newObject[prop] = object[prop];
        }
    }
  return newObject;
};

Now that we have that we can continue on our way. One quick caveat though! Some browsers *cough* IE *cough* don’t support Object.create so we need to shim it. Thankfully MDN has got our back:

1
2
3
4
5
6
7
8
9
10
11

// Polyfill
if (!Object.create) {
    Object.create = function (o) {
        if (arguments.length > 1) {
            throw new Error('Object.create implementation only accepts the first parameter.');
        }
        function F() {}
        F.prototype = o;
        return new F();
    };
}

Drop that into your page and you should be able to use Object.create like we are above. Note that the shim does not support the second properties object. For our purposes that’s ok but definitely keep it in mind if you’re thinking of using it.

Back to the Factory Method

With Object.create and fromPrototype in hand we’re ready to tackle our first Factory Method.

Let’s start by creating a PizzaStore:

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

// Define the Pizza product
var Pizza = {
    description: 'Plain Generic Pizza'
};

// And the basic PizzaStore
var PizzaStore = {
    createPizza: function(type) {
        if (type == 'cheese') {
            return fromPrototype(Pizza, {
                description: 'Cheesy, Generic Pizza'
            });
        } else if (type == 'veggie') {
            return fromPrototype(Pizza, {
                description: 'Veggie, Generic Pizza'
            });
        }
    }
};

Easy enough. Ok now let’s extend the PizzaStore so we have two variations: ChicagoPizzaStore and CaliforniaPizzaStore.

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

var ChicagoPizzaStore = fromPrototype(PizzaStore, {
    createPizza: function(type) {
        if (type == 'cheese') {
            return fromPrototype(Pizza, {
                description: 'Cheesy, Deep-dish Chicago Pizza'
            });
        } else if (type == 'veggie') {
            return fromPrototype(Pizza, {
                description: 'Veggie, Deep-dish Chicago Pizza'
            });
        }
    }
});

var CaliforniaPizzaStore = fromPrototype(PizzaStore, {
    createPizza: function(type) {
        if (type == 'cheese') {
            return fromPrototype(Pizza, {
                description: 'Cheesy, Tasty California Pizza'
            });
        } else if (type == 'veggie') {
            return fromPrototype(Pizza, {
                description: 'Veggie, Tasty California Pizza'
            });
        }
    }
});

// Elsewhere in our app...
var chicagoStore = Object.create(ChicagoPizzaStore);
var pizza = chicagoStore.createPizza('veggie');
console.log(pizza.description); // returns 'Veggie, Deep-dish Chicago Pizza'

The Abstract Factory in JavaScript

Since we have a variety of pizza styles we might also have a variety of ingredients. Let’s see if we can accomodate all the different kinds.

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

var Ingredients = {
    createDough: function() {
        return 'generic dough';
    },
    createSauce: function() {
        return 'generic sauce';
    },
    createCrust: function() {
        return 'generic crust';
    }
};

Ingredients.createChicagoStyle = function() {
    return fromPrototype(Ingredients, {
        createDough: function() {
            return 'thick, heavy dough';
        },
        createSauce: function() {
            return 'rich marinara';
        },
        createCrust: function() {
            return 'deep-dish';
        }
    });
};

Ingredients.createCaliforniaStyle = function() {
    return fromPrototype(Ingredients, {
        createDough: function() {
            return 'light, fluffy dough';
        },
        createSauce: function() {
            return 'tangy red sauce';
        },
        createCrust: function() {
            return 'thin and crispy';
        }
    });
};

In the above example Ingredients is our Abstract Factory. We know that for every different kind of pizza we’ll need different ingredients and therefore a new Factory Method. We also know that we have different styles of pizza so we’ll need Chicago style ingredients and California style ingredients. When a client wishes to grab some ingredients for a particular kind of pizza they just say:

1
2

var californiaIngredients = Ingredients.createCaliforniaStyle();
californiaIngredients.createCrust(); // returns 'thin and crispy';

The object that is returned by the call createCaliforniaStyle is the concrete implementation of our Abstract Ingredients object. In other words, if Ingredients is the Abstract Factory, then the object returned by createCaliforniaStyle could also be thought of as a CaliforniaIngredients object. It is a subclass of Ingredients if you want to think of it that way. The returned object extends Ingredients and overrides its Factory Methods with its own methods. In so doing we provide a lot of additional flexibility to our app. If we want to add a Hawaiian style ingredients we just add a createHawaiianStyle method.

If you recall from the previous article on Decorators we talked about the Open-Closed Principle which states that “classes should be open for extension but closed for modification.” You’ll notice that adding a createHawaiianStyle method would actually violate this principle so it should be noted that when using an Abstract Factory approach you’ll probably have to reopen the class/object a few times to modify it. Not ideal but depending on your use case this might not be such big deal and you might prefer the flexibility and organization that the factory offers.

Grab the Example Source

Related Patterns

• Template Methods: Factory Methods are usually called within Template Methods.
• Singleton: A concrete factory is often a singleton.

Gamma, Erich; Helm, Richard; Johnson, Ralph; Vlissides, John (1994-10-31). Design Patterns: Elements of Reusable Object-Oriented Software. Pearson Education (USA).

Table of Contents

Thanks for reading! If you have questions or feedback please leave a comment below. - Rob

You should follow me on Twitter here.

I want to go through some of what was said so I can refine my examples and also clear up any confusion.

That prototype example sucked!

OK let me start off by apologizing for even including that second example (the Sale decorators). It was meant as a kind of fun academic exercise but I tried to make it clear that I wasn’t suggesting anyone actually implement it. Redditor gizmo490 pointed out that for the pattern to actually work you would have to overwrite all the methods of the Sale object or risk working in the wrong context. You can see our full discussion here.

So I’ll just say if you’re considering that second example: Stop. Just don’t do it. It is way too much code.

We don’t necessarily need all those objects

Another Redditor, Draders, pointed out that the decorator objects aren’t really necessary since we can just put functions directly into the decoratorsList.

1
2
3

// This is presuming that `add` pushes a function into the
// list of decorators
validator.add('zipcode', validateZipCodeFunction);

If you want validateZipCodeFunction to be reusable you’ll have to define it somewhere and attaching it to the Validator object is probably a fine choice. In the end it’s a bit less code so definitely something to think about.

Finally, the power of CLOSURES!

Finally, and this is really the reason why I wanted to write this update, Redditor emehrkay pointed out that my examples are basically ignoring the power of JS functions and closures. In his quick and dirty example he shows how to achieve a similar goal with much less code:

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

function test(arg){
    return arg + arg;
}

function testDecorator(fn, args){
    var arg = args[0] * 2;

    return fn(arg);
}

function decorate(dec, fn, args){
    return function(){
        return dec(fn, args);
    }
}

x = decorate(testDecorator, test, [2])();
console.log(x)

So here’s my attempt to recreate the Sale example but using more of emehrkay’s approach:

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

function Sale(price) {
    this.price = price || 100;
}

Sale.prototype.getPrice = function() {
    return this.price;
};

Sale.prototype.setPrice = function(price) {
    this.price = price;
};

function usd(fn, context) {
    var price = fn.call(context);
    return "$" + price;
}

function decorate(dec, fn, context) {
    return function() {
        return dec.call(context, fn, context);
    };
}

// Let's run it!
var sale = new Sale(50);

// Decorate our getPrice method. We'll just add
// some extra dollar signs to the output.
sale.getPrice = decorate(usd, sale.getPrice, sale);
sale.getPrice = decorate(usd, sale.getPrice, sale);
sale.getPrice = decorate(usd, sale.getPrice, sale);
console.log(sale.getPrice()); // output: $$$50

// Test to make sure other methods can still
// access the price in the correct context
sale.setPrice(100);
console.log(sale.getPrice()); // output: $$$100

Since we’re kind of mixing OO and functional style here the one caveat is that you have to pass the context to your decorators so when they call getPrice they know which instance they’re referring to. So the code is a little funky but still interesting and if anyone can think of a way to write it cleaner I’m all ears!

Grab the Example Source

Thanks for reading! If you have questions or feedback please leave a comment below. - Rob

You should follow me on Twitter here.

Update: Part 2 has been posted!

A Decorator is an object which adds functionality to another object dynamically. It can be used to enhance the behavior of an object without requiring the author to reopen its class. While Decorators might feel a little weird to implement in static languages they’re extremely simple in JavaScript due to the ease with which JS passes around functions and handles dynamic types.

Formal Definition

Attach additional responsibilities to an object dynamically. Decorators provide a flexible alternative to subclassing for extending functionality.

Also Known As

• Wrapper

When to use it

• When you’d like to add responsibilities to individual objects dynamically (i.e. without subclassing/inheritence).

• When you’d like to be able to remove the functionality at a later time. An undecorate method, for instance.

• When extension by subclassing would be unmanageable or lead to a class explosion. For instance, if a Vehicle class is subclassed by 30 other vehicle objects with only minor differences.

Pros and Cons

• Pro: More flexible than inheritance.

• Pro: Avoids feature-laden classes high up in the hierarchy.

• Con: A decorator and its component aren’t identical.

• Con: Lots of little objects.

A Brief Explanation

The Decorator pattern is very similar to one we’ve addressed earlier, called Strategy. The differences between the two can be subtle but usually a decorator enhances, layers upon or “decorates” the object or method it’s wrapping. In contrast, a strategy will replace a method’s algorithm completely.

The primary benefit of the Decorator pattern is that you can take a rather vanilla object and wrap it in more advanced behaviors. For instance a view which renders a plain window can have decorators to add different backgrounds, scroll bars, borders, etc. The underlying code, or guts, of the window object remains the same while the decorators provide a new skin.

Decorators are not limited to visual components. In fact much of the java.io package is composed of Decorators which add additional functionality such as buffering file streams and adding line numbers. A similar application to JavaScript might involve decorating I/O in Node.js. For instance, incoming data might need to be converted to ASCII and then compressed in some way. It might not always need to be converted to ASCII and it might not always need to be compressed. In this scenario we can apply or remove I/O decorators at runtime changing the behavior of our object instead of writing a big class with a bunch of cross-cutting concerns.

Enough Talk! COOOOODE!!!

Ok so let’s do an example. We’re going to create a Validator class which looks at the contents of a form and adds error messages to an array if anything in the form is not correct. We want our Validator to be really simple so it’ll just have two methods: validate and decorate. As the name implies validate will tell our validator to compare the form against its internal rules. We’ll use decorate to specify those rules. The decorate method will accept a String, such as ‘hasAge’ or ‘hasZipCode’ which corresponds to an actual function. We’ll collect these functions in a list and compare the contents of the form to each item in the list.

We’ll start with the constructor and decorate method:

1
2
3
4
5
6
7
8

function Validator () {
  this.errors = [];
  this.decoratorsList = [];
}

Validator.prototype.decorate = function(name) {
  this.decoratorsList.push(name);
};

We’ll collect any error messages in the errors array. We could write a method like validator.hasErrors() to check the length and contents of the array but for now I’ll leave that unspecified. Just know that if we do come across an error we’ll toss it in there.

The decoratorsList will hold all of our decorator functions. This is not how the Gang of Four does things, or how you will see the Decorator pattern presented in languages like Java or C++, but that’s because they’re using static languages which don’t do well with functions being passed around. In our case since JavaScript functions are objects we can pass our decorators into a collection to have them called sequentially. This is the easier approach recommended by Stoyan Stefanov in JavaScript Patterns. A little later I’ll show you the “hard” approach and you can decide which you prefer ;)

OK moving on… Let’s define some decorator functions. We’ll add an object to our constructor called decorators and we’ll attach our functions to it.

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

Validator.decorators = {};

Validator.decorators.hasName = {
  validate: function(form) {
      // Code to verify presence of name...

      // If no name found...
      this.errors.push('no name!');
  }
};

Validator.decorators.hasAge = {
  validate: function(form) {
      // Code to verify presence of age...

      // If no age found...
      this.errors.push('no age!');
  }
};

Validator.decorators.hasZipCode = {
  validate: function(form) {
      // Code to verify presence of zip code...

      // If no zip found...
      this.errors.push('no zip!');
  }
};

Each decorator is actually an object which implements the same interface as our Validator object. When we have all of our decorators added to our decoratorsList we’ll be able to loop through and call validate on each one.

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

Validator.prototype.validate = function(form) {
  var i,
      max,
      name;

  this.form = form;

  max = this.decoratorsList.length;
  for (i = 0; i < max; i++) {
      name = this.decoratorsList[i];
      Validator.decorators[name].validate.call(this, form);
  };
};

At last we come to the validate method. It first receives an object containing all of our form data. Next it prepares to loop through our collection of decorators. We use the name of the decorator object as a key and call its validate method, passing in this for our context and also the form object as an argument. This way all of the validators will execute in the context of our Validator instance and they should all have access to the form data.

Let’s try it out!

1
2
3
4
5
6

var validator = new Validator();
validator.decorate('hasName');
validator.decorate('hasAge');
validator.decorate('hasZipCode');
validator.validate({}); // we'll just use a blank object in place of real form data
console.log(validator.errors);

We aren’t really doing any validation at this point so our console.log at the end should output an array with 3 error messages, one from each of the validator decorators. But there you go, you’ve now got a fully decorated validate function. What was once rather vanilla can have all sorts of new and interesting validations applied to it!

What if my Decorators need additional arguments?

The above example gets us started decorating but it leaves some room for improvement. For starters what if we want to pass additional arguments to our validation functions? Let’s revamp this thing just a bit so we can get really fancy…

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
49
50
51
52

function Validator () {
  this.errors = [];
  this.decoratorsList = [];
}

Validator.prototype.decorate = function(name, args) {
  this.decoratorsList.push({ name: name, args: args });
};

Validator.decorators = {};

Validator.decorators.hasName = {
  validate: function(form, args) {
      // Code to verify presence of name...

      this.errors.push('no name!');
  }
};

Validator.decorators.hasAge = {
  validate: function(form, args) {
      // Code to verify presence of age...

      this.errors.push('no age!');
  }
};

Validator.decorators.hasZipCode = {
  validate: function(form, args) {
      // Code to verify presence of zip code...

      this.errors.push('no zip!');
  }
};

Validator.prototype.validate = function(form) {
  var i,
      max,
      temp,
      name,
      args;

  this.form = form;

  max = this.decoratorsList.length;
  for (i = 0; i < max; i++) {
      temp = this.decoratorsList[i];
      name = temp.name;
      args = temp.args;
      Validator.decorators[name].validate.call(this, form, args);
  };
};

This time we are passing an optional hash to our decorate method which is stored along with its corresponding decorator object. If you’ve ever used validators in Rails this should feel similar. Time to see it in action!

1
2
3
4
5
6

var validator = new Validator();
validator.decorate('hasName', { length: 5 });
validator.decorate('hasAge', { minimum: 21 });
validator.decorate('hasZipCode');
validator.validate({}); // some form data. in this case just an anonymous object
console.log(validator.errors);

Time to do things the hard way…

I promised I would show you the more classical example of Decorator and since I am a man of my word I guess you can see it… I would not recommend using this approach because it can require overwriting all of your methods to make sure you’re always in the correct context. Still, as a kind of academic observation it’s a cool example and demonstrates how JS can emulate other languages. I’m taking this code almost verbatim from JavaScript Patterns so full credit goes to Stoyan for coming up with it.

In this example we’re going to format a Sale price so that it can work for both U.S. and Canadian stores. This means applying different tax rates and outputting the text with different currency symbols.

1
2
3
4
5
6
7

function Sale(price) {
  this.price = price || 100;
}

Sale.prototype.getPrice = function() {
  return this.price;
};

Things start off very similar to our last example. Instead of validate the method we’re interested in this time is getPrice. If you’ve been paying attention you’ll notice that in our previous example validate was rather complex. Yet getPrice is so…simple. Hmm…

Let’s move on to the decorators.

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

Sale.decorators = {};

Sale.decorators.fedtax = {
  getPrice: function() {
      var price = this._super.getPrice();
      price += price * 5 / 100;
      return price;
  }
};

Sale.decorators.quebec = {
  getPrice: function() {
      var price = this._super.getPrice();
      price += price * 7.5 / 100;
      return price;
  }
};

Sale.decorators.usd = { // U.S. dollars
  getPrice: function() {
      return "$" + this._super.getPrice().toFixed(2);
  }
};

Sale.decorators.cdn = { // Canadian dollars
  getPrice: function() {
      return "CDN$" + this._super.getPrice().toFixed(2);
  }
};

This may look similar to the last example but take note of the use of _super. The _super property is actually a reference to a parent class instance. We’ll use this reference to travel up the chain of decorators, performing an operation and returning the price at each stop.

This leads us to the decorate method:

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

Sale.prototype.decorate = function (decorator) {
  var F = function () {},
  overrides = this.constructor.decorators[decorator],
  i,
  newobj;

  // Create prototype chain
  F.prototype = this;
  newobj = new F();
  newobj._super = F.prototype;

  // Mixin properties/methods of our decorator
  // Overriding the ones from our prototype
  for (i in overrides) {
      if (overrides.hasOwnProperty(i)) {
          newobj[i] = overrides[i];
      }
  }

  return newobj;
}

If you’re unfamiliar with JavaScript prototypes this can look a little daunting. We’re using a pattern that JavaScript Patterns refers to as Rented Constructor in order to essentially take a snapshot of our current object, store it in _super and then mixin new decorator methods. Let’s see it in action to clarify things a bit better.

1
2
3
4

var sale = new Sale(50);
sale = sale.decorate('fedtax');
sale = sale.decorate('cdn');
console.log(sale.getPrice()); // outputs $CDN52.50

You’ll notice that each time we call decorate we have to re-assign the sale variable to a new instance. Each new instance has a reference to the previous sale object. When we finally call getPrice it walks up this chain of instances and calls getPrice on each stop along the way. In the end we have something which is functionally identical to our first example but potentially a lot harder to understand. In other words, stick with the first approach! Also be sure to see my update which discusses this example a bit more and points out a few more of its flaws. Again, it’s a neat idea to mess around with but there are much easier ways.

The Open-Closed Principle

I’m going to go off on a quick tangent here because of something I saw in Head First Design Patterns. There’s a common heuristic in software design known as the Open-Closed Principle which states that “classes should be open for extension but closed for modification.” Let’s explore this concept with our Sale object.

Consider the following bit of code:

1
2
3
4
5
6
7

function Sale(price) {
  this.price = price || 100;
}

Sale.prototype.getPrice = function() {
  return this.price;
};

You should be able to look at this snippet of code and say that it’s almost certainly bug free. Now let’s pretend we aren’t using decorators and our boss comes to us and says we need to add US and Canadian taxes and currency symbols.

“Hm…I guess that means I’ll need to pass those parameters into the constructor and then write some booleans or something to check if we’re Canadian or US… Or maybe I’ll put them all in a hash… Or…”

Regardless of what we choose to do, if it involves opening up the class then there’s a chance that we’ll compromise our previous snippet of code. The more times we do this the more we increase the likelihood that we’ll introduce a bug which might go uncaught for a long time. Eventually what started off as extremely simple, bug-free code, can turn into a rat’s nest.

So, where possible, try to avoid reopening classes and find ways to extend their functionality. This can mean simply subclassing the parent, or using one of the many design patterns we’ll be covering.

Grab the Example Source

Related Patterns

• Adapter: A decorator is different from an adapter in that a decorator only changes an object’s responsibilities, not its interface; an adapter will give an object a completely new interface.

• Composite: A decorator can be viewed as a degenerate composite with only one component. However, a decorator adds additional responsibilities—it isn’t intended for object aggregation.

• Strategy: A decorator lets you change the skin of an object; a strategy lets you change the guts. These are two alternative ways of changing an object.

Gamma, Erich; Helm, Richard; Johnson, Ralph; Vlissides, John (1994-10-31). Design Patterns: Elements of Reusable Object-Oriented Software. Pearson Education (USA).

Table of Contents

Thanks for reading! If you have questions or feedback please leave a comment below. Also be sure to checkout Part 2 which covers even more ways to do decorators! - Rob

You should follow me on Twitter here.

Observer is one of the most popular design patterns and chances are you’re probably already using it. If you’ve ever written an event listener with addEventListener or used one of jQuery’s many versions: on, delegate, live, click, etc… then you should already be comfortable with the concept. In a nutshell the Observer pattern allows a Subject to publish updates to a group of Observers. The Subject maintains a list of Observers and provides an interface for objects to register as Observers. Otherwise the Subject doesn’t care who or what is listening to it. In this way the Subject is decoupled from the Observers allowing easy replacement of one Observer for another or even one Subject for another so long as it maintains the same lexicon of events/notifications.

Formal Definition

Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified and updated automatically.

Also Known As

• Dependents
• Publish-Subscribe

When to use it

• When the state or actions of one object depends on the state or actions of another object.

• When changing one object necessitates a change to an unknown number of other objects.

• When an object should be able to notify other objects of changes without knowing anything about these other objects.

Pros and Cons

• Pro: Very loose coupling between objects.

• Pro: The ability to broadcast changes and updates.

• Con: Potentially unexpected updates and sequencing issues.

The Many Faces of Observer

Because of its popularity the Observer pattern often goes by a few different names. The primary objects are the Subject and the Observers though sometimes they are referred to as Publisher/Subscribers or Event Dispatcher/Listeners. Although you can definitely split hairs regarding the actual implementation of this pattern, in essence we’re usually talking about the same thing. When the Subject’s state changes it sends out notifications, unaware of who its Observers are. The Observers, in turn, perform some action in response to this update.

I’m going to heavily quote (*cough* plagiarize *cough*) the wonderful JavaScript Patterns by Stoyan Stefanov to sum up all the parts of an Observer/Pub-Sub relationship:

“The publisher object needs to have a property subscribers that is an array storing all subscribers. The act of subscription is merely adding to this array. When an event occurs, the publisher loops through the list of subscribers and notifies them. The notification means calling a method of the subscriber object. Therefore, when subscribing, the subscriber provides one of its methods to the publisher’s subscribe() method.

The publisher can also provide unsubscribe(), which means removing from the array of subscribers. The last important method of the publisher is publish(), which will call the subscribers’ methods.”

Here is Stoyan’s Pub/Sub implementation. Note that the on function accepts a context argument which allows you to set the handler’s context and in turn, the value of this. We’ll discuss this a bit more later.

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

var publisher = {
  subscribers: {
      any: [] // event type: subscribers
  },
  on: function(type, fn, context) {
      type = type || 'any';
      fn = typeof fn === 'function' ? fn : context[fn];
      if (typeof this.subscribers[type] === "undefined") {
          this.subscribers[type] = [];
      }
      this.subscribers[type].push({ fn: fn, context: context || this });
  },
  remove: function(type, fn, context) {
      this.visitSubscribers('unsubscribe', type, fn, context);
  },
  fire: function(type, publication) {
      this.visitSubscribers('publish', type, publication);
  },
  visitSubscribers: function(action, type, arg, context) {
      var pubtype = type || 'any',
          subscribers = this.subscribers[pubtype],
          i,
          max = subscribers ? subscribers.length : 0;

      for (i = 0; i < max; i += 1) {
          if (action === 'publish') {
              // Call our observers, passing along arguments
               subscribers[i].fn.call(subscribers[i].context, arg);
          } else {
              if (subscribers[i].fn === arg && subscribers[i].context === context) {
                  subscribers.splice(i, 1);
              }
          }
      }
  }
};

In practice using the publisher might look something like this:

1
2
3
4
5
6
7
8
9
10

function handleLogin() {
  console.log('we haz a users!');
}

publisher.subscribe('login.complete', handleLogin);

// ... .
// Elaborate user login process...

publisher.publish('login.complete');

Mind the Context

In JavaScript the keyword this in a function will refer to the context in which the function was called. Sometimes functions are global and sometimes they’re part of a larger Object. Here’s a brief example to clarify:

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

var foobar = {
  doWork: function() {
      console.log('doing some work...');
      console.log(this);
  }
}

foobar.doWork(); // `this` will refer to foobar

var doWorkClone = foobar.doWork;
doWorkClone(); // `this` will refer to window

var workClones = [];
workClones.push(foobar.doWork);
workClones[0](); // `this` will refer to the workClones Array

The first time we call doWork we do so in the context of the foobar object: foobar.doWork(). As a result the term this inside of the doWork method will refer to foobar.

The second time we call doWork we do so by referencing the method through a variable. We’re calling doWork using that variable’s context. But the variable is a global variable, it’s just hanging out on the page! As a result this will refer to window.

In the third example we’re stuffing doWork into an array, then referencing it by index, then calling it. In this context doWork is scoped to the workClones Array, since it’s also an Object. A little confusing I know.

So why do I care?

Well if you go back and look at the publisher example you’ll notice that we pass a function reference to be called whenever the Subject sends out a notification. In our case it looks like this: publisher.subscribe('login.complete', handleLogin); If handleLogin needs to use this we might be in a world of hurt because publisher is going to call handleLogin using itself as the value of this. Uh oh!

Preserving Context in Observer

JavaScript’s context switching can be really bizarre if you’ve never had to manage it before. To mitigate this problem we have a handful of useful strategies.

The first one, which is demonstrated in the publisher, is to pass along a context whenever we subscribe a function. This is the third argument to our publisher’s on method.

1
2
3
4
5
6
7
8

on: function(type, fn, context) {
      type = type || 'any';
      fn = typeof fn === 'function' ? fn : context[fn];
      if (typeof this.subscribers[type] === "undefined") {
          this.subscribers[type] = [];
      }
      this.subscribers[type].push({ fn: fn, context: context || this });
  },

By storing the context we ensure that when it’s time to call our function, we can do so in the correct context with the correct value for this. We do this through the use of JavaScript’s call method which allows us to define in which context a function should execute.

1

subscribers[i].fn.call(subscribers[i].context, arg);

This can be a very powerful feature especially for utility functions. Checkout the MDN docs for a deeper understanding of call and its cousin apply.

But what if you’re not using our publisher example? What if you’re using a slightly more popular library like jQuery to manage your events? Maybe you have some code that looks like this:

1
2
3
4
5
6

// Substitute `on` for `click` or `delegate` or `live` or
// whatever else you're using :)

$('.login-button').on('click', function() {
  // tell the app the user is trying to log in!
});

Well in this case we might have to use a different approach. As anyone who’s used jQuery knows, the value of this in our handler function is going to refer to the DOM element that jQuery selected. Sometimes that’s really useful but other times, like in this case, it isn’t going to do us much good.

Closures

Closures are a powerful feature of ECMAScript and they’re especially useful when passing around functions. The best definition I’ve found for a closure comes from this article:

The simple explanation of a Closure is that ECMAScript allows inner functions; function definitions and function expressions that are inside the function bodies of other functions. And that those inner functions are allowed access to all of the local variables, parameters and declared inner functions within their outer function(s).

So let’s see that in action.

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

var loginController = {
  init: function() {
      var self = this;

      $('.login-button').on('click', function() {
          self.handleLogin(); // use self as a stand in for `this` 
      });
  },
  handleLogin: function() {
      console.log('handling login!');
  }
}

In the above example the var self exists in a kind of interesting limbo: it is part of loginController's init method and also part of the function registered as the on('click') handler. As a result, when the function is executed, self is still in the context of the loginController object and thus logs handling login!

Awesome! We’ve solved the issue of preserving scope, right? Well, yes but it’s not our only option. Many people (myself included) find it annoying to sprinkle var self = this all over their app. To mitigate things we also have Function.bind.

Bindings

The addition of Function.bind in ECMAScript 5 allows us to specify in which context a function should be called, in other words, binding that function (and the value of this) to a particular context. Let’s see it in action:

1
2
3
4
5
6
7
8
9

var widget = {
  name: 'My Awesome Widget!',
  sayName: function() {
      console.log(this.name);
  }
};

var nameFunc = widget.sayName.bind(widget);
nameFunc(); // outputs: 'My Awesome Widget!'

Calling Function.bind will actually create a closure preserving whatever scope we’ve passed in. It returns a clone of our original function but this time it is bound to a particular context. In the above example it’s bound to the widget object. While it’s cleaner than our original closure example we’re still in a dilemma because we want sayName to ALWAYS be called in the context of widget. How about something like this instead: widget.sayName = widget.sayName.bind(widget); Hey, now we’re talking! By overwriting our function and binding it to our widget object we’ve gotten very close to how classical languages like Java and Actionscript handle scope! This means it’s easy to both subscribe and unsubscribe our method, safe in the knowledge that it will always use the proper scope. If you’re lazy (like me) take some time to research Underscore.js which provides both bind and bindAll functions to ease the process of connecting your methods to their parent objects.

I’ll save you the speech on treating JavaScript like other languages except to say anytime you’re writing code to make one language act like another you should obviously research whether that’s the best course of action or not. In my experience I’ve found that binding observers can make writing event listeners much cleaner but your mileage may vary and comments/feedback are always welcome :D

Also if you want to read more on Function.bind you can do so here on MDN.

The Push and Pull Model

Typically when you create a Subject/Observer relationship you’ll want the Subject to send along additional information during its event dispatch. The amount of information can vary widely. Sometimes you’ll want to send a lot of information and other times you’ll want the observers to receive the event and then query for more information. When you’re sending a lot of information it’s referred to as the push model and when the Observers should query for more information it’s referred to as the pull model. The Gang of Four describe the differences between the two:

The pull model emphasizes the subject’s ignorance of its observers, whereas the push model assumes subjects know something about their observers’ needs. The push model might make observers less reusable, because Subject classes make assumptions about Observer classes that might not always be true. On the other hand, the pull model may be inefficient, because Observer classes must ascertain what changed without help from the Subject.

There’s no right or wrong approach but it is good to understand the differences between the two.

PubSub and Observer mixins

If you want a quick, easy to use event dispatcher the PubSubJS library does a wonderful job of providing an easy to use event dispatcher. It also includes a jQuery plugin variant if that’s more your style. If you’re looking for something a little less global and a bit more OO checkout this utility function from JavaScript Patterns which mixes-in the publisher to other objects.

1
2
3
4
5
6
7
8
9
10
11

function makePublisher(o) {
  var i;   
  for (i in publisher) {     
      if (publisher.hasOwnProperty(i) && typeof publisher[i] === "function") {
          o[i] = publisher[i];     
      }   
  }
  o.subscribers = {
      any: []
  };
}

Grab the Example Source

Related Patterns

• Promise: A Promise is an observable token given from one object to another. Promises wrap an operation and notify their observers when the operation either succeeds or fails.

Gamma, Erich; Helm, Richard; Johnson, Ralph; Vlissides, John (1994-10-31). Design Patterns: Elements of Reusable Object-Oriented Software. Pearson Education (USA).

Table of Contents

Thanks for reading! If you have questions or feedback please leave a comment below. - Rob

You should follow me on Twitter here.

If you’re coming from Ruby or Java you probably think of an Iterator as an object which gives you a consistent interface for traversing a collection of some kind. If you’re coming from JavaScript or Actionscript you probably just think of an iterator as the i value in a for loop. The term has mixed meanings but in this case we’re refering to the former, an object which gives us a consistent interface for iterating over a collection of some kind. If you’ve never used them before that might seem kind of silly. “If I need to loop over something I’m just going to loop over it!” For many use cases that’s totally fine. Where Iterator objects are useful is in situations where you might need to loop in an async fashion (stopping and restarting) or if you want to preclude an object from knowing too much about the inner workings of a collection.

Formal Definition

Provide a way to access the elements of an aggregate object sequentially without exposing its underlying representation.

Also Known As

• Cursor

Example Time

The code for an Iterator should be pretty easy to grok if you’ve worked with loops before. Here is a simple example which returns an Iterator for looping over an Array by every third value.

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

var iterator = (function() {

  var index = 0,
      data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
      length = data.length;

  return {
      next: function() {
          var element;
          if (!this.hasNext()) {
              return null;
          }
          element = data[index];
          index += 3;
          return element;
      },
      hasNext: function() {
          return index < length;
      },
      rewind: function() {
          index = 0;
          return data[index];
      },
      current: function() {
          return data[index];
      }
  }

}());

Our iterator has a handful of useful operations including next, hasNext, rewind and current.

next will return the next value and advance the index by 3.

hasNext will check to see if calling next will actually return an item. Good for indicating when we’ve reached the end of a collection.

rewind will reset the index to zero so we can loop over the collection again.

current will return the current item at the index without advancing the index.

Let’s put these into play to see how it works:

1
2
3
4
5
6

while(iterator.hasNext()) {
  console.log(iterator.next());
}

iterator.rewind();
console.log(iterator.current());

If we ran the above we’d see the following output in the console.

1
2
3
4
5

1
4
7
10
1

Since the iterator is mainting its own state if we need to stop iteration at any point we just don’t call next. Using exclusively for loops we’d have to check against a flag of some kind, store our current position and then rebuild the loop starting from that point.

Not just for Arrays

As I mentioned before the Iterator gives us a consistent interface for traversing a collection, which means it can iterate over any object. Calendar Dates, Linked Lists, Node Graphs, whatever! Here’s an example of an iterator that traverses a simple Hash.

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

var iterator = (function() {
  var data = { foo: 'foo', bar: 'bar', baz: 'baz' },
      keys = Object.keys(data),
      index = 0,
      length = keys.length;

  return {
      next: function() {
          var element;
          if (!this.hasNext()) {
              return null;
          }
          element = data[keys[index]];
          index++;
          return element;
      },
      hasNext: function() {
          return index < length;
      },
      rewind: function() {
          index = 0;
          return data[keys[index]];
      },
      current: function() {
          return data[keys[index]];
      }
  }
}());

Notice how the interface is identical to our previous Iterator? That’s one of the key aspects to this pattern: Regardless of the type of collection, we can define a consistent interface to loop through it. It also means that the client doesn’t need to know anything about the implementation of the actual collection, and by wrapping it in a closure we can prevent the client from editing the collection. Personally I like the idea of certain services handing out iterators rather than a wholesale dump of all the data. As always use whichever tool is appropriate for the context.

One quick note regarding Hashes. Previous versions of the ECMA spec did not require that Hash keys be kept in order. While most modern browsers do keep them in order there are some funky inconsistencies. For instance, if you write out the following Hash:

1

var hash = { 'foo': 'foo', 'bar': 'bar', '1': 'hello', '2': 'world' };

Google Chrome will swap the order of the keys such that they appear like this:

1

{ '1': 'hello', '2': 'world', 'foo': 'foo', 'bar': 'bar' };

There are some interesting discussions on StackOverflow which cover this topic but it’s a bit outside the scope of this article. If you’re interested you can find them here:

• How to keep an Javascript object/array ordered while also maintaining key lookups?
• Javascript data structure for fast lookup and ordered looping?

JavaScript 1.7

Although not widely supported yet, JavaScript 1.7 includes a built in Iterator object which can be used to wrap an Array or Hash with just a single line of code.

1
2
3
4

<script type="application/javascript;version=1.7">
  var lang = { name: 'JavaScript', birthYear: 1995 };
  var it = Iterator(lang);
</script>

The above script block will not work in Chrome but it should work in the latest version of Firefox. Note the type attribute of the script tag which instructs the interpreter to handle the code as JS 1.7.

For some further reading on the topic checkout the MDN article which covers Iterators in JavaScript 1.7

Grab the Example Source

Related Patterns

• Composite: Iterators are often applied to recursive structures such as Composites.
• Factory Method: Polymorphic iterators rely on factory methods to instantiate the appropriate Iterator subclass.
• Memento: Often used in conjunction with the Iterator pattern. An iterator can use a memento to capture the state of an iteration. The iterator stores the memento internally.

Gamma, Erich; Helm, Richard; Johnson, Ralph; Vlissides, John (1994-10-31). Design Patterns: Elements of Reusable Object-Oriented Software. Pearson Education (USA).

Table of Contents

Thanks for reading! If you have questions or feedback please leave a comment below. - Rob

You should follow me on Twitter here.

Ah yes the Singleton, a pattern whose name lives in infamy. For the uninitiated a little explanation is in order. A Singleton is an object which can only be instantiated one time. Repeated calls to its constructor return the same instance and in this way one can ensure that they don’t accidentally create, say, two Users in a single User application. Doesn’t sound too bad, right? Well, if you’re responsible then it arguably is OK but there are many caveats. Before I get into those though, let’s throw in the formal definition a la the Gang of Four.

Formal Definition

Ensure a class only has one instance, and provide a global point of access to it.

The icky bits

So I’m sure some of you are already a little anxious because I used the phrase “global point of access” and rightfully you should be. In OO software design global variables and objects are often frowned upon. They break encapsulation and more often than not cause more harm than good. You don’t want the far flung bits of your app to be able to reach all the way up to the very top and fiddle around with stuff. When that starts to happen, and other objects also rely on those global variables, then any piece of code, anywhere in the project can change something which can in turn break a totally unrelated bit of functionality. Debugging becomes a nightmare because you’re constantly moving from deeply nested object graphs up to the global scope and then back down again. I one time worked on a major application which I inherited from another developer. It was so riddled with Singletons that any change became a sisyphean ordeal of unintended consiquences and time lost debugging. Needless to say I want to put this warning front and center or else the programming gods would surely smite me.

Well I’m done! Fuck this shit…

OK before you start running for the hills I want to point out the ways in which Singletons can be useful and then you can make up your mind if they’re right for you.

Let’s start with the most obvious one: You’re probably already using Singletons!

Ever written any code that looks like this?

1
2
3
4
5
6
7

var user = {
  firstName: 'John',
  lastName: 'Doe',
  sayName: function() {
      return this.firstName + ' ' + this.lastName;
  }
};

Yep, that’s a Singleton. Once you create an object literal in JavaScript you’ve reserved a little piece of memory and no other object will ever be just like that one. Now, depending on the scope you might have only created a local variable but if that user is sitting outside a function then it’s globally available to anyone who wants to fiddle with it. I guess the most famous Singleton probably looks like this: $. To put it another way, ever notice how you can use jQuery anywhere in your app after you’ve included it on the page…? Boom! Singleton!

mind blown … face off …

OK, So they have their uses I guess

Yes as much as some are probably loathe to admit it, Singletons are quite useful in JavaScript. And as jQuery demonstrates their primary use is to namespace your code. While other languages like Java or C# have namespaces built in, JavaScript has to emulate them using simple objects.

Consider the following scenario: You have a series of functions hanging out on the page that you frequently use in your program.

1
2
3
4
5
6
7
8
9
10
11

function login() {
  // do some login shtuffs
}

function logout() {
  // do some logout shtuffs
}

function addToCart() {
  // blah, blah blah...
}

A few things are going on here…

1. Our functions are polluting the global space. Since they are just floating around on the page they have to attach to something. With no explicitely declared parent object they get hooked on to the globally available window object.

2. They’re in danger of being overwritten If we were to accidentally define another global addToCart function or if we brought in a library whose author did the same, it would overwrite the original leading to a really gnarly debugging situation.

Let’s revise this by creating one (and only one) global object which our code can branch off of.

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

var NAMESPACE = {};

NAMESPACE.login = function() {
  // do some login shtuffs
}

NAMESPACE.logout = function() {
  // do some logout shtuffs
}

NAMESPACE.addToCart = function() {
  // blah, blah blah...
}

Now so long as no one creates an object which also has the name NAMESPACE our code should be safe. From here we can do all sorts of things. We can nest more object literals or we can create constructor functions:

1
2
3
4
5
6
7
8
9
10
11

var NAMESPACE = {};

NAMESPACE.Widget = function(foo, bar) {
  // Some awesome widget code
}

NAMESPACE.Widget.prototype.doSomethingAwesome = function() {
  // do something awesome!!!
}

var myWidget = new NAMESPACE.Widget('hello', 'world');

Take a look at the Three.js library which relies heavily on this pattern to structure its code.

But I like constructors!

OK so maybe object literals aren’t your thing. That’s understandable so let me show you a few other ways of writing Singletons.

These first few come from Stoyan Stefanov’s excellent book JavaScript Patterns.

Singleton with a cached static property

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

function User() {
  // do we have an existing instance?
  if (typeof User.instance === 'object') {
      return User.instance;
  }
  
  // proceed as normal
  this.firstName = 'John';
  this.lastName = 'Doe';
  
  // cache
  User.instance = this;
  
  // implicit return
  // return this;
}

The cached static property is publicly available which adds a little danger (someone could say Universe.instance = foo) but this version is very straightforward and doesn’t require closures and funky prototype work. If you’re lazy this might be a good approach.

Singleton with a closure

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

function User() {
  // the cached instance
  var instance;

  // rewrite the constructor
  User = function() {
      return instance;
  };

  // carry over the prototype
  User.prototype = this;

  // the instance
  instance = new User();

  // reset the constructor pointer
  instance.constructor = User;

  // all the functionality
  instance.firstName = 'John';
  instance.lastName = 'Doe';

  return instance;
}

This version takes a bit of fiddling to get the prototype to work as expected because we rewrite the constructor. The upshot is that instance is now private (being contained within the closure).

Singleton with a self executing function

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

var User;
(function() {
  var instance;

  User = function User() {
      if (instance) {
          return instance;
      }

      instance = this;

      // all the functionality
      this.firstName = 'John';
      this.lastName = 'Doe';
  };
}());

By wrapping the instance variable in a self executing function we make it private. This version doesn’t require any prototype or constructor reassignment but it may potentially confuse people who aren’t comfortable with self executing functions.

Addy Osmani also defines a Singleton pattern in his book Essential JavaScript Design Patterns.

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
49
50

var mySingleton = (function () {

  // Instance stores a reference to the Singleton
  var instance;

  function init() {

    // Singleton

    // Private methods and variables
    function privateMethod(){
        console.log( "I am private" );
    }

    var privateVariable = "Im also private";

    return {

      // Public methods and variables
      publicMethod: function () {
        console.log( "The public can see me!" );
      },

      publicProperty: "I am also public"
    };

  };

  return {

    // Get the Singleton instance if one exists
    // or create one if it doesn't
    getInstance: function () {

      if ( !instance ) {
        instance = init();
      }

      return instance;
    }

  };

})();

// Usage:

var singleA = mySingleton.getInstance();
var singleB = mySingleton.getInstance();
console.log( singleA === singleB ); // true

This much more elaborate example allows us to define both private and public methods of our Singleton object at the cost of being a bit more complex than all the others.

As Addy is quick to point out:

Whilst the Singleton has valid uses, often when we find ourselves needing it in JavaScript it’s a sign that we may need to re-evaluate our design.

They’re often an indication that modules in a system are either tightly coupled or that logic is overly spread across multiple parts of a codebase. Singletons can be more difficult to test due to issues ranging from hidden dependencies, the difficulty in creating multiple instances, difficulty in stubbing dependencies and so on.

Definitely read his full article on the subject since it contains a handful of links to interesting side topics.

Grab the Example Source

Related Patterns

Many patterns can be implemented using the Singleton pattern. See Abstract Factory, Builder, and Prototype.

Gamma, Erich; Helm, Richard; Johnson, Ralph; Vlissides, John (1994-10-31). Design Patterns: Elements of Reusable Object-Oriented Software. Pearson Education (USA).

Table of Contents

Thanks for reading! If you have questions or feedback please leave a comment below. - Rob

You should follow me on Twitter here.

The Strategy pattern is one of my personal favorites and you’ve probably seen or used it in some fashion without even knowing it. Its primary purpose is to help you separate the parts of an object which are subject to change from the rest of the static bits. Using Strategy objects versus subclasses can often result in much more flexible code since you’re creating a suite of easily swappable algorithms.

Formal Definition

Define a family of algorithms, encapsulate each one, and make them interchangeable. Strategy lets the algorithm vary independently from clients that use it.

Also Known As

• Policy

Contrived Example Time!

Let’s say you’re making a game and you have a Character class. This game has all sorts of different terrain types so your character can run through open fields, walk slowly through swamps or swim under the ocean. Since you don’t know what kind of other terrains the game designer is going to think up you decide that it would be a bad idea to give each character run, walk, and swim methods. After all, what if suddenly the character needs to fly or crawl? What if they’re wounded and they need to limp? This situation could potentially get out of hand very fast…

There’s a good chance you’ve seen or written code like this before:

1
2
3
4
5
6
7
8
9

function move() {
  if (state === 'walking') {
      // do some walk animation
  } else if (state === 'running') {
      // do some running animation
  } else if (state === 'swimming') {
      // do some swimming animation
  }
}

When you see a big conditional like that or a switch statement it’s time to stop and wonder if there’s a better way. For instance if we need to subclass our Character we’re going to have to override that big conditional. What if we only want to replace the swimming bit? We’ll have to copy and paste the code from the super class for walking and running and then write new code specifically for swimming. And of course if walking and running ever change we’re totally screwed.

We need a Strategy to deal with this

Ok so we know that our character is going to be a real contortionist and need to run and jump and crab-walk all over the place. What if we took the code that made her run and we put it in its own object? How about we just define a Class for movements and we do this for all the different kinds of motion? Then when we need to move our Character we’ll just tell it to defer to one of these Movement objects.

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

var Movement = function(func) {
  this.move = func;
};

Movement.prototype.execute = function() {
  this.move();
};

var running = new Movement(function() {
  console.log("Hey I'm running!");
});

var walking = new Movement(function() {
  console.log("Just walking along...");
});