IBM FileNet P8, Version 5.2            

Customizing the File, Insert, and Help Add-In menus

IBM® FileNet® P8 Application Integration provides support for customizing the File, Insert, and Help pop-up menus of Microsoft Outlook, Word, Excel, and PowerPoint. Application Integration utilizes COM Add-Ins to extend these applications by adding custom Add-In menus. These custom menus can be modified by developers through the use of provided XML files, which contain information used by Application Integration to configure the menu contents for the Microsoft applications.

After Application Integration has been installed, developers can manually modify the contents of the XML files in order to customize the Add-In menus to meet their application requirements. The customized XML files can then be copied to other systems in the organization, to provide a means for controlling the application environment and feature availability for a particular user or class of users. Whenever a new change is required for a particular application, the corresponding XML file can be updated and copied again to the appropriate systems.

XML customization techniques

Developers can customize the Add-In menus as follows:
Table 1. Lists and describes the various ways you can customize an Add In menu.
Customize the... Description
Visibility Specify the Application Integration commands and pop-up submenus that should be visible on the menu. This technique enables the complete removal of a submenu or command from a menu in order to control the availability of a certain feature.
Enable State Specify the Application Integration commands and pop-up submenus that should be visible, but disabled (grayed out). This technique allows developers to control whether a particular menu can be opened or a command be executed.
Label or Caption Specify the labels or captions for the Application Integration commands and pop-up submenus as they should appear to the user. For example, developers can rename the "Checkin" command to "Store Document" or group certain commands together on a submenu called "Authoring."
Command Action Specify which Application Integration action should get performed when an Application Integration command is selected.
Note: You cannot specify vendor commands.
Menu Hierarchy Specify the arrangement of the Application Integration commands on the menu, including the order of commands and whether they are contained in a pop-up submenu folder hierarchy.

XML file names and location

During installation of Application Integration, the XML files are written to the installation directory (the default is C:\Program Files\FileNet\AppInt\). Whenever one of the supported Microsoft applications is opened, Application Integration searches for the corresponding XML file in the installation directory and then configures the Add-In menu for that application according to the specifications contained in the XML file. If Application Integration cannot locate the XML files in the installation directory, it attempts to gather the files from the Module directory. (The Module directory is where the Microsoft Office applications are typically stored, by default in C:\Program Files\Microsoft Office\Office.)

CAUTION:
While developers can modify the contents of the XML files, the XML file names must not be changed and the files must be located in the installation or module directory in order for Application Integration to locate and utilize the XML files to configure the Add-In menus.
The following table identifies the names of the XML files, the Microsoft Office applications that are affected by each XML file, and the supported versions for each application.
Table 2. Lists each XML file names along with the corresponding Microsoft Office applications and the supported versons of those applications.
XML file name Corresponding application Supported versions
FnAppIntExcelMenus.xml Excel 2003, 2007, 2010
FnAppIntOutlookMenus.xml Outlook Explorer (item browse window)

Outlook Inspector (item edit window)

2003, 2007, 2010
FnAppIntPowerPointMenus.xml PowerPoint 2003, 2007, 2010
FnAppIntWordMenus.xml Word 2003, 2007, 2010

XML modification considerations

The following points should be considered prior to modifying the XML files:
  • Although the XML files are installed as read-only, developers can modify the file permissions to make them read-writable.
  • The XML files provided by IBM supply the correct syntax and usage for specifying the Add-In menus and their contents. Developers should closely follow the XML formatting and parameter syntax provided in these files. In addition, developers can back up the original XML files prior to implementing any modifications. This assists in debugging and resolving potential syntax errors in the modified files.
  • In order to configure the Add-In menus, Application Integration searches for the XML files by name in the installation directory. While developers can modify the contents of the XML files, the XML file names must not be changed and the files must be located in the installation or module directory in order for Application Integration to locate and utilize the XML files to configure the Add-In menus.
  • Whenever Application Integration is installed, including fix packs, the original XML files are written to the installation directory. As a result, customized XML files can be overwritten. Therefore, developers can make backup copies of their modified XML files, and save them using unique file names or to a unique folder. This enables customized XML files to be quickly restored as needed.

XML Add-In menu schema

The basic structure of the XML schema for the Add-In menus is as follows:
  • addInMenusConfiguration - the top-level object in the schema which identifies that the following XML objects describe the Add-In menus for an application. This object also specifies the version of the schema being employed.
  • applicationName - identifies the target application for which the Add-In menus are being configured.
  • applicationVersion - specifies the supported versions for the target application.
  • addInMenusDefinition - each addInMenusConfiguration object consists of one (or more in the case of Microsoft Outlook) of these objects which contain the objects that specify how each Add-In menu (File, Insert, or Help) should be configured for the application. This object also specifies the type of Add-In menu that should be created. Application Integration supports the following types: main for Word, Excel, and PowerPoint, and explorer and inspector for Outlook.
  • addInMenuItem - each addInMenusDefinition object consists of one or more of these objects which describe the submenu hierarchy and command button behavior for each menu. This is accomplished through the use of the itemType tag, which can be set to popup or button.
    • When itemType="popup", an addInMenuItem object can contain a list of its own addInMenuItem object children, thus enabling the ability to create a submenu structure. This hierarchical structure can be repeated to any depth necessary to achieve your organizational requirements.
    • When itemType="button", the XML structure terminates since only popup menu items can have child menu items.
  • setting - each addInMenuItem object (popup or button) contains a number of setting tags which define the appearance and behavior for the submenu or button, such as a description for the menu item, the visible label or caption, the menu insertion position, and the corresponding Application Integration action to execute when the menu item is opened or selected. The Setting Tags section provides complete details for the setting tags.

For an example of how these tags are used in the XML schema, see Sample XML Schema.

Setting Tags

Each addInMenuItem object uses setting tags to define the appearance and behavior of Add-In menu submenus or command buttons. The syntax for the tag varies depending on the key that is being defined. For example, some keys require the type field, while others do not:

<setting key="itemType">popup</setting>
<setting key="parent"
type="menuId">30002</setting>

In the following table, when a key does not require the use of the type field or does not need a specified value, the entry in the Type or Value column is "Not applicable". When the value for the key is not a known Application Integration variable, such as popup or button, the entry in the Value column appears in italics; for example, 30002. In addition, when a key is not required, the entry in the Description column contains the [Optional] indicator.

Application Integration supports the following setting tags.
Table 3. Lists each key, along with its type, value, and description.
Key Type Value Description
itemType Not applicable popup Indicates that the Add-In menu item is a pop-up submenu with children, which can include command buttons and additional pop-up submenus.
  Not applicable button Indicates that the Add-In menu item is a command button with no children.
description Not applicable P8 File Menu [Optional] Provides a description for the Add-In menu item which is informational only; this description is not visible to the user.
label enum eOpenSubMenuName Supplies the visible label or caption for the Add-In menu item using one of the following enumeration constants:
  • eFileMenuName
  • eOpenButtonName
  • eOpenSubMenuName
  • eOpenMyCheckoutsButtonName
  • eOpenSelectItemButtonName
  • eAddDocumentButtonName
  • eAddDocumentSubMenuName
  • eAddDocumentUseWizardButtonName
  • eAddDocumentSelectTemplateButtonName
  • eAddFolderButtonName
  • eCheckinSubMenuName
  • eCheckinQuickButtonName
  • eCheckinUseWizardButtonName
  • eTasksMyInboxButtonName
  • eSaveButtonName
  • eCancelCheckoutButtonName
  • ePropertiesButtonName
  • eLogoffButtonName
  • eInsertMenuName
  • eInsertButtonName
  • eInsertHyperlinkButtonName
  • eInsertPropPageButtonName
  • eInsertPropertyButtonName
  • eRefreshPropertyButtonName
  • eDeletePropertyButtonName
  • eHelpButtonName
  resourceID 119 Supplies the visible label or caption for the Add-In menu item by specifying an integer value that corresponds to a resource ID defined in a resource localization file.
  text Checkin... Supplies the visible label or caption for the Add-In menu item be providing the actual text string.
visible Not applicable true Specifies that the Add-In menu item (and any children if the menu item is a pop-up submenu) is visible to the user.
    false Specifies that the Add-In menu item (and any children if the menu item is a pop-up submenu) is not visible to the user (that is, the menu item does not appear on the Add-In menu).
enabled Not applicable true Specifies that the Add-In menu item is enabled, thus making it possible for the user to open the pop-up submenu or select the command button.
    False Specifies that the Add-In menu item cannot be opened or selected by the user (that is, the menu item is disabled on the Add-In menu).
parent menuId 30002 Provides the "menuId" value for the parent menu of the Add-In menu item. When the menu item is a pop-up submenu, this value is typically the control ID of an existing Microsoft Office pop-up menu. For more information about menu IDs in Microsoft Office Applications, see the Microsoft Office Developers Guide for Office 2003/XP/2007.
  topLevel Not applicable When the Add-In menu item is a pop-up submenu, this key and type pair indicates that the submenu is placed on the top-level menu bar of the application.
Note: This key and type pair is valid only for pop-up submenus.
  Not applicable Not applicable When the Add-In menu item is a command button, the parent is implied in the specified XML through the use of the <list key="children"> tag. Therefore, no parent specification is required at this setting location in the XML.
Note: This key and type pair is valid only for command buttons.
location Not applicable 4 Specifies the insertion position for this Add-In menu item on the parent menu. A value of -1 indicates that the menu item is appended to the bottom of the existing menu.
Note: This value indicates the desired position for the menu item on the parent pop-up menu.
command standard
OfficeAdd-In.
OpenSelection
Specifies the Application Integration operation to perform when a command button is selected by the user. One of the following enumeration constants can be specified:
  • OfficeAdd-In.AddFolderUseAddWizard
  • OfficeAdd-In.OpenMyCheckouts
  • OfficeAdd-In.OpenSelectItem
  • OfficeAdd-In.AddDocumentUseAddWizard
  • OfficeAdd-In.AddDocumentSelectTemplate
  • OfficeAdd-In.CheckinDocumentUseCheckinWizard
  • OfficeAdd-In.CheckinDocumentQuickCheckin
  • OfficeAdd-In.Save
  • OfficeAdd-In.CancelCheckout
  • OfficeAdd-In.GetInfo
  • OfficeAdd-In.TasksMyInbox
  • OfficeAdd-In.Logoff
  • OfficeAdd-In.Help
  • OfficeAdd-In.InsertItem
  • OfficeAdd-In.InsertProperty
  • OfficeAdd-In.RefreshProperties
  • OfficeAdd-In.DeleteProperties
  • OfficeAdd-In.InsertHyperlink
  • OfficeAdd-In.InsertPropertiesPage
  standard Not applicable When the Add-In menu item is a pop-up submenu, menu clicks are ignored. Therefore, no command specification is required at this setting location in the XML.
Note: This key and type pair is valid only for pop-up submenus.

For an example of how these tags are used in the XML schema, see Sample XML Schema.

Sample XML Schema

The following code fragment illustrates the basic XML schema structure for the Add-In menus for the Excel application:
<?xml version="1.0" ?>
 <!-- IBM FileNet P8 Application Integration 4.0 Excel Add-In Menus-->
 <!-- Add-In Menus - Configuration Info -->
 <object key="addInMenusConfiguration" version="1.0">
 <setting key="applicationName">Excel</setting>
 <array key="applicationVersion">
 <value>2003</value>
 <value>2007</value>
 <value>2010</value>
 </array>
 <!-- Add-In Menus - Main Menu Definitions -->
 <object key="addInMenusDefinition" type="main">
 <list key="children">
 <!-- P8 File Menu -->
 <object key="addInMenuItem">
 <setting key="itemType">popup</setting>
 ...
 <list key="children">
 <!-- Open Document SubMenu -->
 <object key="addInMenuItem">
 <setting key="itemType">popup</setting>
 <setting key="description">Submenu of commands for opening documents.</Setting>
 <setting key="label" type="text">Open Document</setting>
 <setting key="visible">true</setting>
 <setting key="enabled">true</setting>
 <setting key="location">3</setting>
 <setting key="command" type="standard"></setting>
 <list key="children">
 <!-- Open Document - My Checkouts... Button -->
 <object key="addInMenuItem">
 <setting key="itemType">button</setting>
 ...
 <list key="children" />
 </object>
 <!-- Open Document - Select Item... Button -->
 <object key="addInMenuItem">
 <setting key="itemType">button</setting>
 ...
 <list key="children" />
 </object>
 </list>
 <list key="children" />
 </object>
 <!-- Add Document SubMenu -->
 <object key="addInMenuItem">
 <setting key="itemType">popup</setting>
 ...
 <list key="children" />
 </object>
 ...
 <!-- Add Folder... Button -->
 <object key="addInMenuItem">
 <setting key="itemType">button</setting>
 <setting key="description">Performs the Add Folder Wizard</setting>
 <setting key="label" type="enum">eAddFolderButtonName</setting>
 <setting key="visible">true</setting>
 <setting key="enabled">true</setting>
 <setting key="parent" type="menuId">30002</setting>
 <setting key="location">1</setting>
 <setting key="command" type="standard">OfficeAdd-In.AddFolderUseAddWizard</setting>
 <list key="children" />
 </object>
 ...
 </list>
 <list key="children" />
 </object>
 <!-- P8 Insert Menu -->
 <object key="addInMenuItem">
 <setting key="itemType">popup</setting>
 ...
 <list key="children">
 ...
 </list>
 <list key="children" />
 </object>
 <!-- P8 Help Menu -->
 <object key="addInMenuItem">
 <setting key="itemType">popup</setting>
 ...
 <list key="children">
 ...
 </list>
 <list key="children" />
 </object>
 </list>
 </object>
 </object>
...


Feedback

Last updated: March 2013
overview_addin_menus.htm

© Copyright IBM Corporation 2013.
This information center is powered by Eclipse technology. (http://www.eclipse.org)