1. In the Components window, from the Operations panel, in the Drag and Drop group, drag and drop an Attribute Drop Target as a child to the target component on the page.
2. In the Insert Attribute Drop Target dialog, use the Attribute dropdown to select the attribute that will be populated by the drag and drop action. This dropdown list shows all valid attributes on the target component.
3. In the Components window, from the Operations panel, in the Drag and Drop group, drag and drop an Attribute Drag Source as a child to the component that can provide a value for the target.
4. In the Insert Attribute Drag Source dialog, use the Attribute dropdown to select the attribute whose value will be used to populate the target attribute. This dropdown list shows all valid attributes on the source component.

1. In the Components window, from the Operations panel, in the Drag and Drop group, drag a Drop Target and drop it as a child to the target component on the page.
2. In the Insert Drop Target dialog, enter an expression that evaluates to a method on a managed bean that will handle the event (you will create this code in Step 5).

   For information about using managed beans, see Creating and Using Managed Beans.

   Tip:

   You can also intercept the drop on the client by populating the clientDropListener attribute. For more information, see What You May Need to Know About Using the ClientDropListener.

3. In the Insert Data Flavor dialog, enter the class for the object that can be dropped onto the target, for example java.lang.Object. This selection will be used to create a dataFlavor tag, which determines the type of object that can be dropped onto the target, for example a String or a Date. Multiple dataFlavor tags are allowed under a single drop target to allow the drop target to accept any of those types.

   Tip:

   To specify a typed array in a DataFlavor tag, add brackets ([]) to the class name, for example, java.lang.Object[].

4. In the Structure window, select the dropTarget tag. In the Properties window, select a value for the actions attribute. This defines what actions are supported by the drop target. Valid values can be COPY (copy and paste), MOVE (cut and paste), and LINK (copy and paste as a link), for example:.

   MOVE COPY
   

   If no actions are specified, the default is COPY.

   The following example shows the code for a dropTarget component inserted into an panelBox component that takes an array object as a drop target. Note that because an action was not defined, the only allowed action will be COPY.

   <af:panelBox text="PanelBox2">
     <f:facet name="toolbar"/>
     <af:dropTarget dropListener="#{myBean.handleDrop}">
       <af:dataFlavor flavorClass="java.lang.Object[]"/>
     </af:dropTarget>
   </af:panelBox>
   

5. In the managed bean referenced in the EL expression created in Step 2, create the event handler method (using the same name as in the EL expression) that will handle the drag and drop functionality.

   This method must take a DropEvent event as a parameter and return a DnDAction object, which is the action that will be performed when the source is dropped. Valid return values are DnDAction.COPY, DnDAction.MOVE, and DnDAction.LINK, and were set when you defined the target attribute in Step 4. This method should check the DropEvent event to determine whether or not it will accept the drop. If the method accepts the drop, it should perform the drop and return the DnDAction object it performed. Otherwise, it should return DnDAction.NONE to indicate that the drop was rejected.

   The method must also check for the presence for each dataFlavor object in preference order.

   Tip:

   If your target has more than one defined dataFlavor object, then you can use the Transferable.getSuitableTransferData() method, which returns a List of TransferData objects available in the Transferable object in order, from highest suitability to lowest.

   The DataFlavor object defines the type of data being dropped, for example java.lang.Object, and must be as defined in the DataFlavor tag on the JSP, as created in Step 3.

   Tip:

   To specify a typed array in a DataFlavor object, add brackets ([]) to the class name, for example, java.lang.Object[].

   DataFlavor objects support polymorphism so that if the drop target accepts java.util.List, and the Transferable object contains a java.util.ArrayList, the drop will succeed. Likewise, this functionality supports automatic conversion between Arrays and Lists.

   If the drag and drop framework doesn't know how to represent a server DataFlavor object on the client component, the drop target will be configured to allow all drops to succeed on the client.

   The following example shows a method that the event handler method calls (the event handler itself does nothing but call this method; it is needed because this method also needs a String parameter that will become the value of the outputText component in the panelBox component). This method copies an array object from the event payload and assigns it to the component that initiated the event.

   public DnDAction handleDrop(DropEvent dropEvent) 
   {
     Transferable dropTransferable = dropEvent.getTransferable();
             Object[] drinks = dropTransferable.getData(DataFlavor.OBJECT_ARRAY_FLAVOR);
           
       if (drinks != null)
       {
         UIComponent dropComponent = dropEvent.getDropComponent();
             
   // Update the specified property of the drop component with the Object[] dropped
         dropComponent.getAttributes().put("value", Arrays.toString(drinks));
             
         return DnDAction.COPY;
       }
       else
       {
         return DnDAction.NONE;      
       }    
     }   
   

   In this example, the drop component is the panelBox component. Because the panelBox does not have a value attribute, you would need to call the following method to set the text attribute of the panelBox.

   dropComponent.getAttributes().put("text", Arrays.toString(drinks));
   

6. In the Components window, from the Operations panel, drag a Client Attribute and drop it as a child to the source component on the page.

   This tag is used to define the payload of the source for the event. Define the following for the clientAttribute tag in the Properties window:

   • Name: Enter any name for the payload.

   • Value: Enter an EL expression that evaluates to the value of the payload. In the drinks example, this would resolve to the Array that holds the different drink values.

7. In the Components window, from the Operations panel, in the Drag and Drop group, drag a Attribute Drag Source and drop it as a child to the source component on the page.

   In the Insert Attribute Drag Source dialog, use the dropdown list to select the name defined for the clientAttribute tag created in the previous step. Doing so makes the value of the clientAttribute tag the source's payload. The following example shows the code for an outputText component that is the source of the drag and drop operation.

   <af:outputText value="Drag to see drinks">
     <af:clientAttribute name="drinks" value="#{myBean.drinks}"/>
     <af:attributeDragSource attribute="drinks"/>
   </af:outputText>
   

When performing a drag and drop operation, users can press keys on the keyboard (called keyboard modifiers) to select the action they wish to take on a drag and drop. The drag and drop framework supports the following keyboard modifiers:

• SHIFT: MOVE

• CTRL: COPY

• CTRL+SHIFT: LINK

When a user executes the drag and drop operation, the drop target first determines that it can accept the drag source's data flavor value. Next, if the source and target are collections, the framework intersects the actions allowed between the drag source and drop target and executes the action (one of COPY, MOVE, or LINK) in that order from the intersection. When there is only one valid action, that action is executed. When there is more than one possible action and the user's keyboard modifier matches that choice, then that is the one that is executed. If either no keyboard modifier is used, or the keyboard modifier used does not match an allowed action, then the framework chooses COPY, MOVE, LINK in that order, from the set of allowed actions.

For example, suppose you have a drop target that supports COPY and MOVE. First the drop target determines that drag source is a valid data flavor. Next, it determines which action to perform when the user performs the drop. In this example, the set is COPY and MOVE. If the user holds down the SHIFT key while dragging (the keyboard modifier for MOVE), the framework would choose the MOVE action. If the user is doing anything other than holding down the SHIFT key when dragging, the action will be COPY because COPY is the default when no modifier key is chosen (it is first in the order). If the user is pressing the CTRL key, that modifier matches COPY, so COPY would be performed. If the user was pressing the CTRL+SHIFT keys, the action would still be COPY because that modifier matches the LINK action which is not in the intersected set of allowed actions.

1. In the Components window, from the Operations panel, in the Drag and Drop group, drag a Collection Drop Target and drop it as a child to the target collection component on the page.
2. In the Insert Collection Drop Target dialog, enter an expression for the dropListener attribute that evaluates to a method on a managed bean that will handle the event (you will create this code in Step 4).
3. In the Properties window, set the following:

   • actions: Select the actions that can be performed on the source during the drag and drop operation.

     If no actions are specified, the default is COPY.

   • modelName: Define the model for the collection.

     The value of the modelName attribute is a String object used to identify the drag source for compatibility purposes. The value of this attribute must match the value of the discriminant attribute of the dragSource tag you will use in a Step 6. In other words, this is an arbitrary name and works when the target and the source share the same modelName value or discriminant value.

4. In the managed bean inserted into the EL expression in Step 2, implement the handler for the drop event.

   This method must take a DropEvent event as a parameter and return a DnDAction. This method should use the DropEvent to get the Transferable object and from there get the RowKeySet (the rows that were selected for the drag). Using the CollectionModel obtained through the Transferable object, the actual rowData can be obtained to complete the drop. The method should then check the DropEvent to determine whether it will accept the drop or not. If the method accepts the drop, it should perform the drop and return the DnDAction it performed -- DnDAction.COPY, DnDAction.MOVE or DnDAction.LINK, otherwise it should return DnDAction.NONE to indicate that the drop was rejected.

   The following example shows the event handler method on the CollectionDnd.java managed bean used in the collectionDropTarget demo that handles the copy of the row between two tables.

   public DnDAction handleDrop(DropEvent dropEvent)
     {
       return _handleDrop(dropEvent, getTargetValues(), "DnDDemoModel");
     }
   private DnDAction _handleDrop(DropEvent dropEvent, 
                                   ArrayList<DnDDemoData> targetValues,
                                   String discriminator)
   {
     Transferable transferable = dropEvent.getTransferable();
     // The data in the transferable is the row key for the dragged component.
     DataFlavor<RowKeySet> rowKeySetFlavor =
                          DataFlavor.getDataFlavor(RowKeySet.class, discriminator);
     RowKeySet rowKeySet = transferable.getData(rowKeySetFlavor);
     if (rowKeySet != null)
     {
       // Get the model for the dragged component.
       CollectionModel dragModel = transferable.getData(CollectionModel.class);
       if (dragModel != null)
       {
         // Set the row key for this model using the row key from the transferable.
         Object currKey = rowKeySet.iterator().next();
         dragModel.setRowKey(currKey);
           
         // And now get the actual data from the dragged model.
         // Note this won't work in a region.
         //Need to change this to use collectionModel data flavor.
         DnDDemoData dnDDemoData = (DnDDemoData)dragModel.getRowData();
         
         // Put the dragged data into the target model directly. 
         // Note that if you wanted validation/business rules on the drop,
         // this would be different.
         // getTargetValues() is the target collection used by the target component
           if (dropEvent.getProposedAction() == DnDAction.LINK)
             dnDDemoData = DnDDemoData.addALink(dnDDemoData);
             targetValues.add(dnDDemoData);
       }
       return dropEvent.getProposedAction();
     }
     else
     {
       return DnDAction.NONE;      
     }
   }
     

5. In the Components window, from the Operations panel, in the Drag and Drop group, drag and drop a Drag Source as a child to the source component.
6. With the dragSource tag selected, in the Properties window set the actions, discriminant, and any dragDropEndListener as configured for the target. For instance, the dragSource tag may appear similar to the following:

   <af:dragSource actions="MOVE" discriminant="DnDDemoModel
   dragDropEndListener="#{collectionDnD.endListener}"/>

1. In the Components window, from the Operations panel, in the Drag and Drop group, drag a Drop Target and drop it as a child to the target component on the page.
2. In the Insert Drop Target dialog, enter an expression that evaluates to a method on a managed bean that will handle the event (you will create this code in Step 4).
3. With the dropTarget tag still selected, in the Properties window, select a valid action set for the actions attribute.
4. In the managed bean referenced in the EL expression created in Step 2 for the dropListener attribute, create the event handler method (using the same name as in the EL expression) that will handle the drag and drop functionality.

   If the method accepts the drop, it should perform the drop and return the DnDAction it performed -- DnDAction.COPY, DnDAction.MOVE or DnDAction.LINK, otherwise it should return DnDAction.NONE to indicate that the drop was rejected

   This handler method should use the DropEvent event to get the Transferable object and its data and then complete the move or copy, and reorder the components as needed. Once the method completes the drop, it should return the DnDAction it performed. Otherwise, it should return DnDAction.NONE to indicate that the drop was rejected.

   The following example shows the handleComponentMove event handler on the DemoDropHandler.java managed bean used by the componentDragSource JSF page in the demo application.

   public DnDAction handleComponentMove(DropEvent dropEvent)
   {
     Transferable dropTransferable = dropEvent.getTransferable();
     UIComponent movedComponent =  dropTransferable.getData
                                  (DataFlavor.UICOMPONENT_FLAVOR);
     if ((movedComponent != null) &&
          DnDAction.MOVE.equals(dropEvent.getProposedAction()))
     {
       UIComponent dropComponent = dropEvent.getDropComponent();
       UIComponent dropParent = dropComponent.getParent();
       UIComponent movedParent = movedComponent.getParent();
       UIComponent rootParent = null;
       ComponentChange change = null;
       
       // Build the new list of IDs, placing the moved component after the dropped
       //component.
       String movedLayoutId = movedParent.getId();
       String dropLayoutId = dropComponent.getId();
         
       List<String> reorderedIdList = new
                                      ArrayList<String>(dropParent.getChildCount());
           
       for (UIComponent currChild : dropParent.getChildren())
       {
         String currId = currChild.getId();
           
         if (!currId.equals(movedLayoutId))
           {
             if(!movedLayoutIdFound && currId.equals(dropLayoutId))
               reorderedIdList.add(movedLayoutId);
             reorderedIdList.add(currId);
             if(movedLayoutIdFound && currId.equals(dropLayoutId))
               reorderedIdList.add(movedLayoutId);              
           }
           else
             movedLayoutIdFound = true;
         }
         
       change = new ReorderChildrenComponentChange(reorderedIdList);
       rootParent = dropParent;
       ChangeManager cm = RequestContext.getCurrentInstance().getChangeManager();
    
      // add the change
      cm.addComponentChange(FacesContext.getCurrentInstance(),rootParent, change);
         
      // apply the change to the component tree immediately
      change.changeComponent(rootParent);
         
      // redraw the shared parent
      AdfFacesContext.getCurrentInstance().addPartialTarget(rootParent);
         
      return DnDAction.MOVE;
      }
      else
      {
         return DnDAction.NONE;      
      }
    }
   

5. In the Components window, from the Operations panel, in the Drag and Drop group, drag a Component Drag Source and drop it as a child of the source component on the page.

   For instance, the componentDragSource tag may appear similar to the following:

   <af:componentDragSource discriminant="col2"/>

1. In the Structure window, select the panelDashboard component that is to be the target component.
2. In the Properties window, for DropListener, enter an expression that evaluates to a method on a managed bean that will handle the drop event (you will create this code in Step 6).
3. In the Components window, from the Operations panel, in the Drag and Drop group, drag a Data Flavor and drop it as a child to the panelDashboard component.
4. In the Insert Data Flavor dialog, enter javax.faces.component.UIComponent.
5. In the Properties window, set Discriminant to a unique name that will identify the components allowed to be dragged into the panelDashboard component, for example, dragIntoDashboard.
6. In the Components window, from the Operations panel, in the Drag and Drop group, drag a Component Drag Source and drop it as a child to the panelBox component that will be the source component.
7. In the Properties window, set Discriminant to be the same value as entered for the Discriminant on the panelDashboard in Step 5.

1. In the Components window, from the Operations panel, in the Drag and Drop group, drag and drop a Drop Target as a child to the target component.
2. In the Insert Drop Target dialog, enter an expression that evaluates to a method on a managed bean that will handle the event (you will create this code in Step 5) and enter javax.faces.component.UIComponent as the FlavorClass.
3. With the dropTarget tag still selected, in the Properties window, select MOVE as the value action attribute.
4. In the Structure window, select the dataFlavor tag and in the Properties window, set Discriminant to a unique name that will identify the panelBox components allowed to be dragged into this component, for example, dragOutOfDashboard.
5. In the managed bean referenced in the EL expression created in Step 2 for the dropListener attribute, create the event handler method (using the same name as in the EL expression) that will handle the drag and drop functionality.

   This handler method should use the DropEvent event to get the Transferable object and its data and then complete the move and reorder the components as needed. Once the method completes the drop, it should return a DnDAction of NONE.

   You can use the dashboardComponent.prepareOptimizedEncodingOfDeletedChild() method to animate the removal of the panelBox component.

   The following example shows the handleSideBarDrop event handler and helper methods on the oracle.adfdemo.view.layout.DemoDashboardBean.java managed bean used by the dashboard JSF page in the demo application.

   public DnDAction handleSideBarDrop(DropEvent e)
     {
       UIComponent dragComponent = e.getDragComponent();
       UIComponent dragParent    = dragComponent.getParent();
       // Ensure that the drag source is one of the items from the dashboard:
       if (dragParent.equals(_getDashboard()))
       {
         _minimize(dragComponent);
       }
       return DnDAction.NONE; // the client is already updated, so no need to redraw it again
   }
   
   private void _minimize(UIComponent panelBoxToMinimize)
     {
       // Make this panelBox non-rendered:
       panelBoxToMinimize.setRendered(false);
    
       // If the dashboard is showing, let's perform an optimized render so the whole dashboard doesn't
       // have to be re-encoded.
       // If the dashboard is hidden (because the panelBox is maximized), we will not do an optimized
       // encode since we need to draw the whole thing.
       if (_maximizedPanelKey == null)
       {
         int deleteIndex = 0;
         RichPanelDashboard dashboard = _getDashboard();
         List<UIComponent> children = dashboard.getChildren();
         for (UIComponent child : children)
         {
           if (child.equals(panelBoxToMinimize))
           {
             dashboard.prepareOptimizedEncodingOfDeletedChild(
               FacesContext.getCurrentInstance(),
               deleteIndex);
             break;
           }
           if (child.isRendered())
           {
             // Only count rendered children since that's all that the panelDashboard can see:
             deleteIndex++;
           }
         }
       }
       RequestContext rc = RequestContext.getCurrentInstance();
       if (_maximizedPanelKey != null)
       {
         // Exit maximized mode:
         _maximizedPanelKey = null;
         UIXSwitcher switcher = _getSwitcher();
         switcher.setFacetName("restored");
         rc.addPartialTarget(switcher);
       }
       // Redraw the side bar so that we can update the colors of the opened items:
       rc.addPartialTarget(_getSideBarContainer());
   }
   

6. In the Components window, from the Operations panel, drag and drop a Component Drag Source as a child of the source panelBox component within the panelDashboard component.
7. In the Properties window, set Discriminant to be the same value as entered for the Discriminant on the dataFlavor tag for the target component in Step 4.

1. In the Components window, from the Operations panel, in the Drag and Drop group, drag and drop a Calendar Drop Target as a child to the calendar component.
2. In the Insert Calendar Drop Target dialog, enter an expression for the dropListener attribute that evaluates to a method on a managed bean that will handle the event (you will create this code in Step 4).
3. In the Properties window, set Actions. This value determines whether the activity (or other source) can be moved, copied, or copied as a link, or any combination of the three. If no action is specified, the default is COPY.
4. In the managed bean inserted into the EL expression in Step 2, implement the handler for the drop event.

   This method must take a DropEvent event as a parameter and return a DnDAction. The DnDAction is the action that will be performed when the source is dropped. Valid return values are COPY, MOVE, and LINK, and are set when you define the actions attribute in Step 3. This method should use the DropEvent to get the Transferable object, and from there, access the CalendarModel object in the dragged data and from there, access the actual data. The listener can then add that data to the model for the source and then return the DnDAction it performed: DnDAction.COPY, DnDAction.MOVE or DnDAction.LINK; otherwise, the listener should return DnDAction.NONE to indicate that the drop was rejected.

   The drop site for the drop event is an instance of the oracle.adf.view.rich.dnd.CalendarDropSite class. For an example of a drag and drop handler for a calendar, see the handleDrop method on the oracle.adfdemo.view.calendar.rich.DemoCalendarBean managed bean in the ADF Faces Components Demo application.

5. If the source for the activity is external to the calendar, drag a Data Flavor and drop it as a child to the calendarDropTarget tag. This tag determines the type of object that can be dropped onto the target, for example a String or a Date object. Multiple dataFlavor tags are allowed under a single drop target to allow the drop target to accept any of those types.
6. In the Insert Data Flavor dialog, enter the class for the object that can be dropped onto the target, for example java.lang.Object.

   Tip:

   To specify a typed array in a dataFlavor tag, add brackets ([]) to the class name, for example, java.lang.Object[].

For dragging and dropping activities within a calendar, users can drag and drop only within a view. That is, users can drag an activity from one time slot to another in the day view, but cannot cut an activity from a day view and paste it into a month view.

When the user is dragging and dropping activities in the day or week view, the calendar marks the drop site by half-hour increments. The user cannot move any all-day or multi-day activities in the day view.

In the week view, users can move all-day and multi-day activities, however, they can be dropped only within other all-day slots. That is, the user cannot change an all-day activity to an activity with start and end times. In the month view, users can move all-day and multi-day activities to any other day.

Pareto and stock graphs can be configured as a drop target to allow drops from other ADF components. For example, you can configure a stock graph to allow drops from an ADF table cell.

When you want users to be able to drag and drop between Gantt charts and other components, you use the dragSource and dropTarget tags. Additionally, you use the DataFlavor object to determine the valid Java types of sources for the drop target. You also must implement any required functionality in response to the drag and drop action. Both the projectGantt and schedulingGantt components support drag and drop functionality.

For example, suppose you have an projectGantt component and you want the user to be able to drag one time bucket to a treeTable component and have that component display information about the time bucket, as shown in Figure 39-5.

Figure 39-5 Dragging and Dropping an Object

The projectGantt component contains a dragSource tag. And because the user will drag the whole object and not just the String value of the output text that is displayed, you use the dropTarget tag instead of the attributeDropTarget tag.

You also use a dataFlavor tag to determine the type of object being dropped. On this tag, you can define a discriminant value. This is helpful if you have two targets and two sources, all with the same object type. By creating a discriminant value, you can be sure that each target will accept only valid sources. For example, suppose you have two targets that both accept an TaskDragInfo object, TargetA and TargetB. Suppose you also have two sources, both of which are TaskDragInfo objects. By setting a discriminant value on TargetA with a value of alpha, only the TaskDragInfo source that provides the discriminant value of alpha will be accepted.

You also must implement a listener for the drop event. The object of the drop event is called the Transferable, which contains the payload of the drop. Your listener must access the Transferable object, and from there, use the DataFlavor object to verify that the object can be dropped. You then use the drop event to get the target component and update the property with the dropped object.

You can configure hierarchy viewers, sunbursts, and treemaps as drag sources and drop targets for drag and drop operations between supported components on a page.