Extending Module Tray Options

Use

Each module has a tray menu from which the user can access options such as editing module settings or deleting the module. You can extend this menu by adding custom options.

An option in the module tray can represent either a module view or an action.

In addition to its default view, a module can have other views. For example, if your module requires initial configuration before it can be used, you need to display its configuration view when the module is accessed for the first time, and then revert to the default view, once the configuration is completed. You also need to enable the user to access the configuration view from the tray menu, when needed.

An action option represents an action to perform on the client side, such as navigating to a URL.

Defining Additional Module View Options

The server-side Module API enables you to define module view options, select one of the options as initial, and remove the Settings option from the tray menu. You can do this by extending the AbstractModuleViewOptions class that is contained in the com.sap.workspaces.module.extension package. The related ViewOption class, found in the same package, represents a module view option in the module tray menu, and defines the parameters of the view such as its type, URL, and display settings.

For details, see the following sample implementation:

public class ModuleViewOptions extends AbstractModuleViewOptions implements IService {

	// Define additional module view options
	public ViewOption[] getViewOptions(IModuleContext moduleContext) {
		//iView
		ViewInfo iViewInfo = new ViewInfo( "pcd:portal_content/iview_id", ViewType.IVIEW );

		// Portal component with parameters 
		ViewInfo componentInfo = 
			new ViewInfo( "tc~hm.spaces~someapplication.someportalcomponent?param1=value1&param2=value2", ViewType.PORTAL_COMPONENT );

		// External URL
		ViewInfo URLViewInfo = new ViewInfo( "help.sap.com", ViewType.URL );


		ViewOption optionIview = new ViewOption( "iView in place"
				, LaunchMode.IN_PLACE, iViewInfo, 1 );

		ViewOption optionPortalComp = new ViewOption( "Portal component with parameters in new window"
				, LaunchMode.NEW_WINDOW, componentInfo, 2);

		ViewOption optionExternalURL = new ViewOption( "External URL in new window"
				, LaunchMode.NEW_WINDOW, URLViewInfo, 3);


		return new ViewOption[]{optionIview, optionPortalComp, optionExternalURL};
	}	
	// Select the initial module view, which is not necessarily one of the defined options 
 	public ViewInfo getInitialView(IModuleContext moduleContext) {
 		return new ViewInfo( "pcd:portal_content/iview_id", ViewType.IVIEW );
 	}

 	// Indicate that the Settings option cannot be removed
	public boolean removeOptionSettings(IModuleContext moduleContext) {
		return false;
	}
}

Centrally Managing Module Options

Additionally, you can centrally manage the view options of all modules by implementing a service that is called by the page builder when each module is loaded. In this service, you can modify the previously defined list of view options by adding or removing options or changing their order. You can do this by extending the AbstractControlModuleMenu class in the com.sap.workspaces.workspace package.

The following example illustrates how to add an option that opens module-specific help.

// Adds an option that opens module-specific help
public ViewOption[] getViewOptions(IModuleID moduleID,	ViewOption[] originalViewOptions, IUser user, Locale locale) 
{				
	//Locate module-specific help
	String helpURL = "http://mycompany.help.com?topic=" + moduleID.getTemplateID();

	//The option is available for workspace managers and members	
	RoleAvailability roleAvailability = RoleAvailability.FOR_MANAGER_MEMBER;	

	ViewOption newOption = new ViewOption("Help", LaunchMode.NEW_WINDOW, new ViewInfo(helpURL,ViewType.URL), 30, roleAvailability);

	return new ViewOption[]{originalViewOptions[0], originalViewOptions[1], originalViewOptions[2], newOption};

	}

After deployment, configure this service as follows:

Navigate to Workspace Administration Configuration Features .
In the Control Module Menus (Service) field, enter prt_service:<your service key>.

Resetting Initial Module View

After the initial view is no longer needed, you can reset the module to its default view by calling the client-side API, as follows:

	function resetModuleView(moduleID)
 		{
 		// Get the the SAP top window.
		var topSAPWindow = EPCM.getSAPTop(); 
 		var data = {ivuId:moduleID};
 		// Raise the event that resets the module
 		topSAPWindow.EPCM.raiseEvent( 'urn:com.sap.portal.ajaxpagebuilder', 'iviewReset', data );
 		}

Creating Custom Tray Options

The client-side API enables you to create and add custom tray options, which can be either module views or actions.

	function addTrayOptions() {
 		// Get module ID
 		var iFrameID = window.frameElement.id;
 		// Get Tray Options manager
 		var trayOptionsManager = EPCM.getSAPTop().TrayOptions;

 		// Define a new tray option that performs an action
 		var trayOptionAction = trayOptionsManager.createAction(actionTitle, position1, iFrameID, actionMethod);

		// Define a new tray option that opens a view; this option is added to the view options created on the server side
 		var trayOptionView =  trayOptionsManager.createView( optionTitle, position2, iFrameID, "pcd:portal_content/someiViewID", openInNewWindow );
 		var arr = [ trayOptionAction, trayOptionView ];

 		trayOptionsManager.addOptions( arr ); 
 	}	

 	function actionMethod(eventObj) {
 		alert ("Action performed");
 	}

For the complete API reference, see Client-Side Tray Options API.