<?xml version="1.0" encoding="UTF-8"?>
<section>
          <sectioninfo>
                    <keywordset>
                              <keyword>rich:menuItem</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.MenuItem</entry>
                                        </row>
                                        <row>
                                                  <entry>component-class</entry>
                                                  <entry>org.richfaces.component.html.HtmlMenuItem</entry>
                                        </row>
                                        <row>
                                                  <entry>component-family</entry>
                                                  <entry>org.richfaces.DropDownMenu</entry>
                                        </row>
                                        <row>
                                                  <entry>renderer-type</entry>
                                                  <entry>org.richfaces.MenuItemRenderer</entry>
                                        </row>
                                        <row>
                                                  <entry>tag-class</entry>
                                                  <entry>org.richfaces.taglib.MenuItemTag</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 on a page:</para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="XML"><![CDATA[...
    <rich:dropDownMenu>
        ...
        <rich:menuItem value="Active"/>
        ...
    <rich:dropDownMenu>
...
]]></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.HtmlMenuItem; 	
...
HtmlMenuItem myMenuItem = new HtmlMenuItem();
...
]]></programlisting>
          </section>

          <section>
                    <title>Details of Usage</title>
                    <para> The <emphasis>
                                        <property>&quot;value&quot;</property>
                              </emphasis> attribute defines the text representation for an item
                              element. </para>
                    <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. Also you
                              can use the <emphasis>
                                        <property>&quot;icon&quot;</property>
                              </emphasis> and <emphasis>
                                        <property>&quot;iconDisabled&quot;</property>
                              </emphasis> facets. If the facets are defined, the corresponding <emphasis>
                                        <property>&quot;icon&quot;</property>
                              </emphasis> and <emphasis>
                                        <property>&quot;iconDisabled&quot;</property>
                              </emphasis> attributes are ignored and the facets content is shown as
                              an icon. It could be used for an item check box implementation. </para>
                    <para> Here is an example: </para>
                    <programlisting role="XML"><![CDATA[...
    <f:facet name="icon">
        <h:selectBooleanCheckbox value="#{bean.property}"/>
    </f:facet>
...
]]></programlisting>

                    <para>The <emphasis role="bold">
                                        <property>&lt;rich:menuItem&gt;</property>
                              </emphasis>
                              <emphasis>
                                        <property>&quot;submitMode&quot;</property>
                              </emphasis> attribute can be set to 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>The <emphasis>
                                        <property>&quot;action&quot;</property>
                              </emphasis> and <emphasis>
                                        <property>&quot;actionListener&quot;</property>
                              </emphasis> item&apos;s attributes are ignored. Menu items
                              don&apos; fire any submits themselves. The behavior is fully
                              defined by the components nested into items.</para>
                    <para> For example, you can put any content into an item, but, in this case, you
                              should set the <emphasis>
                                        <property>&quot;submitMode&quot;</property>
                              </emphasis> attribute as <emphasis>
                                        <property>&quot;none&quot;</property>
                              </emphasis>.</para>
                    <para> Here is an example: </para>
                    <programlisting role="XML"><![CDATA[...
    <rich:dropDownMenu>
        ...
        <rich:menuItem submitMode="none">
            <h:outputLink value="www.jboss.org"/>
        </rich:menuItem>
        ...
    <rich:dropDownMenu>
...
]]></programlisting>
                    <para> You can use the <emphasis>
                                        <property>&quot;disabled&quot;</property>
                              </emphasis> attribute to set the item state. </para>
                    <para> Here is an example: </para>
                    <programlisting role="XML"><![CDATA[...
    <rich:dropDownMenu>
        <rich:menuItem value="Disable" disabled="true"/>
    <rich:dropDownMenu>
...
]]></programlisting>
                    <note>
                              <title>Note:</title>
                              <para> The <emphasis role="bold">
                                                  <property>&lt;rich:menuItem&gt;</property>
                                        </emphasis> component was designed to be used only for
                                        pop-up menu list creation.</para>
                    </note>
                    <para> Information about the <emphasis>
                                        <property>&quot;process&quot;</property>
                              </emphasis> attribute usage you can find <link linkend="process"
                              >here</link>. </para>
          </section>
          
          <section>
                    <title>Facets</title>
                    <table>
                              <title>Facets</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                            <entry>Facet</entry>
                                                            <entry>Description</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                            <entry>icon</entry>
                                                            <entry>Redefines the icon for the enabled item state. Related attribute is &quot;icon&quot;</entry>
                                                  </row>
                                                  <row>
                                                            <entry>iconDisabled</entry>
                                                            <entry>Redefines the folder icon the disabled item state. Related attribute is &quot;iconDisabled&quot;</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:menuItem&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:menuItem&gt;</property>
                                                  </emphasis> component</para>
                              </listitem>
                    </itemizedlist>
          </section>

          <section>
                    <title>Skin Parameters Redefinition</title>
                    <table>
                              <title>Skin parameters redefinition for an 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>generalSizeFont</entry>
                                                  <entry>font-size</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>

                    <table>
                              <title>Skin parameters redefinition for a hovered item</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Skin parameters</entry>
                                                  <entry>CSS properties</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>tipBorderColor</entry>
                                                  <entry>border-color</entry>
                                                  </row>
                                                  <row>
                                                  <entry>tipBackgroundColor</entry>
                                                  <entry>background-color</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>

                    <table>
                              <title>Skin parameters redefinition for a disabled item</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Skin parameters</entry>
                                                  <entry>CSS properties</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>tabDisabledTextColor</entry>
                                                  <entry>color</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>

                    <table>
                              <title>Skin parameters redefinition for a label</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Skin parameters</entry>
                                                  <entry>CSS properties</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>generalTextColor</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/menuItem_cn.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>
                    <table id="tab_mI">
                              <title>Classes names that define an appearance of item elements</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Class name</entry>
                                                  <entry>Description</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>rich-menu-item</entry>
                                                  <entry>Defines styles for a wrapper
                                                  &lt;div&gt; element
                                                  for an item</entry>
                                                  </row>
                                                  <row>
                                                  <entry>rich-menu-item-label</entry>
                                                  <entry>Defines styles for a label of an
                                                  item</entry>
                                                  </row>
                                                  <row>
                                                  <entry>rich-menu-item-icon</entry>
                                                  <entry>Defines styles for the left icon
                                                  of an item</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>
                    <table>
                              <title>Classes names that define different states</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Class name</entry>
                                                  <entry>Description</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>rich-menu-item-disabled</entry>
                                                  <entry>Defines styles for a wrapper
                                                  &lt;div&gt; element of
                                                  an item</entry>
                                                  </row>
                                                  <row>
                                                  <entry>rich-menu-item-enabled</entry>
                                                  <entry>Defines styles for a wrapper
                                                  &lt;div&gt; element of
                                                  an enabled item</entry>
                                                  </row>
                                                  <row>
                                                  <entry>rich-menu-item-hover</entry>
                                                  <entry>Defines styles for a wrapper
                                                  &lt;div&gt; element of
                                                  a hover item</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-menu-item-label-disabled</entry>
                                                  <entry>Defines styles for a label of a
                                                  disabled item</entry>
                                                  </row>
                                                  <row>
                                                  <entry>rich-menu-item-icon-disabled</entry>
                                                  <entry>Defines styles for the left icon
                                                  of a disabled item</entry>
                                                  </row>
                                                  <row>
                                                  <entry>rich-menu-item-label-enabled</entry>
                                                  <entry>Defines styles for a label of an
                                                  enabled item</entry>
                                                  </row>
                                                  <row>
                                                  <entry>rich-menu-item-icon-enabled</entry>
                                                  <entry>Defines styles for the left icon
                                                  of an enabled item</entry>
                                                  </row>
                                                  <row>
                                                  <entry>rich-menu-item-label-selected</entry>
                                                  <entry>Defines styles for a label of a
                                                  selected item</entry>
                                                  </row>
                                                  <row>
                                                  <entry>rich-menu-item-icon-selected</entry>
                                                  <entry>Defines styles for the left icon
                                                  of a selected item</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>
                    <para>In order to redefine styles for all <emphasis role="bold">
                                        <property>&lt;rich:menuItem&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_mI"> above</link>) and define necessary
                              properties in them. </para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="CSS"><![CDATA[...
.rich-menu-item-disabled{
        font-style: italic;
}
...]]></programlisting>

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

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

                    <para>In the example a disabled item font style was changed.</para>

                    <para>Also it&apos;s possible to change styles of particular <emphasis
                                        role="bold">
                                        <property>&lt;rich:menuItem&gt;</property>
                              </emphasis> component. In this case you should create own style
                              classes and use them in corresponding <emphasis role="bold">
                                        <property>&lt;rich:menuItem&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{
        border-color: #bed6f8;
        background-color: #ffffff;
}
...]]></programlisting>
                    <para>The <emphasis>
                                        <property>&quot;styleClass&quot;</property>
                              </emphasis> attribute for <emphasis role="bold">
                                        <property>&lt;rich:menuItem&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:menuItem ... selectStyle="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/menuItem_oc.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>

                    <para>As it could be seen on the picture above, the background color and border
                              color for selected item were changed. </para>
          </section>
          <section>
                    <title>Relevant Resources Links</title>
                    <para><ulink
                                        url="http://livedemo.exadel.com/richfaces-demo/richfaces/dropDownMenu.jsf?c=menuItem"
                                        >On the component LiveDemo page</ulink> you can see the example of <emphasis
                                        role="bold">
                                        <property>&lt;rich:menuItem&gt;</property>
                              </emphasis> usage and sources for the given example. </para>
          </section>
</section>
