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

			<keyword>HtmlDropSupport</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.DropSupport</entry>
				</row>

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

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

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

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

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

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

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

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


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

		<para>
			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.
		</para>

		<para>
			<emphasis role="bold">Example:</emphasis>
		</para>
		<programlisting role="XML"><![CDATA[...
    <rich:panel>
        <rich:dropSupport acceptedTypes="text"/>
    </rich:panel>
...
]]></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.HtmlDropSupport;
...
HtmlDropSupport myDragZone = new HtmlDropSupport();
...
]]></programlisting>
	</section>

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

		<para>The key attribute for <emphasis role="bold"><property>&lt;rich:dropSupport&gt;</property></emphasis> is <emphasis><property>"acceptedTypes"</property></emphasis>. 
		      It defines, which types of dragable items (zones) could be accepted by the current drop zone. Check the example below:
		</para>
	      <programlisting role="XML"><![CDATA[...
<rich:panel styleClass="dropTargetPanel">
     <f:facet name="header">
          <h:outputText value="PHP Frameworks" />
     </f:facet>
     
     <rich:dropSupport id="php" acceptedTypes="PHP" dropValue="PHP" dropListener="#{eventBean.processDrop}" reRender="phptable, src">
     </rich:dropSupport>
     ...
</rich:panel>
...
]]></programlisting>
	      <para>and here is what happens on the page:</para>
	      <figure>
	            <title>Drop zone accepts dragable item with "PHP" type only</title>
	            <mediaobject>
	                  <imageobject>
	                        <imagedata fileref="images/dropSupport1.png" />
	                  </imageobject>
	            </mediaobject>
	      </figure>
	      
	      <para>Using the <emphasis><property>"typeMapping"</property></emphasis> attribute. Previous example shows that a drop zone could accept a dragable item or not. 
	            Special markers, which are placed at <emphasis role="bold"><property>&lt;rich:dragIndicator&gt;</property></emphasis>, inform user about drop zone’s possible behaviors: 
	            "checkmark" appears if drop is accepted and "No" symbol if it is not. 
	            Moreover, some extra information (e.g. text message) could be put into the Indicator to reinforce the signal about drop zone’s behavior or pass some other additional sense. 
	            This reinforcement could be programmed and attributed to drop zone via <emphasis><property>"typeMapping"</property></emphasis> attribute using JSON syntax. 
	            The type of dragged zone (dragType) should be passed as &quot;key&quot; and name of <emphasis role="bold"><property>&lt;rich:dndParam&gt;</property></emphasis> 
	            that gives needed message to Indicator as &quot;value&quot;:
	      </para>
	      <programlisting role="XML"><![CDATA[...
<rich:panel styleClass="dropTargetPanel">
     <f:facet name="header">
          <h:outputText value="PHP Frameworks" />
     </f:facet>
     
     <rich:dropSupport id="php" acceptedTypes="PHP" dropValue="PHP" dropListener="#{eventBean.processDrop}" reRender="phptable, src" 
                              typeMapping="{PHP: text_for_accepting, DNET: text_for_rejecting}">
          <rich:dndParam name="text_for_accepting" value="Drop accepted!" />
          <rich:dndParam name="text_for_rejecting" value="Drop is not accepted!" />
     </rich:dropSupport>
     ...
</rich:panel>
...
]]></programlisting>
	      <para>What happens on the page:</para>
	      <figure>
	      	<title><emphasis><property>"typeMapping"</property></emphasis> helps to add some extra information to <emphasis role="bold"><property>&lt;rich:dragIndicator&gt;</property></emphasis> </title>
	            <mediaobject>
	                  <imageobject>
	                        <imagedata fileref="images/dropSupport1a.png" />
	                  </imageobject>
	            </mediaobject>
	      </figure>
	      
	      <para>In examples above dropping a dragable item triggers the use a parameter in the event processing; Ajax request is sent and dropListener defined for the component is called.
	      </para>

		<para>
			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.)
		</para>

		<para>
			As draggable items, this table contains a list of such items
			designated as being of type
			<code>"text"</code>
			:
		</para>


		<para>
			<emphasis role="bold">Example:</emphasis>
		</para>

		<programlisting role="XML"><![CDATA[...
    <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>
...
]]></programlisting>

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


		<para>
			<emphasis role="bold">Example:</emphasis>
		</para>

		<programlisting role="XML"><![CDATA[...
    <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>
...
]]></programlisting>

		<para>
			As a part of the page that can be updated in a partial page
			update, this table has an ID of
			<code>box</code>
			:
		</para>


		<para>
			<emphasis role="bold">Example:</emphasis>
		</para>
		<programlisting role="XML"><![CDATA[...
    <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>
...]]></programlisting>

		<para>
			And finally, as a listener, this listener will implement the
			dropped element:
		</para>


		<para>
			<emphasis role="bold">Example:</emphasis>
		</para>
		<programlisting role="JAVA"><![CDATA[...
    public void addCapital2(DropEvent event) {
        FacesContext context = FacesContext.getCurrentInstance();
        Capital cap = new Capital();
        cap.setName(context.getExternalContext().getRequestParameterMap().get("name").toString());
        capitals2.add(cap);
    }
...
]]></programlisting>

		<para>
			Here is the result after a few drops of items from the first
			table:
		</para>

		<figure>
			<title>Results of drop actions</title>

			<mediaobject>
				<imageobject>
					<imagedata fileref="images/dropSupport2.png" />
				</imageobject>
			</mediaobject>
		</figure>

		<para>
			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.
		</para>

		<para>
			As with every Ajax action component,
			<emphasis role="bold">
				<property>&lt;rich:dropSupport&gt;</property>
			</emphasis>
			has all the common attributes (
			<emphasis>
				<property>"timeout"</property>
				,
			</emphasis>
			<emphasis>
				<property>"limitToList"</property>
				,
			</emphasis>
			<emphasis>
				<property>"reRender"</property>
				,
			</emphasis>
			etc.) for Ajax request customization.
		</para>

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

		<itemizedlist>
			<listitem>
				<para><emphasis><property>&quot;ondragenter&quot;</property></emphasis></para>
			</listitem>

			<listitem>
				<para><emphasis><property>&quot;ondragexit&quot;</property></emphasis></para>
			</listitem>

			<listitem>
				<para><emphasis><property>&quot;ondrop&quot;</property></emphasis></para>
			</listitem>

			<listitem>
				<para><emphasis><property>&quot;ondropend&quot;</property></emphasis></para>
			</listitem>
		</itemizedlist>

		<para>
			Developers can use their own custom JavaScript functions to
			handle these events.
		</para>
		<para>
			Information about the
			<emphasis>
				<property>&quot;process&quot;</property>
			</emphasis>
			attribute usage you can find in the 
			<link linkend="process"> &quot;Decide what to process&quot; </link> guide section
			.
		</para>
	</section>

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

		<para>
			<emphasis role="bold">
				<property>&lt;rich:dropSupport&gt;</property>
			</emphasis>
			has no skin parameters and custom
			<emphasis>
				<property>style classes</property>
			</emphasis>
			, as the component isn&apos;t visual.
		</para>
	</section>
	<section>
		<title>Relevant Resources Links</title>
		<para>
			<ulink
				url="http://livedemo.exadel.com/richfaces-demo/richfaces/dragSupport.jsf?c=dropSupport">
				On the component Live Demo page
			</ulink>
			you can see the example of
			<emphasis role="bold">
				<property>&lt;rich:dropSupport&gt;</property>
			</emphasis>
			usage and sources for the given example.
		</para>
	</section>

</section>
