<?xml version="1.0" encoding="UTF-8"?>
<section>
    <sectioninfo>
        <keywordset>
            <keyword>rich:contextMenu</keyword>
            <keyword>contextMenu</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.ContextMenu</entry>
                </row>
                <row>
                    <entry>component-class</entry>
                    <entry>org.richfaces.component.html.ContextMenu</entry>
                </row>
                <row>
                    <entry>component-family</entry>
                    <entry>org.richfaces.ContextMenu</entry>
                </row>
                <row>
                    <entry>renderer-type</entry>
                    <entry>org.richfaces.DropDownMenuRenderer</entry>
                </row>
                <row>
                    <entry>tag-class</entry>
                    <entry>org.richfaces.taglib.ContextMenuTagHandler</entry>
                </row>
            </tbody>
        </tgroup>
    </table>
    <section>
        <title>Creating the Component with a Page Tag</title>
        <para>To create the simplest variant on a page use the following syntax:</para>
        <programlisting role="XML"><![CDATA[<rich:contextMenu />]]></programlisting>
    </section>
    <section>

          <title>Creating the Component Dynamically Using Java</title>        
        <programlisting role="JAVA"><![CDATA[import org.richfaces.component.html.ContextMenu;   
...
html.ContextMenu myContextMenu = new html.ContextMenu();
...]]></programlisting>
    </section>
    <section>
        <title>Details of Usage</title>
        <para>
            <emphasis role="bold">
                <property>&lt;rich:contextMenu&gt;</property>
            </emphasis> is a support-like component. Context menu itself is an invisible panel that
            appears after a particular client-side event (<emphasis><property>&quot;onmouseover&quot;</property></emphasis>, <emphasis><property>&quot;onclick&quot;</property></emphasis>, etc.) occurred on a
            parent component. The event is defined with an <emphasis>
                <property>&quot;event&quot;</property>
            </emphasis> attribute. The component uses <emphasis>
                <property>&quot;oncontextmenu&quot;</property>
            </emphasis> event by default to call a context menu by clicking on the right mouse
            button.</para>

        <para>
              <property><link linkend="menuGroup">&lt;rich:menuGroup&gt;</link></property>, <property><link linkend="menuItem">&lt;rich:menuItem&gt;</link></property> and <property><link linkend="menuSeparator">&lt;rich:menuSeparator&gt;</link></property> components 
              can be used as nested elements for <emphasis role="bold"><property>&lt;rich:contextMenu&gt;</property></emphasis>in the same way as for <emphasis role="bold"><property>&lt;rich:dropDownMenu&gt;</property></emphasis>.
        </para>
          <para>
                By default, the <emphasis role="bold"><property>&lt;rich:contextMenu&gt;</property></emphasis> disables right mouse click on a page in the context menu area only. 
                But if you want to disable browser&apos;s context menu completely you should set the <emphasis><property>&quot;disableDefaultMenu&quot;</property></emphasis> attribute value to &quot;true&quot;.
          </para>
          <para>
                If <emphasis><property>&quot;attached&quot;</property></emphasis> value is &quot;true&quot; (default value), component is attached to the parent component or to the component, 
                which <emphasis><property>&quot;id&quot;</property></emphasis> is specified in the <emphasis><property>&quot;attachTo&quot;</property></emphasis> attribute:
          </para>

          <programlisting role="XML"><![CDATA[<rich:contextMenu event="oncontextmenu" attachTo="pic1" submitMode="none">
      <rich:menuItem value="Zoom In" onclick="enlarge();" id="zin"/>
      <rich:menuItem value="Zoom Out" onclick="decrease();" id="zout"/>
</rich:contextMenu>
<h:panelGrid columns="1" columnClasses="cent">
      <h:panelGroup id="picture">
            <h:graphicImage value="/richfaces/jQuery/images/pic1.png" id="pic"/>
      </h:panelGroup>
</h:panelGrid>
<h:panelGrid columns="1" columnClasses="cent">
      <h:panelGroup id="picture1">
            <h:graphicImage value="/richfaces/jQuery/images/pic2.png" id="pic1"/>
       </h:panelGroup>
</h:panelGrid>]]></programlisting>
        <para>The <code>&quot;enlarge()&quot;</code> and
                <code>&quot;decrease()&quot;</code> functions definition is placed
            below.</para>
        <programlisting role="JAVA"><![CDATA[<script type="text/javascript">
		function enlarge(){
       			document.getElementById('pic').width=document.getElementById('pic').width*1.1;
               document.getElementById('pic').height=document.getElementById('pic').height*1.1;
      	}
       	function decrease(){
       			document.getElementById('pic').width=document.getElementById('pic').width*0.9;
               document.getElementById('pic').height=document.getElementById('pic').height*0.9;
      	}
</script>]]></programlisting>

        <para>In the example a picture zooming possibility with <emphasis role="bold">
                <property>&lt;rich:contextMenu&gt;</property>
            </emphasis> component usage was shown. The picture is placed on the <emphasis
                role="bold">
                <property>&lt;h:panelGroup&gt;</property>
            </emphasis> component. The <emphasis role="bold">
                <property>&lt;rich:contextMenu&gt;</property>
            </emphasis> component is not nested to <emphasis role="bold">
                <property>&lt;h:panelGroup&gt;</property>
            </emphasis> and has a value of the<emphasis>
                <property>&quot;attachTo&quot;</property>
            </emphasis> attribute defined as <code>&quot;pic1&quot;</code>. Thus,
            the context menu is attached to the component, which 
			<emphasis><property>&quot;id&quot;</property></emphasis> is <code>&quot;pic1&quot;</code>. 
			The context menu has two items to zoom in (zoom out) a picture by <emphasis><property>&quot;onclick&quot;</property></emphasis> event.
            For earch item corresponding JavaScript function is defined to provide necessary action
            as a result of the clicking on it. For the menu is defined an <emphasis>
                <property>&quot;oncontextmenu&quot;</property>
            </emphasis> event to call the context menu on a right click mouse event.</para>

        <para>In the example the context menu is defined for the parent <emphasis role="bold">
                <property>&lt;h:panelGroup&gt;</property>
            </emphasis> component with a value of <emphasis>
                <property>&quot;id&quot;</property>
            </emphasis> attribute equal to &quot;<code>picture</code>&quot; You
            should be careful with such definition, because a client context menu is looked for a
            DOM element with a client Id of a parent component on a server. If a parent component
            doesn&apos;t encode an Id on a client, it can&apos;t be found by the <emphasis
                role="bold">
                <property>&lt;rich:contextMenu&gt;</property>
            </emphasis> and it&apos;s attached to its closest parent in a DOM tree.</para>

        <para> If the <emphasis>
                <property>&quot;attached&quot;</property>
            </emphasis> attribute has &quot;false&quot; value,
            component activates via JavaScript API with assistance of <emphasis role="bold">
                <property>&lt;rich:componentControl&gt;</property>
            </emphasis>. An example is placed below.</para>
        <para id="ex">
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[<h:form id="form">
      <rich:contextMenu attached="false" id="menu" submitMode="ajax">
            <rich:menuItem ajaxSingle="true">
                  <b>{car} {model}</b> details
                  <a4j:actionparam name="det" assignTo="#{ddmenu.current}" value="{car} {model} details"/>
            </rich:menuItem>
            <rich:menuGroup value="Actions">
                  <rich:menuItem ajaxSingle="true">
                        Put <b>{car} {model}</b> To Basket
                        <a4j:actionparam name="bask" assignTo="#{ddmenu.current}" value="Put {car} {model} To Basket"/>
                  </rich:menuItem>
                  <rich:menuItem value="Read Comments" ajaxSingle="true">
                        <a4j:actionparam name="bask" assignTo="#{ddmenu.current}" value="Read Comments"/>
                  </rich:menuItem>
                  <rich:menuItem ajaxSingle="true">
                        Go to <b>{car}</b> site
                        <a4j:actionparam name="bask" assignTo="#{ddmenu.current}" value="Go to {car} site"/>
                  </rich:menuItem>
            </rich:menuGroup>
      </rich:contextMenu> 

      <h:panelGrid columns="2">
            <rich:dataTable value="#{dataTableScrollerBean.tenRandomCars}" var="car" id="table" onRowMouseOver="this.style.backgroundColor='#F8F8F8'" onRowMouseOut="this.style.backgroundColor='#{a4jSkin.tableBackgroundColor}'" rowClasses="cur">
                  <rich:column>
                        <f:facet name="header">Make</f:facet>
                        <h:outputText value="#{car.make}"/>
                  </rich:column>
                  <rich:column>
                        <f:facet name="header">Model</f:facet>
                        <h:outputText value="#{car.model}"/>
                  </rich:column>
                  <rich:column>
                        <f:facet name="header">Price</f:facet>
                        <h:outputText value="#{car.price}" />
                  </rich:column>
                  <rich:componentControl event="onRowClick" for="menu" operation="show">
                        <f:param value="#{car.model}" name="model"/>
                        <f:param value="#{car.make}" name="car"/>
                  </rich:componentControl>
            </rich:dataTable>
            <a4j:outputPanel ajaxRendered="true">
                  <rich:panel>
                        <f:facet name="header">Last Menu Action</f:facet>
                        <h:outputText value="#{ddmenu.current}"></h:outputText>
                  </rich:panel>
            </a4j:outputPanel>
      </h:panelGrid>
</h:form>]]></programlisting>
        <para>This is a result:</para>
        <figure>
            <title>The <emphasis>
                <property>&quot;attached&quot;</property>
            </emphasis> attribute usage</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/contextMenu2.png" scalefit="1"/>
                </imageobject>
            </mediaobject>
        </figure>

        <para>In the example the context menu is activated (by clicking on the left mouse button) on
            the table via JavaScript API with assistance of <emphasis role="bold">
                <property>&lt;rich:componentControl&gt;</property>
            </emphasis>. The attribute <emphasis>
                <property>&quot;for&quot;</property>
            </emphasis> contains a value of the <emphasis role="bold">
                <property>&lt;rich:contextMenu&gt;</property>
            </emphasis> Id. For menu appearance Java Script API function
                <code>&quot;show()&quot;</code> is used. It is defined with <emphasis>
                <property>&quot;operation&quot;</property>
            </emphasis> attribute for the <emphasis role="bold">
                <property>&lt;rich:componentControl&gt;</property>
            </emphasis> component. Context menu is recreated after the every call on a client and
            new {car} and {model} values are inserted in it. In the example for a menu customization
            macrosubstitutions were used.</para>

        <para>The <emphasis role="bold">
                <property>&lt;rich:contextMenu&gt;</property>
            </emphasis> component can be defined once on a page and can be used as shared for
            different components (this is the main difference from the <emphasis role="bold">
                <property>&lt;rich:dropDownMenu&gt;</property>
            </emphasis> component). It&apos;s necessary to define it once on a page (as it was
            shown in the example <link linkend="ex">above</link>) and activate it on required
            components via JavaScript API with assistance of <emphasis role="bold">
                <property>&lt;rich:componentControl&gt;</property>
            </emphasis>.</para>

        <para>The <emphasis role="bold">
                <property>&lt;rich:contextMenu&gt;</property>
            </emphasis>
            <emphasis>
                <property>&quot;submitMode&quot;</property>
            </emphasis> attribute can be set to three possible parameters:</para>

        <itemizedlist>
            <listitem>
                  <para><code>Server</code> — default value, uses regular form submition request;</para>
            </listitem>
        </itemizedlist>

        <itemizedlist>
            <listitem>
                  <para><code>Ajax</code> — Ajax submission is used for switching;</para>
            </listitem>
        </itemizedlist>

        <itemizedlist>
            <listitem>
                  <para><code>None</code> — neither <code>Server</code> nor <code>Ajax</code> is used.</para>
            </listitem>
        </itemizedlist>

        <para>The <emphasis>
                <property>&quot;action&quot;</property>
            </emphasis> and <emphasis>
                <property>&quot;actionListener&quot;</property>
            </emphasis> item&apos;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>Notes:</title>
              <itemizedlist>
                    <listitem>
                          <para>
                                When nesting <emphasis role="bold"><property>&lt;rich:contextMenu&gt;</property></emphasis> into JSF <emphasis role="bold"><property>&lt;h:outputText&gt;</property></emphasis>, 
                                specify an <code>id</code> for <emphasis role="bold"><property>&lt;h:outputText&gt;</property></emphasis>, otherwise, do not nest the <emphasis role="bold"><property>&lt;rich:contextMenu&gt;</property></emphasis> to make it work properly.
                          </para>
                    </listitem>
              </itemizedlist>      
              
              <itemizedlist>
                    <listitem>
                          <para>
                                As the <emphasis role="bold"><property>&lt;rich:contextMenu&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>
                    </listitem>
              </itemizedlist>
        </note>
        

   <!--     <para>It&apos;s possible to handle events for contextMenu from JavaScript code. A simplest example of usage JavaScript API is placed below:</para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[...
    <rich:contextMenu ... id="cmID">
        ...
    </rich:contextMenu>
    ...
<h:commandButton value="Show" onclick="#{rich:component('cmID')}.show(event)"/>
...]]></programlisting>  -->

        <!-- Will be done for latest version -->
        <!--para> It&apos;s possible to define the direction for list appear in the <emphasis>
                <property>&quot;direction&quot;</property>
            </emphasis>attribute. If the accordance of the popup corner to corner of the label isn&apos;t
            set <emphasis>
                <property>&quot;direction&quot;</property>
            </emphasis> attribute must set next accordances: </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(default) - smart positioning activation</para>
            </listitem>
        </itemizedlist>
        <para><emphasis role="bold">
                <property>&lt;rich:contextMenu&gt;</property>
            </emphasis> provides <emphasis>
                <property>&quot;jointPoint&quot;</property>
            </emphasis> attribute to set the point on the label element to connect popup. Possible
            values 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(default) - smart positioning activation</para>
            </listitem>
        </itemizedlist>

        <para>In order to set the offset for the menu popup relatively to label, you can use <emphasis>
                <property>&quot;horizontalOffset&quot;</property>
            </emphasis> and <emphasis>
                <property>&quot;verticalOffset&quot;</property>
            </emphasis> attributes. Values can be negative.</para-->

        <!-- For menuItem, not for contexMenu -->
        <!--para><property>menuItem</property> provides <emphasis>
                <property>&quot;submitMode&quot;</property>
            </emphasis> attribute to define the way of submission. Possible values : <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>&quot;reRender&quot;</property>
                </emphasis> attribute are rerendered.</para>
            <itemizedlist>
                <listitem>
                    <para>None</para>
                </listitem>
            </itemizedlist>
            <para> The <emphasis>
                    <property>&quot;action&quot;</property>
                </emphasis> and <emphasis>
                    <property>&quot;actionListener&quot;</property>
                </emphasis> item&apos;s attributes are ignored. Menu items don't fire any submits
                themselves. The behavior is fully defined by the components nested inside items.</para>
            <template
        <para>emphasis role="bold">
            <property>&lt;contextMenu&gt;</property>
            </emphasis> could not be generated for every component where it&apos;s defined. Templating could
            be used instead. So only representation data could be loaded from server. And markup
            could be evaluated on client side. So it&apos;s should accept macrosubstitutions like
            {value} </para>
         
        </para-->
    </section>
    <section>
        <title>JavaScript API</title>
        <table>
            <title>JavaScript API</title>
            <tgroup cols="3">
                <thead>
                    <row>
                        <entry>Function</entry>
                        <entry>Description</entry>
                        <entry>Apply to</entry>
                    </row>
                </thead>
                <tbody>
                    <!--Sorting API -->
                    <row>
                        <entry>hide()</entry>
                        <entry>Hides component or group</entry>
                        <entry>Component, group</entry>
                    </row>
                    <row>
                        <entry>show(event, context)</entry>
                        <entry>Shows component or group</entry>
                        <entry>Component, group</entry>
                    </row>
                    <!--row>
                        <entry>Enable()</entry>
                        <entry>Enable component, item, group</entry>
                        <entry>Component, Item, Group</entry>
                    </row>
                    <row>
                        <entry>Disable()</entry>
                        <entry>Disable component, item or group</entry>
                        <entry>Component, Item, Group</entry>
                    </row-->
                </tbody>
            </tgroup>
        </table>
    </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:contextMenu&gt;</property>
            </emphasis> components at once: <itemizedlist>
                <listitem><para>Redefine the corresponding skin parameters</para></listitem>
                <listitem><para> Add to your style sheets style classes used by a <emphasis role="bold">
                        <property>&lt;rich:contextMenu&gt;</property>
                    </emphasis> component</para></listitem>
            </itemizedlist>
        </para>
    </section>
    <section>
        <title>Skin Parameters Redefinition</title>
        <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>Style classes</title>

            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/contextMenu_cn.png" scalefit="1"/>
                </imageobject>
            </mediaobject>
        </figure>

        <table id="cMC">
            <title>Classes names that define the contextMenu 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:contextMenu&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 tables <link linkend="cMC"> above</link>) and define necessary properties in them. </para>
        
        <programlisting role="CSS"><![CDATA[...
.rich-menu-item{
        font-style:italic;
}
...]]></programlisting>  
        
        <para>This is a result:</para>
        
        <figure>
            <title>Redefinition styles with predefined classes</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/contextMenu_pc.png"/>
                </imageobject>
            </mediaobject>
        </figure>
        
        <para>In the example the font style for row items  was changed.</para>
        
        <para>Also it&apos;s possible to change styles of particular <emphasis role="bold"
            ><property>&lt;rich:contextMenu&gt;</property></emphasis> component. In this case you should create own style classes and use them in corresponding <emphasis role="bold"
                ><property>&lt;rich:contextMenu&gt;</property></emphasis> <emphasis><property>styleClass</property></emphasis> attributes. An example is placed below:</para>
        
        <programlisting role="CSS"><![CDATA[...
.myClass{
        font-weight:bold;
}
...]]></programlisting>  
        <para>The <emphasis><property>&quot;rowClasses&quot;</property></emphasis> attribute for <emphasis role="bold"
            ><property>&lt;h:panelGrid&gt; </property></emphasis> is defined as it&apos;s shown in the example below:</para>
 
        <programlisting role="XML"><![CDATA[<h:panelGrid ... rowClasses="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/contextMenu_oc.png"/>
                </imageobject>
            </mediaobject>
        </figure>  
        
        <para>As it could be seen on the picture above, the font weight for row items  was changed.</para>
        
        
        
    </section>

    <section>
        <title>Relevant Resources Links</title>
        <para>
              Visit the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/contextMenu.jsf?c=contextMenu">ContextMenu page</ulink> at RichFaces LiveDemo for examples of component usage and their sources. 
        </para>
    </section>

</section>
