<?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>
      <emphasis role="bold"><property>&lt;rich:componentControl&gt;</property></emphasis> 
      is a command component, that allows to call JavaScript API function on some defined event. 
      Look at the example:
      </para>
      <programlisting role="XML"><![CDATA[...
<rich:componentControl attachTo="doExpandCalendarID" event="onclick" for="ccCalendarID" operation="Expand"/>
...
]]></programlisting>
    <para>
      In other words it means &quot;clicking on the component with ID &apos;doExpandCalendarID&apos;, 
      expands the component with ID &apos;ccCalendarID&apos;&quot;. 
      It can be said, that <emphasis role="bold"><property>&lt;rich:componentControl&gt;</property></emphasis> 
      connects two components with the help of JavaScript API function.
    </para>
    <para>
      Component ID, to wich the event, that invokes JavaScript API function is applied, 
      is defined with <emphasis><property>&quot;attachTo&quot;</property></emphasis> attribute 
      (see the exapmle above). 
      If <emphasis><property>&quot;attachTo&quot;</property></emphasis> attribute is not defined, 
      the component will be attached to the parent component.
    </para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<h:commandButton value="Show Modal Panel">
      <rich:componentControl for="ccModalPanelID" event="onclick" operation="show"/> <!--attached to the commandButton-->
</h:commandButton>
...]]></programlisting>
    <para>
      On the result page the component is rendered to JavaScript code. 
      This means, that it is possible to invoke the <emphasis role="bold"><property>&lt;rich:componentControl&gt;</property></emphasis> 
      handler operation as usual JavaScript function.  
      This function is called by name, specified in the component <emphasis><property>&quot;name&quot;</property></emphasis> attribute. 
      The definition of <emphasis><property>&quot;name&quot;</property></emphasis> attribute is shown on the example below:
    </para>
    <programlisting role="XML"><![CDATA[...
<rich:componentControl name="func" event="onRowClick" for="menu" operation="show" />
...]]></programlisting>
    <para>
      The generated JavaScript function will look as shown below:
    </para>
    <programlisting role="XML"><![CDATA[function func (event) {
}]]></programlisting>
      <para>
        An important <emphasis role="bold"><property>&lt;rich:componentControl&gt;</property></emphasis> feature, 
        is that it allows transferring parameters, with the help of special attribute <emphasis><property>&quot;params&quot;</property></emphasis>.
      </para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<rich:componentControl name="func" event="onRowClick" for="menu" operation="show" params=”#{car.model}"/>
...]]></programlisting>
    <para>
      The alternative way for parameters transferring uses <emphasis role="bold"><property>&lt;f:param&gt;</property></emphasis> attribute. 
      As the code above, the following code will represent the same functionality.
    </para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<rich:componentControl event="onRowClick" for="menu" operation="show">
      <f:param value="#{car.model}" name="model"/>
</rich:componentControl>
...]]></programlisting>
    
      
      
      
     
      
      
      
      
      
 <!--     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:
    
  
    </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;<code>event</code>&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 <code>ffunction</code>
      is generated. It is used in JavaScript code to trigger an operation on the target component
      with defined <code>id=&quot;comp_ID&quot;</code>.</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 &quot;true&quot; value is used instead
      of <code>onclick="return false;"</code> 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"
        >On RichFaces LiveDemo page </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">On RichFaces LiveDemo page </ulink> you can found some additional information about <emphasis role="bold"><property>&lt;f:param&gt;</property></emphasis> component.
    </para>
  </section>

</section>
