rich:dropSupport HtmlDropSupport

Component identification parameters

Name | Value
--- | ---
component-type | org.richfaces.DropSupport
component-class | org.richfaces.component.html.HtmlDropSupport
component-family | org.richfaces.DropSupport
renderer-type | org.richfaces.DropSupportRenderer
tag-class | org.richfaces.taglib.DropSupportTag

## Creating the Component with a Page Tag

This simple example shows how to make a panel component a potential drop target for drag-and-drop operations using "text" elements as the dragged items.

Example:

    ...
        <rich:panel>
            <rich:dropSupport acceptedTypes="text"/>
        </rich:panel>
    ...

## Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.HtmlDropSupport;
    ...
    HtmlDropSupport myDragZone = new HtmlDropSupport();
    ...

## Details of Usage

As shown in the example, the key attribute for <rich:dropSupport> is "acceptedTypes" . This attribute defines the types of draggable items that can be dropped onto the designated drop zone.

The second most important attribute for <rich:dropSupport> is "typeMapping" . This attribute maps a specific type among the acceptable types for draggable items to a specific <rich:dndParam> child element under <rich:dropSupport> .

Example:

    ...
        <rich:dropSupport acceptedTypes="[iconsDragged, textDragged]" typeMapping="{iconsDragged: DropIcon}">
            <rich:dndParam name="DropIcon">
                <h:graphicImage value="/images/drop-icon.png"/>
    		</rich:dndParam>
    ...

In this example, dropping a draggable item of an "iconsDragged" type will trigger the use a parameter named "DropIcon" in the event processing after a drop event. (Also, an Ajax request is sent, and the action and dropListener defined for the component are called.)

Here is an example of moving records between tables. The example describes all the pieces for drag-and-drop. (To get extra information on these components, read the sections for these components.)

As draggable items, this table contains a list of such items designated as being of type "text":

Example:

    ...
        <rich:dataTable value="#{capitalsBean.capitals}" var="caps">
            <f:facet name="caption">Capitals List</f:facet>
            <h:column>
            <a4j:outputPanel>
                <rich:dragSupport dragIndicator=":form:ind" dragType="text">
                    <a4j:actionparam value="#{caps.name}" name="name"/>
                </rich:dragSupport>
                <h:outputText value="#{caps.name}"/>
            </a4j:outputPanel>
            </h:column>
        </rich:dataTable>
    ...

As a drop zone, this panel will accept draggable items of type "text" and then rerender an element with the ID of "box":

Example:

    ...
        <rich:panel style="width:100px;height:100px;">
            <f:facet name="header">Drop Zone</f:facet>
            <rich:dropSupport acceptedTypes="text" reRender="box"
                            dropListener="#{capitalsBean.addCapital2}"/>
        </rich:panel>
    ...

As a part of the page that can be updated in a partial page update, this table has an ID of "box":

Example:

    ...
        <rich:dataTable value="#{capitalsBean.capitals2}" var="cap2" id="box">
            <f:facet name="caption">Capitals chosen</f:facet>
            <h:column>
                <h:outputText value="#{cap2.name}"/>
            </h:column>
        </rich:dataTable>
    ...

And finally, as a listener, this listener will implement the dropped element:

Example:

    ...
        public void addCapital2(DropEvent event) {
            FacesContext context = FacesContext.getCurrentInstance();
            Capital cap = new Capital();
            cap.setName(context.getExternalContext().getRequestParameterMap().get("name").toString());
            capitals2.add(cap);
        }
    ...

Here is the result after a few drops of items from the first table:

Results of drop actions

In this example, items are dragged element-by-element from the rendered list in the first table and dropped on a panel in the middle. After each drop, a drop event is generated and a common Ajax request is performed that renders results in the third table.

As with every Ajax action component, <rich:dropSupport> has all the common attributes ("timeout", "limitToList", "reRender", etc.) for Ajax request customization.

Finally, the component has the following extra attributes for event processing on the client:

- ondragenter
- ondragexit
- ondrop
- ondropend

Developers can use their own custom JavaScript functions to handle these events.

## Look-and-Feel Customization

<rich:dropSupport> has no skin parameters and custom style classes, as the component isn't visual.

## Relevant Resources Links

Here you can see the example of <rich:dropSupport> usage and sources for the given example.