<?xml version="1.0" encoding="UTF-8"?>
<section>
  <sectioninfo>
    <keywordset>
      <keyword>rich:dragSupport</keyword>

      <keyword>HtmlDragSupport</keyword>
    </keywordset>
  </sectioninfo>


  <table>
    <title>Component identification parameters</title>

    <tgroup cols="2">
      <thead>
        <row>
          <entry>Name</entry>

          <entry>Value</entry>
        </row>
      </thead>

      <tbody>
        <row>
          <entry>component-type</entry>

          <entry>org.richfaces.DragSupport</entry>
        </row>

        <row>
          <entry>component-class</entry>

          <entry>org.richfaces.component.html.DragSupport</entry>
        </row>

        <row>
          <entry>component-family</entry>

          <entry>org.richfaces.DragSupport</entry>
        </row>

        <row>
          <entry>renderer-type</entry>

          <entry>org.richfaces.DragSupportRenderer</entry>
        </row>

        <row>
          <entry>tag-class</entry>

          <entry>org.richfaces.taglib.DragSupportTag</entry>
        </row>
      </tbody>
    </tgroup>
  </table>


  <section>
    <title>Creating the Component with a Page Tag</title>

    <para>Here is a simple example as it could be used on a page:</para>


    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
    <h:panelGrid id="drag1">
        <rich:dragSupport dragType="item"/>
            <!--Some content to be dragged-->
    </h:panelGrid>
...
]]></programlisting>
  </section>

  <section>
    <title>Creating the Component Dynamically Using Java</title>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="JAVA"><![CDATA[import org.richfaces.component.html.HtmlDragSupport;
...
HtmlDragSupport myDragZone = new HtmlDragSupport();
...
]]></programlisting>
  </section>

  <section>
    <title>Details of Usage</title>

    <para>The <property>dragSupport</property> tag inside a component completely specifies the
      events and JavaScript required to use the component and it's children for dragging as part of
      a drag-and-drop operation. In order to work, though, <property>dragSupport</property> must be
      placed inside a wrapper component that outputs child components and that has the right events
      defined on it. Thus, this example won't work, because the <property>h:column</property> tag
      doesn't provide the necessary properties for redefining events on the client:</para>


    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
    <h:column>
        <rich:dragSupport dragIndicator=":form:iii" dragType="text">
            <a4j:actionparam value="#{caps.name}" name="name"/>
        </rich:dragSupport>
        <h:outputText value="#{caps.name}"/> 
    </h:column>
...
]]></programlisting>

    <para>However, using <property>a4j:outputPanel</property> as a wrapper inside
      <property>h:column</property>, the following code could be used successfully:</para>


    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
    <h:column>
        <a4j:outputPanel>
            <rich:dragSupport dragIndicator=":form:iii" dragType="text">
                <a4j:actionparam value="#{caps.name}" name="name"/>
            </rich:dragSupport>
            <h:outputText value="#{caps.name}"/> 
        </a4j:outputPanel>
    </h:column>
...
]]></programlisting>

    <para>This code makes all rows of this column draggable.</para>

    <para>One of the main attributes for <property>dragSupport</property> is
          <emphasis><property>"dragType"</property>,</emphasis> which associates a name with the
      drag zone. Only drop zones with this name as an acceptable type can be used in drag-and-drop
      operations. Here is an example:</para>


    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
    <h:panelGrid id="drag1">
        <rich:dragSupport dragType="singleItems" .../>
        <!--Some content to be dragged-->
    </h:panelGrid>		
...
    <h:panelGrid id="drag2">
        <rich:dragSupport dragType="groups" .../>
        <!--Some content to be dragged-->
    </h:panelGrid>		
...
    <h:panelGrid id="drop1">
        <rich:dropSupport acceptedTypes="singleItems" .../>
        <!--Drop zone content-->
    </h:panelGrid>
...
]]></programlisting>

    <para>In this example, the <property>drop1</property> panel grid is a drop zone that invokes
      drag-and-drop for drops of items from the first <property>drag1</property> panel grid, but not
      the second <property>drag2</property> panel grid. In the section about
      <property>dropSupport</property>, you will find an example that shows more detailed
      information about moving data between tables with drag and drop.</para>

    <para>The <property>dragSupport</property> component also has a <emphasis>
        <property>"value"</property>
      </emphasis> attribute for passing data into the processing after a drop event.</para>

    <para>One more important attribute for <emphasis role="bold">
        <property>&lt;rich:dragSupport&gt;</property>
      </emphasis> is the <emphasis>
        <property>"dragIndicator"</property>
      </emphasis> attribute that point to the component id of the <emphasis role="bold">
        <property>&lt;rich:dragIndicator&gt;</property>
      </emphasis> component to be used for dragged items from this drag zone. If it isn't defined, a
      default indicator for drag operations is used.</para>

    <para>Finally, the component has the following extra attributes for event processing on the
      client:</para>

    <itemizedlist>
      <listitem>ondragenter</listitem>

      <listitem>ondragexit</listitem>
    </itemizedlist>

    <para>You can use your own custom JavaScript functions to handle these events.</para>

  </section>

  <section>
    <title>Look-and-Feel Customization</title>

    <para>The component doesn&apos;t have its own representation.</para>
  </section>
  <section>
    <title>Relevant resources links</title>
    <para>
      <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/dragSupport.jsf?c=dragSupport"
        >Here</ulink> you can see the example of <emphasis role="bold"
        >&lt;rich:dragSupport&gt;</emphasis> usage and sources for the given example.
    </para>
  </section>

</section>
