<section role="NotInToc" id="rich_componentControl">
   <title>
				&lt;
				rich:componentControl
				&gt;
				<emphasis role="since">
         <superscript> available since <emphasis role="version">3.0.0</emphasis>
         </superscript>
      </emphasis>
   </title>
   <section>
        <title>Description</title>
        <para>The <emphasis role="bold">
                <property>&lt;rich:componentControl&gt;</property>
            </emphasis> allows to call JavaScript API functions on components after defined events.</para>
    </section>
   <section>
        <title>Key Features</title>
        <itemizedlist>
            <listitem>
                <para>
                    Management of components JavaScript API 
                </para>
            </listitem>
            <listitem>
                <para>
                    Customizable initialization variants
                </para>
            </listitem>
            <listitem>
                <para>
                    Customizable activation events
                </para>
            </listitem>
            <listitem>
                <para>
                    Possibility to pass parameters to the target component
                </para>
            </listitem>
        </itemizedlist>
    </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" operation="Expand" for="ccCalendarID" />
...
]]></programlisting>
      <para>
          In other words it means "clicking on the component with ID <code>doExpandCalendarID</code> expands the component with ID <code>ccCalendarID</code>". 
          It can be said, that <emphasis role="bold">
            <property>&lt;rich:componentControl&gt;</property>
         </emphasis> makes interact two components with the help of JavaScript API function.
    </para>
      <para>
          The ID of the component the event that invokes JavaScript API function is applied, is defined with <emphasis>
            <property>"attachTo"</property>
         </emphasis> attribute (see the exapmle above). 
          If <emphasis>
            <property>"attachTo"</property>
         </emphasis> attribute is not specified, the <emphasis role="bold">
            <property>&lt;rich:componentControl&gt;</property>
         </emphasis> is supposed to be attached to it's parent.
    </para>
    
      <programlisting role="XML"><![CDATA[<h:commandButton value="Show Modal Panel">
      <!--componentControl is attached to the commandButton-->
      <rich:componentControl for="ccModalPanelID" event="onclick" operation="show"/> 
</h:commandButton>]]></programlisting>
      <para>
          It is possible to invoke the <emphasis role="bold">
            <property>&lt;rich:componentControl&gt;</property>
         </emphasis> handler operation as usual JavaScript function. 
          For this purpose it is necessary to specify the name of the JS function with the help of the <emphasis>
            <property>"name"</property>
         </emphasis> attribute:
    </para>
        <para>
              <emphasis role="bold">Example:</emphasis>
        </para>     
        <programlisting role="text/javascript"><![CDATA[function func (event) {
}]]></programlisting>
        <programlisting role="XML"><![CDATA[<rich:componentControl name="func" event="onRowClick" for="menu" operation="show" />]]></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>"params"</property>
         </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>
   
      <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[<![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[<![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[<![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[<![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>"attachTiming"</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>
              <code>immediate</code> — attached during execution of <emphasis role="bold">
                  <property>&lt;rich:componentControl&gt;</property>
               </emphasis> script
        </para>
         </listitem>
         <listitem>
            <para>
              <code>onavailable</code> — attached after the target component is initialized
        </para>
         </listitem>
         <listitem>
            <para>
              <code>onload</code> — 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>"for"</property>
         </emphasis> attribute field. 
          All operations with defined component you can find in the JavaScript API section of defined component.
    </para>
    
      <programlisting role="XML"><![CDATA[<h:form>
      <rich:toolTip id="toolTip" mode="ajax" value="and then just touch me." direction="top-right" />
</h:form>
<h:commandButton id="ButtonID" value="Push me">
      <rich:componentControl attachTo="ButtonID" event="onmouseover" operation="show" for="toolTip" />
</h:commandButton>]]></programlisting>
      <para>This is a result:</para>
      <figure>
         <title>
            <emphasis role="bold">
               <property>&lt;rich:toolTip&gt;</property>
            </emphasis> is shown 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>One more example of <emphasis role="bold">
        <property>&lt;rich:componentControl&gt;</property>
      </emphasis> usage is placed below:</para>
    <programlisting role="XML"><![CDATA[<![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>Reference Data</title>
      <para>
         <ulink url="&tlddoc;rich/componentControl.html">Table of 
							&lt;rich:componentControl&gt; 
							 attributes</ulink>.
						</para>
      <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>
   <section>
      <title>Relevant Resources Links</title>
      <para>
          Visit the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/componentControl.jsf?c=componentControl">ComponentControl page</ulink> at RichFaces LiveDemo for examples of component usage and their sources. 
     </para>
      <para>
          Information on JSF <emphasis role="bold">
            <property>&lt;f:param&gt;</property>
         </emphasis> component You can find at <ulink url="http://java.sun.com/javaee/javaserverfaces/1.1_01/docs/tlddocs/f/param.html">&lt;f:param&gt; TLD reference</ulink> in Java Server Faces technology section at Sun portal.
    </para>
  </section>
</section>
