Package com.microstrategy.web.app.gui

Class ContextMenuManager

  • public class ContextMenuManager
extends java.lang.Object

    The ContextMenuManager represents a collection of ContextMenu objects. A ContextMenu is displayed when the end user makes click using the right mouse button on an element in the interface; the menu displays a list with different actions associated with that element.

    Context menus can and should be configured using external XML files. All MicroStrategy Web transforms that display context-menus have their AbstractAppTransform.contextMenus formal parameter assigned in the style catalog. Even those transforms that display no context menus out of the box can be configured to display them simply by creating a new XML definition file and setting the contextMenus formal parameter.

    To programatically create and manipulate context-menus, the following steps are required:

    1. Create a new ContextMenuManager instance that will be used as factory of all ContextMenu.
    2. From the ContextMenuManager create the ContextMenu objects. Typically there will be one ContextMenu for each different element, even if the options are the same. For example, in the folder page there is one ContextMenu for each object in the folder.
    3. Next, populate the ContextMenu with its corresponding ContextMenuItem objects. Each ContextMenuItem represents a single option.
    4. Once the ContextMenu has been populated it needs to be associated with the corresponding HTML Tag (typically a <div>). For this purpose you can call the ContextMenu.attachTo(com.microstrategy.web.tags.Tag) or ContextMenu.getTriggerString().
    5. When all the ContextMenus have been created, the getScriptOutput() generates the JavaScript necessary to display the context-menus with-in MicroStrategy Web.

    Classes extending AbstractAppTransform need not to worry about creating the ContextMenuManager instance or invoking the getScriptOutput method. These tasks are automatically taken care of by the abstract class.

    The following sample illustrates these concepts. This transform creates three text elements, and associates to each a ContextMenu with two items and a separator between them: the first one generates a JavaScript alert message in the browser, the second one redirects the user to www.microstrategy.com. 
      import com.microstrategy.web.app.transforms.AbstractAppTransform;
  import com.microstrategy.web.beans.MarkupOutput;
  import com.microstrategy.web.tags.Tag;
  import com.microstrategy.web.app.gui.ContextMenu;

  public class ContextMenuSample extends AbstractAppTransform {

      public ContextMenuSample() {
          super();
      }

      public void transformForRequestSuccessful(MarkupOutput out) {
          renderSample(out, "text A");
          renderSample(out, "text B");
          renderSample(out, "text C");

          out.append(getContextMenuManager().getScriptOutput());
      }

      public void renderSample(MarkupOutput out, String text) {
          //Create a div tag enclosing the given text:
          Tag div =  getTagsFactory().newDivTag();
          div.getContent().append(text);

          //Create and populate the corresponding context-menu:
          ContextMenu menu = getContextMenuManager().getMenu();
          menu.addItem("Alert", "alert", "'" + text + "'");
          menu.addSeparator();
          menu.addItem("MicroStrategy web site", "http://www.microstrategy.com");

          //Once populated, attach the context-menu to the div:
          menu.attachTo(div);

          //Generate the div's HTML:
          div.render(out);
      }

      public String getDescription() {
          return "Shows the programmatic usage of context-menus.";
      }

 }
    Since:
    MicroStrategy Web 7.3.1 or earlier

    • Constructor Detail

      • ContextMenuManager

        public ContextMenuManager​(java.lang.String name,
                          AppContext appContext)
        Class constructor. Initializes a new instance of a ContextMenuManager class.

      • ContextMenuManager

        public ContextMenuManager​(java.lang.String name,
                          ShortcutListSet definition,
                          TransformContext context)
        Class constructor. Initializes a new instance of the ContextMenuManager class. This constructor receives the ShortcutListSet structure (typically initiated from an XML-definition) with the information that will be used to populate the ContextMenu instances.
        Parameters:
        name - A unique identifier for this ContextMenuManager.
        definition - This is a non-null ShortcutListSet instance to be used as the menu definition for the context-menus provided by this manager.
        context - A non-null TransformContext instance for this request. It provides information about where the context-menus will be used.
        Since:
        MicroStrategy Web 8.0.1

      • ContextMenuManager

        public ContextMenuManager​(java.lang.String name)
        Class constructor. Creates a new instance of the ContextMenuManager with the given name.
        Parameters:
        name - A unique identifier for this ContextMenuManager.

      • ContextMenuManager

        @Deprecated
public ContextMenuManager​(AppContext appContext)
        Deprecated.
        This constructor is not supported anymore. The proper usage requires to assign a unique name to every ContextMenuManager.
        Class constructor. Creates a new empty instance of a ContextMenuManager.

      • ContextMenuManager

        @Deprecated
public ContextMenuManager()
        Deprecated.
        This constructor is not supported anymore. The proper usage requires to assign a unique name to every ContextMenuManager.
        Class constructor. Creates an empty new instance of a ContextMenuManager.

    • Method Detail

      • getDynamicMenu

        public ContextMenu getDynamicMenu​(java.lang.String name)

        Returns a dynamic ContextMenu instance identified by the given name.

        Dynamic ContextMenus are different from normal context-menus in a subtle way: there exists only one instance per ContextMenuManager, therefore if you pass the same name you will receive the same ContextMenu instance (as opposed to the other getMenu() methods which always return a new instance). The reason is that these context-menus will be updated in the client using JavaScript so they really not depend on the TransformContext. Still, they are created on the server so the user can modify the context-menu definition using a configuration file.

        Returns:
        a dynamic ContextMenu.
        Since:
        MicroStrategy Web 9.0.0

      • getMenu

        @Deprecated
public ContextMenu getMenu​(java.lang.String name)
        Deprecated.
        use getDynamicMenu(String) instead.

        Returns a dynamic ContextMenu instance identified by the given name.

        Dynamic ContextMenus are different from normal context-menus in a subtle way: there exists only one instance per ContextMenuManager, therefore if you pass the same name you will receive the same ContextMenu instance (as opposed to the other getMenu() methods which always return a new instance). The reason is that these context-menus will be updated in the client using JavaScript so they really not depend on the TransformContext. Still, they are created on the server so the user can modify the context-menu definition using a configuration file.

        Returns:
        a dynamic ContextMenu.
        Since:
        MicroStrategy Web 8.0.1

      • getMenu

        public ContextMenu getMenu​(java.lang.String name,
                           TransformContext context)

        Creates a new ContextMenu instance, populated with the items as specified in the ShortcutListSet definition.

        When this ContextMenuManager is created, the user may specify a ShortcutListSet to be used as the menus definition, when this is the case, this method will search for a ShortcutList within the ShortcutListSet with the corresponding name, if found it will use it to populate the new ContextMenu instance.

        Parameters:
        name - The name of a ShortcutList to use to populate the ContextMenu
        context - A TransformContext instance, used to retrieve information about the context.
        Returns:
        a new (populated) ContextMenu instance
        Since:
        MicroStrategy Web 8.0.1

      • getMenu

        @Deprecated
public ContextMenu getMenu​(ShortcutList shortcuts,
                           WebComponent targetBean)
        Deprecated.
        Instead of passing the ShortcutList as parameter, create a new ContextMenuManager with a ShortcutListSet definition and call getMenu(String name, TransformContext context).
        Creates a new ContextMenu instance populated with the given shortcuts.
        Parameters:
        shortcuts - A ShortcutList, the ContextMenu will have a ContextMenuItem for each element in the ShortcutList.
        targetBean - a WebComponent, used to retrieve context information, for example to validate features or create WebEvents.
        Returns:
        a new ContextMenu instance.
        Since:
        MicroStrategy Web 8.0.0

      • getMenuItems

        public void getMenuItems​(java.lang.StringBuilder builder)
        Fills a StringBuilder with all the menu items of this ContextMenuManager represented by ContextMenuItems stored in the getMenuElements() in the JSON format.
        Parameters:
        builder -
        Since:
        MicroStrategy Web 9.0.0

      • getDrillMenuItems

        public BlockList getDrillMenuItems()
        On Demand Drill menus

      • getDrillDynamicMenus

        public BlockList getDrillDynamicMenus()
        On Demand Drill menus at top-level

      • getDynamicMenus

        public void getDynamicMenus​(java.lang.StringBuilder builder)
        Puts the dynamic menus stored in this ContextMenuManager in JSON format. on a StringBuilder representing the dynamic menus in JSON format
        Parameters:
        builder -
        Since:
        MicroStrategy Web 9.0.0

      • getTriggerString

        public java.lang.String getTriggerString()
        Returns a String with the attributes necessary to link an HTML tag with the context-menus associated with this ContextMenuManager. Typically is not necessary to call this method as the ContextMenu.getTriggerString() already includes the necessary information.
        Since:
        MicroStrategy Web 8.0.0
        See Also:
        ContextMenuManager

      • getTriggerAttributes

        public java.util.Map<java.lang.String,​java.lang.String> getTriggerAttributes()
        Returns a Map (name/value pairs) with the attributes necessary to link an HTML tag with the context-menus associated with this ContextMenuManager. Typically is not necessary to call this method as the ContextMenu.getTagAttributes() or ContextMenu.attachTo(com.microstrategy.web.tags.Tag) methods already includes the necessary information.
        Since:
        MicroStrategy Web 8.0.0
        See Also:
        ContextMenuManager

      • getScriptOutput

        public MarkupOutput getScriptOutput()
        Returns a new MarkupOutput object populated with the JavaScript code required to display the ContextMenu objects associated with this ContextMenuManager. This MarkupOutput needs to be included as part of the HTML output sent to the web-browser.
        See Also:
        ContextMenuManager

      • getMenuElements

        @Deprecated
public HashList<java.lang.String,​ContextMenuItem> getMenuElements()
        Deprecated.
        This method should only be accessed internally and will be marked as private in future releases.
        Returns the collection of all the ContextMenuItems defined within any ContextMenu of this ContextMenuManager.