Username/Email:  Password: 
TwitterFacebookFlickrRSS
Home ›

Dojo, Now with Drawing Tools!

Issue 178

From Issue #178
February 2009

Feb 01, 2009  By Matthew Russell
 in
Internalizing Dojo's “write once, deploy anywhere” philosophy, Dojo's gfx (pronounced “g-f-x” or sometimes “graphics”) library packs a powerful 2-D drawing API that's capable of plugging in to an arbitrary renderer. Out of the box, it works with Canvas, Silverlight, SVG and VML, so regardless of which browser your application is ultimately viewed within, gfx has you covered.

My article “Dojo: the JavaScript Toolkit with Industrial-Strength Mojo” in the July 2008 issue of Linux Journal illustrated how Dojo significantly lowers the amount of effort it takes to develop a cross-browser Web application by normalizing so many of the yucky aspects of Web programming, such as DOM manipulation, non-uniform aspects of the JavaScript across browsers, and repetitive tasks, such as styling nodes, performing AJAX requests and so forth. With that working knowledge, let's turn to Dojo's gfx library—a much more specialized aspect of the toolkit that's expressly designed to give you 2-D drawing tools that can be used to do anything from producing a cool-looking reflection of an image to creating an animated game to rendering a drag-and-drop graph.

Figure 1. An example of a slick effect gfx can produce on an image.

So that you better understand exactly where gfx fits into the larger toolkit, recall that Dojo breaks down into roughly five components: Base, Core, Dijit, DojoX and Util. Base is the tiny dojo.js file that contains hard-live-without library code for common operations; Core includes most of the programmatic machinery for the toolkit; Dijit is an assortment of turnkey widgets; DojoX provides a collection of specialized subprojects; and Util provides a testing framework and scripts for tasks, such as minifying and consolidating JavaScript and CSS files. The gfx library is one of those many specialized subprojects that lives under the DojoX umbrella.

Figure 2. A Conceptual Portrayal of Dojo's Functional Architecture

Note:

A common misunderstanding is that everything within DojoX is experimental or necessarily unstable. Although there certainly are some alpha-quality subprojects within the DojoX namespace that you wouldn't want to rely on for long-term production scenarios, several DojoX subprojects (including gfx) are quite ready for mainstream use. In general, you should be able to check a project's README file to determine information about its status.

A Minimal Development Template

In order to demonstrate the various drawing concepts as clearly as possible, all of the examples you're about to see will plug right in to the following minimal HTML page. Although you're encouraged to download the entire toolkit eventually, so you have full access to the source code whenever you need it, let's take advantage of the version that's hosted on AOL's Content Delivery Network, as it's quicker to get up and running. The latest version of Dojo at the time of this writing is 1.2, so the minimal effort to put Dojo to work is the following page, which uses a script tag to cross-domain load the toolkit: 


<html>
  <head>
      <title>Minimal Development Template</title>
      <script 
          type="text/javascript"
          src="http://o.aolcdn.com/dojo/1.2/dojo/dojo.xd.js">
      </script>
      <script type="text/javascript">
          dojo.addOnLoad(function() {
              /*Add Dojo-dependent logic 
                here to avoid race conditions*/
          });
      </script>
  </head>
  <body>
  </body>
</html>

With the minimal template in place, it is trivial to load the gfx module and start drawing. The next section digs right in to various aspects of the API, but just so you can see where we're heading, consider the modification to the template that instantiates a 600x600 pixel drawing surface and draws a line from the upper-left corner to the lower-right corner shown in Listing 1.

Listing 1. A Minimal Drawing Example


<html>
  <head>
      <title>Square with a Diagonal Line</title>
      <script 
          type="text/javascript"
          src="http://o.aolcdn.com/dojo/1.2/dojo/dojo.xd.js">
      </script>
      <script type="text/javascript">
          dojo.require("dojox.gfx");
          dojo.addOnLoad(function() {
              var node = dojo.byId("surface");
              var surface = dojox.gfx.createSurface(node, 600, 600);

              surface.createLine({
                  x1 : 0,
                  y1 : 0, 
                  x2 : 600,
                  y2 : 600 
              })
              .setStroke("black")
              ;
          });
      </script>
  </head>
  <body>
      <div style="width:600;height:600;border:solid 1px"
       id="surface"></div>
  </body>
</html>

Figure 3. A 600x600 Drawing Surface with a Diagonal Line Drawn through It

Although quite simple, the previous example taught us that the origin of the drawing surface is the upper-left corner with positive axes extending down and to the right, and that you can place a drawing surface into an arbitrary page element. Although not directly stated, the latter implies that you can have multiple drawing surfaces on a single page.

It's also worth noting that the style applied to the div element in no way applies to the gfx surface that is created. Internally, what happens is that the surface is created and placed inside of the div; thus, the containing div exhibits a 600x600 size with a visible border around it, and the surface that is placed into the div just so happened to be 600x600 pixels also. Without using Firebug to inspect the DOM, that may not have been obvious, so hopefully, mentioning it here avoids any confusion.

An additional aspect of this simple demonstration that's important to note is that the browser was detected and a default drawing renderer was assigned automatically without any special intervention. In the case of a Gecko- or KHTML-based browser, like Firefox or Konqueror, SVG is used as the default renderer; Internet Explorer defaults to VML.

Figure 4. The gfx library's flexible design provides a uniform API that supplies a uniform abstraction on top of the most common drawing engines in the mainstream. Because it internally detects the drawing engine that's available, it works right out of the box.

Silverlight and Canvas can be configured to run on supported platforms via a gfxRenderer configuration switch supplied to djConfig via the script tag that loads Dojo into the page. For example, to instruct Firefox to use Canvas as the renderer you would provide the following script tag: 


<script 
    type="text/javascript"
    djConfig="gfxRenderer:'canvas'"
    src="http://o.aolcdn.com/dojo/1.2/dojo/dojo.xd.js">
</script>

______________________

Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Please post missing file 10308.tgz

Anonymous's picture
Submitted by Anonymous (not verified) on Wed, 08/25/2010 - 00:01.

When I try this link in the resources:

ftp://ftp.linuxjournal.com/pub/lj/issue178/10308.tgz

It's a bad link. I found this
ftp://ftp.linuxjournal.com/pub/lj/listings/issue178/README178

10042.tgz -- Web 2.0 Development with the Google Web Toolkit
Federico Kereki

10308.tgz -- Dojo, Now with Drawing Tools!
Matthew Russell

but this file is missing: 10308.tgz

very interesting, good for

Anonymous's picture
Submitted by Anonymous (not verified) on Wed, 07/01/2009 - 01:52.

very interesting, good for gfx beginner just like me. thanks!

where is the download for listing 4

forestial's picture
Submitted by forestial on Thu, 02/12/2009 - 22:16.

Trying to download the code from listing 4 from the ftp link in Resources. I get a "550 Failed to change directory" error.

Tried browsing the ftp site, but there seems to be nothing there for this issue (178).