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

    <para>The standard form submission is performed and the page is completely refreshed.</para>

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

    <para>An Ajax form submission is performed, and specified elements in the <emphasis>
        <property>"reRender"</property>
      </emphasis> attribute are rerendered.</para>

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

    <para>The <emphasis>
        <property>"action"</property>
      </emphasis> and <emphasis>
        <property>"actionListener"</property>
      </emphasis> item's attributes are ignored. Menu items don't fire any submits themselves. The
      behavior is fully defined by the components nested inside items.</para>

    <note><title>Note:</title> As the <emphasis role="bold">
        <property>&lt;rich:dropDownMenu&gt;</property>
      </emphasis> component doesn't provide its own form, use it between &lt;h:form&gt; and
      &lt;/h:form&gt; tags.</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>top-left - a menu drops to the top and left</para>
      </listitem>

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

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

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

      <listitem>
        <para>auto - smart positioning activation</para>
      </listitem>
    </itemizedlist>

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

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

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

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

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

      <listitem>
        <para>auto - 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 <emphasis>
        <property>"auto"</property>
      </emphasis>.</para>

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


    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
    <rich:dropDownMenu value="Item1" direction="bottom-right" jointPoint="tr">
        <!--Nested menu components-->
    </rich:dropDownMenu>
...
]]></programlisting>

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

    <figure>
      <title>Using the "direction" and"joinPoint" 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="Item1" direction="bottom-right" jointPoint="tr" horizontalOffset="-15" verticalOffset="0">
        <!--Nested menu components-->
    </rich:dropDownMenu>
...
  ]]></programlisting>

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

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

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/dropDownMenu3.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 drop-down menus at once:</para>

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

      <listitem>
        <para>Add to your style sheets style classes used by a drop-down menu</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/dropDownMenu4.png"/>
        </imageobject>
      </mediaobject>
    </figure>

    <table>
      <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>
        </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/dropDownMenu5.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 and define necessary properties in them.</para>
    
    <para>To change styles of particular <emphasis role="bold">
      <property>&lt;rich:dropDownMenu&gt;</property>
    </emphasis> components, define your own style classes in the corresponding <emphasis
      role="bold">
      <property>&lt;rich:dropDownMenu&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=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>
