Documentum Developer Program Component Exchange

WDK 5.2 Component

Writing your first WDK Component, a.k.a. Hello WDK World

Updated December, 2003

Developer Program Component Exchange

1/8

Overview
Writing your first WDK component? Like most developers you probably just want to jump in and start coding without reading associated developer documentation1. Obviously, we would never do this ourselves right! This paper will walk you through the process of adding a new component to WebTop; the component will be invoked from a menu item. The paper covers the steps involved in adding the menu item, the associated action and the actual component. The component will simply display 'Hello World' in the WebTop main frame.

Revisions
December 2003 Added instructions for adding the XML config file for the custom menubar component.

References
The following are all great references for use when building your own WDK components. Overview of the Development and Customization Options, WDK node http://www.documentum.com/developer/Roadmap5/index.htm Web Development Kit Development Guide Web Development Kit and Applications Tutorial http://support.documentum.com/support/documentation/dmDocList.asp

Customization Type
Documentum WDK 5.2 Component

Programming Language
Java

Software Environment
Operating System Compiler Runtime Environment Web Browser Application Server WDK version Webtop version WebPublisher DAM EContent Server DFC Tested on Windows 2000 Professional SP3 Sun JDK 1.4.1_02 Sun JRE 1.4.1_02 Microsoft Internet Explorer 6.0 SP1 Apache Tomcat/4.0.6 5.2 5.2 Not tested Not Tested 5.2 5.2.0.55

Dependencies on other third party components or libraries

None
1

Visit Tech Support's documentation section and search for WDK documents to find the development guides and JavaDocs.

Developer Program Component Exchange

2/8

Process Overview
The steps involved in adding a component are shown below. The paper will look at each of the steps in detail and point out the 'hooks' between each step in the process.

Steps
Add the menu item to the WebTop menu bar

Invoke the WDK action

Invoke the WDK component and its accompanying class

Test the Component

Technical Note
Development of this sample was done using Apache Tomcat 4, the paper refers to <VIRTUAL_ROOT>; this is typically C:\Program Files\Apache Tomcat 4.0\webapps\webtop\.

Add the menu item to the WebTop menu bar

The first step in the process is to add a new menu item to trigger the displaying of the component. Open the custom menu bar component jsp file <VIRTUAL_ROOT>\custom\menubar\menubar.jsp. In our example we will be adding a menu item called 'Hello World'. Menu items invoke WDK actions, our action will be called hello_world_action. Add the 2 lines in bold to the file just below the 'file_delete' menu entry as shown.
<dmfx:actionmenuitem dynamic='multiselect' name='file_delete' nlsid='MSG_DELETE' action='delete' showifinvalid='true'/> // Developer Program Hello World Example <dmfx:actionmenuitem dynamic='genericnoselect' name='hello_world_menu_item' value='Hello World' action='hello_world_action' showifinvalid='true'/>

In this paper we are not going to explore all of the options available to you when defining a menu item, we will however take a look at the options we have selected.
Value dynamic='genericnoselect' name='hello_world_menu_item' value='Hello World' action='hello_world_action' showifinvalid='true'

Explanation This menu item will be displayed only if no files or folders have been selected. This is the name of the menu item; in this example we will not need to use this value. This is the text of the menu item. (It should really be held in a language specific resource string.) This is the name of the action that will be invoked. It must match the name field of the action created in the next step. This specified whether the menu item should appear grayed out in the menu or be hidden when it is not valid.

Developer Program Component Exchange

3/8

Next, we need to tell the WDK framework that we are using a custom menubar component. We do this by adding an XML file to <VIRTUAL_ROOT>\custom\config that tells the framework where to look for the custom menubar. Create a file called menubar_component.xml in <VIRTUAL_ROOT>\custom\config. Add the following text to it:
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> <config version='1.0'> <scope> <component id="menubar" extends='menubar:/webtop/config/menubar_component.xml'>

<pages> <start>/custom/menubar/menubar.jsp</start> </pages>

</component> </scope> </config>

Now we have a new menu item in the WebTop 'classic view' file menu. If you restart Tomcat and WebTop you should see the menu item. Note that the menu item is grayed out even though we specified that it should always be active, this is because WebTop was unable to resolve the reference to the action.

Invoke the WDK action

The next step in the process is to add a WDK action. The action is defined by an XML file placed in the <VIRTUAL_ROOT>\custom\config folder; our file is called hello_world_action.xml. Note that the file name is not significant however it is nice to use the word 'action' in the file name as this folder also contains other XML files. (The WDK framework loads all of the XML files in the \webtop\custom\config folder and matches the menu item's action tag to the action's action id tag.) Here is the file we will be creating; copy and paste the text into a file called hello_world_action.xml and place it in <VIRTUAL_ROOT>\custom\config\.
<config version='1.0'> <scope> <action id="hello_world_action"> <execution class="com.documentum.web.formext.action.LaunchComponent"> <component>hello_world_component</component> <container>dialogcontainer</container> </execution> </action> </scope> </config>

Let's take a quick look at the important parts of the file. Value
<action id="hello_world_action">

Description This is the name of the action, it must be unique. It must match the value of the 'name' field specified in the 4/8

Developer Program Component Exchange

menubar.jsp file.
execution class="com..LaunchComponent">

You can call any class from the action including your own custom classes. In our example we are going to use one of the built-in WDK classes to launch our component. This is the name of the component we are going to launch. It needs to match the component name in the component XML file that we will be creating in the next step. This tag is optional for our hello_world example, it instructs WebTop to display the output from the component wrapped in a container that adds OK, Cancel and Help buttons and a pretty blue border.

<component> hello_world_component </component>

<container> dialogcontainer </container>

The next step in the process is to define the actual component to be displayed.

Developer Program Component Exchange

5/8

Invoke the WDK component and its accompanying class

A WDK component is made up of 2 parts; a JSP page and a class file. The JSP file should contain the UI elements and the class file should contain the methods to be used by the JSP file. A component is defined by an XML file placed in the <VIRTUAL_ROOT>\custom\config folder; our file is called hello_world_component.xml. Again, the file name is not significant but it is good to include 'component' in the name for clarity. Copy the following text into a file and save it to the config folder.
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> <config version='1.0'> <scope> <!-- the following tag defines the id of the component --> <component id="hello_world_component"> <pages> <start>/custom/hello_world/hello_world.jsp</start> </pages>

<class>com.documentum.custom.library.DummyComponent</class> </component> </scope> </config>

Let's take a look at the important parts of this file. Value

<component id="hello_world_component"> <pages> <start>..hello_world.jsp</start> </pages> <class> com.documentum.custom.library.Du mmyComponent </class>

Description This is the name of the component, it must be unique. It must match the name specified in the hello_world_action.xml file's <component/> tag. This defines the jsp file to be used by the component. This defines the class file to be used by the component.

The last part of the process is to create the JSP and class files that actually make up the component. We will focus on the JSP file first and then the class file.

Developer Program Component Exchange

6/8

Creating the JSP File

In our example, the output JSP file will be displayed in the WebTop window. We have elected to make the JSP file extremely simple. It will contain the following text;
<%@page contentType="text/html"%> <%@ page errorPage="/wdk/errorhandler.jsp" %> <%@ taglib uri="/WEB-INF/tlds/dmform_1_0.tld" prefix="dmf" %> <%@ taglib uri="/WEB-INF/tlds/dmformext_1_0.tld" prefix="dmfx" %> <html> <head> <dmf:webform /> </head> <body> <dmf:form> <font color="darkred"><b>Hello World</b></font> </dmf:form> </body> </html>

Create a folder called hello_world in your <VIRTUAL_ROOT>\custom\ folder, copy this text into a file called hello_world.jsp and save the file to your new folder. Don't worry about all of the page, taglib and dmf references just know that the WDK framework requires all of these to be able to handle the JSP file as a component. Our worthy addition to the code is the beautifully formatted 'Hello World' line.

Creating the class file

Each component needs a class file2 to contain its associated methods. In our example we are not calling any methods so we are going to create a simple dummy class file. It will contain the following code;
package com.documentum.custom.library; import com.documentum.web.common.ArgumentList; import com.documentum.web.formext.component.Component; public class DummyComponent extends Component { public void onInit(ArgumentList arg) { super.onInit(arg); } }

This is the bare minimum code required in a component's class file. It overrides the component onInit() method and then does nothing except call the original onInit() method. Copy this code into DummyComponent.java and compile it. Copy the resultant class file into <VIRTUAL_ROOT>\WEB-INF\classes\com\documentum\custom\library.
2

Yes we know it is technically possible to create a component from only a JSP file but it is not recommended.

Developer Program Component Exchange

7/8

Test the Component

Now that all of the parts are in place the component should be displayed once you select the option from the file menu3. Stop restart Tomcat and then start WebTop. Click on the file menu and select 'Hello World' and your component should be displayed in the main fame.

It's a beautiful thing!

Bug Submissions
If you find bugs or issues with the component, please contact developer_program@documentum.com with a short description of the issue, steps to reproduce it and the relevant software environment.

Note: This customization will only appear in the Classic view, not in the Streamline view

Developer Program Component Exchange

8/8