During JSConf.eu, we released EmbedJS 0.2. That release was mainly about a fundamental architectural change: the move to the AMD pattern for our features. Let me explain why we decided to do this, why we think this is a big step forward and what this means for the user.

Modules

AMD stands for “Asynchronous Module Definition”. So, what are modules? I’ll quote the definition from the CommonJS Module specification, as it describes it very well:

This specification addresses how modules should be written in order to be interoperable among a class of module systems that can be both client and server side, secure or insecure, implemented today or supported by future systems with syntax extensions. These modules are offered privacy of their top scope, facility for importing singleton objects from other modules, and exporting their own API.

So, modules are isolated parts of code that live in their own scope and are kind of self-contained. Well, that is pretty much how we see the individual Features in EmbedJS – we made our feature implementations as small as possible and reduced dependencies as much as possible. Many of EmbedJS’ features are also browser-independent, so why not make it possible to use some of the tools in a non-browser environment?

(If you want to learn more on modules and why we need them, I recommend @briancavalier‘s presentation on modules.)

Features in EmbedJS

So far, I didn’t really explain what I mean with “Features”, so let me do another quote, this time from the Project Page:

EmbedJS uses the concept of features: Functionalities are split up into features, as fine-grained as possible, and each feature might have multiple implementations.

Our Features are kinda small and contain only few methods, sometimes even just one. The asyc-promise feature, for example, will get you Promises, and the transport-jsonp feature will get you a method for pull in data via jsonp – and that’s it.  If multiple methods are contained within one feature, this is because they are too closely related to each other to split them up, like the html-class feature, which contains the addClass, removeClass, toggleClass and hasClass methods.

AMD vs CommonJS Modules 1.1

Now that we knew modules were the way to go, there was another, quite important question to solve: There are two common patterns for modules, so which one do we want to apply? One pattern is described in the above mentioned CommonJS Wiki, the other pattern is described in the AMD wiki.

Well, there have been some blog posts lately that compare the pros and cons of each of them, so I don’t want to repeat all of this – but I’m hiving a similar tendency towards AMD. Besides this, there was another big reason to go with AMD: Remember, EmbedJS is based on the Dojo Toolkit, and it’s a Dojo Foundation Project – and we hope that the efforts that went into making EmbedJS might flow back into the Dojo Toolkit one day. And as the Dojo Toolkit uses the AMD approach, the decision was quickly made to do so as well.

Implications for EmbedJS

There are several huge benefits for EmbedJS in using the AMD approach. The most noteworthy surely is the ease-of-use for developers. In your code, when you find you want an EmbedJS method, you look up the feature name that provides this method, add it to the require statement and there you go. Man, easy.

A second important thing is that EmbedJS now plays really nice with AMD based projects. In fact, you could see EmbedJS now as a collection of small useful modules, that can be easily integrated – and also easily extended.

The third major benefit is that we can now get rid of all the custom tools we built around EmbedJS – you can load features with any AMD loader (though we use and recommend RequireJS) and build it with any AMD optimizer/builder (we recommend r.js).

Let’s have an extra word on

Building

It was always possible with EmbedJS to create a custom build that would contain only the features you wanted/needed in your project. But, you had to use our build tool that we created. And learning using Yet-Another-Build-Tool™ is always… well, let’s just say it would be cool to avoid it (and, not to forget, so is maintaining it). We did a lot to improve that, we created a GUI that allowed you to just “click together” the features you wanted, and we worked on a dynamic loader that would ease development. But still, the situation was far from ideal, and people just ended up going for our ready-made “kitchensink” builds that contained all of the features.

Now, we still provide those ready-made builds that contain only the implementations for a given platform (and are stripped of require/define calls), but I really hope that using the AMD approach and using an AMD optimizer to deploy will become the more adopted style.

Q: Cross-target? A: The Feature Plugin

One goal of EmbedJS is to allow for easy cross-device development. We got rid of run-time branching but instead went for an approach that held the different implementations for a given feature in separate files, so that one only has to deploy the actually needed code to a given device – and not all the alternate implementations, that sit useless in the device’s memory and never get used. We needed to achieve that with “in-house” means provided by the AMD approach. Lucky us, there’s the concept of loader-plugins, and so I created a feature-plugin for AMD loaders. The idea is simple yet effective: You create an implementation map that maps a feature name to an implementation, and if there are multiple implementations, you supply tests that tells the plugin which feature to use.

When you’re ready to deploy, you have two choices: I f you really don’t know on what target your code is going to end up, you can use the dynamic implementation map containing the tests for the optimizer, and you’ll get a build that contains all of the available implementations. Then, during runtime, the feature plugin will run the tests and load the specific implementation. But, if you do know what target your code will run on, you provide a specific implementation map that doesn’t contain tests but directly maps to the according implementations, and you will only have those in your built file.

Synopsis

AMD is exactly what we needed to make EmbedJS more what we want it to be – an easy to use JavaScript toolbox that is especially handy for cross-target scenarios such as cross-platform mobile development. So, please don’t hesitate and check it out on Github, read the project page and check out the examples!

Resources / Further Reading

• EmbedJS on GitHub
• EmbedJS Project Page
• EmbedJS API Docs
• AMD-Feature plugin
• AMD Wiki
• CommonJS Wiki

Update II: Ben Hockey proposed to do the whole thing without using the pub/sub system. I for one think its a good idea, but in case you want the topic version, I’ll leave the test page and add another one with the topic-less version. Thanks Ben!

Update III: Dojo 1.5 introduces robust Promises with dojo.deferred as Krys Zyp explains in this SitePen post.

—

One of the things/ideas/concepts that I really like about CommonJS is Promises.

Promises? A brief explanation from the CommonJS API:

Promises provide a well-defined interface for interacting with an object that represents the result of an action that is performed asynchronously, and may or may not be finished at any given point in time.

To hear more about Promises, I highly recommend these two posts.

That concept is not entirely new. The dojo toolkit has dojo.Deferred, which does a similar job. You create a Deferred, add (multiple) callbacks and error handlers to it, and when it fires off, all your handlers get called. But dojo.Deferred is pretty heavyweight. It’s loads of code. And it works with .addCallback() and .addErrback() methods – not with .then() methods, which provide maximum readability.

The goal

What I want to have is the follwing code running (with dojo):

asyncComputeTheAnswerToEverything().
    then(addTwo).
    then(printResult, onError);

(This is the example code from the proposed CommonJS Promise API)

And I want the execution to continue right after doSomethingAsnyc() – the async call should still be non-blocking. The .then() methods should recieve the results of the previous part of the chain, but still be non-blocking. Luckily, dojo provides a tool that allows us to achieve this: the publish/subscribe system.

Let’s do it

When we have unique topics for each promise made, we can subscribe the .then() method to the current topic in the chain, and publish the next topic when the data handlers are done computing. Within the then() method we need to check if the data we recieve is an error or not, to determine wich handler we need to call. The spec also demands a progress handler – if we wanted to implement that, we needed to add another topic, but I left that out.

We only need to kick off  the whole thing when we create the first promise, then the rest takes care for itself. Including the changes proposed by Micheil, what you have to do is pretty trivial and you don’t have to care about unique topics or the pub/sub system at all. The asyncComputeTheAnswerToEverything() function mentioned above would look like the following:

var asyncComputeTheAnswerToEverything = function(){
	var promise = new dojox.Promise();
	window.setTimeout(function(){ // some async operation
		var data = 42;
		promise.emit(data);
	},2000);
	return promise;
};

You create a Promise and store a reference to it. You return the promise and use the reference to it to kick off the chain when the data is there. Everything else runs on it’s own now.
Go to the test page or theand check the source – it contains the Promise code and the example functions. Open the console and run testSpec(); to start off the example code from the CommonJS API proposal.

Usage

As a namespace to put the Promise into I chose dojox – but choose whatever floats your boat. You can just drop the promise code somewhere into your code, or, if want to dojo.require("dojox.Promise") it, create a file named Promise.js that contains the code and place a dojo.provide("dojox.Promise"); as the first line in it. Save the file in the dojox directory and you’re done. (Well, to be honest, this violates the dojox naming convention, but if its just in your project, it’s ok and it will work.)

Any questions left? Feel free to leave a comment, @ me at twitter or drop me a line.

References / Files / More

• CommonJS Promise API Proposal
• Post by Kris Zyp @ SitePen blog about CommonJS
• Post on www.michaelharrison.ws about promises and more
• the test page (using topics and pub/sub)
• the test page (w/o topics, recommended)