AMD Refactor Notes

This page tracks the details of our AMD refactor related to issue 29.

Source

AMD work is being done in the amd branch. Currently, only the op engine unit tests work in this branch.

Conversion approach

• 1:1 conversion without optimization to start.

  • Optimize singletons later
  • Optimize op engine IT functions as functions + raw JS objects later

• Modules that define single classes will be CamelCased and expose just the class.

• Modules that are singletons will be lowercase modules.

• Port our existing JS unit tests along the way for sanity.

Dependency issues

Summarizing what was first posted on the issue related to the refactor.

1. We are currently dependent on Dojo 1.5+, particularly dojo.Deferred.
2. CometD requires the use of Dojo or jQuery currently. To work with other toolkits, it needs bindings to those toolkits.
3. Other than Dojo, we have two major non-AMD dependencies, OpenAjax Hub and CometD, that must load before we load (app responsibility) or that we must load (somehow).
4. We require a JSON encode / decoder as does CometD.

Dependency decisions

1. We accept limiting our support to modern browsers that provide JSON encode and decode natively. See http://caniuse.com/#search=JSON.

2. We will attempt to create a plain-JS binding for CometD that relies on the native browser container alone.

   1. Can we / do we want to use the stock cometd.js build if we do this? Answer: Yes.
   2. Can we put this binding AMD format, even if cometd.js is not? (Look at the jquery.cometd.js binding for guidance.) Answer: Yes.

3. Until OpenAjax Hub and CometD are AMD compliant, we will attempt to load these dependencies ourselves somehow.

   1. Should we wrap these at dependency download and build time so they are AMD compliant? Answer: This works. Why not? Only downside is people will HAVE to use our setup scripts and can't use pre-existing downloads of cometd / OpenAjax. Seems like a small price to pay.
   2. Should we use a global cowebConfig object that points us to the location of cometd.js and OpenAjax.js? We have other options that would fit in here too. Answer: Prefer wrapping.
   3. Can all AMD loaders load non-module format JS files? RequireJS can. If that's a unique feature of RequireJS or not standardized, then the app writer will just have to include script tags for our dependencies directly. Answer: Does not matter if we wrap at download or build time.

4. We should start discussions with the CometD folks and OpenAjax folks about their plans for adopting AMD.

5. We will include a copy of dojo.Deferred in OpenCoweb to use in compliance with the CommonJS Promises/A proposal.

6. We will look at the possibility of toolkit bindings just like CometD so that applications using a toolkit already can force our framework to use the necessary functions in that toolkit instead of our own implementations.

   1. This is a nice-to-have that will help reduce some bloat caused by duplication of functionality in our own code and whatever toolkit the app is using.
   2. We don't think it's a necessity during the first-pass of the refactor.

Discussions

Post to RequireJS list about variable dependencies

Need to research if James's aliasing technique is viable with other loaders.

How do we make it easy for people to produce optimized JS builds?

1. CometD, Dojo Toolkit, Require.JS, JQuery, etc. all post an optimize build on each stable release. This is the norm.
2. Our ideal build would bake our OpenAjax and CometD dependencies into the single JS file. This is not normal.
3. A build with only coweb code in it is not possible if we require AMD-wrapped OpenAjax and CometD libs as we currently do.

What do we do with the BusyDialog component. It's strongly Dojo dependent and introduces additional headaches like:

1. What version of Dojo to support?
2. Is it an AMD module itself that uses the old Dojo loader to load deps? (Ugly.)
3. How to configure Dojo to find its non-AMD resources (template, translation)?
4. Style sheets to make it appear properly.
5. It's built for desktop. What about mobile?

Options include:

1. Remove it from the repo. Move it to an external repo.
2. Remove it from the www/libs/coweb part of the repo. Move it to www/libs/dojo and keep it dojo specific.
3. Create a more reusable version of it that isn't Dojo or desktop specific to indicate busy progress.