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
Tested on
Operating System Windows 2000 Professional SP3
Compiler Sun JDK 1.4.1_02
Runtime Environment Sun JRE 1.4.1_02
Web Browser Microsoft Internet Explorer 6.0 SP1
Application Server Apache Tomcat/4.0.6
WDK version 5.2
Webtop version 5.2
WebPublisher Not tested
DAM Not Tested
EContent Server 5.2
DFC 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 Explanation
dynamic='genericnoselect' This menu item will be displayed only if no files or folders
have been selected.
name='hello_world_menu_item' This is the name of the menu item; in this example we will
not need to use this value.
value='Hello World' This is the text of the menu item. (It should really be held in a
language specific resource string.)
action='hello_world_action' 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.
showifinvalid='true' 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 Description
<action id="hello_world_action"> This is the name of the action, it must be unique. It
must match the value of the 'name' field specified in the
Developer Program
Component Exchange 4/8
 menubar.jsp file.
execution You can call any class from the action including your
class="com…..LaunchComponent"> own custom classes. In our example we are going to
use one of the built-in WDK classes to launch our
component.
<component> This is the name of the component we are going to
hello_world_component launch. It needs to match the component name in the
</component> component XML file that we will be creating in the next
step.
<container> This tag is optional for our hello_world example, it
dialogcontainer instructs WebTop to display the output from the
</container> component wrapped in a container that adds OK,
Cancel and Help buttons and a pretty blue border.

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 Description
<component This is the name of the component, it must be unique. It
id="hello_world_component"> must match the name specified in the
hello_world_action.xml file's <component/> tag.
<pages>
This defines the jsp file to be used by the component.
<start>..hello_world.jsp</start>
</pages>
<class>
This defines the class file to be used by the component.
com.documentum.custom.library.Du
mmyComponent
</class>

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.

3
Note: This customization will only appear in the Classic view, not in the Streamline view
Developer Program
Component Exchange 8/8