Beruflich Dokumente
Kultur Dokumente
Component Exchange
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.
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
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\.
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:
<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.
<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>
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.
<pages>
<start>/custom/hello_world/hello_world.jsp</start>
</pages>
<class>com.documentum.custom.library.DummyComponent</class>
</component>
</scope>
</config>
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>
</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.
package com.documentum.custom.library;
import com.documentum.web.common.ArgumentList;
import com.documentum.web.formext.component.Component;
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.
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