Jump to: navigation, search

Difference between revisions of "Orion/Library Independence"

(i18n utilities)
Line 19: Line 19:
  
 
=== DOM manipulation ===
 
=== 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 (this may expand to its own page).
+
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.
 
* <tt>dojo.byId</tt>
 
* <tt>dojo.byId</tt>
 
<pre>
 
<pre>
 
document.getElementById(id);
 
document.getElementById(id);
 +
lib.node(id);  // when you aren't sure if you have an id or node, useful for inbound API calls
 
</pre>
 
</pre>
 
* <tt>dojo.query</tt>
 
* <tt>dojo.query</tt>
Line 28: Line 29:
 
element.querySelector(selector, parentNode);
 
element.querySelector(selector, parentNode);
 
element.querySelectorAll(selector, parentNode);
 
element.querySelectorAll(selector, parentNode);
 +
lib.$(selector, parentNode);  // one node
 +
lib.$$(selector, parentNode);  // node list
 +
lib.$$array(selector.parentNode); // array of nodes
 
</pre>
 
</pre>
 
* <tt>dojo.addClass, removeClass, toggleClass</tt>
 
* <tt>dojo.addClass, removeClass, toggleClass</tt>
Line 52: Line 56:
 
* <tt>dojo.position</tt>
 
* <tt>dojo.position</tt>
 
<pre>
 
<pre>
node.getBoundingClientRect()
+
lib.bounds
 
</pre>
 
</pre>
 
* dojo.empty
 
* dojo.empty
 +
<pre>
 +
lib.empty
 +
</pre>
 
* dojo.attr, removeAttr
 
* dojo.attr, removeAttr
 
+
<pre>
 +
element.setAttribute();
 +
element.getAttribute();
 +
</pre>
 
=== General JavaScript utilities ===
 
=== General JavaScript utilities ===
 
* dojo.hitch Function.bind
 
* dojo.hitch Function.bind
 
* dojo.keys constants
 
* dojo.keys constants
 +
<pre>
 +
lib.KEY.SPACE;
 +
</pre>
 
* dojo.trim
 
* dojo.trim
  
 
=== hash and hash change ===
 
=== hash and hash change ===
* dojo.hash, hashchange events - use HTML5 equivalents
+
* dojo.hash, hashchange events - use HTML5 equivalents.  ''window.location.hash contains the # whereas dojo.hash() did not''
  
 
=== i18n utilities ===
 
=== i18n utilities ===

Revision as of 14:09, 7 December 2012

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, or convert to dynamic DOM node creation when security is an issue. 

(See bug bug 392469 for security discussion).

  • dojo.create
  • dojo.position
lib.bounds
  • dojo.empty
lib.empty
  • dojo.attr, removeAttr
element.setAttribute();
element.getAttribute();

General JavaScript utilities

  • dojo.hitch Function.bind
  • dojo.keys constants
lib.KEY.SPACE;
  • dojo.trim

hash and hash change

  • dojo.hash, hashchange events - use HTML5 equivalents. window.location.hash contains the # whereas dojo.hash() did not

i18n utilities

  • dojo.string substitution (use i18nUtil.formatMessage)

Deferred / Promise support

  • dojo.Deferred (use orion.Deferred)
  • dojo.DeferredList

dijit Menu support

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

dijit Dialogs

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

dijit Layout support

  • Ok green.gif Replace common page use of dijit BorderContainer, ContentPane, Splitter
    • Ok green.gif switch to CSS based layout
    • iOk green.gif mplement small, lightweight splitter
  • Settings page uses custom dijit layouts
  • Some pages (compare, shell) 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