Developing Web Applications with the Web ADF - Web controls  

ContextMenu control



The ContextMenu control is designed to enhance user interactivity with Web ADF components in an application.  In general, the control is displayed by a user event in a browser at runtime.   In most cases, the event is a right-click on an existing control, element, or item already displayed in the page.  A ContextMenu can contain one or more context menu items.  Each item is associated with an action to execute client or server-side code.  In addition, each context menu item may be displayed with an icon and\or text.  Both the Toc and TaskResults controls include preconfigured ContextMenus to interact with their node content.  

The ContextMenu control is not included with the out-of-the-box Web ADF controls integrated with Visual Studio.  So, to use the control you can either add a declarative reference in your page or add the ContextMenu control to the Visual Studio toolbox then drag-and-drop it on the page (see Step 1 in Using the ContextMenu control section below).  In addition, context menu items can only be configured programmatically; no design-time configuration is provided. 

Assembly: ESRI.ArcGIS.ADF.Web.UI.WebControls.dll
Class: ESRI.ArcGIS.ADF.Web.UI.WebControls.ContextMenu
Using the ContextMenu control
  1. Add the ContextMenu control to the Visual Studio toolbox

    Since the ContextMenu control is not added to the Visual Studio toolbox during the Web ADF installation, you need to manually add it.  If you have already added the ContextMenu control, skip to the next step. 
    1. In Visual Studio, expand the ArcGIS Web Controls tab in the toolbox.  Right-click on the tab and select "Choose Items...".
    2. Navigate to the ContextMenu control in the namespace ESRI.ArcGIS.ADF.UI.WebControls and check the box next to the listing.  Click OK.  The ContextMenu control should now be available in the toolbox.

      Page with Toc control
  2. Add supporting controls to the page

    Add a MapResourceManager and Map to the page.  Add a valid resource item to the MapResourceManager.  In this example a ContextMenu control will be constructed for use on a Map control.  Keep in mind that a ContextMenu can be associated with any element in the page, thus the patterns presented here will apply in other situations. 
     
  3. Add the ContextMenu control to the page

    Drag a ContextMenu control on the page.  Note that the location of the ContextMenu control at design-time does not determine the location of the context menu at runtime.  Your page should resemble the following:

    Page with Toc control
  4. Set properties for the ContextMenu control 

    In design mode, click on the ContextMenu control to select it.  The Properties window will display the properties for the control.  While no properties are must be manually changed, one is recommended.   Set the BackColor property to a solid color, for example, white or gray.  By default the BackColor property is not set, thus the context menu appears transparent at runtime.
  5. Add context menu items

    Adding items and configuring the behavior of a ContextMenu will require a writing some code.  New context menu items can be created using the ContextMenuItem class and added to the ContextMenu control.   Properties of a ContextMenuItem include the url to an image, the menu item text, and a string representing some custom JavaScript code to execute when the item is clicked.  An appropriate time to add new context menu items during the page lifecycle is during the initial page load event.   Add the following code to the code behind for your page:

    [C#]
    protected void Page_Load(object sender, EventArgs e)
    {
        if (!IsPostBack)
        {
            ESRI.ArcGIS.ADF.Web.UI.WebControls.ContextMenuItem contextMenuItem = 
                new ESRI.ArcGIS.ADF.Web.UI.WebControls.ContextMenuItem();
    
            contextMenuItem.Text = "Zoom In";
    
            ContextMenu1.Items.Add(contextMenuItem);   
        }
    }         
    
  6. Add event to show context menu at runtime

    The browser event to display the context menu at the appropriate time must to added to the appropriate control/element/item in the page.  In this case, we want the ContextMenu to be displayed during a right-click on a map.   At runtime, the Map control generates a div for display of map data in a browser.   A set of attributes events can be configured on the div.  One attribute is "oncontextmenu" which enables the browser to listen for right-click events on an element.  When this event is triggered, JavaScript code will be used to show the ContextMenu control and its items.   The Web ADF provides a set of JavaScript functions to show and hide context menus.  In this case, when the oncontextmenu event is triggered on the map the esriShowContextMenu() JavaScript function will be called and our ContextMenu will be displayed.  As in the previous step, an appropriate time to add new attribute information to controls and elements is during the initial page load event.   Add the following code (blue) to the existing code added in the previous step (gray):
      
    [C#]
    protected void Page_Load(object sender, EventArgs e)
    {
        if (!IsPostBack)
        {
            ESRI.ArcGIS.ADF.Web.UI.WebControls.ContextMenuItem contextMenuItem = 
                new ESRI.ArcGIS.ADF.Web.UI.WebControls.ContextMenuItem();
    
            contextMenuItem.Text = "Zoom In";
    
            ContextMenu1.Items.Add(contextMenuItem);
            
            string showContextMenu = string.Format("esriShowContextMenu(event,'{0}','{1}','{2}');return false;", ContextMenu1.ClientID, Map1.UniqueID, "");
                              
            Map1.Attributes.Add("oncontextmenu", showContextMenu);                 
        }
    }         
    
  7. Handle click event on context menu item

    Once the ContextMenu is displayed at runtime, a user can click on a context menu item to initiate an action.  To work with the click event on the server, handle the ItemClicked event on the ContextMenu.  When the menu item is clicked, a callback request is sent to the page which contains the context menu.  The context menu item can be identified by its text and made available via the ContextMenuItemEventArgs passed to the ItemClicked event.  The ContextMenu control is explicitly designed to work with the ASP.NET callback architecture.   Implementation code on the server can now interact with server-side content based on the context menu item clicked.  Note, the ContextMenu control generates the callback response designed to be processed by the Web ADF JavaScript.  As a result, changes to other controls in the page must be packaged as CallbackResults and added to the ContextMenu.CallbackResults property (a collection of CallbackResult objects).   More information on Web ADF implementation of the ASP.NET callback framework is available in the topic Working with AJAX capabilities of the Web ADF
    1. To handle the ItemClicked event on the ContextMenu in the page, open the ContextMenu property page and view the events (click the lightning bolt button).

      Page with Toc control
    2. Double-click on the ItemClicked event in the dialog.  The code-behind page will display with the implementation method created for you.
    3. Add the following code to the event handler method.  In this case, the Map.Zoom() convenience method will cause the map to zoom in, thus changing the map extent.  Since the Map has changed, but the ContextMenu is generating the callback response

      [C#]
      protected void ContextMenu1_ItemClicked(object sender, ESRI.ArcGIS.ADF.Web.UI.WebControls.ContextMenuItemEventArgs contextMenuItemEventArgs)
      {
          switch (contextMenuItemEventArgs.Item.Text)
          {
              case "Zoom In":
                  {
                      Map1.Zoom(2);
                      ContextMenu1.CallbackResults.CopyFrom(Map1.CallbackResults);
                      break;
                  }
          }
      }					
      					
  8. Using the ContextMenu at runtime

    When the Web application starts, the ContextMenu is not visible.  Right-click on the control which will show the ContextMenu, in this example it's the Map control.  The ContextMenu will be displayed along with it's context menu items.  In this case, click on the item "Zoom In" to zoom in on the map.    

    Page with Toc control

Members

The following tables provide a list of properties and events of interest.  For complete reference information, see the ContextMenu control in the library reference section.

Properties

Property Name  Type Description
HoverBorderColor Color The color of the border around a context menu item when the mouse cursor hovers over it at runtime.
HoverColor Color The background color of the context menu item when the mouse cursor hovers over it at runtime.

Events


Event Type Description
ItemClicked Occurs when a context menu item is clicked.