Oh and of course, the tutorials are rewritten to take full advantage of the new Dojo loader’s support for AMD, and they lay a groundwork for preparing your application to be lighter and more modular than ever!

So raise your glass and toast with us to the completion and release of the Dojo 1.7 Tutorials and to the best JavaScript toolkit available for scalable web apps!

Ready to upgrade to 1.7?

We stand ready to bring your code current to the latest release or kick off your project right out of the gate with Dojo 1.7! In addition to our dedication to Dojo documentation and tutorials we offer a comprehensive set of services to make your project a success!

Dojo Workshops – Learn Dojo 1.7 from the experts. We’ve posted a nationwide, 2012 workshop schedule that will exceed the expectations of developers and engineering budgets alike! If these dates and locations don’t work for you and your team, reach out to us about our private Dojo workshops.

Dojo Support – SitePen offers 5 different plans, all of which are provided to you by Dojo experts who will provide your team with the knowledge and experience necessary to support your web development efforts. Get pro-active and purchase a plan that will support your team with Dojo 1.0 through 1.7 and eliminate potential schedule-busting roadblocks on your path to success!

Development – Upgrading to Dojo 1.7 will improve your web application. If you know this to be true but don’t have the resources to make it happen, engage our development team to work for you and let us do what we do best – Make you look good. Contact us for a custom quote for your Dojo 1.7 upgrade.

Related posts:

1. The Year of Dojo is Here!
2. Dojo 0.9 Update
3. Everyone can “Ask the Experts”

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!

1.  Mobile

Mobile will gain even more momentum in 2012.  There’s no doubt we will see many new APIs, development tools and capabilities in place to both build and install most any app as a web app rather than using native technology.

2.  AMD

Following on the increasing emergence of microtoolkits in 2010 and 2011, 2012 will be the year everything becomes an AMD module, making it easier for Dojo, jQuery, MooTools and other toolkits to play nicely together.

3.  Builders & Loaders

With so many modules, performance, loading and building will need to be optimized.  Use of package management will become increasingly important.

4… Check out the rest of Dylan’s 11 Trends for 2012! And don’t forget that SitePen’s got your back when it comes to implementing efficient and scalable solutions.  Contact us today!

Related posts:

1. We’ve (unofficially) declared 2012 as the Year of Dojo!
2. The Year of Dojo is Here!
3. SitePen at BlackBerry DevCon Americas 2011

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!

However, the use of Dojo’s declarative tools has been avoided by some because it uses custom attributes that are outside the HTML specification. While this approach works in every browser on the market and is implicitly allowed, it does not validate against the HTML4 validators. Now, the new HTML5 specification provides a namespace for custom attributes. The data-* attributes are available for libraries and authors to use for their own purposes and extensions while still having validating markup. The HTML5 specification further recommends that library use a sub-namespace for their custom attributes to avoid conflicts with other code. All of the Dojo custom attributes begin with data-dojo-. Let’s look at the new Dojo attributes.

data-dojo-config

The data-dojo-config attribute replaces the djConfig attribute on the dojo.js script element to allow for declaration of Dojo’s configuration properties. Here we can specify settings like parseOnLoad, and isDebug. For example, we can load dojo.js with configuration information:

<script src="dojo.js" data-dojo-config="parseOnLoad: true, isDebug: true"></script>

data-dojo-* for widgets

The new data-dojo-type attribute replaces the dojoType attribute to specify the widget class to instantiate a target element. We can add the data-dojo-type to an HTML tag and the Dojo parser will create a widget on that element. This works in conjunction with the new data-dojo-props which replaces the attribute-to-property mapping previously used by the Dojo parser. We can also use the new data-dojo-id to create a new globally rooted variable to reference the new widget. For example, to declare a widget:

	<div data-dojo-type="dijit.Dialog" data-dojo-props='title:"My Dialog",
		onFocus:function(){ /* a focus event handler */ }'
		data-dojo-id="myDialog">
	</div>

This will create a new dijit.Dialog widget, with the title property and onFocus handler set. It will make the widget available from the myDialog global variable. Remember to have parseOnLoad set to true or explicitly execute dojo.parser() (from dojo/parser) after the page is loaded to ensure the widget gets instantiated.

Within widget templates, we can also use the new data-dojo-attach-event and data-dojo-attach-point as replacement for dojoAttachEvent and dojoAttachPoint to register attach points and attach event handlers. And finally, we can also use a data-dojo-event to define the event to register for <script type="dojo/method"> scripts.

When to go Declarative

Even when leveraging the new HTML5-valid custom attributes, there are still pros and cons to declaring widgets within HTML instead of with JavaScript. Declaring JavaScript components from within HTML introduces semantic impurity since the HTML is no longer purely semantic markup, but includes tight coupling to particular visual components. The declarative approach also incurs extra CPU cycles because dojo.parse() must traverse the DOM tree to find elements with Dojo custom attributes. Programmatic instantiation avoids unnecessary cycles and preserves semantic purity of HTML. However, markup-based widget declaration still has a powerful advantage by allowing us to define and create a widget in a single place, facilitating rapid application development and progressive enhancement with minimal effort.

Dojo still provides backward compatibility with the old custom attributes, but the new data-dojo-* attributes leverage the new HTML5 specification to provide fast and efficient declaration of widgets and configuration with clean and validating syntax.

Related posts:

1. HTML Widget Prototyping with the Dojo Toolkit
2. Dojo Charting: Event Support Has Landed!
3. Dijit: Prepackaged

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!

Learn Dojo - We are dedicated to providing you with the highest quality Dojo Toolkit workshops in the industry.  Whether you want to learn the basics of Dojo or sharpen your Dojo skills, we have a workshop just for you.  All of our Dojo Workshops are taught by our Dojo experts.  We promise you won’t be subjected to listening to some trainer who can’t live without his slides.  Wondering if our Dojo Workshops will cover Dojo 1.7?  The answer is yes!

Ready to learn Dojo?  Check out our full list of 2012 workshop dates and locations.  Sign up for any of our 2012 Dojo Workshops by January 31, 2012 with promo code IHEARTDOJO and get 10% off!

Here to help - Did you know we also have support plans to fit every size and every need?  No matter which support plan you choose, our expert engineers will help you by answering questions, resolving bugs, and solving problems. We offer no-hassle ways to get in touch with your SitePen Support team, which means no waiting on hold, or having to explain your issue over and over again until you get to the right person.  With us, you always have access to the right people. If your project runs in to a critical issue, our expert SitePen engineers will jump in to help you quickly get back on track. Oh, and yes, all of our support plans include support for dGrid and Dojo 1.7! Having a SitePen Support plan is preparing for possibilities.  Even football teams have backup quarterbacks.

From 2 support hours to 200 support hours, SitePen has a support plan to fit your needs.  Take a look!

Perfect match of design and development - We are your one stop shop for your next project, including mobile web applications! Our expert team will take your web application from concept to launch.  We’ve mastered the front end and are here to help you build powerful, simple, and usable web apps, every single time.

Whether you need a traditional web application, mobile web application or installable mobile web app store application, SitePen can help!

Still not sure how we can help you?  Contact us today! (You can even call us if you want.)  Celebrate 2012 – The Year of Dojo!

Related posts:

1. Eleven Trends for 2012: The Year of Dojo
2. We’ve (unofficially) declared 2012 as the Year of Dojo!
3. Dojo 1.7 Tutorial Update

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!

Using the new API is very easy, and should be familiar if you have used json.org’s library or the browser native library. We get the JSON object from the “dojo/json” module and then can use the parse and stringify methods. For example, to parse JSON:

define(["dojo/json"], function(JSON){
  var jsonStr = '{"name": "value"}';
  var object = JSON.parse(jsonStr);
  object.name -> "value";
});

Again, note that this will use the native parsing facilities of the browser/platform if they are available, otherwise they will use the library implementation.

To reverse the process and serialize an object to JSON:

define(["dojo/json"], function(JSON){
  var object = {"name": "value"};
  var jsonStr = JSON.stringify(object);
  jsonStr -> '{"name": "value"}'
});

Date Serialization

The new JSON module now properly serializes dates. While previously, dojo.fromJson incorrectly serialized dates as “{}”, serialization now conforms to native date serialization. Dates are serialized to the standard ISO format in UTC.

JSON.stringify({now:new Date()}) -> "{"now":"2011-06-13T19:02:19.650Z"}"

Native Performance

Staying Light

The new JSON module uses has() branching to determine whether or not to use the native JSON capability or not. This is not only a solid feature-detection based approach, but it means when you leverage browser-specific builds, the module is only a few bytes for modern browsers, particularly valuable for mobile applications.

The legacy dojo.fromJson and dojo.toJson will still be available in Dojo base, but it is recommended that you use parse and stringify functions from dojo/json now for better performance and standards conformance.

Related posts:

1. How Do You Serialize Dates from Forms to JSON with Dojo?
2. JSON Referencing in Dojo
3. JSON Schema in 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!

In addition to the useful links Dylan provides, you can also learn more about AMD at a SitePen Dojo Workshop.  AMD + Dojo 1.7= Awesomeness.

Related posts:

1. Dojo Public Workshops
2. SitePen at BlackBerry DevCon Americas 2011
3. SitePen. Dojo Skills. Seattle.

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!

This is an updated version of the post Touching and Gesturing on the iPhone, published in 2008.

In the beginning…

Before we discuss the new features in Dojo 1.7 that make touch interfaces easier to create, it helps to understand some of the underlying technology and concepts. With iPhone, Apple introduced two new event concepts: touches and gestures. Touches are important for keeping track of how many fingers are on the screen, where they are, and what they’re doing. Gestures are important for determining what the user is actually doing when they are interacting with the device at a higher level: pinching, rotating, swiping, double-tapping, and so on.

While touch events are available on most platforms (the touch event model originally established on iOS has been standardized in the W3C Touch Events specification and is supported by iOS, Android, and BlackBerry), native gesture events are not available everywhere, and the gesture event API in iOS is limited in the sorts of gestures it supports. The dojox/gesture package steps in to fill these gaps in functionality; we’ll discuss it shortly.

Touches

When you put a finger down on the screen, it kicks off the lifecycle of touch events. Each time a new finger touches the screen, a new touchstart event happens. As each finger lifts up, a touchend event happens. If, after touching the screen, you move any of your fingers around, touchmove events happen. If too many fingers are on the screen, or another action (such as a push notification from the phone’s OS) interferes with the touch, a touchcancel event happens.

The following touch events exist:

• touchstart: Occurs when a finger is placed on the screen
• touchend: Occurs when a finger is removed from the screen
• touchmove: Occurs when a finger already placed on the screen is moved across the screen
• touchcancel: Occurs when a touch is cancelled before the finger is actually removed from the screen

While it might seem that there should be a 1:1 mapping between a touch event and a mouse event—after all, your finger works much like a cursor—it turns out that TouchEvent objects do not include properties that you might expect to see. For example, pageX and pageY properties are not populated. This is because, with a mouse, you really only have one point of contact: the cursor. With a multi-touch device, though, you could (for example) keep two fingers held down on the left of the screen while you tap the right side of the screen, and all three points are registered.

In order to provide information about all touch points at once, every TouchEvent object has a property containing information about every finger that’s currently touching the screen. It also has two other properties: one which contains a list of information for fingers that originated from the current target node, and one which contains only the information for fingers that are associated with the current event. These properties are:

• touches: A list of information for every finger currently touching the screen
• targetTouches: Like touches, but is filtered to only the information for finger touches that started out within the same node
• changedTouches: A list of information for every finger that has changed state due to the event (see below)

To better understand what might be in these lists, let’s go over some examples quickly.

• When you put one finger down, all three lists will provide the same information.
• When you put a second finger down, touches will contain two items, one for each finger. targetTouches will have two items only if the second finger was placed in the same node as the first finger (otherwise it will only contain the second finger). changedTouches will only have information related to the second finger, because it’s what triggered the event.
• If you put two fingers down at exactly the same time, you will get two items in changedTouches, one for each finger that triggered the event.
• If you move your fingers, the only list that will change is changedTouches. It will contain information about the finger or fingers that moved.
• When you lift a finger, it will be removed from touches and targetTouches, and will appear in changedTouches, since it’s what caused the event.
• Removing your last finger will leave touches and targetTouches empty, and changedTouches will contain information about the last finger.

Using these lists, it is possible to keep very close tabs on what the user is doing. Imagine creating a(nother) Super Mario clone in JavaScript—you’d be able to tell what direction pad the user currently has his or her thumb on, while also being able to watch for when the user wants to jump or shoot a fireball when they touch another virtual button elsewhere.

So far, we’ve been discussing lists of information about fingers on the screen, but we haven’t talked about what this information looks like. The objects contained in the touches lists have properties similar to what you’d see on a MouseEvent object. The following is the full list of properties for these objects:

• clientX: X coordinate of touch relative to the viewport (excludes scroll offset)
• clientY: Y coordinate of touch relative to the viewport (excludes scroll offset)
• screenX: Relative to the screen
• screenY: Relative to the screen
• pageX: Relative to the full page (includes scrolling)
• pageY: Relative to the full page (includes scrolling)
• identifier: An identifying number, unique to each touch point (finger) currently active on the screen
• target: The DOM node that the finger is touching

One of the annoyances of writing Web applications for smartphones has been that even if you set a viewport for your application, dragging your finger around will move the page. Fortunately, the touchmove event object has a preventDefault method that can be used to keep the page still.

Drag and drop with the Touch API

Creating drag and drop functionality on touchscreen devices is made easier due to the fact that touchmove events only fire when a finger is already touching the screen’s surface. This means we don’t need to track button states like we would with a mousemove event. A basic drag and drop implementation, then, can look as simple as this:

node.addEventListener("touchmove", function(event){
    // Only deal with one finger
    if(event.touches.length == 1){
        // Get the information for finger #1
        var touch = event.touches[0],
            // Find the style object for the node the drag started from
            style = touch.target.style;
        // Position the element under the touch point
        style.position = "absolute";
        style.left = touch.pageX + "px";
        style.top = touch.pageY + "px";
    }
}, false);

Better touching in Dojo 1.7

One of the problems with using low-level touch events is that, if you are creating an application that you want to function on both touch-enabled or mouse-enabled devices, you end up needing to set up two sets of event listeners. The new dojo/touch module in Dojo 1.7 normalizes these two types of events, using touch events where available and falling back to mouse events on other platforms in order to provide device-neutral events. Using it is just as easy as listening for a regular event, except instead of passing a string for the event name, you instead pass a function in place of the event name:

require([ "dojo", "dojo/touch" ], function(dojo, touch){
    dojo.connect(dojo.byId("myElement"), touch.press, function(event){
        // handle a mousedown/touchstart event
    });
    dojo.connect(dojo.byId("myElement"), touch.release, function(event){
        // handle a mouseup/touchend event
    });
});

Gestures

On iOS devices, a gesture event occurs any time two or more fingers are touching the screen. If any finger lands in a node you are listening for gesture events on (gesturestart, gesturechange, gestureend), you’ll receive the corresponding gesture events.

Gesture events provide a GestureEvent object with these properties:

• rotation: The amount the user has rotated their fingers, in degrees.
• scale: A multiplier indicating the amount the user has pinched or pushed their fingers, where numbers larger than 1 indicate a push, and numbers smaller than 1 indicate a pinch.

When listening for both gesture events and touch events, the event pattern looks like this:

1. touchstart for finger 1.
2. gesturestart when the second finger touches the surface.
3. touchstart for finger 2.
4. gesturechange sent every time both fingers move while still touching the surface.
5. gestureend when the second finger leaves the surface.
6. touchend for finger 2.
7. touchend for finger 1.

Resizing and rotating with the Gestures API

Using the CSS transform, width, and height properties, we can easily rotate and scale any element in response to these gestures.

var width = 100,
    height = 200,
    rotation = 0;

node.addEventListener("gesturechange", function(event){
    var style = event.target.style;
    // scale and rotation are relative values,
    // so we wait to change our variables until the gesture ends
    style.width = (width * event.scale) + "px";
    style.height = (height * event.scale) + "px";
    style.webkitTransform = "rotate(" + ((rotation
      + event.rotation) % 360) + "deg)";
}, false);

node.addEventListener("gestureend", function(event){
    // Update the values for the next time a gesture happens
    width *= event.scale;
    height *= event.scale;
    rotation = (rotation + event.rotation) % 360;
}, false);

Better gestures with Dojo 1.7

Dojo 1.7 includes a new package, dojox/gesture, that provides functionality for handling more complex gestures on touch-sensitive devices. In addition to defining a basic framework for creating your own custom gestures through extension of the dojox/gesture/Base module, it comes with built-in support for several common gestures, including tap, tap and hold, double tap, and swipe.

Using dojox gestures couldn’t be much simpler. Just like dojo/touch, in order to listen for a gesture, you simply connect to a gesture event using dojo.connect, passing the gesture function in place of the event name:

require([ "dojo", "dojox/gesture/swipe", "dojox/gesture/tap" ],
        function(dojo, swipe, tap){
    dojo.connect(dojo.byId("myElement"), swipe, function(event){
        // handle swipe event
    });

    dojo.connect(dojo.byId("myElement"), tap.doubletap, function(event){
        // handle double tap event
    });
});

In time, dojox/gesture will be extended to include more complex event types and behaviors, such as pinching and zooming. For now, it provides several new events that were difficult to handle before, as well as an excellent framework that can be used to create complex gesture events across all platforms.

Related posts:

1. Touching and Gesturing on the iPhone
2. SDK showdown: iPhone vs. Android
3. Cometd on the iPhone

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!

This is an updated version of the original article, Dojo Drag and Drop, Part 1, published in 2008.

Simple Single Source DnD

Meet Dylan. Collecting junk is his passion. A while back, he decided that he needed to get rid of some of it to make room for more interesting junk, so he got a booth at the local farmers’ market and started a small junk outlet business. Like most people passionate about sharing their junk with the world, he decided to open an online storefront. His brother, currently working towards a degree in Marketing, convinced him that he needed to brand himself as a form of differentiation; thus was born Dylan’s Original. He decided that his best bet would be to create a user experience so ridiculously awesome that people wouldn’t be able to help buying his junk. That’s where we come in. To demonstrate drag and drop techniques, we’ll help build a mockup of Dylan’s Original Junk Outlet.

Let’s start with the basics. Just about the easiest way to get drag and drop working is to demonstrate a single list that the user can reorder dynamically. First, we’ll create our page skeleton, using Dojo from the Google CDN spiced up with a bit of CSS. View the starting point.

As you can see, we’re starting with a simple wish list:

<div id="store">
<div class="wishlistContainer">
<h2>Wishlist</h2>
<ol id="wishlistNode" class="container">
	<li>Wrist watch</li>
	<li>Life jacket</li>
	<li>Toy bulldozer</li>
	<li>Vintage microphone</li>
	<li>TIE fighter</li>
</ol>
</div>
</div>

The DnD Workhorse, dojo/dnd/Source

To enable drag and drop, dojo/dnd gives us a class called Source, which is basically just what it sounds like: a source for dragged items (as well as a target for dropped items). To instantly turn a DOM node into such a source, create a dojo/dnd/Source out of it:

require([ "dojo/dnd/Source",
	"dojo/domReady!" ],
    function(Source){
    var wishlist =
        new Source("wishlistNode");
    wishlist.insertNodes(false, [
        "Wrist watch",
        "Life jacket",
        "Toy bulldozer",
        "Vintage microphone",
        "TIE fighter"
    ]);
});

That’s all there is to it! View the single container DnD example. If you like to create UIs declaratively, instantiate the list in markup with data-dojo-type="dojo.dnd.Source" and use class="dojoDndItem" on draggable child nodes, like so:

<ol data-dojo-type="dojo.dnd.Source" id="wishlistNode" class="container">
	<li class="dojoDndItem">Wrist watch</li>
	<li class="dojoDndItem">Life jacket</li>
	<li class="dojoDndItem">Toy bulldozer</li>
	<li class="dojoDndItem">Vintage microphone</li>
	<li class="dojoDndItem">TIE fighter</li>
</ol>

Of course, when working declaratively, you have to make sure to add dojo/parser and dojo/dnd/Source to the loader’s deps list and enable parseOnLoad, but there you go. View the demo, declarative style.

What can you turn into a DnD source? Well sheesh, what can’t you turn into a DnD source? Take a look at the reference guide. The Source class will take into account the node type of your container when creating child nodes:

• If the container is <div> or <p>, it will create <div> nodes.
• If the container is <ul> or <ol>, it will create <li> nodes.
• If the container is a <table>, it will create a set of <tr><td> and add it to the table’s <tbody>.
• All other times, it will create <span> nodes.

So basically, turn whatever you want into a Source, and Dojo will intelligently set up your DOM. Pretty nifty! Out of the box, dojo/dnd/Source has quite a lot of functionality baked in:

• Multiple selection. Each container has the notion of a selection; click on an item and it’s “selected”. ⌘-click/ctrl-click or shift-click do multiple selection, just like in a regular application.
• Child node introspection. In addition to the insertNodes method demonstrated above, the Source provides a few methods to work with the list of child nodes:
  • getAllNodes() – returns a Dojo NodeList of the contained items.
  • forInItems(fn, ctx) – calls fn in the context of ctx for each contained node. Similar to dojo.forEach.
  • selectNone(), selectAll(), getSelectedNodes(), deleteSelectedNodes() – just what they sound like: methods for manipulating the selection state.
  • plus a few other things you can hook into for customizing the way the internal list gets handled. See the reference guide for details.
• Copy vs. move semantics. By default, nodes are moved when you drag them around. However, holding ⌘/ctrl and dragging performs a copy operation instead, similar to most desktop file managers. This is useful when you don’t want your DnD source to change in response to a user’s drag operations.
• Drag cancellation. This isn’t technically a property of the Source, but it’s worth noting here that pressing the Esc key cancels the current drag operation. You can do this programmatically, too, if you need to.
• Automatic avatar creation. The dojo/dnd framework uses “avatars” to represent the nodes you drag around. It creates these for you automatically, based on the data itself. You can customize this, of course; more on that later.

Using Multiple Sources

Of course, if you’re only using a single Source in your application, the move/copy distinction is only useful for duplicating nodes in the list. Let’s help Dylan expand. Check out Dylan’s Original Junk Outlet, version 2 (and the declarative version).

What have we changed? Well, for starters, we now have three Sources: the Catalog, the Cart, and the Wishlist. Now you can drag items back and forth between them to see multiple-container dojo/dnd in action. Some items are marked as “out of stock” (more on this in a bit), and… hey, some of these items aren’t junk at all—they’re food! Yes, while we weren’t looking, Dylan merged his junk outlet with Dylan’s Nutritious Dietarium, the company he uses to unload what he doesn’t eat from his garden.

DnD Item Types

The biggest change here is the introduction of item types. Notice the new accept and type properties:

require([ "dojo/dom-class", "dojo/dnd/Source", "dojo/domReady!" ],
		function(domClass, Source){
	var catalog = new Source("catalogNode",
		{ accept: [ "inStock", "outOfStock" ] });
	catalog.insertNodes(false, [
		{ data: "Wrist watch",        type: [ "inStock" ] },
		{ data: "Life jacket",        type: [ "inStock" ] },
		{ data: "Toy bulldozer",      type: [ "inStock" ] },
		{ data: "Vintage microphone", type: [ "outOfStock" ] },
		{ data: "TIE fighter",        type: [ "outOfStock" ] },
		{ data: "Apples",             type: [ "inStock" ] },
		{ data: "Bananas",            type: [ "inStock" ] },
		{ data: "Tomatoes",           type: [ "outOfStock" ] },
		{ data: "Bread",              type: [ "inStock" ] }
	]);
	catalog.forInItems(function(item, id, map){
		domClass.add(id, item.type[0]);
	});

	var cart = new Source("cartNode", { accept: [ "inStock" ] });
	var wishlist = new Source("wishlistNode",
		{ accept: [ "inStock", "outOfStock" ] });
});

In the declarative version, it looks like this:

<div class="catalogContainer">
    <h2>Catalog</h2>
    <ul data-dojo-type="dojo.dnd.Source" id="catalogNode" class="container"
		data-dojo-props="accept: [ 'inStock', 'outOfStock' ]" >
      <li class="dojoDndItem inStock" dndType="inStock">Wrist watch</li>
      <li class="dojoDndItem inStock" dndType="inStock">Life jacket</li>
      <li class="dojoDndItem inStock" dndType="inStock">Toy bulldozer</li>
      <li class="dojoDndItem outOfStock" dndType="outOfStock">
		Vintage microphone</li>
      <li class="dojoDndItem outOfStock" dndType="outOfStock">
		TIE fighter</li>
      <li class="dojoDndItem inStock" dndType="inStock">Apples</li>
      <li class="dojoDndItem inStock" dndType="inStock">Bananas</li>
      <li class="dojoDndItem outOfStock" dndType="outOfStock">
		Tomatoes</li>
      <li class="dojoDndItem inStock" dndType="inStock">Bread</li>
    </ul>
</div>

<div class="cartContainer">
    <h2>Cart</h2>
    <ol data-dojo-type="dojo.dnd.Source" id="cartNode" class="container"
		data-dojo-props="accept: [ 'inStock' ]" >
    </ol>
</div>
<div class="wishlistContainer">
    <h2>Wishlist</h2>
    <ol data-dojo-type="dojo.dnd.Source" id="wishlistNode"
		data-dojo-props="accept: [ 'inStock', 'outOfStock' ]"
		class="container">
    </ol>
</div>

Each DnD item can be given one or more types. In JavaScript, this is done by setting the type property of any object you pass to insertNodes. In markup, a comma-separated list of strings in the non-standard dndType attribute is used. Correspondingly, each DnD container can be given a list of item types to accept in the accept property. If left unspecified, the default type for all items and containers is “text”.

Here, we’re using the DnD type to denote whether an item is in stock or not, which then determines which items can be dropped where. The Cart only accepts items that are in stock, while the Wishlist accepts anything. If you drag around multiple items at once, you’ll notice that you can only drop a set of items on a container that accepts every type of item in the set—no partial drops allowed!

This is a good start, but there are still a few issues with this demo that need to be addressed:

• Unless you explicitly invoke copy semantics by pressing the appropriate key, dragging items removes them from the catalog, which doesn’t make much sense for this application.
• You can do a copy/drag, but then it becomes easy to duplicate items, which shouldn’t be possible.
• Using simple lists like this doesn’t really give a great user experience for an establishment as dignified as Dylan’s Original Junk Outlet / Dylan’s Nutritious Dietarium (DOJO/DND, get it? I kill me (groan)).

Let’s start with improving the appearance.

Customizing Item Creation

As was discussed above, the default drag and drop implementation is intelligent enough to create nodes according to the context in the DOM. However, if you want to display more than a string of text, the default can be lacking, since all it does is set the child node’s innerHTML property to whatever is assigned to data. Fortunately, dojo/dnd gives us a way to customize this: the creator function.

Since Dylan wants the product catalog to be both prettier and more informative, let’s give each item an image, short description, and quantity indicator. Our data structures will look like this:

{
    name: "Wrist watch",
    image: "watch.jpg",
    description: "Tell time with Swiss precision",
    quantity: 3
}

Instead of a string, we’ll pass these objects in the data property of the object passed to insertNodes. To create visual representations of this object, we’ll need a function we can pass to the dojo/dnd/Source’s constructor to transform it into a DOM node:

define([ "dojo/string", "dojo/dom-construct", "dojo/dom-class",
		"dojo/dnd/Source", "dojo/text!./itemTemplate.html",
		"dojo/text!./avatarTemplate.html" ],
		function(stringUtil, domConstruct, domClass, Source,
			template, avatarTemplate){
	// create the DOM representation for the given item
	function catalogNodeCreator(item, hint){
		var node = domConstruct.toDom(stringUtil.substitute(
			hint === "avatar" ? avatarTemplate : template, {
				name: item.name || "Product",
				imageUrl: "images/" + (item.image || "_blank.gif"),
				quantity: item.quantity || 0,
				description: item.description ? "<br><span>"
					+ item.description + "</span>" : ""
			})),

			type = item.quantity ? [ "inStock" ] : [ "outOfStock" ];

		return { node: node, data: item, type: type };
	}
});

Our item template looks like this:

<tr>
	<td class="itemImg dojoDndHandle"><img src="${imageUrl}"></td>
	<td class="itemText">${name} ${description}</td>
	<td class="itemQty">${quantity}</td>
</tr>

Our avatar template looks like this:

<table>
	<tr>
		<td class="itemImg"><img src="${imageUrl}"></td>
		<td class="itemText">${name}</td>
	</tr>
</table>

Items of note from this code:

• We’re going to be using tables for our DnD sources now to help improve the presentation.
• We’re dynamically choosing the DnD item type based on the quantity provided.
• The creator function also accepts a second optional parameter, hint. When this is set to “avatar”, we’re being asked to create a DOM representation of the avatar, so our function takes that into account. For us, this means that we skip displaying the description and quantity when we make an avatar, and we put the entire avatar into its own table, since the default node that contains the avatar(s) is itself a table (and we don’t want to ruin our DOM).

At this point, we can introduce version 3 of the demo (we’re doing it all programmatically from here on out, so there’s no declarative version). There’s a substantial overhaul in the appearance now thanks to our table-based DnD sources. We’ve also put the wishlist and shopping cart into a couple of dijit/TitlePanes so we can easily toggle their visibility. This change demonstrates a couple of concepts:

Creating Pure Targets

var cart = new Target("cartPaneNode", { accept: [ "inStock" ] });

We have a new class here: dojo/dnd/Target. This is just a thin wrapper around dojo/dnd/Source that sets this.isSource to false, making it a pure target. You can drop items on it, but can’t drag them back out again! Incidentally, you can freely manipulate this field at runtime on a regular Source object; we’ll do that later on.

Changing the “Drop Parent”

cart.parent = dom.byId("cartNode");

Here, we’re using the dojo/dnd/Source’s parent property to change which element dragged items are actually inserted into. In this case, we’re changing so that when users drop items on the TitlePane, they’ll actually be inserted to the enclosed <table id="cartNode">.

Our store is starting to look pretty good, but there are still some other things we can do to demonstrate a few more concepts.

Handling Events

The drag and drop framework uses Dojo’s pub/sub system to handle event communication. We can polish up a few things if we take advantage of this. For example, it would be nice if we could show the number of items in the wishlist and cart when they’re closed so users don’t need to open them to check. It would also clean things up visually if we cleared the selection states of our containers when we drop an item. By listening for topics, we can do both.

Building a Drop Handler

Let’s hook into the drop notification. We can either listen for the DnD pub/sub topics directly or we can connect to event handlers on DnD objects depending upon what sort of action we are performing.

// sets the count of items in a TitlePane
function setListCount(){
	query(".count", this.node)[0].innerHTML = this.getAllNodes().length;
}

// update the cart’s displayed item count when dropped on
aspect.after(cart, "onDrop", setListCount);

// update the wishlist’s displayed item count when dropped on
aspect.after(wishlist, "onDrop", setListCount);

Here, we connect to the cart’s and wishlist’s onDrop event to update the number of items in the respective list when an item is dropped. Unlike onDndDrop, which fires for all DnD elements on the page regardless of whether or not they were dropped on, the onDrop event only fires for the target of the drop, so is suitable when you only want to perform an action on a single target.

Listening Directly to the Topics

Since I mentioned that you can subscribe to the topics yourself when it makes sense, let’s cook up an example. When you start dragging items around, it’s not completely intuitive where you’re allowed to drop them; you have to keep dragging until the avatar turns green. On top of that, there’s no immediate feedback that your drop was successful. We can create a better experience than that. First, we create some functions to highlight valid targets:

// highlights available drop targets
function highlightTargets(show, source, nodes){
	domClass.toggle("wishlistPaneNode", "highlight", show);
	domClass.toggle("cartPaneNode", "highlight",
			show && arrayUtil.every(nodes, function(node){
		return domClass.contains(node, "inStock");
	}));
}

// glows the target of a drop
function glowTarget(source, nodes, copy, target){
	domClass.add(target.node, "glow");
	setTimeout(lang.hitch(domClass, "remove",
		target.node, "glow"), 1000);
}

Then, in our initialization function, we hook them up to the DnD system:

// highlight valid drop targets when a drag operation is started
// (/dnd/start)
topic.subscribe("/dnd/start", lang.partial(highlightTargets, true));

// remove the highlight when a drag operation is finished
// (/dnd/cancel or /dnd/drop)
topic.subscribe("/dnd/cancel, /dnd/drop",
	lang.partial(highlightTargets, false));

// give the target of a drop an extended glow
topic.subscribe("/dnd/drop", glowTarget);

Since we’re listening to the topic broadcast itself, we know these functions will only run once per event. Manipulating a bit of CSS with dojo/dom-class helps make the drag and drop system a bit friendlier for users, and that’s always a good thing.

Armed with knowledge of how to run code at various times during the drag and drop lifecycle, we can see that it wouldn’t be difficult to extend this further. For example, our item quantities currently only determine whether or not you can drop something on the shopping cart; they could easily be updated when they are dropped on the Cart (but not the Wishlist!). And of course, this little storefront doesn’t have any prices! In a real store you’d want to add that, and probably upgrade setupCartTitle to calculate and display a subtotal.

Avoiding Duplicate Items

One thing I hadn’t pointed out before was that in version 3 of our demo, in addition to specifying the node creator function when instantiating our Source objects, we also passed a parameter copyOnly: true. This overrides the default drag semantics and performs a copy operation by default instead of a move. This is nice because it means we can avoid removing items from the catalog(s) when we drag them around. The downside is that if you copy an item on the container where it already lives, it duplicates the item.

Logically, this shouldn’t happen because we’re not specifying the accept type on the catalogs, so they should default to "text" and keep us from dropping the products on them (we’re explicitly giving them different types, remember). If you dig into the Dojo source, however, you’ll see that the function that checks for matches between item types and container accept values automatically accepts “self drops”, short circuiting the item type check. Often, that’s the correct behavior, but for our copyOnly–style DnD here, this is backwards. Fortunately again, overriding this is easy: just set the selfAccept property to false.

Take a look at version 4 of our demo to see it all working together. Some of the code has been reorganized and/or moved to an external file to reduce clutter, but the new stuff is all there if you view the page source.

Tweaking DnD Behavior

The final thing left to talk about for this demo is the set of buttons we introduce in version 4. We have buttons to clear the wishlist and shopping cart now, but notice the buttons at the bottom of the page: these demonstrate different ways to change the way DnD behaves. You can read the code to see how they work, but here’s what they do:

• Enable DnD (sets isSource) – If you’ve ever wondered how to turn DnD on and off completely, here’s one way. This toggles the isSource member of each of our sources. I mentioned this earlier, but recall that when this is false, the manager won’t initiate any drag operations. Objects will still accept drops, but if there’s nothing acting as a source, we’ve effectively disabled the DnD system.
• Drag via handles only (sets withHandles) – If you give a DOM node the dojoDndHandle class, dojo/dnd will consider it a handle. Each Source has a member variable withHandles that determines whether you can drag any part of an item, or just the handle. This demo sets up the product images as the handles, so if you toggle the button, you’ll see the drag behavior change accordingly.

Finishing Up

For reference, here are the steps we’ve taken so far:

• Step 0: skeleton page
• Step 1: a single list
• Step 2: multiple lists
• Step 3: customizing item creation
• Step 4: listening to events

There’s quite a lot left to discuss in dojo/dnd that we haven’t touched on. For example, there’s been little discussion about the CSS classes that are used by DnD (you can see what this demo uses in dnd.css). We also didn’t discuss how to cleanly set up your own custom DnD sources by extending dojo/dnd/Source using dojo/_base/declare. A lot of dojo/dnd’s internals are specifically set up to be easy to override with your own code so you can customize just about any part necessary. These are all areas that you should explore on your own to get a feel for how DnD can be useful in your own projects. You can download an archive of the entire demo so you can play with it yourself locally.

Happy dragging and dropping!

Related posts:

1. Dojo Drag and Drop, Part 1: dojo.dnd
2. Queued: Drag and Drop in the Queue
3. Inside Dojo DnD: Drag Handles

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 is so dedicated to providing you with the highest quality Dojo Toolkit education in the industry that we will be in 11 states, providing 22 Dojo Workshops throughout 2012.  Whether you want to learn the basics of Dojo or sharpen your Dojo skills, we have a workshop just for you.  We guarantee that all of our Dojo Workshops will be taught by our expert engineers.  We promise you won’t be subjected to listening to some trainer who can’t live without his slides.  Wondering if our Dojo Workshops will cover Dojo 1.7?  The answer is yes.

Register in 2011. Attend in 2012. Where will you start your 2012 Year of Dojo celebration? Check out the full list of SitePen’s 2012 Dojo workshops.

Dojo Toolkit has some vocal fans. Here’s a random sample of what we’ve found recently on Twitter:

Have I been living under a rock? How come I’ve never come across Dojo toolkit? I am going to have to learn the ins and outs… @ deshiknaves

Working on my #Dojo 1.7 presentation, it’s so tough to pick the best new bits in 1.7, there’s so much amazing stuff! @ thomasj

i’ve been working with design part of this system and found out that #dojo is better than #JQuery in terms of performance.. #toolkit @ hayadeen

Psst! What’s that you say?  You want to learn Dojo in January? No problem! Join us in Las Vegas, NV or Raleigh, NC. (Did we mention all of our 2012 workshops will cover Dojo 1.7?)

jUMP into Dojo - Las Vegas, NV - January 9, 2012
jUMP into Dojo is the best starting point for any developer wanting to learn about Dojo, Ajax and Rich Internet Application development. This workshop gives a rapid introduction to the capabilities of Dojo as well as the experience in applying them to solve real-world problems.  And did we mention this one is in Las Vegas?  Enuff said.

Dojo Master – Raleigh, NC - January 18-19, 2012
Dojo Master is our black diamond workshop, taking the advanced scripter through the expert techniques needed when tackling the unique problems web applications can bring. This workshop is best for the intermediate-advanced developer who has used Dojo in several projects and who wants to get the most out of Dojo and JavaScript to make reliable and scalable applications.

What are you waiting for? Register today! Use promo code IHEARTDOJO and get 10% off!

Related posts:

1. Eleven Trends for 2012: The Year of Dojo
2. The Year of Dojo is Here!
3. Dojo. Dontcha know? SitePen. Dojo. Minnesota.

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!

Dylan had this to say about his time at #RWX2011:

The level of interest in AMD, object stores, and mobile is impressive. And the excitement around the potential of xstyle and put-selector was also very cool to see. The community is seemingly rabid for new tools and features that make development easier, and it’s incredible to be part of that.

And if you haven’t seen this already- Dojo 1.7 Released!

We have made all of Dylan’s Rich Web Experience 2011 (and many other) presentations available here.  Don’t forget to follow SitePen on Twitter and Google+!

Related posts:

1. Rich Web Experience 2011- Day 2- Dojo 2.0
2. SitePen’s Dylan Schiemann to Keynote at Rich Web Experience 2011
3. Rich Web Experience 2011- Day 1 – Killer Keynote

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!