Documentation site

Third party components: the A list

Origami components may have dependencies (via Bower) on third party components. This page documents which third party libraries are preferred where there may be multiple libraries that achieve the same goal.

For thisUse thisNot theseBecause
DOM manipulation o-dom (TBC) jQuery
A general purpose DOM manipulation library is invariably a common request, but large DOM libraries should be avoided since they contain numerous other features beyond simple DOM manipulation. See also Why not jQuery
AJAX fetch jQuery, superagent Components should not use jQuery, fetch is better and will be supported natively by browsers. In the meantime a polyfill exists and is available through the Polyfill Service.
Event delegation ftdomdelegate jQuery Components should not use jQuery.
JavaScript utils Lodash Underscore, lodash-node Lodash V3 allows each method to be individually requireable e.g. require('lodash/function/defer'), which is more preferable than requiring the whole library. Lodash is roughly functionally equivalent to Underscore, but generally delivers faster performance, and includes some useful things not available in Underscore. Lodash-node was deprecated with the release of Lodash V3.
Throttle/debounce o-utils Lodash o-utils has its own throttle and debounce functions.
Template engine Hogan Mustache

It's compatible with Mustache templates, but offers additional features on top of Mustache's syntax. Origami has no opinion on how product developers should build applications, so when a component's purpose is to offer a raw template to the developer, it must use only fully Mustache-compatible syntax (but these components would also not actually require the template engine themselves).

Components that contain templates but only use them internally in order to render a UI element, may use the more advanced template syntax offered by Hogan, and prefer Hogan as the template engine.

Touch interactions Hammer.JS

It offers a highly extensible, well tested and lightweight way to interact with touch events, including both single- and multi-touch gestures.

Why not Modernizr?

Components are required to not do anything in global scope, which rules out invoking Modernizr directly. Components wishing to use a new browser feature should simply declare it as a requirement in the browserFeatures section of origami.json. A product developer can then choose to either load the module only if the required feature is present, or polyfill it to ensure that it is.

Why not jQuery?

jQuery is a commonly requested general purpose library, and may well already be on a product page due to use in the product or demands from advertisers. However, component authors should avoid using jQuery. As a whole, jQuery is an example of a god object which poses problems for smooth upgrading of component dependencies (it’s much easier to update things if they have smaller APIs and fewer dependents).

There are also specific modules within jQuery that don’t operate in an optimal way:

  • Events: jQuery’s event system is great, but it includes a proprietary namespacing strategy which isn’t consistent with the way Origami namespacing normally works. Instead, use ftdomdelegate, which provides the same familiar on and off methods.
  • Promises: jQuery lacks promises but does have Deferred, which can achieve similar ends but is not compatible with the standards-based promise. Instead, use native promises, and declare promises as a requirement for your module in the browserFeatures property of origami.json.
  • Data: jQuery provides the ability to store arbitrary data against DOM elements outside of the scope of your JavaScript module, which is a practice we would like to avoid.