Critical Masses Technology, Inc.

Welcome to the first in a series on how to implement drag and drop behavior in your XPages applications using the Dojo drag and drop toolkit. I’d be in remiss if I didn’t take the opportunity to recommend that XPages beginners refer to Declan Lynch’s excellent and easy to follow Learning XPages tutorial series to bring you up to speed. Declan’s tutorial was also an inspiration, of sorts, for me to embark on this series. I leaned heavily –and borrowed liberally- from sitepen’s Dojo Drag and Drop, Part 1: dojo.dnd article, and encourage all readers to digest this excellent tutorial as well. DISCLAIMER: I am learning as I go along, so please forgive any discrepancies and –as always- comment liberally.

Objectives

In this tutorial

• Overview of Dojo Drag and Drop
  • Containers, sources, targets
  • Multiple selection, copying
• Issues implementing drag and drop in XPages
  • Resource referencing
  • Custom dojo attributes
• Basic drag and drop in XPages
  • Rearranging an ordered list
  • Rearranging a datatable
  • Rearranging view items
• Advanced drag and drop
  • Moving items from one list/table to another
  • Embellishing drag handles
  • Listening to drag and drop events
• Sprinkle in some AJAX
  • About JSON
  • Building a JSON request
  • Building a JSON request response

Prerequisites

• Basic understanding of XPages
• Javascript

System requirements

• Lotus Domino Designer 8.5 or higher

About

Adding drag and drop abilities to your IBM Lotus Domino XPages application using the Dojo Javascript toolkit.

Overview of Dojo Drag and Drop

Containers, sources, targets

The Dojo framework, supplied and baked into IBM’s XPages JSP implementation in Lotus Domino is a powerful collection of widgets, functions, events and resources that enrich the end-user experience in modern, Javascript-enabled and DOM-aware web browsers. A lot of the Dojo functionality, though, may not be explicitly exposed in the componentry IBM supplies. The developer must therefore explicitly declare the use of such widgets, such as the slider control used in the 8.5 discussion template, with markup in the source view of the XPage. This becomes a bit more involved as we shall see later when the need for enhancing the functionality of an existing control, that was dragged into the XPage in Design view arises.

Of particular interest to us is the drag and drop (dojo.dnd) API of Dojo 1.1, which is the version supplied with XPages. Dojo drag and drop enables the contents of any collection on your web page to be dragged and dropped onto any other collection. The collections, commonly lists or tables, are collectively grouped into containers. Containers may be drag sources, that is, they contain items that will be the initiators of a drag and drop operation; drag targets, receivers of dragged and dropped items or both. Containers are declared in the HTML markup with an id of container and Dojo’s custom dojoType tag with a value of dojo.dnd.Source. Our first several examples, in fact, will consist of containers used as both targets and receivers to illustrate how to reorder a list or table rows with dojo.dnd. Items are denoted by the class name of dojoDndItem. To round out a complete declarative example, specify the use of the Dojo.dnd framework on your web page with dojo.require("dojo.dnd.Source") and turn on Dojo’s parser with the djConfig="parseOnLoad:true" directive.

Example A: Basic List Drag and Drop (right-click in the example frame to view source)

Let’s examine the source page HTML header’s CSS section more thoroughly.

<style type="text/css">
@importurl(http://o.aolcdn.com/dojo/1.1.1/dojo/resources/dojo.css);
@importurl(http://o.aolcdn.com/dojo/1.1.1/dojo/resources/dnd.css);
...
.dojoDndItem{
	padding:3px;
}
 
.dojoDndItemOver{
	background-color:#ededed;
	cursor:pointer;
}
...
</style>

To begin with, the header (lines 2 and 3) contains the CSS include directives that the Dojo toolkit uses, including style information that Dojo.dnd uses. For this first example, we are using the publicly available Dojo toolkit hosted by AOL’s content developer’s network, although in later examples we will be using the toolkit on our Domino servers (or in the Domino directory of our Notes Designer clients.) We round out the CSS portion of the header with some additional style information that prettifies the drag and drop operation by styling elements when they are moused over and styling the drop target’s position to make it easier to discern where the source will be inserted. This information belongs in a separate CSS file as well, but for the succinctness of this example, I’ve included it in the HTML source. (I’ve removed the copyright and accreditation portion of the CSS from this display, although it is present in its entirety in the example’s source code.)

Now let’s take a look at the script portion of the header.

<script type="text/javascript" src="http://o.aolcdn.com/dojo/1.1.1/dojo/dojo.xd.js" djConfig="parseOnLoad:true"></script>
<script type="text/javascript">
	dojo.require("dojo.dnd.Source");
</script>

Again, we are sourcing our Dojo script library from AOL’s CDN. We are actually using a special version of the Dojo core library called dojo.xd. This is the cross-domain version that allows the Dojo script to fetch files from AOL. (I’m not sure of the details of this, but it may have something to do with code signing and security, i.e. cross-site scripting attacks.) For our later examples, we will be using the Dojo library on our own host, so there will be no cross-domain sourcing issues. In our later examples we will thus be referring to the file dojo.js instead of dojo.xd.js. The added parameter in our Javascript include tells Dojo to parse the body of the HTML file on the onLoad event, which will parse and register any elements appropriately tagged as Dojo objects. This causes Dojo to act on and modify the HTML elements we’ve specified as Dojo-enabled later on in the document and effectively “turns on” our Dojo-enhanced functionality. The XPages property inspector allows us to enable or disable parseOnLoad. For reasons to be explained later in this tutorial, we will not be using the parseOnLoad function but will instead explicitly order Dojo to parse after we perform some initial housekeeping.

<ol dojoType="dojo.dnd.Source" class="container">
  <li class="dojoDndItem">Apples</li>
  <li class="dojoDndItem">Oranges</li>
  <li class="dojoDndItem">Pears</li>
  <li class="dojoDndItem">Kiwis</li>
  <li class="dojoDndItem">Nectarines</li>
  <li class="dojoDndItem">Bananas</li>
</ol>

Here is the actual drag and drop ordered list in the body of our document. The flag that tells Dojo to look at this list and turn it into a dnd object is the special attribute dojoType="dojo.dnd.Source" on line 1. Individual items are flagged as draggable and droppable with the class definition of dojoDndItem (lines 2-7)

NOTE: Although we can easily create Dojo.dnd container lists programmatically, for the duration of this tutorial series we will be focusing on using the declarative approach as much as possible to integrate as simply as possible into the XPages designer environment. Advanced developers can use the declarative approach as a stepping stone to sophisticated UI development and manipulation using more of the programmatic approach as they see fit.

Multiple selection, copying, Avatars

Dojo.dnd’s power, though is more than skin deep. Dojo.dnd allows you to multiple select sources by holding down the Control or Command key (Windows or Macintosh, respectively) during item selection. Shift-clicking two items will select the items and anything in between them as well for dragging. You can try this on Example A, above.

The default action for Dojo.dnd targeting is to move the dragged objects to the target location, Holding the Control or Command key while dragging changes the operation to a copy, in which the sources items remain and copies of the originals are placed on the target. This can also be viewed by testing Example A, above.

You may notice while dragging and dropping that a useful “ghost” of the dragged item or items is positioned by your mouse pointer. This is referred to in Dojo.dnd as an Avatar. Avatars are created dynamically by Dojo.dnd from the source data and can be customized.

NEXT: Issues implementing drag and drop in XPages and Basic drag and drop in XPages

HUMBLE REQUEST: Your feedback in the comments section are invaluable in improving this site and its contents. Please rate me as an author using the Scribnia widget in the right sidebar of this blog or click here.