Drag and drop zones

Drag and drop zones

WebSphere Portal includes markup that allows users to drag portlets on a page. Learn about the tags and APIs provided to enable the drag and drop features and how you can include them in custom themes and skins. The Tab Menu - Page Builder theme does not use drag and drop tags. It uses the Dojo drag and drop framework. Refer to the Page builder drag and drop topic for more information.
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 entire content of the drag zone is used as a handle in this example, but it is possible to specify certain pieces of content inside a drag zone as a handle by using the <dnd:dragHandle /> tag. Multiple drag handles are allowed within a 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.

Use 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 Portal 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" %>
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 are provided by the com.ibm.portal.dnd package. To use drag and drop, first retrieve an instance of the DNDService interface using a JNDI lookup for the name 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 WebSphere Portal API documentation 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 styles_theme.jspf in the /Portal directory. Additional class names can be specified on some of the drag and drop tags. In 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 the style properties of the user's cursor when a portlet is dragged over an allowed matching drop zone (but not yet dropped)

.dndNoDropCursor
defines the style properties of the user's cursor when a portlet is dragged over a non-allowed matching drop zone (but not yet dropped)

.dndDragSelected
defines the style properties of an item that is selected to be dragged

.dndDropAwareVerticalCSA
defines the style properties of a drop zone located in a vertical container in the aware state for themes using client side aggregation

.dndDropAwareHorizontalCSA
defines the style properties of a drop zone located in a horizontal container in the aware state for themes using client side aggregation

.dndDropActiveCSA
defines the style properties of a drop zone in the active state for themes using client side aggregation with dynamic portlet preview

.dndStaticDropActiveVerticalCSA
defines the style properties of a drop zone located in a vertical container in the active state for themes using client side aggregation but without dynamic portlet preview

.dndStaticDropActiveHorizontalCSA
defines the style properties of a drop zone located in a horizontal container in the active state for themes using client side aggregation but without dynamic portlet preview

Parent
Develop portlets
Page builder drag-and-drop

+
Search Tips | Advanced Search

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.