ASP.NET Ajax Extender for multi-column widget drag & drop
My open source Ajax Start Page www.dropthings.com has an ASP.NET Ajax Extender which provides multi-column drag & drop for widgets. It allows reordering of widgets on the same column and also drag & drop between column. It also supports client side notification so that you can call web service and store the position of the widgets behind the scene without (async) postback.
I first thought of going for a plain vanilla Javascript based solution for drag & drop. It requires less code, less architectural complexity and provides better speed. Another reason was the high learning curve for making Extenders in proper way in Asp.net Ajax given that there’s hardly any documentation available on the web (during the time of writing this blog). However, writing a proper extender which pushes Asp.net Ajax to the limit is a very good way to learn under-the-hood secrets of Asp.net Ajax framework itself. So, the two extenders I will introduce here will tell you almost everything you need to know about Asp.net Ajax Extenders.
Ajax Control Toolkit comes with a DragPanel extender which I could use to provide drag & drop support to panels. It also has a ReorderList control which I could use to provide reordering of items in a single list. Widgets are basically panels that flow vertically in each column. So, it might be possible that I could create reorder list in each column and use the DragPanel to drag the widgets. But I could not use ReorderList because:
ReorderListstrictly uses Html Table to render its items in a column. I have no table inside the columns. Only one Panel is there inside an UpdatePanel.ReorderListtakes a Drag Handle template and creates a drag handle for each item at runtime. I already have drag handle created inside a Widget which is the widget header. So, I cannot allowReorderListto create another drag handle.- I need client side callback on drag & drop so that I can make Ajax calls and persist the widget positions. The callback must give me the Panel where the widget is dropped, which is dropped and at what position.
Next challenge is with the DragPanel extender. The default implement of Drag & Drop in Ajax Control Toolkit has some problems:
- When you start dragging, the item becomes absolutely positioned, but when you drop it, it does not become static positioned. There's a small hack needed for restoring the original position to "static".
- It does not put the dragging item on top of all items. As a result, when you start dragging, you see the item being dragged below other items which makes the drag get stuck especially when there's an IFRAME.
So, I have made a CustomDragDropExtender and a CustomFloatingExtender. CustomDragDropExtender is for the column containers where widgets are placed. It provides the reordering support. You can attach this extender to any Panel control.
Here's how you can attach this extender to any Panel and make that Panel support drag & drop of Widgets:
1: <asp:Panel ID="LeftPanel" runat="server" class="widget_holder" columnNo="0">
2: <div id="DropCue1" class="widget_dropcue">
3: </div>
4: </asp:Panel>
5: 6: <cdd:CustomDragDropExtender ID="CustomDragDropExtender1"
7: runat="server"
8: TargetControlID="LeftPanel"
9: DragItemClass="widget"
10: DragItemHandleClass="widget_header"
11: DropCueID="DropCue1"
12: OnClientDrop="onDrop" />
<cdd:CustomDragDropExtender> offers the following properties:
- TargetControlID – ID of the Panel which becomes the Drop zone
- DragItemClass – All child elements inside the Panel having this class will become draggable. E.g. Widget DIV has this class so that it can become draggable.
- DragItemHandleClass – Any child element having this class inside the draggable elements will become the drag handle for the draggable element. E.g. Widget Header area has this class, so it acts as the drag handle for the Widget.
- DropCueID – ID of an element inside the Panel which acts as Drop Cue.
- OnClientDrop – Name of a Javascript function which is called when widget is dropped on the Panel.
LeftPanel becomes a widget container which allows widgets to be dropped on it and reordered. The DragItemClass attribute on the extender defines the items which can be ordered. This prevents from non-widget Html Divs from getting ordered. Only the DIVs with the class "widget" are ordered. Say there are 5 DIVs with the class named "widget". It will allow reordering of only these five divs:
1: <div id="LeftPanel" class="widget_holder" >
2: <div class="widget"> ... </div>
3: <div class="widget"> ... </div>
4: 5: <div class="widget"> ... </div>
6: <div class="widget"> ... </div>
7: <div class="widget"> ... </div>
8: 9: <div>This DIV will not move</div>
10: <div id="DropCue1" class="widget_dropcue"></div>
11: </div>
When a widget is dropped on the panel, the extender fires the function specified in OnClientDrop. It offers standard Ajax Events. But unlike basic Ajax events where you have to programmatically bind to events, you can define property and specify the function name to call. So, instead of doing this:
1: function pageLoad( sender, e ) {
2: 3: var extender1 = $get(‘CustomDragDropExtender1’);
4: extender1.add_onDrop( onDrop ); 5: 6: }You can do this:
1: <cdd:CustomDragDropExtender ID="CustomDragDropExtender1"
2: runat="server"
3: OnClientDrop="onDrop" />
When the event is raised, the function named onDrop gets fired. This is done with the help of some handy library available in ACT project.
When the event is fired, it sends the container, the widget and the position of the widget where the widget is dropped.
1: function onDrop( sender, e )
2: {3: var container = e.get_container();
4: var item = e.get_droppedItem();
5: var position = e.get_position();
6: 7: //alert( String.format( "Container: {0}, Item: {1}, Position: {2}", container.id, item.id, position ) );
8: 9: var instanceId = parseInt(item.getAttribute("InstanceId"));
10: var columnNo = parseInt(container.getAttribute("columnNo"));
11: var row = position;
12: 13: WidgetService.MoveWidgetInstance( instanceId, columnNo, row ); 14: }
The widget location is updated by calling the WidgetService.MoveWidgetInstance.
CustomDragDropExtender has 3 files:
- CustomDragDropExtender.cs – The server side extender implementation
- CustomDragDropDesigner.cs – Designer class for the extender
- CustomDragDropExtender.js – Client side scriptfor the extender
Server side class CustomDragDropExtender.cs has the following code:
1: [assembly: System.Web.UI.WebResource("CustomDragDrop.CustomDragDropBehavior.js", "text/javascript")]
2: 3: namespace CustomDragDrop
4: {5: [Designer(typeof(CustomDragDropDesigner))]
6: [ClientScriptResource("CustomDragDrop.CustomDragDropBehavior", "CustomDragDrop.CustomDragDropBehavior.js")]
7: [TargetControlType(typeof(WebControl))]
8: [RequiredScript(typeof(CustomFloatingBehaviorScript))]
9: [RequiredScript(typeof(DragDropScripts))]
10: public class CustomDragDropExtender : ExtenderControlBase
11: {12: // TODO: Add your property accessors here.
13: //
14: [ExtenderControlProperty]15: public string DragItemClass
16: { 17: get 18: {19: return GetPropertyValue<String>("DragItemClass", string.Empty);
20: } 21: set 22: {23: SetPropertyValue<String>("DragItemClass", value);
24: } 25: } 26: 27: [ExtenderControlProperty]28: public string DragItemHandleClass
29: { 30: get 31: {32: return GetPropertyValue<String>("DragItemHandleClass", string.Empty);
33: } 34: set 35: {36: SetPropertyValue<String>("DragItemHandleClass", value);
37: } 38: } 39: 40: [ExtenderControlProperty]41: [IDReferenceProperty(typeof(WebControl))]
42: public string DropCueID
43: { 44: get 45: {46: return GetPropertyValue<String>("DropCueID", string.Empty);
47: } 48: set 49: {50: SetPropertyValue<String>("DropCueID", value);
51: } 52: } 53: 54: [ExtenderControlProperty()]55: [DefaultValue("")]
56: [ClientPropertyName("onDrop")]
57: public string OnClientDrop
58: { 59: get 60: {61: return GetPropertyValue<String>("OnClientDrop", string.Empty);
62: } 63: set 64: {65: SetPropertyValue<String>("OnClientDrop", value);
66: } 67: } 68: 69: } 70: }Most of the code in the extender defines the property. The important part is the declaration of the class:
1: [assembly: System.Web.UI.WebResource("CustomDragDrop.CustomDragDropBehavior.js", "text/javascript")]
2: 3: namespace CustomDragDrop
4: {5: [Designer(typeof(CustomDragDropDesigner))]
6: [ClientScriptResource("CustomDragDrop.CustomDragDropBehavior", "CustomDragDrop.CustomDragDropBehavior.js")]
7: [TargetControlType(typeof(WebControl))]
8: [RequiredScript(typeof(CustomFloatingBehaviorScript))]
9: [RequiredScript(typeof(DragDropScripts))]
10: public class CustomDragDropExtender : ExtenderControlBase
11: {The extender class inherits from ExtenderControlBase defined in ACT project. This base class has additional features over Ajax runtime provided Extender base class. It allows you to define RequiredScript attribute, which makes sure all the required scripts are downloaded before the extender script is downloaded and initialized. This extender has dependency over another extender named CustomFloatingBehavior. It also depends on ACT’s DragDropManager. So, the RequiredScript attribute makes sure those are downloaded before this extender’s script is downloaded. The ExtenderControlBase is a pretty big class and does a lot of work for us. It contains default implementations for discovering all the script files for the extender and rendering them properly.
The [assembly:System.Web.UI.WebResource] attribute defines the script file containing the script for extender. The script file is an embedded resource file.
[ClientScriptResource] attribute defines the scripts required for the extender. This class is also defined in ACT. ExtenderControlBase uses this attribute to find out which .js files are working for the extender and renders them properly.
The challenge is to make the client side javascript for the extender. On the js file, there’s a Javascript pseudo class:
1: Type.registerNamespace('CustomDragDrop');
2: 3: CustomDragDrop.CustomDragDropBehavior = function(element) {
4: 5: CustomDragDrop.CustomDragDropBehavior.initializeBase(this, [element]);
6: 7: this._DragItemClassValue = null;
8: this._DragItemHandleClassValue = null;
9: this._DropCueIDValue = null;
10: this._dropCue = null;
11: this._floatingBehaviors = [];
12: }During initialize, it hooks on the Panel it is attached to and the drop cue to show while drag & drop is going on over the Panel:
1: CustomDragDrop.CustomDragDropBehavior.prototype = { 2: 3: initialize : function() {
4: // Register ourselves as a drop target.
5: AjaxControlToolkit.DragDropManager.registerDropTarget(this);
6: //Sys.Preview.UI.DragDropManager.registerDropTarget(this);
7: 8: // Initialize drag behavior after a while
9: window.setTimeout( Function.createDelegate( this, this._initializeDraggableItems ), 3000 );
10: 11: this._dropCue = $get(this.get_DropCueID());
12: },After initializing the DragDropManager and marking the Panel as a drop target, it starts a timer to discover the dragable items inside the panel and create Floating behavior for them. Floating behavior is the one which makes a DIV draggable.
FloatingBehavior makes one DIV freely draggable on the page. But it does not offer drop functionality. DragDropBehavior offers the drop functionality which allows a freely moving DIV to rest on a fixed position.
Discovering and initializing floating behavior for the dragable items is the challenging work:
1: // Find all items with the drag item class and make each item
2: // draggable
3: _initializeDraggableItems : function()
4: {5: this._clearFloatingBehaviors();
6: 7: var el = this.get_element();
8: 9: var child = el.firstChild;
10: while( child != null )
11: {12: if( child.className == this._DragItemClassValue && child != this._dropCue)
13: {14: var handle = this._findChildByClass(child, this._DragItemHandleClassValue);
15: if( handle )
16: {17: var handleId = handle.id;
18: var behaviorId = child.id + "_WidgetFloatingBehavior";
19: 20: // make the item draggable by adding floating behaviour to it
21: var floatingBehavior = $create(CustomDragDrop.CustomFloatingBehavior,
22: {"DragHandleID":handleId, "id":behaviorId, "name": behaviorId}, {}, {}, child);
23: 24: Array.add( this._floatingBehaviors, floatingBehavior );
25: } 26: } 27: child = child.nextSibling; 28: } 29: },Here’s the algorithm:
- Run through all immediate child elements of the control where the extender is attached to
- If the child item has the class for draggable item, then:
- Find any element under the child item which has the class for Drag handle
- If such item found, then attach a CustomFloatingBehavior with the child item
The _findChildByClass function recursively iterates through all the child elements and looks for an element which has the defined class. It’s an expensive function. So, it is important that the drag handle is very close to the dragable element.
1: _findChildByClass : function(item, className)
2: {3: // First check all immediate child items
4: var child = item.firstChild;
5: while( child != null )
6: {7: if( child.className == className ) return child;
8: child = child.nextSibling; 9: } 10: 11: // Not found, recursively check all child items
12: child = item.firstChild;13: while( child != null )
14: {15: var found = this._findChildByClass( child, className );
16: if( found != null ) return found;
17: child = child.nextSibling; 18: } 19: },When user drags an item over the Panel where the extender is attached to, DragDropManager fires the following events:
1: onDragEnterTarget : function(dragMode, type, data) {
2: this._showDropCue(data);
3: }, 4: 5: onDragLeaveTarget : function(dragMode, type, data) {
6: this._hideDropCue(data);
7: }, 8: 9: onDragInTarget : function(dragMode, type, data) {
10: this._repositionDropCue(data);
11: },Here we deal with the drop cue. The challenging work is to find out the right position for the drop cue.
We need to find out where we should show the drop cue based on where user is dragging the item. The idea is to find out the widget which is immediately below the dragged item. The item is pushed down by one position and the drop cue takes its place. While dragging, the position of the drag item can be found easily. Based on that, I locate the widget below the drag item:
1: _findItemAt : function(x,y, item)
2: {3: var el = this.get_element();
4: 5: var child = el.firstChild;
6: while( child != null )
7: {8: if( child.className == this._DragItemClassValue && child != this._dropCue && child != item )
9: {10: var pos = Sys.UI.DomElement.getLocation(child);
11: 12: if( y <= pos.y )
13: {14: return child;
15: } 16: } 17: child = child.nextSibling; 18: } 19: 20: return null;
21: },This function returns the widget which is immediately under the dragged item. Now I add the drop cue immediately above the widget:
1: _repositionDropCue : function(data)
2: {3: var location = Sys.UI.DomElement.getLocation(data.item);
4: var nearestChild = this._findItemAt(location.x, location.y, data.item);
5: 6: var el = this.get_element();
7: 8: if( null == nearestChild )
9: {10: if( el.lastChild != this._dropCue )
11: {12: el.removeChild(this._dropCue);
13: el.appendChild(this._dropCue);
14: } 15: }16: else
17: {18: if( nearestChild.previousSibling != this._dropCue )
19: {20: el.removeChild(this._dropCue);
21: el.insertBefore(this._dropCue, nearestChild);
22: } 23: } 24: },One exception to consider here is that there can be no widget immediately below the dragged item. It happens when user is trying to drop the widget at the bottom of column. In that case, the drop cue is shown at the bottom of the column.
When user releases the widget, it drops right on top of drop cue and the drop cue disappears. After the drop the onDrop event is raised to notify where the widget is dropped.
1: _placeItem : function(data)
2: {3: var el = this.get_element();
4: 5: data.item.parentNode.removeChild( data.item );6: el.insertBefore( data.item, this._dropCue );
7: 8: // Find the position of the dropped item
9: var position = 0;
10: var item = el.firstChild;
11: while( item != data.item )
12: { 13: if( item.className == this._DragItemClassValue ) position++;
14: item = item.nextSibling; 15: }16: this._raiseDropEvent( /* Container */ el, /* droped item */ data.item, /* position */ position );
17: }1: add_onDrop : function(handler) {
2: this.get_events().addHandler("onDrop", handler);
3: }, 4: 5: remove_onDrop : function(handler) {
6: this.get_events().removeHandler("onDrop", handler);
7: },1: <cdd:CustomDragDropExtender ID="CustomDragDropExtender1"
2: runat="server"
3: OnClientDrop="onDrop" />
The declaration only allows properties. In order to support such declarative assignment of events, we need to first introduce a property named OnClientDrop in the extender. Then during assignment of the property, we need to find out the function specified there and attach event notification on that function. The discovery of the function from its name is done by CommonToolkitScripts.resolveFunction which is available in ACT project.
1: // onDrop property maps to onDrop event
2: get_onDrop : function() {
3: return this.get_events().getHandler("onDrop");
4: }, 5: 6: set_onDrop : function(value) {
7: if (value && (0 < value.length)) {
8: var func = CommonToolkitScripts.resolveFunction(value);
9: if (func) {
10: this.add_onDrop(func);
11: } else {
12: throw Error.argumentType('value', typeof(value), 'Function', 'resize handler not a function, function name, or function text.');
13: } 14: } 15: },1: _raiseEvent : function( eventName, eventArgs ) {
2: var handler = this.get_events().getHandler(eventName);
3: if( handler ) {
4: if( !eventArgs ) eventArgs = Sys.EventArgs.Empty;
5: handler(this, eventArgs);
6: } 7: },CustomDragDropExtender. Next challenge is to make the CustomFloatingBehavior. The server side class is declared as:1: [assembly: System.Web.UI.WebResource("CustomDragDrop.CustomFloatingBehavior.js", "text/javascript")]
2: 3: namespace CustomDragDrop
4: {5: [Designer(typeof(CustomFloatingBehaviorDesigner))]
6: [ClientScriptResource("CustomDragDrop.CustomFloatingBehavior", "CustomDragDrop.CustomFloatingBehavior.js")]
7: [TargetControlType(typeof(WebControl))]
8: [RequiredScript(typeof(DragDropScripts))]
9: public class CustomFloatingBehaviorExtender : ExtenderControlBase
10: { 11: [ExtenderControlProperty]12: [IDReferenceProperty(typeof(WebControl))]
13: public string DragHandleID
14: { 15: get 16: {17: return GetPropertyValue<String>("DragHandleID", string.Empty);
18: } 19: set 20: {21: SetPropertyValue<String>("DragHandleID", value);
22: } 23: } 24: } 25: }There’s only one property – DragHandleID. Widget’s header works as the drag handle. So, the header ID is specified here.
This extender has dependency on DragDropManager so the [RequiredScript(typeof(DragDropScripts))] attribute is there.
Besides the designer class, there’s one more class which CustomDragDropExtender need in order to specify its dependency over this floating behavior:
1: [ClientScriptResource(null, "CustomDragDrop.CustomFloatingBehavior.js")]
2: public static class CustomFloatingBehaviorScript
3: { 4: }This class can be used inside RequiredScript attribute. It only defines which script file contains the client side code for the extender.
The client side Javascript is same as FloatingBehavior that comes with ACT. The only difference is some hack when drag starts. DragDropManager does not return the item being dragged to static position once it makes it absolute. It also does not increase the zIndex of the item. If the drag item does not become the top most item, while dragging it goes below other elements on the page. So, I have made some changes in the mouseDownHandler of the behavior to add these features:
1: function mouseDownHandler(ev) {
2: window._event = ev;3: var el = this.get_element();
4: 5: if (!this.checkCanDrag(ev.target)) return;
6: 7: // Get the location before making the element absolute
8: _location = Sys.UI.DomElement.getLocation(el); 9: 10: // Make the element absolute
11: el.style.width = el.offsetWidth + "px";
12: el.style.height = el.offsetHeight + "px";
13: Sys.UI.DomElement.setLocation(el, _location.x, _location.y); 14: 15: _dragStartLocation = Sys.UI.DomElement.getLocation(el); 16: 17: ev.preventDefault(); 18: 19: this.startDragDrop(el);
20: 21: // Hack for restoring position to static
22: el.originalPosition = "static";
23: el.originalZIndex = el.style.zIndex;24: el.style.zIndex = "60000";
25: }Setting el.originalPosition = static fixes the bug in DragDropManager. It incorrectly stores absolute has the originalPosition when startDragDrop is called. So, after calling this function, I set it to correct originalPosition which is “static”.
When drag completes, the original zIndex is restored and left, top, width and height is cleared. DragDropManager makes the item position static, but it does not clear the left, top, width and height attributes. This moves the element away from the place where it is dropped. This bug is fixed in the onDragEnd event:
1: this.onDragEnd = function(canceled) {
2: if (!canceled) {
3: var handler = this.get_events().getHandler('move');
4: if(handler) {
5: var cancelArgs = new Sys.CancelEventArgs();
6: handler(this, cancelArgs);
7: canceled = cancelArgs.get_cancel(); 8: } 9: } 10: 11: var el = this.get_element();
12: el.style.width = el.style.height = el.style.left = el.style.top = "";
13: el.style.zIndex = el.originalZIndex; 14: }That's all folks!
You can get the code for the extenders here.