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

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

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

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

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

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

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

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

          <entry>org.richfaces.taglib.PanelMenuTag</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:panelMenu event="onmouseover">
            <!--Nested panelMenu components-->
      </rich:panelMenu>
...]]></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.HtmlPanelMenu; 	
...
HtmlPanelMenu myPanelMenu = new HtmlPanelMenu();
...
]]></programlisting>
  </section>

  <section>
    <title>Details of Usage</title>

    <para>All attributes are not required.</para>
    <para>Use <emphasis>
        <property>&quot;event&quot;</property>
      </emphasis> attribute to define an event for appearance of collapsing/expanding sublevels.
      Default value is &quot;onclick&quot;. An example could be seen below.</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
      <rich:panelMenu event="onmouseover">
            <!--Nested panelMenu components-->
      </rich:panelMenu>
...]]></programlisting>

    <para>Switching mode could be chosen with the <emphasis>
        <property>&quot;mode&quot;</property>
      </emphasis> attribute for all panelMenu items except ones where this attribute was redefined.
      By default all items send traditional request. </para>
    <para>The <emphasis>
        <property>&quot;expandMode&quot;</property>
      </emphasis> attribute defines the submission modes for all collapsing/expanding panelMenu
      groups except ones where this attribute was redefined. </para>
    <para>The <emphasis>
        <property>&quot;mode&quot;</property>
      </emphasis> and <emphasis>
        <property>&quot;expandMode&quot;</property>
      </emphasis> attributes could be used with three possible parameters. The <emphasis>
        <property>&quot;mode&quot;</property>
      </emphasis> attribute defines parameters for all included <emphasis role="bold">
        <property>&lt;rich:panelMenuItem&gt;</property>
      </emphasis> elements.</para>

    <itemizedlist>
      <listitem>
        <para><code>Server</code> (default)</para>
      </listitem>
    </itemizedlist>

    <para>The common submission of the form is performed and a page is completely refreshed.</para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
      <rich:panelMenu mode="server">
          <rich:panelMenuGroup label="test Group" action="#{bean.action}"> 
              <rich:panelMenuItem label="test" action="#{capitalsBean.action}"> 
                  <f:param value="test value" name="test"/> 
              </rich:panelMenuItem> 
          </rich:panelMenuGroup>
      </rich:panelMenu>
...]]></programlisting>
    <itemizedlist>
      <listitem>
        <para><code>Ajax</code></para>
      </listitem>
    </itemizedlist>

    <para>An Ajax form submission is performed, and additionally specified elements in the <emphasis>
      <property>&quot;reRender&quot;</property>
    </emphasis> attribute are reRendered.</para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
      <rich:panelMenu mode="ajax">
           <rich:panelMenuGroup label="test Group" action="#{bean.action}"> 
               <rich:panelMenuItem label="test" reRender="test" action="#{capitalsBean.action}"> 
                   <f:param value="test value" name="test"/> 
               </rich:panelMenuItem> 
          </rich:panelMenuGroup>
      </rich:panelMenu>
...]]></programlisting>
    <itemizedlist>
      <listitem>
        <para><code>None</code></para>
      </listitem>
    </itemizedlist>
    
    <para><emphasis>
        <property>&quot;Action&quot;</property>
      </emphasis> and <emphasis>
        <property>&quot;ActionListener&quot;</property>
      </emphasis> item&apos;s attributes are ignored. Items don&apos;t fire any submits itself. Behavior is
      fully defined by the components nested into items.</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
      <rich:panelMenu event="onclick" submitMode="none">
            <rich:panelMenuItem label="Link to external page">
                  <h:outputLink ... >
            <rich:panelMenuItem>
      </rich:panelMenu>
...]]></programlisting>

    <note><title>Note:</title><para> As the <emphasis role="bold">
        <property>&lt;rich:panelMenu&gt;</property>
      </emphasis> component doesn&apos;t provide its own form, use it between
      <emphasis role="bold"> <property>&lt;h:form&gt;</property></emphasis> and  <emphasis role="bold"><property>&lt;/h:form&gt;</property> </emphasis> tags.</para></note>

    <para>The <emphasis>
        <property>&quot;expandSingle&quot;</property>
      </emphasis> attribute is defined for expanding more than one submenu on the same level. The
      default value is <emphasis>
        <property>&quot;false&quot;</property>
      </emphasis>. If it&apos;s true the previously opened group on the top level closes before
      opening another one. See the picture below.</para>

    <figure>
      <title>Using the <emphasis><property>&quot;expandSingle&quot;</property></emphasis> attribute</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/panelMenu2.png"/>
        </imageobject>
      </mediaobject>
    </figure>

    <para>The <emphasis>
        <property>&quot;selectedChild&quot;</property>
      </emphasis> attribute is used for defining the name of the selected group or item. An example
      for group is placed below:</para>

    <para>Here is an example:</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
      <rich:panelMenu selectedChild="thisChild">
        <rich:panelMenuGroup label="Group1" name="thisChild">
          <!--Nested panelMenu components-->
        </rich:panelMenuGroup>
      </rich:panelMenu>
      ...]]></programlisting>
    <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>JavaScript API</title>
    <para>In Java Script code for expanding/collapsing group element creation it&apos;s
      necessary to use <code>expand()</code>/<code>collapse()</code> function.</para>

    <table>
      <title>JavaScript API</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Function</entry>

            <entry>Description</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>expand()</entry>

            <entry>Expands group element</entry>
          </row>

          <row>
            <entry>collapse()</entry>

            <entry>Collapses group element</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

  </section>
  
  <section>
    <title>Look-and-Feel Customization</title>
    
    <para>For skinnability implementation, the components use a <emphasis>
      <property>style class redefinition method.</property>
    </emphasis></para>
    
    <para>There are no skin parameters. To redefine the appearance of all <emphasis role="bold">
      <property>&lt;rich:panelMenu&gt;</property>
    </emphasis> components at once, you should add to your style sheets the <emphasis>
          <property>style class</property>
        </emphasis> used by a <emphasis role="bold">
          <property>&lt;rich:panelMenu&gt;</property>
        </emphasis> component.</para>
  </section>

  <section>
    <title>Definition of Custom Style Classes</title>
    
    <table id="tab_cn_pM">
      <title>Classes names that define a component appearance</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            <entry>Class description</entry>
          </row>
        </thead>
        <tbody>
         
          <row>
            <entry>rich-pmenu</entry>
            <entry>Defines styles for a wrapper  &lt;div&gt; element of a component</entry>
          </row>
                    <row>
            <entry>rich-pmenu-top-group</entry>
             <entry>Defines styles for a top group element of a component</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <para>In order to redefine styles for all <emphasis role="bold">
      <property>&lt;rich:panelMenu&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="tab_cn_pM"> above</link>) and define necessary properties in them. </para>
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[...
.rich-pmenu{
    font-style:italic;
}
...]]></programlisting>  
    
    <para>This is a result:</para>
    
    <figure>
      <title>Redefinition styles with predefined classes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/panelMenu_pc.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    
    <para>In the example the font style was changed.</para>
    
    <para>Also it&apos;s possible to change styles of particular <emphasis role="bold"
      ><property>&lt;rich:panelMenu&gt;</property></emphasis> component. In this case you should create own style classes and use them in corresponding <emphasis role="bold"
        ><property>&lt;rich:panelMenu&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: #ecf4fe;
}
...]]></programlisting>  
    <para>The <emphasis><property>&quot;hoveredItemClass&quot;</property></emphasis> attribute for <emphasis role="bold"
      ><property>&lt;rich:panelMenu&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:panelMenu ... hoveredItemClass="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/panelMenu_oc.png"/>
        </imageobject>
      </mediaobject>
    </figure>  
    
    <para>As it could be seen on the picture above,background color for hovered item was changed.</para>
    
    
    
  </section>
  <section>
    <title>Relevant Resources Links</title>
    <para><ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/panelMenu.jsf?c=panelMenu"
      >On the component LiveDemo page</ulink> you can see the example of <emphasis role="bold"
        ><property>&lt;rich:panelMenu&gt;</property></emphasis> usage and sources for the given example. </para>
  </section>        

</section>
