Critical Masses Technology, Inc.

This is part 5 of a series on drag and drop with Xpages and Dojo.

Our last installment showed how to drop two data containers on a page that can accept Dojo drag and drop elements between them and set up the data structure to facilitate the processing of these events –namely associating the items with Notes document UNIDs. We also left off with a teaser question that we’ll get to later in this installment.

Collecting our drag & drop data

Now that we’ve instrumented our table rows so that we can semantically determine their relationship to backend Notes documents, we need to collect the rows we’ve acted upon in a UI drag & drop event and the target container that they have been dropped on. The event we’ll be listening to is the target container’s (the table we drop tables rows in to) “onDndDrop” event, an event that is published as part of the Dojo.dnd container class. We subscribe the target container by appending a dojo.connect call (line 5, see code block below) to the initialization function for the table from the previous lesson, passing the connect function the parameters of the subscribing object (the container) the event to listen to and the function to be called on the event:

function initDndTable(tid) {
    setUNIDS(tid,true,true,2);
    var tVar = new dojo.dnd.Source(tid);   
    dojo.parser.parse();
    dojo.connect(tVar,"onDndDrop", movedata);
}

function movedata(source, nodes, copy){
    if(dojo.dnd.manager().target !== this){ return; }
    targetName = dojo.dnd.manager().target.node.id;
    tNameArr = targetName.split(":");
    targetName = tNameArr[tNameArr.length - 1];
    var docsArr = new Array();
    for (i=0;i<nodes.length;i++){
        docsArr.push(nodes[i].id);
    }
    var obj = {};
    obj.table = targetName;
    obj.docs = docsArr;   
    var tableDataJSON = dojo.toJson(obj);
    var stashField = document.getElementById(hiddenFldId);
    stashField.value = tableDataJSON;
}//movedata

We’ll finish up this function in a moment, but for now take note that line 2 is to make sure that we’re only executing the code when the container that has subscribed to the event is the target of the DnD operation as the “onDndDrop” event is fired no mater where the nodes are dropped (a peculiarity of the Dojo event topic system.) On Line 3 we get the name of the receiving container from the dojo.dnd.Manager object, as this information is not passed directly to the event. The receiver is useful for us to determine the eventual operation to perform on the backend with the collection of document UNIDs we’re gathering. Note that we’re only interested in the least significant component of targetName, which corresponds to the IDs of our XPages’ data tables. Lastly, lines 10-14 take the collected data and place it in a Javascript object that we serialize to JSON to tuck neatly into our hidden field.

Performing the Partial Submit

Next we need to perform the partial submit to update the Domino backend with our move. Like the R3 days of yore, the simplest way to execute server side code on a page refresh is to embed it in a computed field, which we’ll do. Let’s drop a panel onto our XPage and drop a computed field into the panel. Then move our existing hidden field into the panel as well, taking care to place it after the computed field. Like the old days, order of placement matters for order of execution. (See screenshot.)

The goal here is to trigger a partial refresh of the panel that contains the computed field and hidden field components on the drop event. Placing the computed field with the ServerSide Javascript (SSJS) logic for updating the Domino backend before the hidden field ensures that the hidden field will be recomputed for browser display properly. The logic for the move operation in SSJS gets put into the computed field’s value:

try {
    dragdata = getComponent("inputHidden1").getValue();
    if (dragdata == "") return;
    ddObject = fromJson(dragdata);
    archiveAction = (ddObject.table == "dataTable2") ? "Y" : "N";   
    for (i=0;i<ddObject.docs.length;i++){
        doc = database.getDocumentByUNID(ddObject.docs[i]);
        doc.replaceItemValue("Archive",archiveAction);
        doc.save(true,true);
    }
    getComponent("inputHidden1").setValue("")   
}
catch (e) {
    print(e)
}

Lines 2 & 3 (obviously) halt execution of the script if there’s nothing to do, especially on initial page load. Line 4 reconstitutes the Javascript object from the JSON representation we stashed in the hidden field in our earlier client-side script. In our example the archive action is determined by the target table name. If we dropped documents onto the archive table, we’ll set their “Archive” field value to “Y.” We then cycle through the UNIDs, grab the document objects from the database and perform the updates’ Lastly, we reset the hidden field back to empty. Note that if we didn’t place the computed field before the hidden field, the hidden field would not be updated and the client value after the refresh would still contain the JSON data we stashed there.

Now the only thing we need to do to complete the demo is to perform the partial submit on the drag and drop event. We can programmatically perform the submit from the client using the XSP.PartialRefreshPost method (hat tip: Jeremy Hodge) by appending the code to our movedata function:

XSP.partialRefreshPost(computePanelId, {
        onStart: null,
        onComplete: null,
        onError: null                       
    }) 

The variable computePanelId refers to the panel that contains our computed field and hidden (stash) field. We’ll add this variable to the script block component’s code in our XPage as follows:

var computePanelId = "#{id:computePanel1}"

Saving and running the completed XPage will result in a drag and drop operation that will update the backend in real-time on the drop event in the client browser!

The UI Gotcha (paginators)

If you’ve been following along, you’ll know that there’s a UI “gotcha” that I’ve alluded to at the end of the last lesson. Our drag and drop functionality is predicated on a Javascript initialization that creates the dojo.dnd containers and preps them for DnD operations. If we use a partially refreshing data component such as a view or data table, however, the table rows only partially refresh, and the dojo containers are not reinitialized with the new data. Thus using your XPage components’ pagers to page through a data container breaks the functionality. In theory, Dojo provides an “onComplete” event to fire off a script after a partial occurs that should allow us to trigger our initializations and reset our DnD functionality. As Domino is computing the partial refresh events for us, however, how to do this is not obvious. Once again, Jeremy Hodge to the rescue with a method to overrode the partial refresh event listener on the page to add a custom onComplete handler that calls our initDndTable function with the table ID we need to refresh taken from the event’s refresh ID parameter:

XSP._inheritedPartialRefresh = XSP._partialRefresh;
XSP._partialRefresh = function(method,form,refreshId,options){
    dojo.publish("/XSP/partialRefresh", new Array(method,form,refreshId,options));
    this._inheritedPartialRefresh(method,form,refreshId,options);
}
dojo.subscribe("/XSP/partialRefresh", null, function(method,form,refreshId,options) {
    if ((refreshId == mainTableId) || (refreshId == archiveTableId)){   
        if (options.onComplete)
            options._inheritedOnComplete = options.onComplete;
        options.onComplete = function() {
            initDndTable(refreshId);
            if (this.inheritedOnComplete)
                this.inheritedOnComplete();
        }
    }
}); 

The script overrides the XSP._partialrefresh method, taking care to call the inherited functionality when done with out custom code. Line 7 adds the custom onComplete functionality specifically to our two data tables and consists of triggering the initDndTable function with the table id to refresh. Remember in our last lesson when we alluded to the value of breaking out the table initialization into a separate function to be fired for each table? This is the reason. Drop this override code into your script library to complete the demo and generate a fully functioning drag and drop environment with paged data tables. Read Jeremy’s whole post on the XPages Blog for more information on how this works.

The complete source for this demo can be downloaded here.

Learning More

We’ev only touched on the capabilities of Dojo’s DND framework in this series. For example, you may want to learn how to enable or disable the copy feature of your DnD elements or add custom event handlers and triggers. Sitepen’s Dojo Drag and Drop, Part 1: dojo.dnd is an excellent starting point for learning DnD and contains links to other DnD related articles on the sitepen blog. The Dojocampus reference guide on Dojo.dnd is also useful, as is the API reference.

Rate me as an author on Scribnia!