AMD in Depth

London Ajax User Group April 10, 2012 @london_ajax

http://londonajax.com/

Welcome!• About Us • Dylan Schiemann (@dylans), Piotr Zalewa (@zalun), Andy Richardson, Mustafa Celik, and Darren Waddell (@fakedarren) • Thanks to Skills Matter, JSFiddle, SitePen, Comet Daily, & OReilly

Tonight• 18:00 Meet & Greet• 18:25 Introduction• 18:30 AMD in Depth• 19:50 Future Events• 20:00 Pub

Dojo Nano and AMD "Base-less" Dojo Only using the parts of Dojo you really need, on a much more granular level Dojo 1.7 AMD loader <4K gzip/miniﬁed Asynchronous Module Deﬁnition (AMD) A grassroots standard for interoperable code modules Client and Server Plugin framework for additional extensibility Default module system for Dojo 1.7+ Works with jQuery, MooTools (2.0), and hundreds of© SitePen, Inc. All Rights Reserved

Squeezing Performance • Automated build Dojo Nano with dependency Dojo Base resolution, AMD & dojo/store (Model) has.js optimized builds. • All from one place with full licensing and Dijit (View) support. dojox Grid© SitePen, Inc. All Rights Reserved

What is AMD? Asynchronous Module Deﬁnition A grassroots standard for interoperable code modules Client and Server Plugin framework for additional extensibility Default module system for Dojo 1.7+© SitePen, Inc. All Rights Reserved

Why AMD is Awesome Easy to mix and match code from different projects without risk of name collisions or dependency conﬂicts Loads and executes dependencies asynchronously and in parallel; much faster during development Supports cross-domain loading out of the box, no special builds required Supports all debuggers out of the box, no need for hacks like debugAtAllCosts or forcing xdomain loading Trivial to load multiple versions of the same package, or load two different packages with the same name, or patch a single module with another module© SitePen, Inc. All Rights Reserved

Basics Creates two global functions, require and define Replaces dojo.provide, dojo.require, dojo.requireIf, dojo.requireAfterIf, dojo.platformRequire, & dojo.requireLocalization Modules are grouped into collections called packages Examples: dojo, dijit, and dojox Modules normally have a 1:1 mapping to ﬁles Except when production-optimized through a build© SitePen, Inc. All Rights Reserved

Module Identiﬁers Look like path fragments; e.g. dijit/form/Button Work a lot like paths relative path fragments like "./" and "../" can be used to refer to other modules within the same package Necessary for fully portable packages Can be aliased/overridden to point to different code© SitePen, Inc. All Rights Reserved

require() require takes three arguments: configuration: Optional, a configuration object for the loader dependencies: Optional, an array of strings as a list of module identifiers to load before calling the callback callback: Optional, a function to call when dependencies are loaded What does it do? Reconfigures the loader at runtime Loads modules and executes an optional callback when they are loaded, passing loaded modules into the© SitePen, Inc. All Rights Reserved

require() // Were not using the configuration object here, just an array of requirements and // a callback. dojo/domReady! is a plug-in that we will explain in a moment. require(["dojo/dom-construct", "dojo/domReady!"], function(domConstruct){ var newButton = domConstruct.create("button", {innerHTML: "foo"}); domConstruct.place(newButton, document.body, "last"); }); // The same code in the legacy system // dojo.require("dojo/dom"); //this module was included by default dojo.ready(function(){ var newButton = dojo.create("button", {innerHTML: "foo"}); dojo.place(newButton, document.body, "last"); })© SitePen, Inc. All Rights Reserved

Deﬁning Modules Use the define function Code contained within is not resolved until they they are required (lazy instantiation) Factory is only called once; the return value is cached by the loader and shared between all modules Special plugin modules exist to extend loader functionality© SitePen, Inc. All Rights Reserved

define() define takes three arguments: moduleId: Optional, a string to explicitly identify the module dependencies: Optional, an array of strings as a list of module identifiers to load before calling the factory factory: The value of the module, or a function that returns the value of the module What does it do? Defines the value of a module Typically the moduleId is reserved for the build system - dont explicitly identify your modules!© SitePen, Inc. All Rights Reserved

Creating a widget before // Creating a widget old style dojo.provide("populizr.TemplatedWidget"); dojo.require("dijit._WidgetBase"); dojo.require("dijit._TemplatedMixin"); dojo.declare("populizr.TemplatedWidget", [dijit._WidgetBase, dijit._TemplatedMixin], { templateString: dojo.cache("populizr","templates/ TemplatedWidget.html"); });© SitePen, Inc. All Rights Reserved

Creating a widget with deﬁne + declare // Creating a widget with AMD define( ["dojo/_base/declare", "dijit/_WidgetBase", "dijit/_TemplatedMixin", "dojo/text!./templates/TemplatedWidget.html"], function(declare, _WidgetBase, _TemplatedMixin, template){ return declare([_WidgetBase, _TemplatedMixin], { templateString: template }); } ); // Note how the dependencies map into the function call!© SitePen, Inc. All Rights Reserved

// Creating a widget with AMD define( ["dojo/_base/declare", "dijit/_WidgetBase", "dijit/_TemplatedMixin", "dojo/dom-class", "dojo/dom-style", "dojo/dom-attr", "dojo/_base/xhr", "dojo/_base/array", "dojo/_base/lang", "dojo/text!./templates/TemplatedWidget.html"], function(declare, _WidgetBase, _TemplatedMixin, domClass, domStyle, domAttr, array, xhr, lang, template){ ... module code goes here .... } ); // What’s wrong here?!?© SitePen, Inc. All Rights Reserved

Issue: Dependencies mis-match // Creating a widget with AMD define( ["dojo/_base/declare", "dijit/_WidgetBase", "dijit/_TemplatedMixin", "dojo/dom-class", "dojo/dom-style", "dojo/dom-attr", "dojo/_base/xhr", "dojo/_base/array", "dojo/_base/lang", "dojo/text!./templates/TemplatedWidget.html"], function(declare, _WidgetBase, _TemplatedMixin, domClass, domStyle, domAttr, array, xhr, lang, template){ ... module code goes here .... } ); // What’s wrong here?!?© SitePen, Inc. All Rights Reserved

Solution #1: Don’t use (all of) them // Creating a widget with AMD define( ["dojo/_base/declare", "dijit/_WidgetBase", "dijit/_TemplatedMixin", "dojo/dom-class", "dojo/dom-style", "dojo/dom-attr", "dojo/_base/xhr", "dojo/_base/array", "dojo/_base/lang", "dojo/text!./templates/TemplatedWidget.html"], function(declare, _WidgetBase, _TemplatedMixin){ return declare([_WidgetBase, _TemplatedMixin], { templateString: template, hide: function () { var domClass = require(“dojo/dom-class”); domClass.add(this.domNode, “dijitHidden”); } });© SitePen, Inc. All Rights Reserved

Taking it further... // Creating a widget with AMD define( function(declare, _WidgetBase, _TemplatedMixin){ // Use requires on per-dependency basis var declare = require("dijit/_base/declare"), _WidgetBase = require("dijit/_WidgetBase"), _TemplatedMixin = require("dijit/_TemplatedMixin"), template = require("dojo/text!./template.html"; return declare([_WidgetBase, _TemplatedMixin], { templateString: template, hide: function () { var domClass = require(“dojo/dom-class”); domClass.add(this.domNode, “dijitHidden”); } });© SitePen, Inc. All Rights Reserved

deﬁne() The value given for a module can also be just a plain object In this case, the dependencies will still be resolved as normal, but obviously will not be passed to the factory, since it is not a function define(["foo/app"], { enabled: true, delay: 500 });© SitePen, Inc. All Rights Reserved

Key differences between deﬁne, dojo.provide AMD is less verbose AMD is fully self-encapsulated No references to global variables or the modules own package name Faster scope lookups Better miniﬁcation Impossible to forget a dependency and still have working code Zero global namespace pollution Completely portable© SitePen, Inc. All Rights Reserved

Conditional requires Use cases for conditional requirements: Dependencies that cannot be determined until runtime dojox/gfx uses this concept to decide which rendering engine to use (VML, SVG, canvas, etc) Modules that you only want to load when a certain condition occurs (conﬁguration, event, etc)© SitePen, Inc. All Rights Reserved

Special Module Names require Context sensitive require Relative module lookups dont work with global require exports An object that is the initial value of the module If you are returning an object with functions deﬁned on it, use this instead of creating and returning a new object© SitePen, Inc. All Rights Reserved

Special Module Names define(["dojo/dom-construct", "dojo/on", "dojo/_base/window", "require", "dojo/domReady!" ], function (domConstruct, on, win, require) { var debugButton = domConstruct.create(input, { type: button, value: Debug }, win.body()); on(debugButton, "click", function () { require([ "./debugger/console" ], function (console) { console.open(); }); }); });© SitePen, Inc. All Rights Reserved

Plugins Extend AMD loaders in lots of useful ways Common plugins available with most loaders are "text", "i18n", and "domReady" Plugin dependencies are identified by the exclamation point in the module identifier: "dojo/ text!", "dojo/i18n!", "dojo/domReady!" Data to the left of the "!" identifies the plugin to load; data to the right of the "!" is passed to the plugin for processing© SitePen, Inc. All Rights Reserved

dojo/text Loads a string from a ﬁle Replaces dojo.cache Used mostly for loading template strings, but can load any string Build system interns strings loaded using dojo/text, just like dojo.cache Compatible with RequireJSs text plugin // in populizr/quoteLogger.js define([ "dojo/text!./quotes.txt" ], function (quotes) { // quotes will simply be the content of the file, // so well split on newlines var quotes = quotes.split("n"); // Write out a random quote to the console console.log(quotes[Math.floor(quotes.length * Math.random())]); });© SitePen, Inc. All Rights Reserved

dojo/i18n Loads an internationalization bundle Replaces dojo.requireLocalization and dojo.getLocalization Compatible with RequireJSs i18n plugin define( [ "dojo/i18n!dijit/nls/common", "dojo/i18n!dijit/nls/common/it" ], function (common, commonIT) { console.log(common.buttonCancel); // "Cancel" console.log(commonIT.buttonCancel); // "Annula" } );© SitePen, Inc. All Rights Reserved

dojo/domReady and dojo/ready Ensures the module does not resolve until the DOM is ready Replaces dojo.ready Compatible with RequireJSs domReady plugin dojo/ready implements a priority queue, so applications can register which callbacks ﬁre ﬁrst by setting a priority for each callback require([ "dojo/domReady!" ], function () { console.log("DOM is ready!"); }); require(["dojo/ready", "dojo/parser", "dijit/registry", "dijit/Dialog"], function(ready, parser, registry){ ready(function(){ // This wont run until the DOM has loaded, the parser has run, and other // modules like dijit/hccss have also run. var dialog = registry.byId("myDialog"); ... }); });© SitePen, Inc. All Rights Reserved

dojo/has Allows modules to be conditionally loaded, using has.js features Replaces dojo.requireIf // in populizr/configureEvents.js define( [ "dojo/has!dom-attachEventListener?./events/w3cHandlers:./ events/ieHandlers" ], function (eventHandlers) { // Do something with eventHandlers } );© SitePen, Inc. All Rights Reserved

Loading non-AMD code Special module identifiers can be used to load arbitrary, non-AMD scripts as dependencies, in which case the modules returned value will be undefined: Any identifier starting with "/" Any identifier starting with a protocol (e.g. "http:", "https:") Any identifier ending with ".js" curl.js and perhaps others use js! prefix (e.g. "js!https://ajax.googleapis.com/ajax/libs/mootools/1.4.1/ mootools-yui-compressed.js© SitePen, Inc. All Rights Reserved

Conﬁguring AMD Loaders Given this directory structure, the conﬁguration would look like so: require({ baseUrl: "js/", packages: [ { name: "dojo", location: "lib/dojo" }, { name: "dijit", location: "lib/dijit" }, { name: "dojox", location: "lib/dojox" }, { name: "my", location: "my" }, { name: "util", location: "util" }, { name: "external", location: "http://foo.com/external" } ] });© SitePen, Inc. All Rights Reserved

Configuring AMD Loaders baseUrl: defines the base path for all modules; can be relative or absolute Relative values are relative to the HTML file in browsers and relative to the current working directory on servers packages: defines all of the packages registered for the application name is the name of the package location is the location of the package; relative paths are relative to baseUrl main is the name of the module that will be loaded if someone tries to require the package itself; this defaults to "main" (e.g. requiring "foo" will load the "foo/main" module)© SitePen, Inc. All Rights Reserved

Conﬁguring AMD Loaders Many other conﬁguration options exist; only packages is really necessary for a working application If baseUrl and tlmSiblingOfDojo are both not set, Dojo 1.7s loader uses the directory above the dojo/ directory as baseUrl tlmSiblingOfDojo = Top-level Module Sibling of Dojo© SitePen, Inc. All Rights Reserved

dgrid and Dojo Store require(["dgrid/List", "dgrid/OnDemandGrid","dgrid/Selection", "dgrid/editor", "dgrid/Keyboard", "dgrid/tree", "dojo/_base/declare", "dojo/store/JsonRest", "dojo/ store/Observable", "dojo/store/Cache", "dojo/store/Memory", "dojo/domReady!"], function(List, Grid, Selection, editor, Keyboard, tree, declare, JsonRest, Observable, Cache, Memory){ var testStore = Observable(Cache(JsonRest({ target:"./data/rest.php?", idProperty: "id", query: function(query, options){ return JsonRest.prototype.query.call(this, query, options); } }), Memory())); testStore.getChildren = function(parent, options){ return testStore.query({parent: parent.id}, options); }; // ...© SitePen, Inc. All Rights Reserved

dgrid and Dojo Store (continued) // ... var columns = [ tree({label:Name, field:name, sortable: false}), {label:Id, field:id, sortable: false}, editor({label:Comment, field:comment, sortable: false}, "text"), editor({label:Boolean, field:boo, sortable: false, autoSave: true}, "checkbox") ]; window.grid = new (declare([Grid, Selection, Keyboard]))({ store: testStore, getBeforePut: false, columns: columns }, "grid"); });© SitePen, Inc. All Rights Reserved

Shipyard Example // require Person model class from models/Person.js file var Person = require(./models/Person); // View is a base class that handles rendering data from Models into HTML var View = require(shipyard/view/View), // Container renders to a <div> element Container = require(shipyard/view/Container), // TextField view is <input type="text"> TextFieldView = require(shipyard/view/TextFieldView); // instantiate an object of class Person var person = new Person({name: Sean}); // create a new text field with data from person object var whoAreYou = new TextFieldView({ placeholder: What is your name, id: whoAreYou }).bind(person, { value: name }); // render the text field onto the page inside the element with "example" id // if youd ommit the example, text field will be rendereed into // <body> whoAreYou.attach(example); // ...© SitePen, Inc. All Rights Reserved

xstyle A framework for shimming (or polyﬁlling) and extending CSS, to efficiently support various plugins for additional CSS functionality and backwards compatibility of newer features. A CSS loader plugin for AMD loaders define(["xstyle!./path/to/example.css"], function(){ // module starts after css is loaded });© SitePen, Inc. All Rights Reserved

AMD Plans for Dojo 1.8+ API Clean-up, Further Split of Features Compose (improved declare), xstyle, put-selector, Dijit/ Widget Remove weight of deprecated APIs Tighter dependencies DojoX completely moved to Dojo Foundation packages Releases Independent releases of packages, roll out package release sets Support major HTML5, mobile, modern browser features Web Builder and Dojo Foundation Packages© SitePen, Inc. All Rights Reserved

Getting Started AMD Spec: https://github.com/amdjs/amdjs-api/ wiki/AMD Why AMD?: http://requirejs.org/docs/ whyamd.html Deﬁne AMD Modules with Dojo: http:// dojotoolkit.org/documentation/tutorials/1.7/ modules/ Learn more about AMD: http://dojotoolkit.org/ blog/learn-more-about-amd© SitePen, Inc. All Rights Reserved

Portable Modules moduleId should never be specified explicitly in a define call (it is for build tools) dojo.declare should never specify the name of the class being declared (unless creating declarative widgets) If you want to create private classes, remember you can just assign the return value of dojo.declare to a local variable Dependencies to modules within a package should always use relative module identifiers© SitePen, Inc. All Rights Reserved

Portable Modules Using global variables is verboten There are some areas where this is still required (some Dijits break the rules and declare multiple classes), but should improve beyond 1.7 This is especially relevant if you are deﬁning a module without a factory function; if you have any direct dependencies, you should be using a factory function Conditional requires with relative module identiﬁers must use a context-sensitive require© SitePen, Inc. All Rights Reserved

Known AMD-Friendly Toolkits Dojo 1.7+ MooTools 2.0+ and Node.js (easy to add Shipyard one) jQuery Mobile 1.1+ Lightstreamer (next rev) Backbone.js* OpenCoWeb jQuery 1.7 (w/ RequireJS) PhoneGap Wink Toolkit (1.4+) EmbedJS© SitePen, Inc. All Rights Reserved

Dojo Foundation Community App require([ "wink/ui/layout/scroller/js/scroller.js", "dojox/mobile", "dojox/mobile/parser", "dojox/mobile/compat", "dojox/mobile/RadioButton", "dojox/mobile/Carousel", "dojox/mobile/Opener", "dojox/mobile/SpinWheel", "dojo/data/ItemFileReadStore", "wink/ui/xyz/coverflow/js/coverflow.js" ], function(Scroller, dojoMobile) { df.utils.sizeElements(); df.utils.positionElements(); // Parse the page dojoMobile.parser.parse(); // Display the right options if ( !wink.has(css-perspective)){ $(rb3).disabled = true; } });© SitePen, Inc. All Rights Reserved

dQuery (Dojo + jQuery) <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/dojo/1.7.2/dojo/dojo.js" data-dojo-config="async: true, packages: [ { name: jquery, location: http://ajax.googleapis.com/ajax/libs/jquery/ 1.7.2, main: jquery } ]"> </script> <script type="text/javascript"> define.amd.jQuery = true; require(["jquery", "dojo/query", "dojo/NodeList-dom"], function(jquery, query){ jquery("#jquery").click(function () { jquery("#jquery > img").toggle(); }); query("#dojo").on("#click", function () { query("#dojo > img").toggleClass("hidden"); }); }); </script> https://github.com/jthomas/amd_examples/tree/master/dojo_and_jquery© SitePen, Inc. All Rights Reserved

Dojools (MooTools + Dojo) <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/dojo/1.7.2/dojo/dojo.js" data-dojo-config="async: true, packages: [ { name: mootools, location: ./mootools/amdified/} ]"> </script> <script type="text/javascript"> require(["dojo/has", "dojo/query", "dojo/NodeList-dom"], function(has, query){ window.has = has; query("#dojo").on("#click", function () { query("#dojo > img").toggleClass("hidden"); }); require(["mootools/Element/Element", "mootools/Element/Element.Event"], function(Element, Event){ Element.$("mootools").addEvent("click", function () { Element.$$("#mootools > img").each(function (elem) { elem.toggleClass("hidden"); }); }); }); }); https://github.com/jthomas/amd_examples/tree/master/dojo_and_mootools© SitePen, Inc. All Rights Reserved

BBC iPlayer "On top of this we layer our JavaScript application. Each page has a block of inline JavaScript that checks the capabilities of the browser before deciding whether to kick start the enhanced experience. Progressive enhancement, really, at heart. The JavaScript will include curl.js into the page and then AMD modules will load additional functionality into the page (our drop-down section navigation for example). The USP of this UI is that it provide a news service that tailored to new hardware/software."© SitePen, Inc. All Rights Reserved

Landmarks: Goals AMD example application Shows off famous landmarks (Eiffel Tower, Golden Gate Bridge, etc.) ESRI map API (using Dojo 1.6, pre-AMD) Flickr image API Wikipedia content Work well on desktop, phones, and tablets WebKit, Firefox, iOS, and Android were the initial targets© SitePen, Inc. All Rights Reserved

package.json { "name": "landmarks", "version": "1.0", "main": "main", "dependencies": { "dojo": "current", "dijit": "current", "dojox": "current", "util": "current" }, "description": "Landmarks. A demonstration of cross-platform Dojo technologies.", "licenses": [ { "type": "AFLv2.1", "url": "http://trac.dojotoolkit.org/browser/dojo/trunk/LICENSE#L43" }, { "type": "BSD", "url": "http://trac.dojotoolkit.org/browser/dojo/trunk/LICENSE#L13" } ], "dojoBuild": "app.profile.js" }© SitePen, Inc. All Rights Reserved

esriApi.js define([ "require" ], function(require){ // Exposes the Esri API for AMD applications as an AMD loader plugin. var esriApi; return { load: function(moduleId, require, callback){ if(esriApi){ callback(esriApi); return; } // The Esri API *requires* the older djConfig variable name // for its configuration var oldDjConfig = window.djConfig; window.djConfig = { scopeMap: [ // Lowercase scope map names are used because of some // peculiar behaviour observed during testing where JSONP // requests would be sometimes returned with lowercase // callback names even though the original call used // mixed-case names [ "dojo", "esridojo" ], [ "dijit", "esridijit" ], [ "dojox", "esridojox" ] ] }; // ...© SitePen, Inc. All Rights Reserved

main.js define([ "require", "dojo/_base/array", "dojo/has", "dojo/topic", "dojo/store/Observable", "./store/LocalStorage" ], function(require, arrayUtil, has, topic, makeObservable, LocalStorage){ var app = {}; has.add("sff", function(){ return screen.width < 1000 && screen.height < 1000; }); // store init var landmarkStore = app.landmarkStore = makeObservable(new LocalStorage()); // ui init var uiClass = has("touch") ? (has("sff") ? "Mobile" : "Tablet") : "Desktop"; document.body.className += " app" + uiClass; console.info("Loading UI " + uiClass);© SitePen, Inc. All Rights Reserved

main.js (continued) require([ "./ui/" + uiClass ], function(Ui){ app.ui = new Ui({ id: "container" }).placeAt(document.body); app.ui.startup(); navigator.geolocation && navigator.geolocation.getCurrentPosition(function(currentPosition){ var nearestXyDelta = Infinity, nearestLandmark; landmarkStore.query().forEach(function(landmark){ var xyDelta = Math.abs(currentPosition.coords.latitude - landmark.latitude) + Math.abs(currentPosition.coords.longitude - landmark.longitude); if(xyDelta < nearestXyDelta){ nearestXyDelta = xyDelta; nearestLandmark = landmark; } }); topic.publish("/landmark/selected", nearestLandmark); }); landmarkStore.query({}, { count: 1 }).forEach(function(landmark){ topic.publish("/landmark/selected", landmark); }); }); return app; });© SitePen, Inc. All Rights Reserved

Result: Modular Tools Tools to mix and match to Modular enough for very create your app simple projects, ﬂexible Separate data from UI and consistent enough to logic simple and handle the most seamlessly challenging, feature-rich© SitePen, Inc. All Rights Reserved web apps

Skills Matter Events• Essential Node.js, April 11• Find Your Ninja, April 23• Node.js eXchange, June 22

Future Events• Visit http://londonajax.com/• Submit your talk ideas at http://bit.ly/lFvYo2• Second Tuesday of every month

Thanks!(to the pub)

AMD in Depth

by SitePen

Accessibility

Categories

Upload Details

Usage Rights

Statistics

AMD in Depth Presentation Transcript