Orion/Library Independence

For Orion 2.0, we are investigating client side implementations that do not depend on a particular javascript library, and instead use raw HTML5/CSS3 constructs where possible.

At the DOM manipulation level, this is made largely possible by our adoption of IE10 for Orion 2.0, since it includes many HTML5 features that were not available in in IE9. Since we no longer need to rely on shims and other workarounds for missing features, we should be able to use the browser native API for things like events, CSS class manipulation, etc.

For UI components, or widgets, that we need in the UI, we will look at existing small, library-independent implementations of the functionality, as well as considering our own implementation. Any custom implementations should be as small/simplified as possible, satisfying Orion use cases but not starting out with the intention to be an independently consumable component.

This document outlines what would be needed to reduce or eliminate our dependence on dojo in favor of these other approaches.

Advantages of library independence

• Orion consumers wish to make their own choices regarding JavaScript libraries and UI plugins, and do not wish to bring in other libraries (such as dojo) when they depend on a different library.
• Orion consumers who use the same libraries as us (such as dojo) wish to switch versions at their own pace.
• Size reduction and performance improvements as we eliminate library methods that are already available in the browser, as well as eliminating JavaScript and CSS code that we no longer need.
• Simplified learning curve for consumers
  • theming doesn't require understanding of a separate library/widget level theming mechanism
  • we don't force consumers to learn multiple conventions/life cycles in the UI (dijit lifecycle vs. Orion, dijit layout vs. raw CSS, etc.).

Existing dependencies and proposed replacements

The remainder of this document categorizes our dependencies and gives status on the replacement candidates.

DOM manipulation

We extensively use the dojo.* utility methods. Many of these are now available in our supported browser set. The following list shows method usage and replacement. A small library (orion/webui/littlelib) implements a few methods. Examples referring to "lib" are using this module.

• dojo.byId

document.getElementById(id);
lib.node(id);  // when you aren't sure if you have an id or node, useful for inbound API calls

• dojo.query

element.querySelector(selector, parentNode);
element.querySelectorAll(selector, parentNode);
lib.$(selector, parentNode);  // one node
lib.$$(selector, parentNode);  // node list
lib.$$array(selector, parentNode); // array of nodes

• dojo.addClass, removeClass, toggleClass

element.classList.add('class');  // one at a time
element.classList.remove('class');
element.classList.contains('class');
element.classList.toggle('class'); 

• dojo.connect/disconnect

element.addEventListener/removeEventListener

• dojo.style

element.style.visibility = "hidden";
element.style.left = "1px";

• dojo.place

For node placement, use the addChild/appendChild/insertBefore DOM equivalents.  
If placing HTML, use innerHTML, parse HTML with a document fragment, or convert to dynamic 
DOM node creation when security is an issue. 

(See bug bug 392469 for security discussion).

• dojo.create

var element = document.createElement("a");  // good old dom API
element.tabIndex = 0;  // set the properties directly if they were used in the create api
element.setAttribute("aria-label", "foo");  // set attributes when there is not a browser standard property

• dojo.position

lib.bounds

• dojo.empty

lib.empty

• dojo.attr, removeAttr

element.setAttribute();
element.getAttribute();

General JavaScript utilities

• dojo.hitch

this.myFunction.bind(this);  // when referring to a function by name
var self = this;
window.setTimeout(function() { self.update(); }, 0);  // bind "this" to a variable when creating an anonymous function

• dojo.keys constants

lib.KEY.SPACE;

hash and hash change

• dojo.hash

// window.location.hash contains the # whereas dojo.hash() did not
window.addEventListener("hashchange", function() { window.location.hash; }, false);  

i18n utilities

• dojo.string substitution

i18nUtil.formatMessage("this has ${0} parameters ${1}", "one", "two");
// note that it's not an array like dojo.string.substitute

• date and time formatting

someDate.toLocaleString();
someNumber.toLocaleString();

If you need more control over the default toLocaleString() see the ECMAScript Spec but check browser support, it may not be implemented everywhere yet. However, it should gracefully degrade to the default formatting.

Deferred / Promise support

• dojo.Deferred

use orion.Deferred.
Note that you should use resolve, not callback.  And reject, not errback.

• dojo.DeferredList

   Deferred.all(promises, function(error) {return error; }).then(function(resultsArray) {});
   // note that you MUST have an error handler argument or else the promises will not be processed after an error is found.
   // the results array has either the result or whatever you returned in the error function.  

dijit Menu support

• bug 393813
  • Command service should replace dijit implementation
    • Replace DropDown, MenuItem, PopupMenu with a simplified dropdown widget
    • Replace dijit Tooltip with simplified tooltip
  • Replace orion menu extensions
    • orion.UserMenu functionality supported by new dropdown + styling

dijit Dialogs

See Programming an Orion Dialog for detailed information about Orion dialogs and templates.

• replace dijit.Dialogs with simple div-based equivalent
  • client templating of content
  • i18n variable substitution in templates
  • conversion of all existing Orion dijit dialogs (approximately 20)
• small js add-ons for special features
  • modal support
  • lightweight, automatic dismissal

dijit Layout support

• Replace common page use of dijit BorderContainer, ContentPane, Splitter
  • switch to CSS based layout
  • implement small, lightweight splitter
• Settings page uses custom dijit layouts
• Some pages (compare, search replace) use internal dijit layout such as BorderContainer

Orion custom dijits

• domain-specific widgets don't need a framework, replace with application level code
  • plugin related widgets (plugin entry, plugin list, service carousel)
  • site editor
• settings layout widgets replaced with CSS/splitter (SettingsContainer, SplitSelectionLayout)
• settings custom field widgets (TextField, Select, Toggles, Buttoms) replaced with HTML5 dom elements
• settings section moved to existing Orion section support

move unused dijit-based experiments out of orion repository

• plugin maker

Removing dijit and dojo from a page

Once you believe you have fixed the dojo/dijit dependencies in your page code and its dependent modules, it's time to try removing the modules from your page. Our pages typically have an html, js, and css file associated with them. Let's assume you have a page called mypage. Presumably you've removed dojo/dijit from the glue code (mypage.js). Now you need to do the following:

• remove all dojo/dijit css file references from your mypage.css class
• remove the package descriptions for dojo, dijit, dojox from your mypage.html file requires statement

If you have correctly anticipated all of the dependencies while fixing your page, then the page should load. More likely, there is still some module declaring a dependency and you have more files to fix. Figuring out which is the offending module is a little tricky, but here is what I've had success with (maybe Simon knows a better way):

• put a breakpoint at require.js line 1645 (in the req.load method).
• edit the breakpoint to print the module being loaded to the console.

console.log("loading module " + moduleName + " from URL " + url); return false;

• this will print the module loads to the console. They are asynchronous, so you can't fully tell who is calling who, but you know that one of the modules hit before the missing one is the culprit. I've found that I can usually tell my looking at the list. Since many of the common modules are already sanitized, you'll usually recognize the problem one. If you're lucky, it's just an unneeded module definition, but if you're not, there's a module you forgot to do.