<?xml version='1.0' encoding='UTF-8'?>
<section>
  <sectioninfo>
    <keywordset>
      <keyword>facet</keyword>
      <keyword>rich:togglePanel</keyword>
      <keyword>HtmltogglePanel</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.TogglePanel</entry>
        </row>
        <row>
          <entry>component-class</entry>
          <entry>org.richfaces.component.html.HtmlTogglePanel</entry>
        </row>
        <row>
          <entry>component-family</entry>
          <entry>org.richfaces.TogglePanel</entry>
        </row>
        <row>
          <entry>renderer-type</entry>
          <entry>org.richfaces.TogglePanelRenderer</entry>
        </row>
        <row>
          <entry>tag-class</entry>
          <entry>org.richfaces.Taglib.togglePanelTag</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 in a page: </para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
    <rich:togglePanel>
        <f:facet name="first">
            ...
        </f:facet>
        <f:facet name="second">
            ...
        </f:facet>
            ...
    </rich:togglePanel>
    ...
    <!--//Set of the toggleControls somewhere on a page.-->
...
]]></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.HtmltogglePanel;
...	
HtmltogglePanel myPanel = new HtmltogglePanel();
...
]]></programlisting>
  </section>
  <section>
    <title>Details of Usage</title>
    <para>As it was mentioned <link linkend="togglePanel">above</link>, <property>togglePanel</property> splits content into named
      facets that become rendered and processed when a click performed on controls linked to this
        <property>togglePanel</property> (either switched on the client or send requests on the
      server for switching).</para>
    <para>The initial component state is defined with <emphasis>
        <property>&quot;initialState&quot;</property>
      </emphasis> attribute, where a facet name that is shown at first is defined.</para>
    <note><title>Note:</title><para> It&apos;s also possible to define an
      <emphasis><property>&quot;empty&quot;</property></emphasis> facet to implement the functionality as
      drop-down panels have and make the facet active when no content is required to be rendered.</para></note>
    <para>Switching mode could be defined with the <emphasis>
        <property>&quot;switchType&quot;</property>
      </emphasis> attribute with three possible parameters:</para>
    <itemizedlist>
      <listitem><para> <code>Server</code> (DEFAULT)</para><para>The common submission is performed around
            <property>togglePanel</property> and a page is completely rendered on a called panel.
          Only one at a time the panel is uploaded onto the client side.</para>
      </listitem>
      <listitem><para> <code>Ajax</code></para><para>AJAX form submission is performed around the panel, content of the called
          panel is uploaded on an Ajax request and additionally specified elements in the <emphasis>
            <property>&quot;reRender&quot;</property>
          </emphasis> attribute are rendered. Only one at a time the panel is uploaded on the client
          side.</para>
      </listitem>
      <listitem><para> <code>Client</code></para><para> All panels are uploaded on the client side. The switching from the
          active to the hidden panel is performed with client JavaScript.</para>
      </listitem>
    </itemizedlist>
    <para>&quot;Facets&quot; switching order could be defined on the side of <emphasis
        role="bold">
        <property>&lt;rich:toggleControl&gt;</property>
      </emphasis> component or on the panel. On the side of the togglePanel it&apos;s possible
      to define facets switching order with the <emphasis>
        <property>&quot;stateOrder&quot;</property>
      </emphasis> attribute. The facets names are enumerated in such an order that they are rendered
      when a control is clicked, as it&apos;s not defined where to switch beforehand.</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
    <rich:togglePanel id="panel" initialState="panelB" switchType="client"
                        stateOrder="panelA,panelB,panelC">
        <f:facet name="panelA">
            ...
        </f:facet>
        <f:facet name="panelB">
            ...
        </f:facet>
        <f:facet name="panelC">
            ...
        </f:facet>
    </rich:togglePanel> 
    <rich:toggleControl for="panel" value="Switch"/>
...
]]></programlisting>
    <para>The example shows a <property>togglePanel</property> initial state when the second facet
      (<code>panelB</code>) is rendered and successive switching from the first to the second happens.</para>
    <para>
      The <emphasis>
        <property>&quot;label&quot;</property>
      </emphasis> attribute is a generic attribute.
      The <emphasis>
        <property>&quot;label&quot;</property>
      </emphasis> attribute provides an association between a component, and the message that the component (indirectly) produced.  
      This attribute defines the parameters of localized error and informational messages that
      occur as a result of conversion, validation, or other application actions during the request
      processing lifecycle. With the help of this attribute you can  replace the
      last parameter substitution token shown in the messages. For example, {1} for <code>&quot;DoubleRangeValidator.MAXIMUM&quot;</code>, {2}
      for <code>&quot;ShortConverter.SHORT&quot;</code>.
    </para>
  </section>
  <section>
    <title>Look-and-Feel Customization</title>
    <para>The component doesn&apos;t have its own representation rendering only content of its
      facets, thus all look and feel is set only for content.</para>
  </section>
  
  <section>
    <title>Definition of Custom Style Classes</title>
    <table  id="togglePC">
      <title>Classes names that define a component appearance</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>rich-toggle-panel</entry>
            <entry>Defines styles for all component</entry>
          </row>
          
          <row>
            <entry>rich-tglctrl</entry>
            <entry>Defines styles for a toggle control</entry>
          </row>
          
        </tbody>
      </tgroup>
    </table>
    <para>In order to redefine styles for all <emphasis role="bold">
      <property>&lt;rich:togglePanel&gt;</property>
    </emphasis> components on a page using CSS, it&apos;s enough to create classes with the
      same names (possible classes could be found in the tables <link linkend="togglePC"> above</link>) and define necessary properties in them. </para>
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[...
.rich-toggle-panel{
    font-style:italic;
}
...]]></programlisting>  
    
    <para>This is a result:</para>
    
    <figure>
      <title>Redefinition styles with predefined classes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/togglePanel_pc.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    
    <para>In the example the font style for output text was changed.</para>
    
    <para>Also it&apos;s possible to change styles of particular <emphasis role="bold"
      ><property>&lt;rich:togglePanel&gt;</property></emphasis> component. In this case you should create own style classes and use them in corresponding <emphasis role="bold"
        ><property>&lt;rich:togglePanel&gt;</property></emphasis> <property>styleClass</property> attributes. An example is placed below:</para>
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[...
.myClass{
    background-color:#bed6f8;
}
...]]></programlisting>  
    <para>The <emphasis><property>&quot;styleClass&quot;</property></emphasis> attribute for <emphasis role="bold"
      ><property>&lt;rich:togglePanel&gt;</property></emphasis> is defined as it&apos;s shown in the example below:</para>
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[<rich:togglePanel ... styleClass="myClass"/>
]]></programlisting>    
    
    <para>This is a result:</para>
    
    <figure>
      <title>Redefinition styles with own classes and <emphasis><property>&quot;styleClass&quot;</property></emphasis> attributes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/togglePanel_oc.png"/>
        </imageobject>
      </mediaobject>
    </figure>  
    
    <para>As it could be seen on the picture above, background color for panel was changed.</para>
    
    
    
    
  </section>
  
  <section>
    <title>Relevant Resources Links</title>
    <para>
      <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/togglePanel.jsf?c=togglePanel"
        >Here</ulink> you can see the example of <emphasis role="bold"
        ><property>&lt;rich:togglePanel&gt;</property></emphasis> usage and sources for the given example.
    </para>
  </section>
    
</section>
