<?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>Label Skin parameters redefinition</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters for label div element</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 selected label element</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>Popup Skin parameters redefinition</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters for border element</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>Popup Skin parameters redefinition</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters for background element</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>In the screenshot, there are classes names that define the element label.</para>

    <figure>
      <title>Classes names</title>

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

    <table>
      <title>Classes names that define element 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 the text style of a representation element</entry>
          </row>

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

            <entry>Defines the class for wrapping div element of a representation element</entry>
          </row>

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

            <entry>Defines the class for wrapping div element of the selected representation
            element</entry>
          </row>

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

            <entry>Defines the class for wrapping div element of a representation element that isn't
              selected</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <para>In the screenshot, there are classes names that define an element pop-up.</para>

    <figure>
      <title>Classes names</title>

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

    <table>
      <title>Classes names that define element popup</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 a class for borders elements</entry>
          </row>

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

            <entry>Defines the class for a general background list</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <para>In order to redefine the style for all drop-down menus on a page using CSS, it's enough to
      create classes with the same names and define the necessary properties in them.</para>

    <para>To change the style peculiarities of the particular drop-down menus define your own style
      classes in the corresponding dropDownMenu 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">&lt;rich:dropDownMenu&gt;</emphasis> usage and sources for the given example.
    </para>
  </section>
</section>
