<?xml version="1.0" encoding="UTF-8"?>
<section>
  <sectioninfo>
    <keywordset>
      <keyword>rich:componentControl</keyword>
      <keyword>componentControl</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.ComponentControl</entry>
        </row>

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

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

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

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

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

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

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

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

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

    <para>To create the simplest variant on a page use the following syntax:</para>


    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<rich:componentControl attachTo="doExpandCalendarID" for="ccCalendarID" event="onclick" operation="Expand" />
...]]></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.HtmlComponentControl; 	
...
HtmlComponentControl myComponentControl = new HtmlComponentControl();
...
]]></programlisting>
  </section>

  <section>
    <title>Details of Usage</title>
    <para>
      In order to use the <emphasis role="bold"><property>&lt;rich:componentControl&gt;</property></emphasis> with another components you need to take the following steps:
    
    <!--
      There are three ways to use the <emphasis role="bold">
        <property>&lt;rich:componentControl&gt;</property>
      </emphasis> to another component.
      -->
    </para>
    <itemizedlist>
      <listitem><para>Define a name of a function that is generated (definition is similar to a
        definition of <emphasis role="bold">
          <property>&lt;a4j:jsFunction&gt;</property>
        </emphasis>). An &quot;event&quot; argument is passed to this function.</para></listitem>
    </itemizedlist>
    <para>An example is placed below:</para>
    <programlisting role="XML"><![CDATA[...
<rich:componentControl name="ffunction" for="comp_ID" operation="show"/>
...
]]></programlisting>
    <para>According to this code a function with name <property>ffunction</property>
      is generated. It is used in JavaScript code to trigger an operation on the target component
      with defined <property>id</property>=&quot;comp_ID&quot;.</para>
    <para>The generated function is shown below:</para>
    <programlisting role="JAVA"><![CDATA[function ffunction (event) {
}
]]></programlisting>
    <itemizedlist>
      <listitem><para>Attach to a parent component (usage is similar to <emphasis role="bold">
          <property>&lt;a4j:support&gt;</property>
        </emphasis> component).</para></listitem>
    </itemizedlist>
    <para>An example is placed below:</para>

    <programlisting role="XML"><![CDATA[...
<rich:modalPanel id="ccModalPanelID" onshow="alert(event.parameters.show)" onhide="alert(event.parameters.hide)">
    <h:outputText value="#{bean.text}"/>
</rich:modalPanel>
<h:commandButton value="Show Modal Panel">
    <rich:componentControl for="ccModalPanelID" event="onclick" disableDefault="true" operation="show">
        <f:param name="show" value="componentControl work(show)"/>
    <rich:componentControl/>
</h:commandButton>
...
]]></programlisting>
    <para>In the example the <emphasis>
        <property>&quot;for&quot;</property>
    </emphasis> attribute contains value of an <property>id</property> of <emphasis role="bold">
        <property>&lt;rich:modalPanel&gt;</property>
      </emphasis> component. The <emphasis>
        <property>&quot;operation&quot;</property>
      </emphasis> attribute contains a name of JavaScript API function. An <emphasis>
        <property>&quot;event&quot;</property>
      </emphasis> attribute is used to trigger an operation defined with the <emphasis>
        <property>&quot;operation&quot;</property>
      </emphasis> attribute. A set of parameters is defined with <emphasis role="bold">
        <property>&lt;f:param&gt;</property>
      </emphasis>. As an alternative, the <emphasis>
        <property>&quot;params&quot;</property>
      </emphasis> attribute can be used. Thus, one of main features is that <emphasis role="bold">
        <property>&lt;rich:componentControl&gt;</property>
      </emphasis> allows to transfer parameters. The <emphasis>
        <property>&quot;disableDefault&quot;</property>
      </emphasis> attribute with <property>&quot;true&quot;</property> value is used instead
      of <property>onclick="return false;"</property> attribute for <emphasis role="bold">
        <property>&lt;h:commandButton&gt;</property>
      </emphasis> to avoid a problem with form submit and <property>modalPanel</property> showing.</para>
    <itemizedlist>
      <listitem><para>Attach with <emphasis>
          <property>&quot;attachTo&quot;</property>
        </emphasis> attribute.</para></listitem>
    </itemizedlist>
    <para>An example is placed below:</para>

    <programlisting role="XML"><![CDATA[...
<rich:calendar popup="#{componentControl.calendarPopup}" id="ccCalendarID" />
    ...
<f:verbatim>
    <a href="#" id="doExpandCalendarID">Calendar (nextYear)</a>
</f:verbatim>
<rich:componentControl attachTo="doExpandCalendarID" for="ccCalendarID" event="onclick" disableDefault="true" operation="nextYear" />
...
]]></programlisting>
    <para>In the example the <emphasis>
        <property>&quot;attachTo&quot;</property>
    </emphasis> attribute contais a value of an <property>id</property> of <emphasis role="bold"><property>&lt;a&gt;</property></emphasis> element.
      The <emphasis>
        <property>&quot;for&quot;</property>
      </emphasis> attribute contains value of an <property>id</property> of <emphasis role="bold">
        <property>&lt;rich:calendar&gt;</property>
      </emphasis> component. The <emphasis>
        <property>&quot;operation&quot;</property>
      </emphasis> attribute contains a name of JavaScript API function. Thus, clicking on the link
      represents the next year on the calendar.
    </para>
    <para>
      With the help of the <emphasis><property>&quot;attachTiming&quot;</property></emphasis> attribute you can define the page loading phase when
      <emphasis role="bold"><property>&lt;rich:componentControl&gt;</property></emphasis> is attached to source component. Possible values are: 
    </para>
    <itemizedlist>
      <listitem>
        <para>
          &quot;immediate&quot; - attached during execution of <emphasis role="bold"><property>&lt;rich:componentControl&gt;</property></emphasis> script
        </para>
      </listitem>
      <listitem>
        <para>
          &quot;onavailable&quot; - attached after the target component is initialized
        </para>
      </listitem>
      <listitem>
        <para>
          &quot;onload&quot; - attached after the page is loaded
        </para>
      </listitem>
    </itemizedlist>
    <para>
      <emphasis role="bold">
        <property>&lt;rich:componentControl&gt;</property>
      </emphasis> interacts with such components as:

<emphasis role="bold">
          <property>&lt;rich:contextMenu&gt;</property>
        </emphasis>, <emphasis role="bold">
          <property>&lt;rich:toolTip&gt;</property>
        </emphasis>, <emphasis role="bold">
          <property>&lt;rich:modalPanel &gt;</property>
        </emphasis>, <emphasis role="bold">
          <property>&lt;rich:listShuttle&gt;</property>
        </emphasis>, <emphasis role="bold">
          <property>&lt;rich:orderingList&gt;</property>
        </emphasis>, <emphasis role="bold">
          <property>&lt;rich:calendar&gt;</property>
        </emphasis>
             
    </para>
    <para>In order to use  <emphasis role="bold">
      <property>&lt;rich:componentControl&gt;</property>
    </emphasis> with another component you should place the id of this component into <emphasis>
      <property>&quot;for&quot;</property>
    </emphasis> attribute field. All operations with defined component you can find in the JavaScript API section of defined component.</para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<f:view>
    <h:form>
        <br />
        <rich:toolTip id="toolTipFor" followMouse="false" direction="top-right" mode="ajax" value="This is button" horizontalOffset="5" verticalOffset="5" layout="block" />
    </h:form>
    <h:commandButton id="ButtonID" value="Button">
        <rich:componentControl for="toolTipFor" attachTo="ButtonID" operation="show" event="onclick"/>
    </h:commandButton>
</f:view>
...]]></programlisting>
    <para>This is a result:</para>
    <figure>
      <title><emphasis role="bold">
        <property>&lt;rich:toolTip&gt;</property>
      </emphasis> shows with the help of <emphasis role="bold">
        <property>&lt;rich:componentControl&gt;</property>
      </emphasis>.</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/componentControl_init.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    
    <para>
      As it could be seen in the picture above, the <emphasis role="bold">
        <property>&lt;rich:toolTip&gt;</property>
      </emphasis> shows after you click the button.
    </para>
    
    <!--para>One more example of <emphasis role="bold">
        <property>&lt;rich:componentControl&gt;</property>
      </emphasis> usage is placed below:</para>
    <programlisting role="XML"><![CDATA[...
    <rich:panelMenu id="ccContextMenuPanelMenuID">
        <h:outputText value="click text" />
    </rich:panelMenu>
    <rich:contextMenu id="ccContextMenuID" submitMode="ajax">
        <rich:menuItem icon="/pics/header.png" value="tab1" reRender="cmInfoID">
            <f:param name="cmdParam" value="menu" />
        </rich:menuItem>
        <rich:menuSeparator />
        <rich:menuItem icon="/pics/info.png" value="a" reRender="cmInfoID">
            <f:param name="cmdParam" value="a" />
        </rich:menuItem>
        <rich:menuItem icon="/pics/info.png" value=" b" reRender="cmInfoID">
            <f:param name="cmdParam" value="b" />
        </rich:menuItem>
        <rich:menuItem icon="/pics/info.png" value="c" reRender="cmInfoID">
            <f:param name="cmdParam" value="c" />
        </rich:menuItem>
    </rich:contextMenu>
    <rich:componentControl event="oncontextmenu" attachTo="ccContextMenuPanelMenuID" for="ccContextMenuID" disableDefault="true" operation="Show" />
...
]]></programlisting-->

  </section>

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

    <para><emphasis role="bold">
        <property>&lt;rich:componentControl&gt;</property>
      </emphasis> has no skin parameters and custom <property>style classes</property>, 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/componentControl.jsf?c=componentControl"
        >Here</ulink> you can see an example of <emphasis role="bold">
        <property>&lt;rich:componentControl&gt;</property>
        </emphasis> usage and sources for the given example. </para>
    <para>
      <ulink url="http://java.sun.com/javaee/javaserverfaces/1.1_01/docs/tlddocs/f/param.html">Here</ulink> you can found some additional information about <emphasis role="bold"><property>&lt;f:param&gt;</property></emphasis> component.
    </para>
  </section>

</section>
