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

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

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

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

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

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

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

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

                                                  <entry>org.richfaces.taglib.PanelMenuItemTag</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>
             ...
            <rich:panelMenuItem value="Item1"/>
            ...	
      </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.HtmlPanelMenuItem; 	
...
HtmlPanelMenuItem myPanelMenuItem = new HtmlPanelMenuItem();
...
]]></programlisting>
          </section>

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

                    <para>All attributes except <emphasis>
                                        <property>&quot;label&quot;</property>
                              </emphasis> are optional. The <emphasis>
                                        <property>&quot;label&quot;</property>
                              </emphasis> attribute defines text to be represented.</para>
                    <para>The <emphasis>
                                        <property>&quot;mode&quot;</property>
                              </emphasis> attribute could be used with three possible parameters:</para>

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

                    <para>Regular form submission request is used.</para>

                    <itemizedlist>
                              <listitem>
                                        <para>
                                                  <code>Ajax</code>
                                        </para>
                              </listitem>
                    </itemizedlist>

                    <para>Ajax submission is used for switching.</para>

                    <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> attributes are ignored. Items don&apos;t fire any
                              submits itself. Behavior is fully defined by the components nested
                              into items.</para>

                    <para>Here is an example for value &quot;none&quot;:</para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="XML"><![CDATA[...
      <rich:panelMenu>
            ...
            <rich:panelMenuItem mode="none" onclick="document.location.href='http://labs.jboss.com/jbossrichfaces/">
                  <h:outputLink value="http://labs.jboss.com/jbossrichfaces/">
                        <h:outputText value="RichFaces Home Page"></h:outputText>
                  </h:outputLink>
            </rich:panelMenuItem>
            ...
      </rich:panelMenu>
...]]></programlisting>

                    <para>There are two icon-related attributes. The <emphasis>
                                        <property>&quot;icon&quot;</property>
                              </emphasis> attribute defines an icon. The <emphasis>
                                        <property>&quot;iconDisabled&quot;</property>
                              </emphasis> attribute defines an icon for a disabled item.</para>

                    <para>Default icons are shown on the picture below:</para>

                    <figure>
                              <title>Default icons</title>

                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/panelMenuItem2.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>

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

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="XML"><![CDATA[...
      <rich:panelMenu>
            ...
            <rich:panelMenuItem value="Item 1.1" icon="chevronUp" />
            ...	
      </rich:panelMenu>
...]]></programlisting>
                    <para> As the result the picture is shown below:</para>

                    <figure>
                              <title>Using an <emphasis>
                                                  <property>&quot;icon&quot;</property>
                                        </emphasis> attribute</title>

                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/panelMenuItem3.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>

                    <para>It&apos;s also possible to define a path to the icon. Simple code is
                              placed below.</para>

                    <programlisting role="XML"><![CDATA[...
      <rich:panelMenu>
            ...
            <rich:panelMenuItem value="Item 1.1" icon="\images\img1.png" />
            ...	
      </rich:panelMenu>
...]]></programlisting>
                    <para> Information about the <emphasis>
                                        <property>&quot;process&quot;</property>
                    </emphasis> attribute usage you can find in the 
                              <link linkend="process"> &quot;Decide what to process&quot; </link> guide section. </para>
          </section>

          <!--section>
    <title>JavaScript API</title>
    <para>In Java Script code for expanding/collapsing group element creation it&apos;s
      necessary to use doExpand()/doCollapse() function.</para>

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

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

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

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

            <entry>Expand group element</entry>
          </row>

          <row>
            <entry>doCollapse()</entry>

            <entry>Collapse 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> Default style classes are mapped on <emphasis>
                                        <property>skin parameters.</property>
                              </emphasis></para>

                    <para>There are two ways to redefine the appearance of all <emphasis role="bold">
                                        <property>&lt;rich:panelMenuItem&gt;</property>
                              </emphasis> components at once:</para>

                    <itemizedlist>
                              <listitem>
                                        <para>Redefine the corresponding skin parameters</para>
                              </listitem>

                              <listitem>
                                        <para>Add to your style sheets <emphasis>
                                                  <property>style classes</property>
                                                  </emphasis> used by a <emphasis role="bold">
                                                  <property>&lt;rich:panelMenuItem&gt;</property>
                                                  </emphasis> component</para>
                              </listitem>
                    </itemizedlist>
          </section>

          <section>
                    <title> Skin Parameters Redefinition</title>

                    <table>
                              <title>Skin parameters redefinition for a table element of the first
                                        level item</title>

                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Skin parameters</entry>

                                                  <entry>CSS properties</entry>
                                                  </row>
                                        </thead>

                                        <tbody>
                                                  <row>
                                                  <entry>generalFamilyFont</entry>

                                                  <entry>font-family</entry>
                                                  </row>

                                                  <row>
                                                  <entry>generalWeightFont</entry>

                                                  <entry>font-weight</entry>
                                                  </row>

                                                  <row>
                                                  <entry>generalSizeFont</entry>

                                                  <entry>font-size</entry>
                                                  </row>

                                                  <row>
                                                  <entry>generalTextColor</entry>

                                                  <entry>color</entry>
                                                  </row>

                                                  <row>
                                                  <entry>panelBorderColor</entry>

                                                  <entry>border-top-color</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>

                    <table>
                              <title>Skin parameter redefinition for a disabled item </title>

                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Parameter for disabled item</entry>

                                                  <entry>CSS properties</entry>
                                                  </row>
                                        </thead>

                                        <tbody>
                                                  <row>
                                                  <entry>tabDisabledTextColor</entry>

                                                  <entry>color</entry>
                                                  </row>

                                        </tbody>
                              </tgroup>
                    </table>

          </section>

          <section>
                    <title>Definition of Custom Style Classes</title>
                    <para>On the screenshot there are classes names that define styles for component
                              elements.</para>
                    <figure>
                              <title>Classes names</title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/panelMenuItem_cn.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>
                    <figure>
                              <title>Classes names</title>

                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/panelMenuItem_cn2.png"
                                                  />
                                        </imageobject>
                              </mediaobject>
                    </figure>

                    <table id="tab_cn_pMI">
                              <title>Classes names that define the first level items</title>

                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Class name</entry>

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

                                        <tbody>
                                                  <row>
                                                  <entry>rich-pmenu-top-item</entry>

                                                  <entry>Defines styles for a top panel
                                                  menu item</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-pmenu-top-item-icon</entry>

                                                  <entry>Defines styles for a top panel
                                                  menu item icon</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-pmenu-top-item-label</entry>

                                                  <entry>Defines styles for a top panel
                                                  menu item label</entry>
                                                  </row>

                                        </tbody>
                              </tgroup>
                    </table>

                    <table>
                              <title>Classes names that define the second and lower level items</title>

                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Class name</entry>

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

                                        <tbody>
                                                  <row>
                                                  <entry>rich-pmenu-item</entry>

                                                  <entry>Defines styles for a panel menu
                                                  item</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-pmenu-item-icon</entry>

                                                  <entry>Defines styles for a panel menu
                                                  item icon</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-pmenu-item-label</entry>

                                                  <entry>Defines styles for a panel menu
                                                  item label</entry>
                                                  </row>

                                        </tbody>
                              </tgroup>
                    </table>

                    <table>
                              <title>Classes names that define items state</title>

                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Class name</entry>

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

                                        <tbody>
                                                  <row>
                                                  <entry>rich-pmenu-item-selected</entry>

                                                  <entry>Defines styles for a panel menu
                                                  selected item</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-pmenu-disabled-element</entry>

                                                  <entry>Defines styles for a disabled
                                                  panel menu item</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-pmenu-hovered-element</entry>

                                                  <entry>Defines styles for a hovered
                                                  panel menu item</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>

                    <para>In order to redefine styles for all <emphasis role="bold">
                                        <property>&lt;rich:panelMenuItem&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_pMI"> above</link>) and define
                              necessary properties in them. </para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="CSS"><![CDATA[...
.rich-pmenu-hovered-element {
	background-color: #ff7800;
}
...]]></programlisting>

                    <para>This is a result:</para>

                    <figure>
                              <title>Redefinition styles with predefined classes</title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/panelMenuItem_pc.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>

                    <para>In the example a hovered element background color was changed.</para>

                    <para>Also it&apos;s possible to change styles of particular <emphasis
                                        role="bold">
                                        <property>&lt;rich:panelMenuItem&gt;</property>
                              </emphasis> component. In this case you should create own style
                              classes and use them in corresponding <emphasis role="bold">
                                        <property>&lt;rich:panelMenuItem&gt;</property>
                              </emphasis>
                              <emphasis>
                                        <property>styleClass</property>
                              </emphasis> attributes. An example is placed below:</para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="CSS"><![CDATA[...
.myClass {
        color: #a0a0a0;
}
...]]></programlisting>
                    <para>The <emphasis>
                                        <property>&quot;disabledClass&quot;</property>
                              </emphasis> attribute for <emphasis role="bold">
                                        <property>&lt;rich:panelMenuItem&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:panelMenuItem ... disabledClass="myClass"/>
]]></programlisting>

                    <para>This is a result:</para>

                    <figure>
                              <title>Redefinition styles with own classes and <emphasis>
                                                  <property>styleClass</property>
                                        </emphasis> attributes</title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/panelMenuItem_oc.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>

                    <para>As it could be seen on the picture above, the text color for disabled item
                              was changed.</para>
          </section>
          <section>
                    <title>Relevant resources links</title>
                    <para> Some additional information about usage of component can be found on this <ulink
                                        url="http://livedemo.exadel.com/richfaces-demo/richfaces/panelMenu.jsf?c=panelMenuItem"
                                        >LiveDemo page</ulink>. </para>
          </section>
</section>
