Drag and drop zones

WebSphere Portal Express includes markup that allows users to drag portlets on a page. This topic describes the tags and APIs provided to enable the drag and drop features and how you can include them in your custom themes and skins.

The drag and drop feature is available to portal and portlet developers using public JSP tags and APIs to create drag zones and drop zones in the JSPs. The content of a drag zone can be placed in any drop zone that has a matching type.

The following example snippet provides a simple outline of how the drag and drop tags can be used in a portlet.

Figure 1. Drag and drop portlet example

<table>
<tr>
  <td>
    <dnd:drag type="myImage" value="0">
      <img src='<%=imageURL%>' alt="logo"/>
    </dnd:drag>
  </td>
  <td>
    <dnd:drop type="myImage" name="num" action="<%=myPortletURL%>">
      <%=value%>
    </dnd:drop>
  </td>  
</tr>
</table>

This example shows a simple table with two cells. The content of one cell is marked as a drag zone and provides an image for the content of the drag zone. The content of the next cell is marked as a drop zone and provides a variable which is initialized as empty content when the portlet is first rendered.

The type attribute identifies matching drag and drop zones. This attribute is required. A drag zone can only be dropped into drop zones with a matching type. Drag and drop zones can match between portlets on a page or between portlets and other elements in the portal page.
The action specifies a URL which is invoked in the request that is issued after the drop is performed. This is equivalent to the action on an HTML form.
The name attribute from the <dnd:drop/> tag and the value attribute from the <dnd:drag/> tag combine to create a name/value pair that is included as a parameter of the URL specified by the action attribute. This parameter is available in the request so that the portlet JSP in this example can obtain the value using renderRequest.getParameter(“num”).

Typically, the URL in the action specifies a portlet URL and optionally includes any parameters that the portlet needs to update the markup. The developer is responsible for implementing changes in the response as a result of the drop. For example, the developer could change the markup so that the content that was dropped is rendered in the new location. Or the developer might process an action that launches a new page or changes the value of content in the current view. For one drop zone, multiple actions can be provided using the <dnd:additionalAction/> tag, and each action can be associated with different types of drag zones.

Using drag and drop in custom themes and skins

WebSphere Portal implements drag and drop by defining drag zones in the Control.jsp that holds the portlets and drop zones in the row and column containers. When developing themes and skins that use the drag and drop features, start with the JSPs provided by the IBM skin. Be sure to modify only the HTML markup and content and to not alter the Java scriptlets or JSP tags and attributes. For example, changes to any of the following content would result in either compile errors or prevent the drag and drop from working correctly:

Missing or misplaced <dnd:DnDPortletHelper/> tag.
Missing or misplaced Java scriptlets containing the jspInit() method and Strings for the object ID of the layout node and JavaScript.
Wrong attribute values for the drag and drop JSP tags.
Missing JavaScript for the <dnd:drop/> and <dnd:additionalAction/> tags.

Summary of the drag and drop tags

JSPs require this taglib declaration at the top of the file:

<%@ taglib uri="/WEB-INF/tld/dnd.tld" prefix="dnd" %>

The following table provides a brief description of each tag. For more complete descriptions, see Drag and drop JSP tags.

Tag	Description
<dnd:drag/>	designates the content of the tag as a drag zone that can be dropped into drop zones of matching types.
<dnd:drop/>	designates the content of the tag as a drop zone that can accept content from drag zones of matching types. Drop zones have three states: `dormant`: a drag zone is not being dragged `aware`: a drag zone is being dragged `active`: a drag zone is being dragged and the drop zone is the closest in proximity and will be the recipient of the drop
<dnd:dragHandle/>	designates content within the parent <dnd:drag/> tag to be used as a visual handle for the drag operation. If this tag is not provided within the <dnd:drag/> tag, the entire drag content is used as a handle.
<dnd:additionalAction/>	indicates an additional action associated with the parent <dnd:drop/> tag.
<dnd:additionalProperty/>	indicates additional properties that can be included in the parent <dnd:drag/>, <dnd:drop/>, or <dnd:additionalAction/> tag.
<dnd:DNDPortletHelper/>	required for portal themes and skins prior to other drag and drop markup.

Drag and drop API

The Java classes and interfaces that implement drag and drop and provided by the com.ibm.portal.dnd package. To use drag and drop, you must first retrieve and instance of the DNDService interface using a JNDI lookup on the String, portal:service/themes/DragAndDrop. The following shows a general outline of the programming model for drag and drop operations.

Drag zone

Create one or more DNDProperty objects that will belong to this drag zone using DNDFactory.createProperty().
Create a DNDSource using DNDFactory.createSource(). Pass the DNDProperty objects to this method in an array.
Call DNDMarkupGenerator.doLibraryIncludeMarkup() to add the markup that loads the JavaScript libraries.
Call DNDMarkupGenerator.doBeginDNDSource() to generate the markup for the beginning of the drag zone.
Call DNDMarkupGenerator.doBeginDNDSourceHandle() and DNDMarkupGenerator.doEndDNDSourceHandle() for each part of the markup you need to include in the drag zone’s handle.
Call DNDMarkupGenerator.doEndDNDSource() to generate the markup for the end of the drag zone.

Drop zone

Create DNDProperty objects for one or more DNDAction objects that will belong to this drop zone using DNDFactory.createProperty().
Create DNDAction objects using DNDFactory.createAction() for each set of DNDProperty objects created .
Create a DNDTarget using DNDFactory.createTarget(). Pass the DNDAction objects to this method in an array.
Call DNDMarkupGenerator.doLibraryIncludeMarkup() to add the markup that loads the JavaScript libraries.
Call DNDMarkupGenerator.doBeginDNDTarget() to generate the markup for the beginning of the drop zone.
Call DNDMarkupGenerator.doEndDNDTarget() to generate the markup for the end of the drop zone.

See the API documentation in the portal_server_root/Javadoc directory for more information about the interfaces, classes, and methods used.

Style classes used for drag and drop

The following style classes that define the appearance of drag and drop zones are defined in the themeStyles.jspf in the /IBM directory. Additional class names can be specified on some of the drag and drop tags. If this case, the style file for the theme must be updated with the new class definitions.

.dndDropAware: defines the style properties of a drop zone in the aware state (a drag object is being dragged)
.dndDropActive: defines the style properties of a drop zone in the active state (a object is being dragged and this drop zone is in the closest proximity)
.dndDragging: defines the style properties of content as it is being dragged
.dndMoveCursor: defines the style properties of the user’s cursor when it hovers over a drag zone
.dndDropCursor: defines style properties of the user’s cursor when a portlet is dragged over a matching drop zone (but not yet dropped)
.dndNoDropCursor: defines style properties of the user’s cursor when a portlet is dragged over a matching drop zone (but not yet dropped)