Customizing and Creating Application Connector Components

Connector Components and Actions

This chapter includes these topics: • Overview, page 65

• List of Application Connectors components and actions, page 65 • appintgcontroller component, page 68

• Creating new application connector components and actions, page 66

Overview

All Documentum menu selections in the content authoring application are dispatched through the Application Connectors controller component, appintgcontroller. This component launches an action or component via a URL and adds messages and return listeners so that it can return messages, errors or results to the native modal dialog window. If authentication is required, the appintgcontroller component jumps to the appintgcontrollerlogin component.

All Application Connectors components and actions are described inEMC Documentum Web Development Kit and Webtop Reference Guide.

List of Application Connectors components

and actions

All Application Connectors component and action names and configuration files are prepended with the text,appintg.

Application Connectors components are:

• appintgcontroller • appintgcontrollerlogin • appintghelp

Customizing and Creating Application Connector Components and Actions • appintgopen • appintgopenfrom • appintgopenfromcabinetslocator • appintgopenfromcategorieslocator • appintgopenfromlocatorcontainer • appintgopenfrommyfileslocator • appintgopenfromrecentfileslocator • appintgopenfromsubscriptionslocator • appintgsaveascabinets • appintgsaveascategories • appintgsaveascontainer • appintgsaveasmyfiles • appintgsaveasrecentfiles • appintgsaveassubscriptions

Application Connectors actions are:

• appintgnewfromtemplate • appintgopenfrom

• appintgsaveas

Creating new application connector

components and actions

You can create a completely new component or action or extend an existing one. Extending an existing component or action means that the new component or action inherits the existing component or action’s configuration file <component> or <action> element’s child elements.

Note: Hereafter, a <component> or <action> element’s child elements will be called a configuration structure. For example, a <params> configuration structure is:

To create a new Aapplication connector component or action:

1. Copy the configuration file of an application connector component or action that closely resembles your new component or acion to the webtop\custom\config directory. 2. Rename the configuration file to the name of your new component or action.

Customizing and Creating Application Connector Components and Actions

3. To extend an existing component or action, add the extends attribute to the component or action element and specify the relative path to the component or action that you want to extend.

For example, your new component, appintgnewcomponent extends the appintgnewfromtemplate component:

<component id="appintgnewcomponent" extends="appintgnewfromtemplate:webcomponent/ config/library/appintgnewfromtemplate/appintgnewfromtemplate_component.xml"> 4. Specify <component> or <action> configuration structures.

See theEMC Documentum Web Development Kit and Webtop Reference GuideandEMC Documentum Web Development Kit Development Guidefor the specific configuration structures that are available. 5. If you have extended an existing component or action, override or create a new <component> or

<action> configuration structure by specifying the entire configuration structure including any unmodified sibling elements in the parent configuration file.

For example, to override the contentType parameter: <params>

1 If the configuration structure of an element that you want to modify includes sibling elements that you want to inherit, you must specify them as well. In this case, the parameter, existingparam, already exists in the parent configuration file, but because you modified contentType, you must you must also specify the existingparam parameter exactly as it is in the parent configuration file. 6. To remove or add configuration structures or JSP user interface elements based on your

application connector, use the <filter> element.

SeeRestricting menu items to specific applications, page 62.

7. To display the new component’s own success and failure JSP pages, add the new component’s success and failure JSP pages in the appintgcontroller component configuration file.

For example, for the appintgnewmenu menu item, the shownewcomponentpage success page is specifiedbut no failure page is specified, so the default failure page in <pages><failure> is used. <item>

<name>appintgnewmenu</name> <type>action</type>

<successpage>shownewcomponentpage</successpage> </item>

8. Either add a new menu item or modify an existing one that causes the appintgcontroller to execute and display your component.

SeeRestricting menu items to specific applications, page 62andAdding custom menu items to all applications, page 62.

Customizing and Creating Application Connector Components and Actions

appintgcontroller component

The appintgcontroller component consists of the AppIntgController servlet and JavaScript. This component performs these functions:

• Sets the locale, theme, Webtop view, and current repository if they are defined in the component arguments or stored in a cookie. If they are not in the argument list or a cookie, the default values as defined in the appintgcontroller component definition are used.

• Enables login: Checks for connection requirement and, if required, sets a menu version event and forces login. Provides the loginas action that disconnects from all repositories and allows the user to log in with different credentials.

• Dispatches a JSP page or action as specified in the <type> element:

Value of page in <type> element dispatches an event and, if the dispatch item has a <page> element, loads a named JSP page from the component definition in a native modal dialog window. Value of action in <type> element dispatches the action, adds a return listener, and displays the success or failure page after action completion. Adds context arguments to a menu action map that is downloaded to the client.

If the menu item does not have a <dispatchitems> entry, the action or component is dispatched and the default success or failure page is used.

The appintgcontroller dispatches menu items from the menu that is named in the <menugroupid> element of the appintgcontroller component definition. Each action or component that is

defined as a menu item in the menugroup definition (in appintgmenubar_menugroup.xml) can have a corresponding entry of type "action in the appintgcontroller component definition. This allows you to configure a specific success or failure page for the action. For example, for the appintgnewfromtemplate menu item, there is an item in the controller definition (in apptgcontroller_component.xml) that specifies a success page:

<dispatchitems> <item> <name>appintgnewfromtemplate</name> <type>action</type> <successpage>opendocumentevent</successpage> </item> </dispatchitems>

Table 2, page 68describes the configuration elements for dispatching actions or components.

Table 2. Appintgcontroller <dispatchitems> elements

Element Description

<item> Contains one of each: <name>, <type>, and either <page> or <successpage>

.<name> Contains the name of a menu action, if the type

is action. Contains the name of an event, if the type is page.

.<type> Specifies the type of menu item to dispatch:

Customizing and Creating Application Connector Components and Actions

Element Description

.<page> Specifies a named child element of <pages>, to launch a page

.<successpage> Optional. Specifies a named child element of <pages>, to launch a success page after action completes. If this element is not present, the default success page in <pages><success> is used.

.<failurepage> Optional. Specifies a named child element of <pages>, to launch a failure page after action fails. If this element is not present, the default success page in <pages><success> is used.

When the user selects a menu item, the appintgcontroller builds a URL, and the requested page loads in a modal dialog window that hosts a browser control within your application. If the menu item maps to an action, the WDK action dispatcher performs the action and returns the success or failure JSP page to the modal dialog window. If the menu item maps to a component, the WDK component dispatcher returns the component JSP start page to the modal dialog window.

Each JSP page that is named for a dispatch item must be defined in the apptgcontroller component definition. For example, the appintgopendocumentevent item specifies a value of opendocumentevent for the <successpage> element. The element <pages>.<opendocumentevent> defines this page and has a value of /webcomponent/library/appintgcontroller/appIntgOpenDocumentEvent.jsp, which specifies the path to the page to be loaded.

The following default pages are defined within the <pages> element of the component definition. If an item does not specify a success or failure page, then the default page is used:

Table 3. Required pages in appintgcontroller component definition

Element Description

<start> Specifies the path to an error handler page

that is loaded if the action or component is not dispatched

<disconnect> Specifies the path to a page that is used to disconnect existing sessions and return to the controller for new login. This page invalidates the HTTP session.

<success> Specifies the path to the default success page that is loaded after the action completes successfully <failure> Specifies the path to the default faliure page that

Customizing and Creating Application Connector Components and Actions

Client environment qualifier in the WDK

application

The clientenv qualifier is introduced to enable component configuration based on the client environment. This qualifier matches the context value "webbrowser or "appintg to the context "clientenv.

The client environment context is established in one of the following ways:

• Specify clientenv in a URL request parameter, preferably in the first URL request that invokes a WDK-based application. This method takes precedence over the value in app.xml (the second option). For example:

http://webtop/component/main?clientenv=webbrowser

• Specify the default clientenv value in your custom app.xml as the value of

<application>.<environment>.<clientenv>. Valid values: webbrowser | appintg | not appintg The client environment is stored as a session cookie so that WDK can restore the context for a given client session when the server times out.

The clientenv qualifier can be used as a filter in component definitions to specify a different set of JSP pages depending on the environment. For example, the changepassword component definition uses the value of appintg and not appintg to present different pages depending on whether the user is in an Application Connectors environment. The filter is applied as follows:

<pages>

<start>/wdk/system/changepassword/changepassword.jsp</start> </filter> <filter clientenv="appintg"> <start>/wdk/system/changepassword/appintgchangepassword.jsp</start> </filter> </pages>

A more granular environment configuration can be applied within a JSP page itself using the clientenvpanel control. This control is used to show or hide UI elements based on the runtime clientenv context. The client environment is specified as the value of the environment attribute. For example, the checkin component JSP page has a clientenvpanel control that is rendered only in the AppConnectors environment:

<dmfx:clientenvpanel environment="appintg"> <dmf:fireclientevent event="aiEvent"

includeargname="true">

<dmf:argument name="event" value="ShowDialog"/> ...

</dmf:fireclientevent> </dmfx:clientenvpanel>

The reversevisible attribute on the clientenvpanel control toggles the display. In the same example above (checkin.jsp), another panel is hidden in the AppConnectors environment:

<dmfx:clientenvpanel environment="appintg" reversevisible="true"> ... <dmf:checkbox name="checkinfromfile" id="checkinfromfile" nlsid="MSG_CHECKIN_FROM_FILE" onclick="onCheckinFromFileClick" runatclient="true"/> ... </dmfx:clientenvpanel>

Customizing and Creating Application Connector Components and Actions

JSP fragments can also be defined, so that a component JSP page includes fragments that are dispatched based on the client environment.

To trace problems in the client environment, turn on the tracing flag CLIENTENV.

Sample

Introduction

This sample demonstrates adding a Documentum menu item, Delete, in your application. The Delete menu item calls the standard Webtop delete action.

Procedure

1. On the Webtop application server machine, copy the \webcomponent\config/

library\appintgmenubar\appintgmenubar_menugroup.xml file to the Webtop custom\config directory.

2. In the Webtop custom\config\appintgmenubar_menugroup.xml, extend the original file by using the extends attribute on the <menugroup> element:

<menugroup id="appintgmenubar" version="latest" extends="appintgmenubar:/ webcomponent/config/library/appintgmenubar/appintgmenubar_menugroup.xml"> 3. Add this <actionmenuitem> element after the save_as <actionmenuitem> in the

appintgmenubar_menugroup.xml file: <actionmenuitem> <aidynamic>repository_content</aidynamic> <name>delete_menu</name> <value>Delete...</value> <action>delete</action> <arguments>

</arguments> </actionmenuitem>

4. Save the appintgmenubar_menugroup.xml file.

5. Copy the webtop\config\appintgcontroller_component.xml file to the Webtop custom/config directory

6. In the Webtop custom\config\appintgcontroller_component.xml, extend the original file by using the extends attribute on the <component> element:

Customizing and Creating Application Connector Components and Actions

7. In the Webtop custom\config\appintgcontroller_component.xml file after the <pages><appintgmenumap> element, add this code:

<deletesuccess>/webcomponent/library/appintgcontroller/ deleteSuccess.jsp</deletesuccess>

and after the checkin <item> element, add this code:  <item> <name>delete</name> <type>action</type> <successpage>deletesuccess</successpage> </item>

8. In the Webtop custom/config directory, create a file named deleteSuccess.jsp that contains this JSP code:

<%@ page contentType="text/html; charset=UTF-8" %> <%@ page errorPage="/wdk/errorhandler.jsp" %>

<%@ page import="com.documentum.webcomponent.library.appintgcontroller. AppIntgController"%>

<%@ taglib uri="/WEB-INF/tlds/dmform_1_0.tld" prefix="dmf" %> <%@ taglib uri="/WEB-INF/tlds/dmformext_1_0.tld" prefix="dmfx" %> <dmf:html>

<dmf:head>

<!---> <dmf:webform/>

<dmf:fireclientevent event=’aiEvent’ includeargname=’true’> <dmf:argument name=’event’ value=’HideDialog’/>

</dmf:fireclientevent>

<dmf:fireclientevent event=’aiEvent’ includeargname=’true’> <dmf:argument name=’event’ value=’DeleteSuccess’/> <dmfx:argument name=’message’ contextvalue=’

<%=AppIntgController.MESSAGE%>’/> </dmf:fireclientevent> </dmf:head> <dmf:body> <dmf:form> </dmf:form> </dmf:body> </dmf:html>

9. In your application connector’s app.config file as a child of <actionSettings>, add this code:

Note: You must generate your own public key tokens for MyCompany.AppConnector. TextEditorAppIntg.CustomNotificationHandler and MyCompany.AppConnector.MyAppIntg. MyAppAppIntegrationProvider and specify them for each one’s PublicKeyToken attribute.

<actionInfo name="customhandler"

Customizing and Creating Application Connector Components and Actions

MyCompany.AppConnector.TextEditorAppIntg, Version=1.0.0.0,

Culture=neutral,

PublicKeyToken=CustomNotificationHandlerPublicKeyToken" /> and after the <actionSettings> element code, add this code:

10. In your application connector project, implement a CustomNotificationHandler that inherits from ActionProviderBase by creating this code in a CustomNotificationHandler.cs file:

using System; using log4net; using Documentum.AppConnector.Logging; using Documentum.AppConnector.Application; namespace MyCompany.AppConnector.TextEditorAppIntg {

public class CustomNotificationHandler : ActionProviderBase {

private const string DELETE_SUCCESS = "DeleteSuccess"; private static readonly ILog logger =

Log.GetLogger(typeof(WdkComponentNotificationHandler)); TextEditorAppIntegrationProvider provider = null;

public CustomNotificationHandler(){}

public override void HandleWdkEvent(string args) { logger.Info("Within CustomNotificationHandler::HandleWdkEvent..."); string eventName = actionParent.GetArgumentValue(args, ApplicationConstants.EVENT); if (base.actionParent is TextEditorAppIntegrationProvider) {

provider = (TextEditorAppIntegrationProvider) base.actionParent; } switch (eventName) { case DELETE_SUCCESS: if (provider != null) { string message = actionParent.GetArgumentValue(args, ApplicationConstants.MESSAGE); provider.HandleMyCustomEvent(eventName, message);

Customizing and Creating Application Connector Components and Actions } break; default: break; } } } }

Chapter 8

In document EMC Documentum Application Connectors Software Development Kit (Page 65-75)