<?xml version='1.0' encoding='UTF-8'?>
<section>
  <sectioninfo>
    <keywordset>
      <keyword>dragged element</keyword>
      <keyword>rich:dragIndicator</keyword>
      <keyword>HtmlDragIndicator</keyword>
      <keyword>dndParam</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.Draggable</entry>
        </row>
        <row>
          <entry>component-class</entry>
          <entry>org.richfaces.component.html.HtmlDragIndicator</entry>
        </row>
        <row>
          <entry>component-family</entry>
          <entry>org.richfaces.DragIndicator</entry>
        </row>
        <row>
          <entry>renderer-type</entry>
          <entry>org.richfaces.DragIndicatorRenderer</entry>
        </row>
        <row>
          <entry>tag-class</entry>
          <entry>org.richfaces.taglib.DragIndicatorTag</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[...	
    <rich:dragIndicator  id="indicator">
        <f:facet name="single">
            <f:verbatim>
                <b>Single item</b> {DragInfo}
            </f:verbatim>
        </f:facet>
    </rich:dragIndicator>
    ...
    <rich:dragSupport dragType="text" dragIndicator="indicator">
...
]]></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.HtmlDragIndicator;
...
HtmlDragIndicator myDragIndicator = new HtmlDragIndicator();
...
]]></programlisting>
  </section>

  <section>
    <title>Details of Usage</title>
    <para> In the simplest way the component could be defined empty - in that case a default
      indicator is shown like this: </para>
    <figure>
      <title>The simplest <emphasis role="bold"><property>&lt;rich:dragIndicator&gt;</property></emphasis> </title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/dragIndicator3.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    <para>For indicator customization you need to define one of the following facets:</para>
    <itemizedlist>
		<listitem>
			<para>
				<emphasis><property>&quot;single&quot;</property></emphasis> — indicator shown when dragging a single item;
			</para>
		</listitem>
		<listitem>
			<para>
				<emphasis><property>&quot;multiple&quot;</property></emphasis> — indicator shown when dragging several items.
			</para>
		</listitem>
    </itemizedlist>
    	  
	  <note>
      <title>
        Note:
      </title>
      <para>
         The current implementation of the <emphasis role="bold"><property>&lt;rich:dragIndicator&gt;</property></emphasis> component 
		 does not support multiple items selection. The feature is described for future releases.
	  </para>
    </note>
	  
    <para>Thus for specify a look-and-feel you have to define one of these facets and include into
      it a content that should be shown in indicator.</para>
    <section>
      <title>Macro definitions</title>
      <para>To place some data from drag or drop zones into component you can use macro definitions.
        They are being defining in the following way:</para>
      <itemizedlist>
        <listitem><para>
          <emphasis role="bold">
            <property>&lt;rich:dndParam&gt;</property>
          </emphasis> component with a specific name and value is being included into a drag/drop
          support component (an image can be defined as placed inside <emphasis role="bold">
            <property>&lt;rich:dndParam&gt;</property>
          </emphasis> without defining a value). </para></listitem>
        <listitem><para> in needed place a parameter value is included into the marking of indicator using
          syntax (name of parameter)</para></listitem>
      </itemizedlist>
      <para> For instance, this:</para>
      <programlisting role="XML"><![CDATA[...	
    <rich:dropSupport...>
        <rich:dndParam name="testDrop">
            <h:graphicImage value="/images/file-manager.png" />
        </rich:dndParam>
    </rich:dropSupport>
...
]]></programlisting>
      <para>Is placed into indicator as follows:</para>
      <programlisting role="XML"><![CDATA[...	
    <f:facet name="single">
        {testDrop}
    </f:facet>
...
]]></programlisting>
    </section>
    <section>
      <title>Predefined macro definitions</title>
      <para> Indicator can accept two default macro definitions:</para>
      <itemizedlist>
        <listitem><para>marker</para></listitem>
        <listitem><para>label</para></listitem>
      </itemizedlist>
      <para>Thus including one of these elements in the marking of indicator, in other words after
        setting up appropriate parameters in DnD components and defining only default indicator -
        without specifying facets - a developer gets these parameters values displayed in indicator
        in the order &quot;marker - label&quot;.</para>
    </section>

    <section>
      <title>Marker customization</title>
      <para>The macro definition <emphasis>
          <property>&quot;marker&quot;</property>
        </emphasis> can be customized depending on what a draggable element is located over. For
        that you should define one of these three parameters (specify a parameter with one of three
        names):</para>
      <itemizedlist>
        <listitem><para><code>accept</code> </para></listitem>
      </itemizedlist>
      <para>Parameter will be set instead of {marker} into indicator when a draggable element is
        positioned over drop zone that accept this type of elements</para>

      <itemizedlist>
        <listitem><para><code>reject</code></para></listitem>
      </itemizedlist>
      <para>Parameter is set instead of {marker} into indicator when a draggable element is
        positioned over drop zone that doesn&apos;t accept this type of elements </para>

      <itemizedlist>
        <listitem><para><code>default</code></para></listitem>
      </itemizedlist>
      <para>Parameter is set instead of {marker} into indicator when a draggable element is
        positioned over all the rest of page elements</para>
    </section>

    <note>
      <title>
        Note:
      </title>
      <para>
        If you use <emphasis role="bold"><property>&lt;rich:dragIndicator&gt;</property></emphasis> inside a form 
        do not forget to use id like <code>formId:indicatorID</code> 
        defined in <emphasis role="bold"><property>&lt;rich:dragSupport&gt;</property></emphasis> indicator attribute.
      </para>
    </note>
    
  </section>

  <!--section>
    <title>Details of Usage</title>
    <para>The component seems to be combined of two elements: an icon on the left and informational
      part on the right. The definition and usage is described further for each element.</para>
    <section>
      <title>Indicator informational part</title>
      <para>Inside the component, the definition should present for two facets with single and
        multiple names providing templates for rendering during dragging one or several elements.
        The facets define the right side of the <property>indicator</property> element.</para>
      <para>The following elements on a page are obtained for a code defined in the example:</para>
      <figure>
        <title>DragIndicator informational part</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/dragIndicator2.png"/>
          </imageobject>
        </mediaobject>
      </figure>
      <para>Hence, defining dndParam corresponding to drag areas, information transmitted into an
          <property>indicator</property> is defined.</para>
    </section>
    <section>
      <title>Indicator icon element</title>
      <para>Inside the component there also could be definitions for three faces with
            <emphasis><property>&quot;accept&quot;</property>,</emphasis>
        <emphasis>
          <property>&quot;reject&quot;</property>
        </emphasis> and <emphasis>
          <property>&quot;default&quot;</property>
        </emphasis> names that specify icons on the left side according to states when an
          <property>indicator</property> is above:</para>
      <itemizedlist>
        <listitem> a drop zone that processes the facets written in the <emphasis>
            <property>&quot;acceptedTypes&quot;</property>
          </emphasis> attribute of this drop zone </listitem>
        <listitem> a drop zone that doesn&apos;t process the facets </listitem>
        <listitem> not above any drop zone </listitem>
      </itemizedlist>
      <para>Here is an example for an accept facet:</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
      <programlisting role="XML"><![CDATA[...
    <f:dndParam name="accept">
        <h:graphicImage value="./images/1.png"/>
    </f:dndParam>
...
]]></programlisting>
      <para>Each of these three facets have a default structure for icons rendering on the left
        side.</para>
      <para>When it&apos;s necessary to define individual icons for dragged above elements of a
          <property>drop zone</property> from each particular drag area, use a <property>drop zone</property>
        <emphasis>
          <property>&quot;typeMapping&quot;</property>
        </emphasis> attribute for the corresponding icons.</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
      <programlisting role="XML"><![CDATA[...
    <rich:dropSupport acceptedTypes="[iconsDragged, textDragged]" typeMapping="{iconsDragged: DropIcon}">
        <dnd:dndParam name="DropIcon">
            <h:graphicImage value="/images/drop-icon.png"/>
        </dnd:dndParam>
    <rich:dropSupport/>
...
]]></programlisting>
      <para>Here, drag areas that are to be processed with this drop zone are of iconsDragged and
        textDragged type. An icon is redefined for iconsDragged with the help of the drop zone <emphasis>
          <property>&quot;typeMapping&quot;</property>
        </emphasis> attribute defined with the <emphasis role="bold">
          <property>&lt;rich:dndParam&gt;</property>
        </emphasis>component.</para>

    </section>
    </section-->

  <section>
    <title>Look-and-Feel Customization</title>
    <para>The <emphasis role="bold"><property>&lt;rich:dragIndicator&gt;</property></emphasis> component has no skin parameters and special <emphasis>
      <property>style classes</property></emphasis>, as it consists of one element
      generated with a your method on the server. To define some style properties such as an indent
      or a border, it&apos;s possible to use <emphasis>
        <property>&quot;style&quot;</property></emphasis> and <emphasis>
          <property>&quot;styleClass&quot;</property></emphasis> attributes on the component.</para>
  </section>
  <section>
    <title>Relevant Resources Links</title>
    <para>
      <ulink
        url="http://livedemo.exadel.com/richfaces-demo/richfaces/dragSupport.jsf?c=dragIndicator"
        >On the component LiveDemo page</ulink> you can see the example of <emphasis role="bold">
        <property>&lt;rich:dragIndicator&gt;</property>
      </emphasis> usage and sources for the given example. </para>
  </section>
 
</section>
