Creating custom menu in Documentum 6

WDK of Documentum 6 brings in come major enhancement for developers. The new library is Section 508 compliant and has also undergone user testing for accessibility and usability by the NFB (National Federation for the Blind). The list of new features is a big list including change to UI like right-click context menus, XML-based fixed menus that can be modified or extended, Configurable keyboard shortcuts etc. In this post we will see how to add a menu to the menu bar using configuration elements rather than extending menubar component.

In previous versions on WDK, you would have extended the menubar component and placed the xml in custom/config folder. You would also move the menubar.jsp with your new menu and menu items. In D6, things are little different. Let me quote from WDK tutorial PDF:

In earlier versions of the Web Development Kit, you would extend and override the configuration information files that come with the product as shipped. That approach still works. However, in Version 6, you have the option of modifying the user interface by adding, removing, or replacing individual configuration elements.

And this is exactly what we are going to do today. The concept of configuration elements is a great advantage to developers. By just changing XMLs you can modify the component. There is no need to extend each component for a minor change. This concept also makes the customizations more manageable and developer friendly.

WDK introduces component modification instead of extending it. To modify a specific component all you have to do is create a XML file in custom/config and specify the component you need to modify using modifies attribute of component element. Have a look at the below XML where I simply add a new menu item in tool menu of the webtop:

<config>
 <scope>
  <menuconfig modifies="menubar_tools_menu:webcomponent/config/library/menubar/menubar_component.xml">
   <insert path="menu[name=tools_menu]">
    <actionmenuitem dynamic = "genericnoselect"
     name = "hello_world_menu_item"
     id = "hello_world_menu_item"
     value = "Hello World"
     action = "hello_world_action"
     showifinvalid = "true"/>
   </insert>
  </menuconfig>   
 </scope>
</config>

The XML is simple and clean. In earlier versions, you will have used the “extends” attribute and specified the component you are extending. Here we just specify the component you want to modify and specify the section (in the above case menubar_tools_menu). WDK offers five different configuration elements: insert, insertafter, insertbefore, replace and remove. You can use these elements to modify any component.

An important change to notice is the way how menu component works. If you open menubar_component.xml in /webcomponent/config/library/menubar you will notice that all the menu and menu items are declared as part of the component.In previous versions, this would have been part of the JSP. Also notice each menu is defined by the tag menuconfig. These entire menus are declared in menuconfigids element as shown below:

<menuconfigids>
 <id>menubar_file_menu</id>
 <id>menubar_edit_menu</id>
 <id>menubar_view_menu</id>
<id>menubar_tools_menu</id>
</menuconfigids>

To add a new menu, we will have to modify the menuconfigids and our custom menu into it. Let’s see how we will insert a new menu into menuconfigids:

<component modifies="menubar:webcomponent/config/library/menubar/menubar_component.xml">
 <replace path="menuconfigids">
  <menuconfigids>
   <id>menubar_file_menu</id> 
   <id>menubar_tools_menu</id>
   <id>my_tools_menu</id>
  </menuconfigids>
 </replace>  
</component>

And to define the menu and one menu item:

<menuconfig id="my_tools_menu">
   <menu name="Level1" value="Level One">
    <actionmenuitem dynamic = "genericnoselect"
     name = "hello_world_menu_itemx"
     id = "hello_world_menu_itemx"
     value = "Hello World"
     action = "hello_world_action"
     showifinvalid = "true"/>
   </menu>
</menuconfig>

So finally we have a single XML containing the above two fragments:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<config version="1.0">
 <scope>  
  <menuconfig id="my_tools_menu">
   <menu name="Level1" value="Level One">
    <actionmenuitem dynamic = "genericnoselect"
     name = "hello_world_menu_itemx"
     id = "hello_world_menu_itemx"
     value = "Hello World1"
     action = "hello_world_action"
     showifinvalid = "true"/>
   </menu>
  </menuconfig>  
  <component modifies="menubar:webcomponent/config/library/menubar/menubar_component.xml">
   <replace path="menuconfigids">
    <menuconfigids>
     <id>menubar_file_menu</id> 
     <id>menubar_tools_menu</id>
     <id>my_tools_menu</id>
    </menuconfigids>
   </replace>   
  </component>  
 </scope>
</config>

A simple WDK refresh will make your menu appear on webtop! That's all and it's time for a hot tea :)