<?xml version="1.0" encoding="UTF-8"?>
<section>
    <sectioninfo>
        <keywordset>
            <keyword>menuGroup</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.MenuGroup</entry>
                </row>
                <row>
                    <entry>component-class</entry>
                    <entry>org.richfaces.component.html.HtmlMenuGroup</entry>
                </row>
                <row>
                    <entry>component-family</entry>
                    <entry>org.richfaces.DropDownMenu</entry>
                </row>
                <row>
                    <entry>renderer-type</entry>
                    <entry>org.richfaces.MenuGroupRenderer</entry>
                </row>
                <row>
                    <entry>tag-class</entry>
                    <entry>org.richfaces.taglib.MenuGroupTag</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 value="Active">
        ...
        <rich:menuGroup value="Active">
            <!--Nested menu components-->
        </rich:menuGroup>
        ...
    </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.HtmlMenuGroup; 	
...
HtmlMenuGroup myMenuGroup = new HtmlMenuGroup();
...
]]></programlisting>
    </section>

    <section>
        <title>Details of Usage</title>
        <para> The <emphasis>
                <property>&quot;value&quot;</property>
            </emphasis> attribute defines the text representation of a group element in the page. </para>
        <para> The <emphasis>
                <property>&quot;icon&quot;</property>
            </emphasis> attribute defines an icon for the component. The <emphasis>
                <property>&quot;iconDisabled&quot;</property>
            </emphasis> attribute defines an icon for when the group is disabled. 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&apos; contents are used as icons.
            This 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>
                <property>&quot;iconFolder&quot;</property>
            </emphasis> and <emphasis>
                <property>&quot;iconFolderDisabled&quot;</property>
            </emphasis> attributes are defined for using icons as folder icons. The <emphasis>
                <property>&quot;iconFolder&quot;</property>
            </emphasis> and <emphasis>
                <property>&quot;iconFolderDisabled&quot;</property>
            </emphasis> facets use their contents as folder icon representations in place of the
            attribute values. </para>
        <para> The <emphasis>
                <property>&quot;direction&quot;</property>
            </emphasis> attribute is used to define which way to display the menu as shown in the
            example below: </para>
        <para>Possible values are:</para>
        <itemizedlist>
            <listitem>
                <para>left - down - a submenu is attached to the left side of the menu and is
                    dropping down</para>
            </listitem>
            <listitem>
                <para>left - up - a submenu is attached to the left side of the menu and is dropping
                    up</para>
            </listitem>
            <listitem>
                <para>right - down - a submenu is attached to the right side of the menu and is
                    dropping down</para>
            </listitem>
            <listitem>
                <para>right - up - a submenu is attached to the right side of the menu and is
                    dropping up</para>
            </listitem>
            <listitem>
                <para>auto - smart positioning activation</para>
            </listitem>
        </itemizedlist>
        <para> By default, the <emphasis>
                <property>&quot;direction&quot;</property>
            </emphasis> attribute is set to <emphasis>
                <property>&quot;auto&quot;</property>
            </emphasis>. </para>
        <para> Here is an example: </para>
        <programlisting role="XML"><![CDATA[...
    <rich:menuGroup value="Active" direction="left-down"
        <!--Nested menu components-->
    </rich:menuGroup>
...
]]></programlisting>
        <para> This would be the result: </para>
        <figure>
            <title>Using the <emphasis><property>&quot;direction&quot;</property></emphasis> attribute</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/menuGroup2.png"/>
                </imageobject>
            </mediaobject>
        </figure>
    </section>

    <section>
        <title>Look-and-Feel Customization</title>
        <para> For skinnability implementation, the components use a style class redefinition
            method. Default style classes are mapped on skin parameters. </para>
        <para> There are two ways to redefine the appearance of all menu groups at once: </para>
        <itemizedlist>
            <listitem>
                <para>Redefine corresponding skin parameters</para>
            </listitem>
            <listitem>
                <para>Add to your styles heet style classes used by a menu group</para>
            </listitem>
        </itemizedlist>
    </section>
    <section>
        <title>Skin parameters redefinition</title>
        <table>
            <title>Label Skin parameters redefinition</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters for group</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>Label Skin parameters redefinition</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters for disabled group</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>tabDisabledTextColor</entry>
                        <entry>color</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <table>
            <title>Label Skin parameters redefinition</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters for text label</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>generalTextColor</entry>
                        <entry>color</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </section>

    <section>
        <title> Definition custom style classes </title>
        <para> The classes names that define group element appearance are in the screenshot. </para>
        <figure>
            <title>Classes names</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/menuGroup3.png"/>
                </imageobject>
            </mediaobject>
        </figure>
        <table>
            <title>Classes names that define group element appearance.</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Class name</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>Rich-menu-group</entry>
                        <entry>Defines the class for wrapping div element for the whole
                        group</entry>
                    </row>
                    <row>
                        <entry>Rich-menu-item-label</entry>
                        <entry>Defines properties for the text</entry>
                    </row>
                    <row>
                        <entry>Rich-menu-item-icon</entry>
                        <entry>Defines properties for the left icon element</entry>
                    </row>
                    <row>
                        <entry>Rich-menu-item-folder</entry>
                        <entry>Defines properties for the right icon element</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <para> All listed elements except for the general one are defined for disabled mode. </para>
        <table>
            <title>Classes names for disabled mode</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Class name</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>Rich-menu-item-label-disabled</entry>
                        <entry>Defines properties for the text</entry>
                    </row>
                    <row>
                        <entry>Rich-menu-item-icon-disabled</entry>
                        <entry>Defines properties for the left icon element</entry>
                    </row>
                    <row>
                        <entry>Rich-menu-item-folder-disabled</entry>
                        <entry>Defines properties for the right icon element</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <para> In order to redefine the style for all menu groups on a page using CSS, it&apos;s
            enough to create classes with the same names and define the necessary properties in
            them. </para>
        <para> To change style aspects of particular panel menu groups define your own style classes
            in the corresponding menuGroup attributes. </para>
    </section>
</section>
