Posts in the ‘Dojo’ Category

In addition SitePen’s various commercial support options, there are a number of ways to find helpful information on your own. Dojo has a large community of developers and hobbyists all across the globe that are willing to assist with problems and offer guidance. Many tutorials and examples exist and are ready to be found, you just have to look.

Here are some vital community resources available to assist you in your Dojo-learning, and some hints to ensure success:

Dojo Search

Search first, ask later. A quick stop at the dojotoolkit.org search page usually turns up lots of commonly encountered problems. The new search engine has options to help you target specific resources in the Dojo community, like blogs, forums, or archived mailing lists.

Dojo Forums

If you are unable to find any discussion or book entry already, start a new topic in the Dojo forums.

It helps to provide examples contained within code tags, and to politely state your question. If you have tried other methods and failed, mention them as well. The more infomation you provide in your post, the more likely someone is going to quickly be able to assist you.

Also available on the Dojotoolkit website: a collection of Frequently Asked Questions.

#dojo

Join the #dojo chat room on the irc server irc.freenode.net. This room acts as a realtime development center for numbers of people ranging from beginner to expert. Often, many core Dojo developers are available for any level of discussion, at seemingly odd hours of the day. There is no experience requirement, just a desire to learn.

The conversations range from deeply technical to outlandishly silly. It is a very friendly room, and a great way to be in immediate contact with like minded people while developing or learning Dojo. The first rule in the channel topic “Don’t Ask to Ask, just Ask” means just that: Jump right in, and start talking. If help is available, you will likely get a response.

Mailing Lists

Though the forums have taken the place of the once-active mailing lists, this resource is still available, and the preference of some. Simply signup, and begin writing a thoughtful, well researched question, and you are typically going to receive a response. The more thought you put into your post, the more willing people will be to help you.

There are several thousand subscribers to dojo-interest, so civility is expected of everyone.

It is important to remember the Dojo community is entirely voluntary. People helping other people for the good of the Open Web, typically in their spare time. Civility is expected of everyone, and you are not guaranteed any speedy response, if at all. If you find things within the community to be lacking, you are always welcome to contribute. See the Getting Involved guide for more information about what you can do. The community grows daily, and your contributions are just as welcome as everybody elses.

Dojo’s widget system is called Dijit. Dijits are the official, accessible, themed components shipped with the Dojo Toolkit. It has its own namespace, and likewise its own collection of utility functions:

Using dijits

There are two ways to make Dijits: via markup, or programatically. The markup route breaks W3C validation because Dojo conveniently uses customized attributes in the markup to configure the widget. If this concerns you, it can all be done with script. We’ll do both.

Start by making a new skeleton file, including a couple changes for dijit styling: the default theme tundra’s CSS, and setting to enable it:

Dijit uses Dojo’s package system to track dependencies via dojo.require. Simply call in the modules you need in a script tag. For instance, to use a dijit.Dialog and dijit.form.Button, you need the following calls:

From markup

You can specify all the attributes needed to setup your widget directly in markup, the most important being the dojoType. The parser finds the dojoType attribute, and turns the node into a Dijit with the matching classname. title is a common attrbute used by many widgets with headings:

If parseOnLoad is true, the widgets will be created, then addOnLoad code will be executed. If you want to execute code before widgets are parsed, set parseOnLoad:false, and put your code inside an addOnLoad function as before. Issuing the command dojo.parser.parse(); will create the widgets when you are ready.

From JavaScript

The same results can be achieved using valid HTML and JavaScript. Our markup is simple, valid HTML:

And our script is standard dojo code. We pass all the attributes as an object into our constructor, and tell it to use the node “sampleNode” for it’s content. All Dijits (or declared classes) can be created using the JavaScript new function.

When the button is clicked, you should see the word “clicked” in your Firebug (or Firebug Lite) console.

Manipulating The Widget

With our dialog successfully loaded and parsed (no errors were thrown, and the content of the Dialog is hidden), we need to explore some of the ways to manipulate the widgets. The function dijit.byId gives us a reference to our widget. The dijit.Dialog has an id of sampleNode.

To make the button the button control the dialog, modify the button’s onClick attribute to do more than print text:

If using the programmatic method, modify the lines that create the button:

The dijit.Dialog inherits from a dijit.layout.ContentPane which provides a few content-handling methods, including setHref. Add a new button outside the dialog with a new onClick function:

Or programatically by adding another button to our HTML:

And an additional new call:

Adding an id attribute to the paragraph inside the Dialog is an easy way to demonstrate another useful Dijit tool, dojo.getEnclosingWidget, to find which widget contains a passed domNode:

Ajax is an acronym for “Asynchronous JavaScript and XML”, a technology employed to send and receive data on the fly. It can be used to update sections of a website from any number of remote sources, send data to the server and pass responses back and forth, all without ever refreshing the webpage.

Having been versed on some essential Dojo methods, we’ll move on the the bread and butter of Ajax: XmlHttpRequest (or XHR for short). Dojo has several XHR methods available using common HTTP verbs: POST, GET, PUT, and DELETE.

To prepare, we need to create a file with some text to load in. Create a file named sample.txt in your js/ folder with sample text:

And modify the skeleton.html to have some basic markup and style:

Getting data

The first stepping stone is dojo.xhrGet, which will return the contents of a GET call on a URL. The XHR methods share a lot of common parameters. Most important are the url: (our destination) and handleAs: (how we handle what is coming back). When the data arrives, it will be passed the the load: function we define:

You will notice we’ve combined techniques above. The content will fade out, be replaced by the received data, and fade back in using methods we’ve learned to this point. It was almost too easy.

A single handle argument can be used instead of load and error, handling both success and failure cases in a common function:

XHR has limitations. The big one being that url is not cross-domain. You can’t submit the request outside of the current host (eg: to url:”http://google.com”). It is a known limitation and a common mistake when getting excited about Ajax. Dojo provides alternatives like dojo.io.iframe and dojo.io.script for more advanced usage.

A full list of XHR parameters is available at the API page, or in the Dojo Book. We are only going to skim the surface here.

Sending Data

All Dojo XHR methods are bi-directional. The only difference is the method. Using dojo.xhrPost, we use the POST method, embedding the data in the request (as opposed to the query string as with dojo.xhrGet). The data can be set directly as an object passed to the content parameter:

Or more commonly, conveniently converted from a form parameter. First, make a simple unobtrusive form in the skeleton.html:

Then, add in some JavaScript to submit the form by using dojo.connect to listen to the onSubmit event, and post the contents of the form to an alternate URL:

An example alternate-submit.php would look like:

Object Data

Getting text back from the server is nice, but the really great stuff comes when you start passing JavaScript objects around. Using a different handleAs: attribute, we can alter how Dojo handles the response data. Make a new file named simple-object.json to load:

We’ll target our xhrPost url: to the new file, and supply a handleAs: "json" parameter to convert the response data to an actual object we can use:

This allows us to send literally any kind of data back and forth across the wire, without ever interrupting the user experience.

Dojo has a powerful animation system with several pre-made animations for a lot of common use cases. Adding some visual flair to you projects has never been easier, and typically makes the users experience a lot more interesting.

All animations use a single “magic object” as it’s only parameter. The most important being the node: attribute, the domNode on which to apply our animation. Some parameters are optional, and some are for advanced usage. A common setup would look something similar to:

Base Animations:

Animations included in base dojo.js are: fadeIn, fadeOut, and animateProperty. dojo.animateProperty is very powerful, and is the foundation for most advanced animations, and other animations in Dojo Core.

As seen, dojo.animateProperty will fade the element back in via it’s opacity property, and simultaneously make the text larger. You can animate most any CSS property this way.

Additional FX

A lot can be done visually with the base animations, animateProperty especially. To keep the size of the base dojo.js down, all the additional animations and tools have been packaged into a single module: dojo.fx to be optionally called in via dojo.require. Adding the module to your code provides several additional animation methods: dojo.fx.combine, dojo.fx.chain, dojo.fx.wipeIn, dojo.fx.wipeOut and dojo.fx.slideTo.

dojo.fx.chain and dojo.fx.combine are very useful, too. They run animations in parallel or in sequence, returning a single instance of dojo._Animation to use:

Combining an animation to fade in and out wouldn’t make sense, so lets fade it out and slide the node simultaneously using dojo.fx.combine:

Animation Events

Each dojo._Animation has a series of “events” to tie into for more advanced usage. Going back to the one-stop-event-shop dojo.connect, we can connect to specific actions of the animation, and do other things. The most common are onEnd and beforeBegin:

These events are especially helpful when you want to do things like change some content out while a node is hidden and then fade it back in:

Conveniently, you can pass the event functions as properties to the animation. Using dojo.connect to setup the functions gives us a lot more power, and are typically safer for advanced uses, but sometimes it’s easier to wrap it all in:

The full explanation of events is available at the dojo._Animation API pages.

animateProperty

Probably the most powerful of the base animations, dojo.animateProperty allows us to easily animate multiple css properties simultaneously.

Since animateProperty is a dojo._Animation, it uses the same arguments as other animations. With an additional object, properties we can define any style property of a node. From start to end, and optionally using a unit attribute.

Manipulating our header element to use a new font color, size, and overall opacity is as easy as:

dojo.query Animations

Dojo provides another convenient module: dojo.NodeList-fx, which adds additional methods to dojo.query for the available dojox.fx animations. To enable these methods, simply add in the required module:

The above gives us the same effect as calling dojo.fadeOut directly, but dojo.query here makes an animation for each of of the NodeList elements, and combines them into a single dojo._Animation. This can be useful when you have groups of like nodes you want to easily affect (in this case, all the nodes with class=”fadeNode”):