Create new RichFaces Documentation Jira issue

This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.orgCommunity Documentation

6.8.1.  < rich:contextMenu > available since 3.0.0

expand all
6.8.1.1. Description
6.8.1.2. Key Features
6.8.1.3. Details of Usage
6.8.1.4. Reference Data
6.8.1.5. Relevant Resources Links

The <rich:contextMenu> component is used for creation of multilevelled context menus that are activated after defined events like "onmouseover" , "onclick" etc. The component could be applied to any element on the page.


<rich:contextMenu> is a support-like component. Context menu itself is an invisible panel that appears after a particular client-side event ( "onmouseover" , "onclick" , etc.) occurred on a parent component. The event is defined with an "event" attribute. The component uses "oncontextmenu" event by default to call a context menu by clicking on the right mouse button.

<rich:menuGroup> , <rich:menuItem> and <rich:menuSeparator> components can be used as nested elements for <rich:contextMenu> in the same way as for <rich:dropDownMenu> .

By default, the <rich:contextMenu> disables right mouse click on a page in the context menu area only. But if you want to disable browser's context menu completely you should set the "disableDefaultMenu" attribute value to "true".

If "attached" value is "true" (default value), component is attached to the parent component or to the component, which "id" is specified in the "attachTo" attribute:


<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>

The "enlarge()" and "decrease()" functions definition is placed below.

&lt;script type="text/javascript"&gt;

        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>

In the example a picture zooming possibility with <rich:contextMenu> component usage was shown. The picture is placed on the <h:panelGroup> component. The <rich:contextMenu> component is not nested to <h:panelGroup> and has a value of the "attachTo" attribute defined as "pic1". Thus, the context menu is attached to the component, which "id" is "pic1". The context menu has two items to zoom in (zoom out) a picture by "onclick" 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 "oncontextmenu" event to call the context menu on a right click mouse event.

In the example the context menu is defined for the parent <h:panelGroup> component with a value of "id" attribute equal to "picture" 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't encode an Id on a client, it can't be found by the <rich:contextMenu> and it's attached to its closest parent in a DOM tree.

If the "attached" attribute has "false" value, component activates via JavaScript API with assistance of <rich:componentControl> . An example is placed below.

Example:


<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>

This is a result:


In the example the context menu is activated (by clicking on the left mouse button) on the table via JavaScript API with assistance of <rich:componentControl> . The attribute "for" contains a value of the <rich:contextMenu> Id. For menu appearance Java Script API function "show()" is used. It is defined with "operation" attribute for the <rich:componentControl> 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.

The <rich:contextMenu> component can be defined once on a page and can be used as shared for different components (this is the main difference from the <rich:dropDownMenu> component). It's necessary to define it once on a page (as it was shown in the example above) and activate it on required components via JavaScript API with assistance of <rich:componentControl> .

The <rich:contextMenu> "submitMode" attribute can be set to three possible parameters:

  • Server — default value, uses regular form submition request;

  • Ajax — Ajax submission is used for switching;

  • None — neither Server nor Ajax is used.

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

Notes:

  • When nesting <rich:contextMenu> into JSF <h:outputText> , specify an id for <h:outputText> , otherwise, do not nest the <rich:contextMenu> to make it work properly.

  • As the <rich:contextMenu> component doesn't provide its own form, use it between <h:form> and </h:form> tags.

Table of <rich:contextMenu> attributes.




You can find all necessary information about style classes redefinition in
Definition of Custom Style Classes section.

Visit the ContextMenu page at RichFaces LiveDemo for examples of component usage and their sources.