Copyright © Cloud Software Group, Inc. All Rights Reserved

Adding Custom Menu Items and Toolbar Buttons

Custom menus and/or toolbar buttons can be added to the client application using configuration settings in the client application’s configuration file, config.xml.

The record element that specifies a custom menu or toolbar button has a jsxid attribute value of customMenus:

---

---

 

The <record jsxid="customMenus"> element can have either toolbar or menu child elements. Both the toolbar and menu elements have three attributes:

•	parent - The name of the menu or toolbar location. The following values are valid:

−	“MainAppToolbar”

−	“WorkQList”

−	"WorkItemList"

−	“ProcList”

−	“CaseList”

−	“CaseSummary’

•	width - The display width in pixels.

•	prototype - The path to the default prototype XML file. This is the TIBCO® TIBCO® General Interface prototype that defines the GUI components for the menu or toolbar.

The custom menu files should be added in a directory under the application root:

ClientInstallDir\JSXAPPS\ipc

The following example shows a toolbar and a menu element taken from the samples given in config.xml:

---

---

 

Both the toolbar and menu elements may also have optional locale child elements that define prototype XML files that are localized for specific languages. If a locale child element exists, and it corresponds to the language and locale currently selected by the user, the language-specific prototype is loaded, otherwise the default prototype is loaded. For more information on customizing the client application for language localization, see Localization.

Each locale child element has three attributes:

•	localeKey - Locale identifier. This value must correspond to one of the locale element key attributes defined in the JSXAPPS\ipc\locale\locales.xml configuration file. For example:

The localeKey attribute values are of the format: ll or ll_CC, where ll is a lowercase, two- letter ISO 639 language code, and CC is the optional, uppercase, two-letter ISO 3166 country code. For a list of codes, visit these web sites:

−	International Organization for Standardization (ISO):

http://www.iso.ch/iso/en/ISOOnline.frontpage

−	Language codes:

http://www.loc.gov/standards/iso639-2/langhome.html

−	Country codes:

http://www.iso.ch/iso/en/prods-services/iso3166ma/
02iso-3166-code-lists/index.html

•	width - The display width in pixels.

•	prototype - The path to the prototype XML file containing language-specific data. This is the TIBCO® General Interface prototype that defines the GUI components for the menu or toolbar.

The custom localized menu files should be added in a directory under the application root:

ClientInstallDir\JSXAPPS\ipc

The following example shows a toolbar and a menu element, with localized language-specific prototypes, taken from the samples in config.xml:

---

---

 

There is an example entry in config.xml for each of the valid parent attribute values. These examples make reference to the sample files that can be found under the installation home directory:

InstallationHomeDir\iprocessclientbrowser\samples\CustomMenus

where InstallationHomeDir is the directory in which the installer places administrative files, such as the uninstaller, documentation, and sample code. This defaults to C:\tibco on Windows systems, and /opt/tibco on UNIX systems, but can be specified as a different directory when the TIBCO iProcess Workspace (Browser) is installed.

The files in the ...\CustomMenus directory show examples of how to use both menu and toolbar prototype XML files and handle the events using a CustomEventHandler class.

The sample custom menus and toolbars can be installed using the steps listed below. These same steps can be used to install actual custom menus and toolbars, substituting the actual custom prototype, JavaScript, and image files and config.xml entries. See the TIBCO® General Interface Builder documentation for details on creating custom menu or toolbar prototype files.

1.	Create a custom directory under the application root:

   ClientInstallDir\JSXAPPS\ipc\custom

Any valid directory name can be used. The “custom” directory name is used in the sample entries shown in config.xml.

2.	Copy all of the files from the following directory:

   InstallationHomeDir\iprocessclientbrowser\samples\CustomMenus

... to your custom directory:

   ClientInstallDir\JSXAPPS\ipc\custom

Note that the custom directory structure, and the examples in config.xml, include samples for localizing the client application in German (locale de_DE). These files provide an example of the structure necessary to provide language-specific support, however, to utilize these localized files, the client application must be configured for German language support (see Localization).

3.	In config.xml, add menu or toolbar elements under the <record jsxid=”customMenus”> element. (Uncomment the samples shown in the description for <record jsxid=”customMenus”>.)

4.	Add a new mapping record in the config.xml file as a child element under <record jsxid=”includes” type=”array”> for CustomEventHandler.js as shown below:

---

---

 

Note - The someId in the jsxid attribute can be any number as long as it’s unique among the mapping records in the config.xml file.

The application should now load with the sample custom menus and toolbars displayed.

Extending User Access Profiles to Control Custom Menus and Toolbar Buttons

This section describes how to extend the user access profiles to control access to custom menus and toolbar buttons.

The sample code in these instructions, utilizes the sample custom menus and toolbar buttons in the samples files that can be found in the following directory:

InstallationHomeDir\iprocessclientbrowser\samples\CustomMenus

Therefore, these instructions assume you have configured custom menus and toolbar buttons as described in Adding Custom Menu Items and Toolbar Buttons (i.e., you’ve copied the sample code to a custom directory in the ClientInstallDir\JSXAPPS\ipc directory).

In this example, two custom menus and two custom toolbar buttons have been added to the main application toolbar by including the following record in the JSXAPPS\ipc\config.xml file:

---

---

 

This causes the following buttons to be displayed on the main application toolbar:

To extend the user access profiles to control these new custom menus and toolbar buttons, follow these steps:

1.	Add properties to the user access profiles that control custom menus and toolbar buttons. The user access profiles are defined in the UserAccessProfiles record in the following file:

        ClientInstallDir\JSXAPPS\ipc\userAccessProfiles.xml

For more information about user access profiles, see User Access.

The following shows the properties added for our example:

---

---

 

The new properties in this example have been added to the profile for “Admin” users. You will need to add them to all profiles to which you want them to apply (Default, General, etc.).

2.	Set the state attribute for each new property to the desired state, where “1”= allow access, and “0” = deny access.

The property state attribute controls access as follows:

−	The “MainAppToolbar” property controls access to the new custom menus and toolbar buttons on the main application toolbar.

−	The “tbbCustomSample1” and “tbbCustomSample2” properties control access to the individual custom toolbar buttons.

−	The “mnuCustom1” and “mnuCustom2” properties control access to the individual custom menus.

−	The “mnuSample1” and “mnuSample2” properties control access to the individual selections on the custom menus.

3.	Edit your custom event handler class (CustomEventHandler.js in the JSXAPPS\ipc\custom\js directory) to include methods for determining whether the logged in user has access to custom menus and toolbars and take action to either remove or disable items for which the user is not authorized.

An example custom event handler is provided that contains a method named “authorizeMenus” for controlling the menus, and a method named “authorizeToolBar” for controlling the toolbar buttons. This example event handler is located in the following directory:

InstallHomeDir\iprocessclientbrowser\samples\CustomMenus\js

4.	Make the necessary changes so that the authorization methods are called when toolbars and menus are deserialized. This can be done in one of two ways:

−	The first way is to add the following lines of code to the XML prototypes for the custom menus and toolbars:

To JSXAPPS\ipc\custom\prototypes\menus\MenuSample.xml, add:

      <onAfterDeserialize><![CDATA[com.xyz.sample.custom.
      CustomEventHandler.singleton.authorizeMenus();]]>
      </onAfterDeserialize>

To JSXAPPS\ipc\custom\prototypes\toolbars\ToolbarSample.xml, add:

      <onAfterDeserialize><![CDATA[com.xyz.sample.custom.
      CustomEventHandler.singleton.authorizeToolBar();]]>
      </onAfterDeserialize>

−	You can also add the method calls to the XML prototypes through GI Builder. To do this, open the prototypes for the custom menus and toolbars in GI Builder, then select ‘Component Profile’. In the Component Profile Editor, enter the following code in the onAfterDeserialization field:

For the custom menus prototype, enter:

com.xyz.sample.custom.CustomEventHandler.singleton.
authorizMenus();

For the custom toolbars prototype, enter:

com.xyz.sample.custom.CustomEventHandler.singleton.
authorizeToolbars();

Your custom menus and toolbar buttons should now react to the access settings in the userAccessProfiles.xml file.

 

Copyright © Cloud Software Group, Inc. All Rights Reserved