A brief review of some of the best practices for maintenance & longevity when building applications with Dojo:

• Use a separate namespace for your custom modules rather than dojo, dijit, or dojox – this makes it very clear which modules come from the Dojo distribution and which modules were created for your application or organization
• Never edit Dojo modules directly – Dojo provides dojo/_base/declare for inheritance and provides many modules that were designed to be extended or used as mixins

With a clear separation in your codebase between Dojo modules and custom modules created for your application you have a much greater chance of a simple & successful upgrade to a new release of Dojo.

If you find yourself wanting to edit a Dijit’s template, you should first see if you can meet your needs using CSS or the widget’s content area. By inspecting the DOM of Dijits rendered in a page, you can see the element structure and CSS rules applied. You can override the CSS rules using the same selectors simply by including your custom CSS after Dijit’s CSS has been loaded. Dialog, layout, and container Dijits are explicitly designed to display arbitrary content, so see if you can place your custom elements in the content area.

If you have really exhausted other possibilities and feel a need to significantly modify a Dijit’s DOM, it’s best to leave the existing template intact – the code for the widget is expecting a certain DOM structure and may fail if you remove or rearrange elements. One approach is to copy the Dijit’s template, edit it to meet your needs, and use it in your own custom widget that extends the original Dijit. If you feel OK with keeping your modified template up-to-date with the base template as you update the release of Dojo you use, this approach may work for you.

A somewhat complicated, but more resilient approach would be to programmatically add your elements to the DOM in your custom widget’s buildRendering method. Don’t remove existing elements – you may be able to get away with hiding them, but removing them may lead to code errors. Since the DOM structure has potential to change with new releases of Dojo, you should locate an element that has an attach point, as these are less prone to change. Insert your custom DOM nodes, or even other widgets, into the Dijit’s DOM with an attach point node as the reference for positioning. With this approach, your custom widget is more likely to continue working unmodified as you upgrade your application to use new releases of Dojo.

SitePen offers beginner, intermediate, and advanced Dojo Toolkit workshops to make your development team as skilled and efficient as possible when creating dynamic, responsive web applications. Sign up today!

Why? As simple as these may seem on the surface, each organization or application often needs something subtly different in terms of layout, appearance, behavior, events, and internationalization. Dojo and Dijit provide all the elements you need to make a variety of dialogs, including dijit/Dialog, dijit/form/Button, dojo/on, dojo/Deferred and dojo/i18n.

The time spent creating a dialog that suits your needs perfectly will be small compared to the overall time spent developing an application, and you will have a reusable module tailored to your specific needs that you can use throughout your application, or even across applications throughout your organization. Creating a custom dialog also ensures that teams of developers don’t have to struggle to get a generic confirmation dialog to respond and look like other dialogs in the application.

That being said, Dojo is an open-source, community-driven project, and you are encouraged to share general-purpose components with the community:

• Dojo Foundation Packages
• Dojo Foundation Packages and Phasing out DojoX

SitePen offers beginner, intermediate, and advanced Dojo Toolkit workshops to make your development team as skilled and efficient as possible when creating dynamic, responsive web applications. Sign up today!

Width/height issues

The most common culprit when your dijit/layout/BorderContainer doesn’t display at all is forgetting to set the width and height of the html and body elements. Somewhat counter-intuitively, these elements default to a width and height of 0, only expanding to fill content.

A BorderContainer is often configured to expand to fill its container node like so:

#borderContainer {
    width: 100%;
    height: 100%;
}

In a typical scenario, if all you have on a page is a BorderContainer directly under the body element, the body will have height and width of 0, so the BorderContainer will calculate the space it has to work in and will fill 100% of… no space! That is, unless you set width and height explicitly, like so:

html,
body {
    width: 100%;
    height: 100%;
    margin: 0;
    padding: 0;
    overflow: hidden;
}

With the html and body elements configured to use the full viewport, your BorderContainer will be able to expand as you would expect.

Did your widget start?

As with all Dijit widgets, if you are using BorderContainer programmatically, you need to ensure that you explicitly call startup after creating it and putting it into the document:

require([
    'dijit/layout/BorderContainer'
], function(BorderContainer){
    var mainContainer = new BorderContainer({
        id: 'mainContainer',
        design: 'headline'
    });
    mainContainer.placeAt(document.body);
    mainContainer.startup();
});

In Closing

If your BorderContainer fails to display, check two things:

• The size of the BorderContainer's containing element – if it’s the body element, make sure both the html and body elements are sized appropriately.
• If using BorderContainer programmatically, ensure that you have called its startup method after creating and placing it.

If it still isn’t showing up, check your console and make sure there are no errors — a parsing error will often cause subsequent content to not display correctly.

SitePen offers beginner, intermediate, and advanced Dojo Toolkit workshops to make your development team as skilled and efficient as possible when creating dynamic, responsive web applications. Sign up today!

JavaScript tooling has gained a huge amount of attention over the past few years, no doubt due to the language’s rapidly increasing popularity and maturity. Many fantastic utilities and powerful debuggers have emerged to help close painful gaps for Web developers, but despite these advancements, high-quality JavaScript testing is still notably absent.

Up to this point, JavaScript authors have had to pick and choose testing tools with incredibly fragmented feature sets. Whereas one tool might support easily running tests manually in many browsers, another might allow command-line automation but only use PhantomJS. A third might be designed to integrate with a continuous integration service, where a fourth might support none of that but allow you to emulate true browser events from outside the JavaScript sandbox. One might have so many plugins that it’s impossible to figure out which ones to use, whereas another might be so inflexible that adding any new features is impossible. It’s a mess.

Intern, from SitePen Labs, is different. It combines all the best features from various testing tools (plus a few new ones of our own) into a single, versatile, easy-to-use, standards-based browser testing stack for JavaScript. We’ve been using this testing framework internally for a while with great success and are really excited to be able to make this level of JavaScript testing available to the entire Web community.

For more information on Intern’s features, usage examples, and documentation, please visit the Intern Web site. If you just want to get started straight away, take a look at the quick start guide. We’ll be making an npm package available very soon to make getting started even easier. Bug reports and feature requests can be posted to the GitHub issue tracker. If you have any other questions, we’re here to help! Free end-user support is currently available via Stack Overflow. SitePen also offers commercial JavaScript support if you need a little extra TLC.

Please let us know in the comments how Intern can work better for you, so you can focus on delivering high-quality code while the Intern does the testing. Happy coding!

SitePen offers beginner, intermediate, and advanced Dojo Toolkit workshops to make your development team as skilled and efficient as possible when creating dynamic, responsive web applications. Sign up today!

While most web browsers provide DOM events in a manner compliant with the W3C model, prior to version 9 Internet Explorer implemented its own model with the attachEvent method and some different properties on the event object.

Using dojo/on allows you to interact with event objects using the W3C event model regardless of the web browser. Specifically, the following properties and methods are added to event objects in IE8 and below (see the MDN reference for details – keep in mind some properties only apply to certain event types, like KeyboardEvent and MouseEvent):

• target
• currentTarget
• relatedTarget
• charCode
• keyChar
• charOrCode
• stopPropagation()
• stopImmediatePropagation()
• preventDefault()

Non-standard MouseEvent Properties

The properties pageX, pageY, offsetX, offsetY, layerX, and layerY are not normalized as it is expensive and often not needed, but the dojo/dom-geometry module provides a convenient method for doing so: normalizeEvent.

require([
    'dojo/on',
    'dojo/dom-geometry'
], function(on, domGeom){
    on('button', 'click', function(event){
        domGeom.normalizeEvent(event);
        console.log(event.pageX, event.offsetY, event.layerX);
    });
});

In Closing

Using Dojo provides an easy, consistent API across web browsers, smoothing out incompatibilities and inconsistencies, with a focus on adhering to open standards. Even if you’re not ready to update existing code that depends on certain properties (like layerX, layerY), you can still start using Dojo and take advantage of normalization methods to ensure your existing code works as expected.

SitePen offers beginner, intermediate, and advanced Dojo Toolkit workshops to make your development team as skilled and efficient as possible when creating dynamic, responsive web applications. Sign up today!

We have bucket-loads of answered questions. What to do with them all…
Oh? Provide you with the answers? Ok.

Here it is! Each week we’ll answer a commonly asked question about Dojo and then we’ll give it to you. Here we go!

A question we commonly get is what the difference between dojo/domReady and dojo/ready is and why we would actually choose one over the other. In order to understand the answer to this question, let’s quickly look at how they work under the hood.

dojo/domReady

require(["dojo/domReady!"], function () {
	console.log("The DOM is ready");
});

require(["dojo/domReady"], function (domReady) {
	domReady(function () {
		console.log("The DOM is ready");
	});
});

The most common use of dojo/domReady is as a plugin in a require call, but it can also be used as a function. In order to determine when the DOM is ready, domReady listens for the DOMContentLoaded event where available and window.onload as a fallback. If the document is not yet ready, it will queue any registered callbacks, and will execute them in the order that they are queued. If used after the DOM is ready, the callback is immediately invoked.

dojo/ready

require(["dojo/ready"], function (ready) {
	ready(function () {
		console.log("The DOM is ready");
	});
});

require(["dojo/ready"], function (ready) {
	ready(100, function () {
		console.log("The DOM is ready");
	});

	ready(1, function () {
		console.log("This fires first");
	});
});

The dojo/ready module provides a function that registers a callback that will run once three conditions have met:

1. The DOM is ready
2. All outstanding modules of requested code have completed loading
3. Other registered functions with a higher priority have completed.

It can take up to three parameters:

• priority signifies the order in which to execute the callback relative to other registered callbacks, where lower values are considered higher priority. This argument is optional, defaults to 1000, and must be a number.
• context is the context in which to execute the registered callback (the value of this in the invocation). This argument is optional.
• callback is the function to be registered. It is required.

Internally, dojo/ready uses dojo/domReady to determine when the DOM has loaded. Additionally, the dojo/parser module uses dojo/ready to queue up its automatic parse when parseOnLoad is set to true, so it can be used to ensure that the parse has completed before you perform further work that may be dependent on the fully parsed page.

Determining the right module to use

As you can see, the primary difference between dojo/domReady and dojo/ready is that dojo/ready allows you to specify a priority and context, and dojo/ready cannot be used as a plugin, like dojo/domReady. Additionally, dojo/ready waits for all requested code to finish loading, as opposed to simply just waiting on the DOM to be ready. Given these differences, we can easily determine the appropriate time for each module.

If you need to ensure that your callbacks execute in a set order, or they need to wait for things like all modules of code to finish loading, dojo/ready is the right choice. If you’re depending on parseOnLoad in your application, you need to use dojo/ready.

If you don’t need to wait for all code other than your dependencies to complete loading, or you don’t need to worry about the parsed results, dojo/domReady is the recommended solution, as it requires no changes to your code other than adding the dojo/domReady! dependency to your require call.

In Closing

As you can see, both of these modules are useful and have their purposes in registering callbacks to fire when the DOM is ready. If you’re interested in diving into the Dojo Toolkit more, SitePen offers a number of workshops that will help broaden and deepen your knowledge of Dojo!

SitePen offers beginner, intermediate, and advanced Dojo Toolkit workshops to make your development team as skilled and efficient as possible when creating dynamic, responsive web applications. Sign up today!

Introducing the dojo-amd-converter

We have created an alpha quality release of dojo-amd-converter, a tool for helping you make a one-time migration of your existing source code to a newer version of Dojo.

Be warned, the tool handles only 70-80% of the manual conversion process, and generally does better with more standard usage of Dojo. Normally we wait a bit longer before announcing our projects, but this should be useful in its early alpha state. We know this tool has quite a few open issues that need to be fixed and we invite you to help us improve it.

Our hope is that this conversion tool, which is today useful for converting pre-AMD code to AMD code, could also form the basis for a community effort to make it possible to migrate code bases more efficiently from Dojo 1.x (pre-AMD or AMD) to Dojo 2.x. That work has not yet started, since Dojo 2.0 is not yet an actual thing.

What does it do?

Based on a collection of rules, and leveraging Node.js, libxml.js, and esprima, the parser will take an existing Dojo source tree, and convert the following:

• non-AMD modules to AMD modules
• namespace references to module references
• legacy HTML custom attributes to HTML5 compliant data-dojo-*
• legacy i18n bundles to AMD bundles
• older Dojo APIs to their refined replacements

For example, if before conversion you had a file like this:

dojo.provide("my.namespace.i18n.Bundle");
dojo.requireLocalization("dijit", "common");
dojo.requireLocalization("foo.package", "Bundle");
dojo.requireLocalization("bar.package", "Bundle2");

var foo = dojo.i18n.getLocalization("foo.package", "Bundle"),
	bar = dojo.i18n.getLocalization("bar.package", "Bundle2", foo.bar),
	baz = {
		locale: "en-lol",
		i18n: dojo.i18n.getLocalization("bar.package", "Bundle2", this.locale)
	};

You would end up with this, after conversion:

define([
	"dojo",
	"dojo/i18n",
	"dojo/i18n!bar/package/nls/Bundle2",
	"dojo/i18n!dijit/nls/common",
	"dojo/i18n!foo/package/nls/Bundle"
], function (dojo, i18n, i18nBundle2, i18ncommon, i18nBundle) {

	var foo = i18nBundle,
		bar = i18n.getLocalization("bar.package", "Bundle2", foo.bar),
		baz = {
			locale: "en-lol",
			i18n: i18n.getLocalization("bar.package", "Bundle2", this.locale)
		};
});

Usage

To use the dojo-amd-converter, Mac and Linux users should follow these simple steps:

1. Clone the repo using Git:

   git clone --recursive https://github.com/SitePen/dojo-amd-converter.git

2. Modify the provided config.js file to specify some basic settings for your application, such as your source and destination directories.
3. From within the repo, run the provided shell script on your configuration file:

   ./parse.sh config.js

chmod +x parse.sh

config.js options

• excludePaths – An array of paths that will be excluded from processing. Each path should be a regular expression
• srcDir – Root directory of the files to process.
• distDir – Output directory of the processed files.
• printOutput – Print output instead of sending it to the output directory.
• makeDeclareAnonymous – Make declare calls anonymous instead of leaving the first argument as-is. This will avoid creating any global variables with declare.
• removeUnusedDependencies – Remove dependencies that are not referenced in a converted module.
• onlyProcessTemplates – Only process HTML files inside template directories.

The AMD converter does not currently work on Windows, due to the dependency on libxmljs.

Getting Involved

This project is in the early stages, and our hope is that it will also be used for work to convert to Dojo 2.0. We have many open issues for items we have already identified in our work using this tool. The dojo-amd-converter tool is licensed under the same terms and conditions as other Dojo Foundation projects.

To get involved, you will need to have a Dojo Foundation CLA on file for us to consider your code change. Please get involved if this tool is of interest to you now or in the future, as we think it is a much needed improvement for making it easier to upgrade between Dojo releases.

SitePen offers beginner, intermediate, and advanced Dojo Toolkit workshops to make your development team as skilled and efficient as possible when creating dynamic, responsive web applications. Sign up today!

Feature Detection and Device Optimized Builds

Dojo 1.7+ now uses the popular has() pattern for feature detection in combination with a has()-aware build system. While it is easy enough to write feature detection tests with ad-hoc JavaScript expressions, the has() pattern defines a specific syntax such that the build system can detect these feature-based branches, and one can create application builds that are highly optimized for specific devices, with known feature shims factored out.

Check out the Feature Detection and Device Optimized Builds tutorial for Dojo 1.8 and 1.7!

Want to see a specific Tutorial? Want to Learn More?

Is there something you’d like to learn how to do with Dojo? Always wanted to know how something in Dojo works? Leave us a message in the blog comments and we’ll see about getting a tutorial created for you. Or sign-up for an upcoming SitePen Dojo Workshop to get a fully immersive hands-on experience with Dojo.

SitePen offers beginner, intermediate, and advanced Dojo Toolkit workshops to make your development team as skilled and efficient as possible when creating dynamic, responsive web applications. Sign up today!

SitePen’s dgrid project leverages the AMD loader and other features new since Dojo 1.7 to minimize the load and rendering times of dynamic grids in web applications. In this post, we conduct tests in four common scenarios for both dgrid and DojoX DataGrid, contrasting startup, render, and destroy times in several popular browsers. We also discuss the amount of code involved in loading common components of dgrid and DojoX DataGrid.

The demos below test each grid in three phases:

1. Startup – the time required to create the instance of the grid, define the columns and any other configuration, and display the grid with headers but no data
2. Render – the time required to process and present the first page of data in the grid (25 items); since both grids use lazy loading, render time for the first page is representative for all pages
3. Destroy – the time taken to remove the grid’s DOM from the document, and perform any internal cleanup

In order to offer an accurate comparison, the following practices were established for each test:

• Both grids use identical data and are rendered in a space with the same dimensions on the page. Since DojoX DataGrid only supports dojo/data stores, the ObjectStore module is used to wrap a Memory store. This may slightly influence timing of render tests, but it is still a legitimate factor when comparing the two implementations.
• The steps have been verified to ensure that both grids are in the same state at the end of each of the three steps, as described above.
• Testing is done sequentially: first the dgrid is tested, then the DojoX DataGrid.
• For each operation, the start time is noted, the actions are performed, and the elapsed time is calculated. A total time is also included, representing the sum of the startup and render times, as the performance of these two operations combined is a common concern.
• The time taken to load modules is not included in these performance comparisons. Payload size is discussed later, in the context of built layers.
• All tests were run on the same machine, running Windows 7, with the exception of IE8 testing, which was conducted within a Windows XP VM on that machine. However, it is important to note that the objective of these tests is to compare the timings between the grid implementations on each browser, not necessarily to compare timings between browsers/platforms themselves.

All the demo pages are available for you to run, with the results displayed both on the page and in the browser console. The startup, render, and destroy tests all run immediately in sequence, so it’s likely you won’t actually see the grids on the page. However, the demo pages are also constructed such that you can easily copy the source code and pick apart the tests on your own Web server.

The first test is for a very basic grid. A Memory store is created with simple items containing only a name and a unique id. For a basic grid configured to only display the name field, the times to startup, render and destroy the grid are as follows:

Run demo

Most grids include more columns and data. The second demonstration uses a larger store with more complex items, rendered in 6 columns; the times to startup, render the first 25 rows, and destroy are as follows:

Run demo

Subrows can be used to further organize data such that each item’s data is presented across multiple table rows. The results of tests using the same data as the previous example in a grid with subrows are as follows:

Run demo

ColumnSets (known as Views in the DojoX DataGrid) allow for even more complex organization of data. In addition to supporting subrows, they also support arranging data into sets of columns with independent horizontal scrolling. The results of tests using the same data as the previous example in a grid with two columnsets/views are as follows:

Run demo

From the tests above, although results vary across browsers, we can easily conclude that dgrid shows the most significant advantage in terms of startup and destroy times, which are consistently over twice as fast as the startup times of the DojoX DataGrid. The relation between render times ranges between staying on par between the two implementations, and being up to twice as fast on modern browsers, especially in simple scenarios.

However, the results above reflect only the processing time through stages of the grids’ lifecycles. It is also important to consider the time and bandwidth required to load the necessary modules. The architecture of dgrid leaves it up to the developer to choose which mixins, column plug-ins, extensions, and utilities to load. On the other hand, DataGrid includes more functionality by default, which requires loading more code and performing more initial setup.

In a production environment, code for any modules used in an application should be built into layers using Dojo’s build system. The table below lists the size (in bytes) of the built code for layers containing the following modules and their dependencies:

• dgrid’s OnDemandGrid
• OnDemandGrid plus features equivalent to those DataGrid includes by default (namely the Keyboard, Selection, and ColumnSet mixins, as well as the ColumnReorder and ColumnResizer extensions)
• DojoX DataGrid

For additional information about performing custom builds with dgrid, refer to our previous post on dgrid and Dojo’s nano build.

Bear in mind the objective of this post and these tests is to compare dgrid and DataGrid as accurately as possible, not the browsers or versions. You may wish to conduct additional tests with tools such as JSLitmus or benchmark.js.

Conclusion

dgrid performs more efficiently than DataGrid, which was one of the primary goals in its design. In addition, its modern architecture allows it to be easily extended and serve as a foundation for a wide variety of UI applications.

SitePen offers beginner, intermediate, and advanced Dojo Toolkit workshops to make your development team as skilled and efficient as possible when creating dynamic, responsive web applications. Sign up today!

Dojo Markup Syntax

Any project wishing to take advantage of the API generation tools should comment their code using Dojo’s Inline Documentation syntax – a straightforward set of commenting conventions that allow for easy documentation parsing. This is analogous to Javadoc and other similar conventions used in most programming languages today. For example:

// summary:
//            This is the summary for the method.
//            It's indented by two tabs.
// foo: Integer
//            First argument to this function
// bar: String
//            Second argument to this function
// returns:
//            A calculated value.

When parsing a comment block, the parser searches for a specific list of words or “keys”, including summary, description, this, and returns. Custom object properties and function parameters can also be documented using the same key-value comment format, as shown in the snippet above. Several other options are also supported, check out the full documentation for Dojo’s inline markup for more details.

Generating the docs

The Dojo team has worked hard to ensure that the actual generation of the docs was as simple as possible to configure and run. Before proceeding, make sure you have apache, node.js, and php 5.2 or greater installed. Next, it’s just three simple steps to generate shiny new API documentation:

1. Clone js-doc-parse.

$ git clone --recursive https://github.com/wkeese/js-doc-parse.git
$ cd js-doc-parse
$ git checkout all-my-changes

2. Edit environmentConfig object in config.js.

This tells the parser where your project is located. basePath should indicate the path to your project relative to config.js, and package paths should be relative to the basePath.

environmentConfig: {
    basePath: '../some/path/',
    packages: {
        myApp: 'myApp'
    }
}

Note: other configuration options exist in config.js.

3. Parse like there’s no tomorrow.

The output will consist of the details.xml and tree.json files within the js-doc-parse folder.

$ ./parse.sh ../some/path/myApp

That’s it! The documentation for your custom project has officially been generated. But how do we see it?

Viewing the docs

Now that the documentation has been successfully generated, all that’s left is to grab the API viewer in order to view the docs locally.

1. Clone api-viewer.

$ cd 
$ git clone git@github.com:wkeese/api-viewer.git api

Note: If you want to put the API viewer in a location other than your server root, config.php and .htaccess need to be updated to point to the other location.

2. Move generated files.

We need to put the generated details.xml and tree.json in a location so the API viewer can find them. The viewer expects an api_data/ folder as its sibling with subfolders corresponding to project version numbers.

$ cd 
$ mkdir api_data/
$ mkdir api_data/1.0
$ mv js-doc-parse/details.xml api_data/1.0/
$ mv js-doc-parse/tree.json api_data/1.0/
$ chmod -R +a 'user:_www allow delete,list,search,add_file,add_subdirectory,read,write' api_data

Finally, start your local Apache instance and point your browser to http://localhost/api/.

Theming the docs

Many users have asked how to modify the default theming of the API viewer itself. The styles and static content are broken down into a few key files that can easily be customized to fit your style needs, each of which will be included as the pages are generated.

• theme.css – Includes any CSS styling that needs to be included in the document
• index.php – Populates the Welcome tab of the API Viewer
• header.php – Inserted before the main content area
• footer.php – Inserted after the main content area

Conclusion

Rather than simply generating an endless page of formatted API documentation, Dojo’s documentation tools provide a clean, simple method to produce an enterprise-quality API viewer and documentation for any JavaScript project. While more advanced configuration options for generation and viewing are available, the above guide should get any project up and running with their very own API viewer.

SitePen offers beginner, intermediate, and advanced Dojo Toolkit workshops to make your development team as skilled and efficient as possible when creating dynamic, responsive web applications. Sign up today!