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

        <row>
          <entry>component-class</entry>
          <entry>org.richfaces.component.html.HtmlDropDownMenu</entry>
        </row>

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

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

        <row>
          <entry>renderer-type</entry>
          <entry>org.richfaces.DropDownMenuRenderer</entry>
        </row>

        <row>
          <entry>tag-class</entry>
          <entry>org.richfaces.taglib.DropDownMenuTag</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="Item1">
    <!--Nested menu components-->
</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.HtmlDropDownMenu; 	
...
HtmlDropDownMenu myDropDownMenu = new HtmlDropDownMenu();
...
]]></programlisting>
  </section>

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

    <para>All attributes except <emphasis>
        <property>"value"</property>
      </emphasis> are optional. The <emphasis>
        <property>"value"</property>
      </emphasis> attribute defines text to be represented. If you can use the <emphasis>
        <property>"label"</property>
      </emphasis> facet, you can even not use the <emphasis>
        <property>"value"</property>
      </emphasis> attribute.</para>

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


    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<f:facet name="label">
    <h:graphicImage value="/images/img1.png"/>
</f:facet>
...]]></programlisting>

    <para>Use the <emphasis>
        <property>"event"</property>
      </emphasis> attribute to define an event for the represented element that triggers a menu
      appearance. An example of a menu appearance on a click can be seen below.</para>


    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>

    <programlisting role="XML"><![CDATA[...
<rich:dropDownMenu event="onclick" value="Item1">
    <!--Nested menu components-->
</rich:dropDownMenu>
...]]></programlisting>

    <para>The <emphasis role="bold">
        <property>&lt;rich:dropDownMenu&gt;</property>
      </emphasis>
      <emphasis>
        <property>"submitMode"</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>"action"</property>
      </emphasis> and <emphasis>
        <property>"actionListener"</property>
      </emphasis> item&apos;s attributes are ignored. Menu items don&apos;t fire any submits themselves. The
      behavior is fully defined by the components nested into items.</para>

    <note><title>Note:</title><para> As the <emphasis role="bold">
        <property>&lt;rich:dropDownMenu&gt;</property>
    </emphasis> component doesn'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>"direction"</property>
      </emphasis> and <emphasis>
        <property>"jointPoint"</property>
      </emphasis> attributes are used for defining aspects of menu appearance.</para>

    <para>Possible values for the <emphasis>
        <property>"direction"</property>
      </emphasis> attribute are:</para>

    <itemizedlist>
      <listitem>
        <para>&quot;top-left&quot; - a menu drops to the top and left</para>
      </listitem>

      <listitem>
        <para>&quot;top-right&quot; - a menu drops to the top and right</para>
      </listitem>

      <listitem>
        <para>&quot;bottom-left&quot; - a menu drops to the bottom and left</para>
      </listitem>

      <listitem>
        <para>&quot;bottom-right&quot; - a menu drops to the bottom and right</para>
      </listitem>

      <listitem>
        <para>&quot;auto&quot; - smart positioning activation</para>
      </listitem>
    </itemizedlist>

    <para>Possible values for the <emphasis>
        <property>"jointPoint"</property>
      </emphasis> attribute are:</para>

    <itemizedlist>
      <listitem>
        <para>&quot;tr&quot; - a menu is attached to the top-right point of the button element</para>
      </listitem>

      <listitem>
        <para>&quot;tl&quot; - a menu is attached to the top-left point of the button element</para>
      </listitem>

      <listitem>
        <para>&quot;br&quot; - a menu is attached to the bottom-right point of the button element</para>
      </listitem>

      <listitem>
        <para>&quot;bl&quot; - a menu is attached to the bottom-left point of the button element</para>
      </listitem>

      <listitem>
        <para>&quot;auto&quot; - smart positioning activation</para>
      </listitem>
    </itemizedlist>

    <para>By default, the <emphasis>
        <property>"direction"</property>
      </emphasis> and <emphasis>
        <property>"jointPoint"</property>
      </emphasis> attributes are set to &quot;auto&quot;.</para>

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


    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<rich:dropDownMenu value="File" direction="bottom-right" jointPoint="tr">
    <rich:menuItem submitMode="ajax" value="New" action="#{ddmenu.doNew}"/>
    <rich:menuItem   submitMode="ajax"  value="Open" action="#{ddmenu.doOpen}"/>
    <rich:menuGroup value="Save As...">
        <rich:menuItem   submitMode="ajax" value="Text File"  action="#{ddmenu.doSaveText}"/>
        <rich:menuItem   submitMode="ajax" value="PDF File"  action="#{ddmenu.doSavePDF}"/>
    </rich:menuGroup>
    <rich:menuItem  submitMode="ajax" value="Close" action="#{ddmenu.doClose}"/>
    <rich:menuSeparator id="menuSeparator11"/>
    <rich:menuItem  submitMode="ajax" value="Exit"  action="#{ddmenu.doExit}"/>
</rich:dropDownMenu>
...]]></programlisting>

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

    <figure>
      <title>Using the <emphasis role="bold"><property>"direction"</property></emphasis> and <emphasis><property>"joinPoint"</property></emphasis> attributes</title>

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

    <para>You can correct an offset of the pop-up list relative to the label using the following
      attributes: <emphasis>
        <property>"horizontalOffset"</property>
      </emphasis> and <emphasis>
        <property>"verticalOffset"</property>
      </emphasis>.</para>

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


    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>

    <programlisting role="XML"><![CDATA[...
<rich:dropDownMenu value="File" direction="bottom-right" jointPoint="tr" horizontalOffset="-15" verticalOffset="0">
    <rich:menuItem submitMode="ajax" value="New" action="#{ddmenu.doNew}"/>
    <rich:menuItem   submitMode="ajax"  value="Open" action="#{ddmenu.doOpen}"/>
    <rich:menuGroup value="Save As...">
        <rich:menuItem   submitMode="ajax" value="Text File"  action="#{ddmenu.doSaveText}"/>
        <rich:menuItem   submitMode="ajax" value="PDF File"  action="#{ddmenu.doSavePDF}"/>
    </rich:menuGroup>
    <rich:menuItem  submitMode="ajax" value="Close" action="#{ddmenu.doClose}"/>
    <rich:menuSeparator id="menuSeparator11"/>
    <rich:menuItem  submitMode="ajax" value="Exit"  action="#{ddmenu.doExit}"/>
</rich:dropDownMenu>
...]]></programlisting>

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

    <figure>
      <title>Using the <emphasis><property>"horizontalOffset"</property></emphasis> and <emphasis><property>"verticalOffset"</property></emphasis> attributes</title>

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

    <!--para> The <emphasis>
        <property>&quot;disabled&quot;</property>
      </emphasis> attribute is used for disabling whole <emphasis role="bold">
        <property>&lt;rich:dropDownMenu&gt;</property>
      </emphasis>, <emphasis role="bold">
        <property>&lt;rich:menuGroup&gt;</property>
      </emphasis> or <emphasis role="bold">
        <property>&lt;rich:menuItem&gt;</property>.
      </emphasis>
    </para>
    <para>An example of a menu appearance with <emphasis>
      <property>&quot;disabled&quot;</property>
    </emphasis> attribute can be seen below.</para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    
    <programlisting role="XML"><![CDATA[...
    <rich:dropDownMenu value="Item1">
       <rich:menuItem id="menuItem1" value="Active1"/>
       <rich:menuItem id="menuItem2" value="Disabled1" disabled="true"/>
       <rich:menuGroup id="menuGroup1" value="Group1">
         <rich:menuItem id="menuGroup1Item1" value="Active"/>
         <rich:menuItem id="menuGroup1Item2" value="Active"/>
       </rich:menuGroup>
        <rich:menuItem id="menuItem3" value="Active2"/>
           <rich:menuGroup id="menuGroup1Dsbld" value="Group1 dsbld." disabled="true" />
    </rich:dropDownMenu>
...
]]></programlisting-->

<para>
  The <emphasis><property>&quot;disabled&quot;</property></emphasis> attribute is used for disabling whole
  <emphasis role="bold"><property>&lt;rich:dropDownMenu&gt;</property></emphasis> component. In this case it is 
  necessary to define <emphasis><property>&quot;disabled&quot;</property></emphasis> attribute as &quot;true&quot;.
  An example is placed below.  
</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    
    <programlisting role="XML"><![CDATA[...
<rich:dropDownMenu value="File"  disabled="true">
    ...
</rich:dropDownMenu>
...]]></programlisting>

  </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:dropDownMenu&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:dropDownMenu&gt;</property>
          </emphasis> component</para>
      </listitem>
    </itemizedlist>
  </section>

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

    <table>
      <title>Skin parameters redefinition for a label &lt;div&gt; element</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 selected label</title>

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

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

        <tbody>
          <row>
            <entry>panelBorderColor</entry>

            <entry>border-color</entry>
          </row>

          <row>
            <entry>controlBackgroundColor</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>generalTextColor</entry>

            <entry>background-colorcolor</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for a border</title>

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

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

        <tbody>
          <row>
            <entry>panelBorderColor</entry>

            <entry>border-color</entry>
          </row>

          <row>
            <entry>additionalBackgroundColor</entry>

            <entry>background-color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for a background</title>

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

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

        <tbody>
          <row>
            <entry>additionalBackgroundColor</entry>

            <entry>border-top-color</entry>
          </row>

          <row>
            <entry>additionalBackgroundColor</entry>

            <entry>border-left-color</entry>
          </row>

          <row>
            <entry>additionalBackgroundColor</entry>

            <entry>border-right-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/dropDownMenu_cn.png"/>
        </imageobject>
      </mediaobject>
    </figure>

    <table id="tab_cn4">
      <title>Classes names that define a label</title>

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

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

        <tbody>
          <row>
            <entry>rich-label-text-decor</entry>

            <entry>Defines text style for a representation element</entry>
          </row>

          <row>
            <entry>rich-ddmenu-label</entry>

            <entry>Defines styles for a wrapper &lt;div&gt; element of a representation
              element</entry>
          </row>

          <row>
            <entry>rich-ddmenu-label-select</entry>

            <entry>Defines styles for a wrapper &lt;div&gt; element of a selected
              representation element</entry>
          </row>

          <row>
            <entry>rich-ddmenu-label-unselect</entry>

            <entry>Defines styles for a wrapper &lt;div&gt; element of an unselected
              representation element </entry>
          </row>
          
          <row>
            <entry>rich-ddmenu-label-disabled</entry>
            
            <entry>Defines styles for a wrapper &lt;div&gt; element of a disabled
              representation element </entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <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/dropDownMenu_cn2.png"/>
        </imageobject>
      </mediaobject>
    </figure>

    <table>
      <title>Classes names that define a popup element</title>

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

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

        <tbody>
          <row>
            <entry>rich-menu-list-border</entry>

            <entry>Defines styles for borders</entry>
          </row>

          <row>
            <entry>rich-menu-list-bg</entry>

            <entry>Defines styles for a general background list</entry>
          </row>

          <row>
            <entry>rich-menu-list-strut</entry>

            <entry>Defines styles for a wrapper &lt;div&gt; element for a strut of a popup
              list</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <para>In order to redefine styles for all <emphasis role="bold">
      <property>&lt;rich:dropDownMenu&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 table <link linkend="tab_cn4">above</link>) and define necessary properties in them. An example is placed below:</para>
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[...
.rich-ddmenu-label-select{
    background-color:  #fae6b0;
    border-color: #e5973e;
}
...]]></programlisting>  
    
    <para>This is a result:</para>
    
    <figure>
      <title>Redefinition styles with predefined classes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/dropDownMenu_pc.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    
    <para>In the example a label select background color and border color  were changed.</para>
    <para>Also it&apos;s possible to change styles of particular <emphasis role="bold"
      ><property>&lt;rich:dropDownMenu&gt;</property></emphasis> component. In this case you should create own style classes and use them in corresponding <emphasis role="bold"
        ><property>&lt;rich:dropDownMenu&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{
    font-style: italic;
}
...]]></programlisting>  
    <para>The <emphasis><property>&quot;itemClass&quot;</property></emphasis> attribute for <emphasis role="bold"
      ><property>&lt;rich:dropDownMenu&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:dropDownMenu ... itemClass="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/dropDownMenu_oc.png"/>
        </imageobject>
      </mediaobject>
    </figure>  
    
    <para>As it could be seen on the picture above, the font style for items was changed.</para>
  </section>

  <section>
    <title>Relevant Resources Links</title>
    <para>
      <ulink
        url="http://livedemo.exadel.com/richfaces-demo/richfaces/dropDownMenu.jsf?c=dropDownMenu"
        >Here</ulink> you can see the example of <emphasis role="bold">
        <property>&lt;rich:dropDownMenu&gt;</property>
      </emphasis> usage and sources for the given example. </para>
  </section>
</section>
