<?xml version="1.0" encoding="UTF-8"?>
<section>
    <sectioninfo>
        <keywordset>
            <keyword>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>Server (default)</para>
            </listitem>
        </itemizedlist>

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

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

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

        <itemizedlist>
            <listitem>
                <para>None</para>
            </listitem>
        </itemizedlist>

        <para>The <emphasis>
                <property>"action"</property>
            </emphasis> and <emphasis>
                <property>"actionListener"</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;mode&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>
    </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>Class names</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/menuItem2.png"/>
                </imageobject>
            </mediaobject>
        </figure>
        <table>
            <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 and define necessary properties in them.</para>

        <para>To change styles of particular <emphasis role="bold">
                <property>&lt;rich:menuItem&gt;</property>
            </emphasis> components, define your own style classes in the corresponding <emphasis
                role="bold">
                <property>&lt;rich:menuItem&gt;</property>
            </emphasis>attributes.</para>
    </section>
    <section>
        <title>Relevant Resources Links</title>
        <para><ulink
                url="http://livedemo.exadel.com/richfaces-demo/richfaces/dropDownMenu.jsf?c=menuItem"
                >Here</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>
