wdk 6.5 tutorial

EMC® Documentum®

Web Development KitVersion 6.5

TutorialP/N 300007232 A01

EMC CorporationCorporate Headquarters:

Hopkinton, MA 01748‑91031‑508‑435‑1000www.EMC.com

Copyright © 2005 ‑ 2008 EMC Corporation. All rights reserved.

Published July 2008

EMC believes the information in this publication is accurate as of its publication date. The information is subject to changewithout notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONSOR WARRANTIES OF ANY KINDWITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLYDISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.

For the most up‑to‑date listing of EMC product names, see EMC Corporation Trademarks on EMC.com.

All other trademarks used herein are the property of their respective owners.

Table of Contents

Preface ................................................................................................................................. 9

Chapter 1 Tutorial Preparation and Basics .................................................................. 11Typographical Conventions Used in the Tutorials ............................................... 11Setting Up the Environment for the WDK Tutorials ............................................ 12Tutorial Basics .................................................................................................. 12Clearing Caches and Refreshing .................................................................... 12Overview of the Custom Layer ...................................................................... 13Custom Layer Definition Inheritances and Overrides .................................. 14

Setting Up an IDE............................................................................................. 15Creating a Project in NetBeans....................................................................... 15Mounting the WDK Directories ................................................................. 15Mounting the DFC JAR Files ..................................................................... 15

Stopping the Internal Tomcat Server .............................................................. 16

Chapter 2 Configuring the Webtop Menubar ............................................................... 17Finding the files................................................................................................ 17Adding a command to a menu .......................................................................... 17Removing a command from a menu .................................................................. 21Rearranging commands in a menu..................................................................... 22Replacing a command in a menu ....................................................................... 24Removing an entire menu ................................................................................. 25When the application behaves in an unexpected manner..................................... 27Small changes, big impact ................................................................................. 27

Chapter 3 Configuring Columns in a Webtop List Control ........................................... 29Areas of personal confusion .............................................................................. 29Finding the Files ............................................................................................... 30Adding a column.............................................................................................. 31Removing a column.......................................................................................... 32Rearranging Columns ....................................................................................... 33

Chapter 4 Hello Webtop ............................................................................................... 35Step 1 — Configuring the MenuBar ................................................................... 35Step 2 — Configuring the Hello World Action .................................................... 36Step 3 — Configuring the Hello World Component............................................. 38Step 4 — Creating the Hello World JSP............................................................... 39Step 5 — Adding Static Controls to the JSP......................................................... 41Step 6 — Adding Dynamic Controls to the JSP ................................................... 47Step 7 — Adding Databound Controls to the JSP ................................................ 51

EMC Documentum Web Development Kit Version 6.5 Tutorial 3

Table of Contents

Step 8 — Linking to a Second JSP....................................................................... 59

Chapter 5 Creating a Start Page for a New WDK Application ....................................... 69Variations on This Tutorial ................................................................................ 71

Chapter 6 Adding a Logout Link .................................................................................. 73Task Objective .................................................................................................. 73Technical Overview .......................................................................................... 74Creating the Custom Layer Files ........................................................................ 75Extending the Drilldown Component ................................................................ 76Modifying the Generic Actions XML File ........................................................... 76Creating a Custom Resource File ....................................................................... 77Testing the Logout Link .................................................................................... 78Extending the Logout Action............................................................................. 78Variations on This Tutorial ................................................................................ 79

Chapter 7 Creating an Action List Component ............................................................ 81Task Objective .................................................................................................. 81Technical Overview .......................................................................................... 83Creating the Component Definition ................................................................... 83Creating the Component Layout........................................................................ 84Creating the Component Class .......................................................................... 86Supporting Navigation Between Pages............................................................... 87Creating the Action List Datagrid ...................................................................... 88Creating the Action Info Datagrid...................................................................... 91Creating the Resource Bundle............................................................................ 95Testing the Customization................................................................................. 96Variations on This Tutorial ................................................................................ 96

Chapter 8 Creating a Content Transfer Listener .......................................................... 99Task Objective .................................................................................................. 99Technical Overview ........................................................................................ 100Creating the Component Definition ................................................................. 100Creating the Component Layout...................................................................... 100Creating the Component Class ........................................................................ 101Creating the Resource Bundle.......................................................................... 103Testing the Customization............................................................................... 104Variations on This Tutorial .............................................................................. 104

Chapter 9 Limiting Import Types ................................................................................ 109Task Objective ................................................................................................ 109Technical Overview ........................................................................................ 110Creating the Component Definition ................................................................. 110Creating the Component Layout...................................................................... 111Creating the Component Class ........................................................................ 111Creating the Resource Bundle.......................................................................... 113

4 EMC Documentum Web Development Kit Version 6.5 Tutorial

Table of Contents

Testing the Customization............................................................................... 114Variations on This Tutorial .............................................................................. 116

Chapter 10 Using Tracing and Logging in a Component ............................................. 117Task Objective ................................................................................................ 117Technical Overview ........................................................................................ 118Creating the Tracing Class............................................................................... 118Adding Tracing to the Component Class .......................................................... 119Adding Custom Tracing to the List .................................................................. 120Turning on Tracing ......................................................................................... 120Testing the Customization............................................................................... 121Examining the Trace Log................................................................................. 121Variations on This Tutorial .............................................................................. 122

Chapter 11 Customizing UCF Export ........................................................................... 123Task Objective ................................................................................................ 124Technical Overview ........................................................................................ 124Creating the Component Definition ................................................................. 125Creating the Component Layout...................................................................... 125Creating the Component Class ........................................................................ 125Creating the Resource Bundle.......................................................................... 127Testing the Customization............................................................................... 128Variations on This Tutorial .............................................................................. 128

Chapter 12 Troubleshooting ........................................................................................ 129Did you precompile your Java class? ................................................................ 129Did you refresh the Configuration Service? ...................................................... 129Did you remove generated files?...................................................................... 130Did you clear the browser cache?..................................................................... 130Did you check the name and location of the XML resource file? ......................... 130


Table of Contents

List of Figures

Figure 1. Custom Directory Contents after Installation .......................................................... 13Figure 2. Fragment of /webtop/config/menubar_component.xml as shipped .......................... 17Figure 3. File menu before modification. .............................................................................. 18Figure 4. File menu with Rename command......................................................................... 19Figure 5. File menu with Cancel Checkout command removed.............................................. 22Figure 6. File menu with Cancel Checkout command moved before Delete command............. 23Figure 7. Webtop menubar with the View menu removed ..................................................... 26Figure 8. My Files page with Title column displayed ............................................................ 32Figure 9. My Files page with Name column hidden .............................................................. 33Figure 10. Rearranging columns by moving column elements ................................................. 33Figure 11. Size column moved in front of the Version column ................................................. 34Figure 12. Tools menu with inserted Hello World command ................................................... 37Figure 13. Post‑Login Drilldown Page ................................................................................... 71Figure 14. Drilldown Page with Logout Link.......................................................................... 74Figure 15. Action List Page ................................................................................................... 82Figure 16. Action Info Page ................................................................................................... 82Figure 17. Testlistener Console Output ................................................................................ 104Figure 18. New Menu Item Calls the Listener Component .................................................... 106Figure 19. TestListener Console Output, Enhanced ............................................................... 107Figure 20. Restricted file types in Webtop Import UI............................................................. 115Figure 21. Statements in standard output log ....................................................................... 115Figure 22. Tracing JSP Page ................................................................................................. 121Figure 23. Tracing Output ................................................................................................... 122Figure 24. JavaScript Tracing............................................................................................... 122Figure 25. Export Location Dialog ....................................................................................... 123


Table of Contents

List of Tables

Table 1. Directory Structure of the Custom Layer ................................................................ 13Table 2. Highlights from hello_world_action.xml ................................................................ 36Table 3. Highlights from hello_world_component.xml ........................................................ 38Table 4. Highlights from hello_world.jsp ............................................................................ 42


Table of Contents


Preface

The EMC|Documentum Web Development Kit (WDK) is a huge, daunting, powerful, intimidating(etc.) development platform. It can be hard to figure out where to get started. That’s where this guidecomes in. The purpose of this manual is to give smart, capable programmers (like you) insight into thedesign decisions and practical use of WDK so that you can move on to solving your own businessproblems.

This manual covers two types of task:• Configuration

Changes to XML files or modifications to JavaServer Pages to configure controls on the page.Configuration does not require a developer license.

• Customization

Extending WDK classes or modifying JSPs to add new functionality. Customization requiresa developer license.

To configure WDK‑based applications, you should be familiar with the following technologies:• JavaServer Pages technology, including tag libraries, in the version supported by your application

server• Cascading style sheets (CSS)• HTML, particularly forms, tables, and framesets• JavaScript, including client events and event handling, frame referencing, and form actionmethods• XMLTo customize WDK‑based applications, you should be familiar with the above‑mentioned technologiesin addition to the following additional languages and standards.• Java 1.4.x• J2EE Java Servlet technology, in the version supported by your application server• Portlet Specification (JSR 168) (WDK for Portlets only)

Revision HistoryThe following changes have been made to this document:


Preface

Revision History

Revision Date Description

July 2008 Initial release.


Chapter 1Tutorial Preparation and Basics

This chapter contains information that will help you complete the tutorials in the chapters that follow:The chapter contains the following sections:• Typographical Conventions Used in the Tutorials, page 11• Setting Up the Environment for the WDK Tutorials, page 12• Tutorial Basics, page 12

Typographical Conventions Used in theTutorialsThis guide uses italics for replaceable parts of a path or URL. For example:http://server_name:port_number/virtual_dir/wdk/samples/dumpRequest.jsp

In the above URL, server_name should be replaced with the host name, the port_number should bereplaced with the port number defined for your application server (the default port number for aTomcat application server is 8080), and virtual_dir should be replaced with the virtual directory thatwas created during installation of WDK or a WDK application. If you are accessing the applicationthrough a browser running on the server machine, substitute localhost for server_name.

A note on the use of quotation marks: XML allows the use of double quotes (“) and single quotes(’)interchangeably. Generally, it doesn’t matter which you use, unless you are nesting quotes withinquotes (in which case they simply need to match). In this exercise, double quotes are used for newentries, unless single quotes are required. The use of quotation marks in existing files is largely up tothe whim of the original developer, and is not significant.


Tutorial Preparation and Basics

Setting Up the Environment for the WDKTutorialsThe procedures in this guide are based on the following environment:• Sun Java JDK 1.5 available from http://java.sun.com/• Tomcat 5.5.20, available from http://jakarta.apache.org/tomcat/

Note: The tutorial procedures are based on the Tomcat J2EE application server, selected because itis freely available for download. You can use any application server that is certified for WDK.

• WDK 6

See the WDK release notes for hardware requirements and software certifications. See theWebDevelopment Kit and Applications Deployment Guidefor information on installing WDK and verifyingyour installation on an application server.

• (Optional) Webtop or another WDK client application, with WDK installed to customize thatapplication (SeeWeb Development Kit and Applications Deployment Guide for the procedure oninstalling WDK to customize a WDK client application.)

• A Java IDE

Note: You can use any J2EE‑compliant IDE to compile the Java code for the customization tasks.

Tutorial BasicsThe following sections provide some basic information that will help you with the tutorials.

Clearing Caches and Refreshing

If you add or change XML resource files, you should refresh the configuration service. Aneasy way to do this is to open a browser, log into the WDK application, and navigate tohttp://server_name:port_number/virtual_dir/wdk/refresh.jsp. (You must have a session before refreshingthe configuration definitions in memory.)

If you add a new JSP file, the page will be compiled automatically by the applicationserver. If you change a JSP file that contains server‑side generated content or included JSPfiles, or if you modify any JavaScript function, you should clear the java and class files bydeleting the folder tomcat_home/work/Standalone/localhost/virtual_dir or navigating withinthe folder to the files themselves and deleting them. Repeat the process if necessary fortomcat_home/work/catalina/localhost/virtual_dir.

If you change a .properties file containing an externalized string that appears in your JSP or Java class,you must restart the application server to pick up the change.


http://java.sun.com/j2se/1.3/

http://jakarta.apache.org/tomcat/


If you are working with the data dictionary and you make a change to a custom type, you can clearthe data dictionary cache to see your changes. You must wait until the dictionary change has beenpublished to the Content Server, which is usually done by a job running at regular intervals on theServer.

If you have access to the application server, you can delete the data dictionary files yourself, forcingthe system to redeploy them. The files are located in the directory app_server_root/documentum/cache.

If you add or customize a Java file, you need to compile it using IDE or other compiler and replaceany existing class files.

Overview of the Custom Layer

WDK and WDK applications make use of a customization layer, which allows you to keepconfigurations and customizations in a location separate from the installed product. This allows thecustom layer to be easily migrated after an upgrade or reinstallation.

A default custom directory is installed with the product in the following location:virtual_dir/custom

This directory is installed with the subdirectories and files shown in the following figure.

Figure 1. Custom Directory Contents after Installation

The custom layer usually contains the directories shown above. The directory contents, and additionaldirectories for your custom components, are described in the table below.

Table 1. Directory Structure of the Custom Layer

Directory of File Name Contents

custom/config XML resource files

custom/component_name JSP pages. Recommended one folder percomponent.

custom/strings Custom resource strings



Directory of File Name Contents

custom/theme Custom themes (to change the look and feel ofthe UI)

app.xml File for changes to app.xml settings

Custom Layer Definition Inheritances and Overrides

When you extend a definition in a configuration file in WDK or a WDK application, any element thatis defined in the custom definition will override that same element in the definition that has beenextended. If the element is not specified in the custom definition, that element will be inherited fromthe component that has been extended in the XML resource file.

For example, suppose you want to extend the docbaseattributelist control definition, which includesthe section below:<config version="1.0">

<scope>...

<category><name><nlsid>MSG_INFO</nlsid></name><attributes><attribute name="object_name"/><attribute name="title"/><attribute name="authors"/><attribute name="keywords"/><attribute name="subject"/><attribute name="r_version_label"/><attribute name="owner_name"/><attribute name="r_creation_date"/><attribute name="r_modify_date"/><attribute name="r_content_size"/></attributes><moreattributes>

<attribute name="a_status"/><attribute name="i_is_reference"/><attribute name="i_is_replica"/>...

</moreattributes></category>

...</scope>

</config>

In this example, if you include the category element in your extended definition, this will overwriteall <category> elements. This means that you must repeat any <attribute> elements that you want toinclude in your override. If you want to add a single element, in your extended definition you mustrepeat the entire list of attributes plus add the one additional attribute.



Setting Up an IDEWhen you create a custom class, you compile it using either an IDE, such as the NetBeans IDE, oran external compiler. This section contains information on creating a project in the NetBeans IDE.If you use another IDE, consult the IDE documentation for the proper way to set the classpath andreference the external libraries.

This guide uses the NetBeans IDE version 3.6 for the customization tutorials that require compilingJava classes. You can use it as your text editor for the configuration tutorials as well.

Creating a Project in NetBeansTo create a new project in NetBeans

1. Open the NetBeans IDE.

2. Choose Project?Project Manager.

3. Click New.

4. Create a name for your project, such as wdk6, and click OK.

Mounting the WDK Directories

Mounting the WDK Java archives effectively sets the classpath for your project.

To mount the WDK directories

1. Select File?Mount Filesystem from the NetBeans IDE menu bar.

2. Select Local Directory as the filesystem type, then click Next .

3. Navigate to the directy in which you have installed the Tomcat application server, and open the/webapps subdirectory. Highlight the virtual directory in which you installed WDK (for example,wdk53), then click Finish.

Note: If you see a message that an alternate view is available, you can safely ignore it.

4. Select File?Mount Filesystem from the NetBeans menu bar.

Mounting the DFC JAR Files

Use the following procedure to mount the DFC JAR files necessary for the project.



To mount the DFC JAR files:

1. Select File?Mount Filesystem from the NetBeans IDE menu bar.

2. Select Archive Files as the filesystem type, then click Next to move to the next page.

3. Navigate to the Shared subdirectory of the DFC program root. (The default location on MicrosoftWindows is C:\Program Files\Documentum\Shared.) Highlight all the JAR files listed, andthen click Finish.

Stopping the Internal Tomcat Server

If you are running NetBeans, stop the internal Tomcat server instance before starting an externalTomcat server. Use the following procedure.

To stop the NetBeans IDE server instance:

1. Click the Runtime tab in the Explorer frame.

2. Expand the tree to Server Registry?Tomcat 5 Servers?http://localhost:8084.

3. Right‑click on http://localhost:8084 to see whether the server has been started. If the status isrunning, select Stop Server.

Caution: Do not start an internal or external Tomcat server from within the IDE using the defaultcommand arguments. The default start script will not use the environment settings requiredby WDK.


Chapter 2Configuring the Webtop Menubar

A good place to start configuring and customzing WDK applications is to make simple changes to themenubar to address your users’ specific business requirements.

Finding the filesThe first step in any configuration or customization is to locate the files we want to modify. Thistakes a bit of detective work with Webtop. The “obvious” place to start is the configuration file/webtop/config/menubar_component.xml (all path references in this chapter are relative to the/webtop‑root/ directory. When you look in that file, though, you find that the primary element isdefined as shown in .

Figure 2. Fragment of /webtop/config/menubar_component.xml as shipped

<component id = "menubar"extends="menubar:/webcomponent/config/library/menubar/menubar_component.xml">

That tells us that the actual configuration information is extended from the lower‑level definition inthe webcomponent directory. That’s where you will find the information you actually want to modify.

In earlier versions of the Web Development Kit, you would extend and override the configurationinformation files that come with the product as shipped. That approach still works. However, inVersion 6, you have the option of modifying the user interface by adding, removing, or replacingindividual configuration elements. The new approach makes it more likely that your customizationswill continue to work with future releases without having to make modifications.

Adding a command to a menuWe will insert the Rename command to the File menu, just after the Save As... command.


Configuring the Webtop Menubar

Figure 3. File menu before modification.

To insert the Rename command to the File menu:

1. Using any text editor, create a new file named “menu_configuration_1.xml” in the <webtoproot>/custom/config directory.

2. Enter the code listing as shown.<config>

<scope><menuconfig

modifies="menubar_file_menu:webcomponent/config/library/menubar/menubar_component.xml"

><insertafter path=

"menu[name=file_menu].actionmenuitem[name=file_saveas]">

<actionmenuitemdynamic = "singleselect"id = "file_rename"name = "file_rename"value = "Rename"action = "rename"showifinvalid = "true"

/></insertafter>

</menuconfig></scope>

</config>

3. Save the file.



4. Refresh the configuration by opening http://<your_host_name>/webtop/wdk/refresh.jsp in yourbrowser.

Figure 4. File menu with Rename command

Now we will take a closer look at the elements of the file you just created.

<config> <scope> . . . </scope>

</config>

The primary element in the configurationfile is the <config> tag. The <scope> tag isrequired, whether or not you’re restricting theconfiguration to a specific scope.

<menuconfig modifies= "menubar_file_

menu: webcomponent/config/library/

menubar/menubar_component.xml"> ...

</menuconfig>

This tag identifies the primary element in theconfiguration file we want to modify. Note thatthe modifies attribute string begins with the IDof the element we will modify. This is not anarbitrary value (as with namespaces) but thespecific ID of the element as it appears in thereferenced configuration file.The portion afterthe colon gives the location of the configurationfile to be modified, relative to the <webtop_root>directory.



<insertafter path= "menu[name=file_

menu]. actionmenuitem[name=file_

saveas]" > ... </insertafter>

This tag identifies the type of modification.In this case, we will insert a new menu itemand have it appear after an existing item. Thepath argument uses dot notation to identify thelocation to be modified in the referenced XMLconfiguration file.Our new menu item is added to the menudefinition named file_menu. It appears after theactionmenuitem tag with the name file_save_as.

<actionmenuitem dynamic =

"singleselect" id = "file_rename"

name = "file_rename" value = "Rename"

action = "rename" showifinvalid =

"true" />

We need to create a new action menu itemobject and set its custom attributes. Youcan use the command descriptions in themenubar_component.xml configuration file as aguide for creating your own action menu item.

This is a dynamic control, meaning that it canbe automatically enabled or disabled based onselections in a content component such as a filelist. By setting it to “singleselect,” the commandwill be enabled when one and only one item isselected in a list control.

The name attribute is used internally by the server– controls with names are cached automatically.

The value is the text string displayed on themenu. Usually, you will use an NLSID to pointto an entry in the strings directory. For thisexample, we just enter the value directly as atext string.

The action called by this menu option will be the“rename” action.

showifinvalid is a boolean value. If the commandis not valid for the selected items, the commandwill be displayed in grey on the menu. Settingthis attribute to false hides this commandwhen the selection is an invalid target for thiscommand.

You may notice a difference in the way I formatthe tags. Since the whitespace is ignored, I findit easier to read tags that have one attribute per



line. This has no impact on the application, butmakes it easier for humans to read.

Removing a command from a menuRemoving a command from a menu follows a similar pattern to adding a menu item. We create aconfiguration file that identifies the <menuconfig> tag to modify, then use a <remove> element to hidethe <actionmenuitem> element we do not want to display. As an example, we will remove the CancelCheckout command (for no particular reason, just a random target for illustrative purposes).

To remove a menu item from a menu

1. Using any text editor, create the file <webtop_root>/custom/config/remove_cancel_checkout_command.xml

2. Enter the code as shown.<config><scope>

<menuconfigmodifies="menubar_file_menu:webcomponent/config/library/menubar/menubar_component.xml"

><remove

path="menu[name=file_menu].actionmenuitem[name=file_cancelcheckout]"

/></menuconfig>

</scope></config>

3. Save the file.

4. Refresh the configuration by opening http://<your_host_name>/webtop/wdk/refresh.jsp in yourbrowser.



Figure 5. File menu with Cancel Checkout command removed

The only way this file differs from the configuration file for adding a menu is the <remove> element.<remove

path="menu[name=file_menu].actionmenuitem[name=file_cancelcheckout]"

/>

Since we are not adding anything new to the menu, we just have to provide the dot path to thecancelcheckout actionmenuitem in a single closed tag. Nothing is actually lost or changed in theunderlying application — the command is just hidden at runtime.

Rearranging commands in a menuTo rearrange items in a menu, remove the item from its current position, then insert it at the newposition.

To move a menu item to a new location on the same menu:

1. Using any text editor, create the file <webtop_root>/config/menubar_configuration_3.xml

2. Enter the code as shown<config>

<scope><menuconfig


><remove

path=



"menu[name=file_menu].actionmenuitem[name=file_cancelcheckout]"/>

<insertbeforepath=

"menu[name=file_menu].actionmenuitem[name=file_delete]"><actionmenuitem

dynamic="multiselect"name="file_cancelcheckout"nlsid="MSG_CANCEL_CHECKOUT"action="cancelcheckout"showifinvalid="true"

/></insertbefore>


</config>

3. Save the file.

4. Refresh the configuration by opening http://<your_host_name>/webtop/wdk/refresh.jsp in yourbrowser..

Figure 6. File menu with Cancel Checkout command moved before Delete command

In that example we used the <insertbefore> element to make the command appear above the Deletecommand in the menu.



It is interesting to note that it does not actually matter in which order you add or remove itemsfrom the menu. The changes you make in the configuration modification file only affect the itemsin the original configuration file, not the items in your configuration modification file. There is noconflict when you say “remove” and “insert” the same command on the same menu, because you areremoving from the original configuration file and inserting to the original configuration file.

Replacing a command in a menuYou can also replace an existing command in a menu with a version of your own. One use case wouldbe changing the attributes of an existing command to one better suited for your organization. Forexample, you might be concerned that your users could inadvertently delete the wrong file whendeleting a multiple selection from what should be a stable, archival repository. We can redefinethe delete menu item with the dynamic attribute set to singleselect, forcing users to carefully deleteone file at a time.

When changing an element this way, the easiest thing to do is to copy the original element from theconfiguration file that ships with the product, create a new configuration file that modifies the original,paste the element into a <replace> element, and make the modifications there.

To replace a menu item:

1. Using any text editor, create the file <webtop_root>/config/menubar_configuration_4.xml

2. Enter the code as shown<config>

<scope><menuconfig


><replace

path="menu[name=file_menu].actionmenuitem[name=file_delete]"

><actionmenuitem

dynamic="singleselect"name="file_delete"nlsid="MSG_DELETE"action="delete"hotkeyid="HOTKEY_DELETE"showifinvalid="true"

/></replace>


</config>

3. Save the file.



4. Refresh the configuration by opening http://<your_host_name>/webtop/wdk/refresh.jsp in yourbrowser

In Webtop, when you select one item in a file list, the Delete command is still enabled. If you selectmore than one item at a time, the Delete command is now disabled.

Removing an entire menuYou can use a configuration modification file to add, move, or remove entire menus on the menubar.In this case, you reference the primary element <component> and modify the <menuconfigids>element. These elements do not have a name or ID attribute — you modify the configuration of themenus by copying the entire configuration element to your modification file to make your changes.You can add, rearrange, or remove menus in your modification file. Just as an illustration, we willremove the View menu from the menubar.

To remove the View menu from the menubar

1. Using any text editor, open the file <webtop_root>/webcomponent/config/library/menubar/menubar_component.xml.

2. In the <config> element, locate the <menuconfigids> element.

3. Select the entire <menuconfigids> element and copy it.

4. Create a new configuration file, <webtop_root>/custom/config/remove_view_menu.xml

5. Enter the following code in the configuration file.<config version="1.0">

<scope><component

modifies="menubar:webcomponent/config/library/menubar/menubar_component.xml">

<replace path="menuconfigids"></replace>

</component></scope>

</config>

6. Paste the current <menuconfigids> information inside the <replace> element.<config version="1.0">

<scope><component


<replace path="menuconfigids"><menuconfigids>

<id>menubar_file_menu</id><id>menubar_edit_menu</id><id>menubar_view_menu</id><id>menubar_tools_menu</id>



<filter entitlement="recordsmanager,rps"><id>menubar_rpm_menu</id>

</filter></menuconfigids>

</replace></component>

</scope></config>

7. Delete the element <id>menubar_view_menu</id><config version="1.0">

<scope><component


<replace path="menuconfigids"><menuconfigids>

<id>menubar_file_menu</id><id>menubar_edit_menu</id><id>menubar_tools_menu</id><filter entitlement="recordsmanager,rps">

<id>menubar_rpm_menu</id></filter>

</menuconfigids></replace>


</config>

8. Save your work.

9. Refresh the configuration.

Figure 7. Webtop menubar with the View menu removed



When the application behaves in an unexpectedmannerThere are times when you change the configuration of your application, but your changes are notreflected when you open the browser. There are many possible explanations, none of which reallymatters, since what you want to do is see your application work the way you defined it.

Any parent knows that when a baby will not stop crying, you strip it, diaper it, dress it, feed it, burpit, hold it and sing to it. When your application will not pick up your changes, close your browser,restart the application server, open your browser, delete all offline content, then open Webtop, andyour changes should display.

When you modify a configuration file, you can refresh your configuration by openinghttp://<webtop_root>/wdk/refresh.jsp in your browser.

When you modify a JSP, the change is automatically picked up by the application server the next timeyou access the page, but only if the modification date on the file is later than the previous version. Forexample, if you replace your JSP with a sample file from the developer site, the date of the samplefile will likely be older than the date on your installed file, and the change will not be picked up. Thesimplest way to fix this problem is to make an innocuous change to the file, such a adding and deletinga space at the end of the file, and re‑saving the file to give it a new modification date.

If you change Java code, you need to restart the application server in order for the system to pickup your changes.

Small changes, big impactAs you can see, rather minor updates to the configuration of a component can tailor the interface tomeet the specific needs of your users. The complex programming that supports these controls haslargely been handled for you. Before you contemplate creating your own components, be sure youhave explored the options that ship with our product to see if the behavior is either already availableor easily configured.


Chapter 3Configuring Columns in a Webtop ListControl

In this lesson, we are going to add, move, and remove columns from the My Files classic listcomponent. We will need to:

Identify the configuration files to modify.Create a modification file in the /custom/config directory.Edit the column elements and attributes in the configuration modification file.Refresh the configuration to see the results.

Areas of personal confusionThere are a couple of potential points of confusion when you are refreshing column configuration, so Iwill talk about those here, before we get started.

When I was preparing these examples, everything was working fine, then suddenly the configurationstopped updating after my changes. Now, I shut everything down and brought it all back up andthe changes appeared as they should. But that is the brute force approach; the actual solution to myconfusion took a little more digging. It has to do with the user column preferences settings in Webtop.

If a user has never saved column preferences, any changes you make on the application server arepicked up by the browser automatically. If a user has set column preferences, the user can open theColumn Preferences dialog and click “Reset to defaults” to return the new default settings.

However, it is important to note that “Reset to defaults” does not clear the user’s settings: it storesthe default list of visible columns. If the defaults change, the user will need to return to the ColumnPreferences dialog every time s/he wants to pick up the changes. If the user clears the browser’scookies, that enables the browser to pick up any changes going forward.

To save trouble, I cleared my cookies so that I could see the changes reflected immediately after Irefreshed the configuration, but that is a decision I will leave up to you.


Configuring Columns in a Webtop List Control

Finding the FilesOnce again, there is some detective work required to track down where columns are actually defined,due to the clever reuse and extension of the default Webtop components that come into play. All of thefile paths given in this example are relative to the <webtop_root> directory on your application server.Looking in the /webtop/config/myfiles_component.xml configuration file, we see that it extends the/webcomponent/config/library/myobjects/myobjects_list_component.xml configuration file.

Then, we can copy the entire <columns> element from /webcomponent/config/library/myobjects/myobjects_list_component.xml and paste it into our new configuration modification file.

To create the myfiles component column configuration file

1. Using any text editor, create the file /custom/config/myfiles_configuration_modification.xml

2. Enter the following code in the file you just created:<config version="1.0">

<scope><component

modifies="my_object_list:webcomponent/config/library/myobjects/myobjects_list_component.xml"><replace path="columns"></replace>


</config>

3. Using any text editor, open the file webcomponent/config/library/myobjects/myobjects_list_component.xml

4. Copy the entire <columns> element. (You need to copy and override the entire element, becausethe columns element does not have a defined ID.)

5. Close myobjects_list_component.xml — if prompted, do not save changes.

6. Return to the file myfiles_configuration_modification.xml, and paste the <columns> elementinto the <replace> element.

<config version="1.0"><scope>

<componentmodifies="my_object_list:webcomponent/config/library/myobjects/myobjects_list_component.xml"

><replace path="columns">

<columns><loadinvisibleattribute>true</loadinvisibleattribute><column>

<attribute>object_name</attribute><label>

<nlsid>MSG_NAME</nlsid></label><visible>true</visible>

</column>



<column><attribute>title</attribute><label>

<nlsid>MSG_ATTR_TITLE</nlsid></label><visible>false</visible>

</column>...

<column><attribute>i_is_reference</attribute><label><nlsid>MSG_REFERENCE</nlsid></label><visible>false</visible>

</column></columns>

</replace></component>

</scope></config>

7. Save the file myfiles_configuration_modification.xml.That is a large amount of code to reproduce, but if you modify any column, you have to copy notjust that element but all of its siblings as well.

Adding a columnWhat is nice is that the default list of all available columns is already included in the columns element.The <visible> element determines whether or not the column is displayed. When we talk about addinga column, we are really just talking about making the column visible to the user.

To make a column visible

1. Locate the title definition (second <column> element from the top).

2. Comment out the existing <visible> element; a best practice is to include your name and thedate you made the change.

3. Create a new <visible> tag set and set the value to true, as shown:.

.

.<column>

<attribute>title</attribute><label>

<nlsid>MSG_ATTR_TITLE</nlsid></label><! Changed to true by Dennis Dawson July 2007

<visible>false</visible>><visible>true</visible>



</column>...

4. Refresh the configuration by opening http://<hostname>/webtop/wdk/refresh.jsp.

Figure 8. My Files page with Title column displayed

Removing a columnRemove a column from the display by changing its visible attribute to false. For no particular reason,we will remove the Name column, just because it is easy to find — this is not a practical example.

To make a column visible

1. Locate the object_name column definition (the first <column> element).

2. Comment out the existing <visible> element; a best practice is to include your name and thedate you made the change.

3. Create a new <visible> tag set and set the value to false, as shown:.

.

.<column>

<attribute>object_name</attribute><label>

<nlsid>MSG_NAME</nlsid></label><! Changed to false by Dennis Dawson July 2007

<visible>true</visible>>



<visible>false</visible></column>...

4. Refresh the configuration by opening http://<hostname>/webtop/wdk/refresh.jsp.

Figure 9. My Files page with Name column hidden

Rearranging ColumnsYou can rearrange columns by moving the <column> elements into your preferred position.

For example, you could move the Size column element above the Version column element in theconfiguration file.

Figure 10. Rearranging columns by moving column elements

.

.

.<! Rearranged Size and Version columns

Dennis Dawson July 2007><column>

<attribute>r_content_size</attribute><label><nlsid>MSG_SIZE</nlsid></label><visible>true</visible>

</column><column>

<attribute>r_version_label</attribute><label><nlsid>MSG_VERSION_LABEL</nlsid></label><visible>true</visible>



</column>...

Figure 11. Size column moved in front of the Version column

When you refresh the configuration, the columns are reversed.

I hope that at this point you can see that you can very quickly make useful updates to your Webtopapplication without burrowing through page after page of spaghetti code. The kinds of changesthat are most important to your users are, by design, quick and convenient to implement. Onceyou understand the configuration paradigm, updating your application can be a (comparatively)painless process.


Chapter 4Hello Webtop

This lesson provides a complete, if not terribly useful, example of Webtop customization. In thislesson, you will configure the Webtop menubar to display a custom command, configure a customaction to be invoked by the command, create a component with a JSP UI launched by the action,populate the controls on the page with both static and dynamic values, and use the results of a queryin one component page to open another page to display detailed information.

Step 1 — Configuring the MenuBarWe will begin by performing a series of configurations. Many of the most common changes reported byour customers are not so much customizations (involving massive redesign and modification of Javacode) as minor changes to existing behavior (changing the layout of components, adding or removingoptions, etc.). You can make most configuration changes by modifying XML files.

We will start by inserting a new command, Hello World, to the Tools menu. This will require amodification to the menubar_component.xml configuration file.

To insert the Hello World command to the Tools menu:

1. Using any text editor, create a new file named “helloworld_menu_configuration.xml” in the<webtop root>/custom/config directory.

2. Enter the code listing as shown.<config>

<scope><menuconfig

modifies="menubar_tools_menu:webcomponent/config/library/menubar/menubar_component.xml"

><insert path="menu[name=tools_menu]">

<actionmenuitemdynamic = "genericnoselect"name = "hello_world_menu_item"id = "hello_world_menu_item"


Hello Webtop

value = "Hello World"action = "hello_world_action"showifinvalid = "true"

/></insert>


</config>

3. Save the file.

Step 2 — Configuring the Hello World ActionIn Step 1, you modified an existing configuration file, making a minor adjustment to include ourcustom command. For this step, you will configure a completely new component. We will add a newXML file. We will name the file <webtop_root>\custom\config\hello_world_action.xml. Note that thefile name is not significant, but it can be helpful to include the word “action” in the title to distinguishthe file from other configuration files in the same folder.

Here is the text of hello_world_action.xml. Enter this code in a text editor, then save the file in as<webtop_root>\custom\config\hello_world_action.xml.<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>

Table 2. Highlights from hello_world_action.xml

<action id = "hello_world_action">This is the name of the action. It must be unique.It must match the name we gave the commandin the menubar.jsp file in order to work with ourexample.

<execution class="com...

LaunchComponent">

You can call any Webtop class from the action,including your own custom classes. In ourexample, we will use one of the built‑in WDKclasses to launch the component.


Hello Webtop

<component>hello_world_component</

component>

This is the name of the component we will launchwith the action. It needs to match the componentname in the component XML file that we willcreate in the next step.

<container>dialogcontainer</

container>

This tag is optional for the hello_world example.It tells Webtop to display the output from thecomponent wrapped in a container that addsOK, Cancel, and Help buttons.

Figure 12. Tools menu with inserted Hello World command

To recap, you have now defined the Hello World menu command, and configured a new actionthat will be invoked by your menu command. Just for fun, you can restart your application serverand look at the Tools menu.

You can select the command, and get an exciting error message (always nice to know that the errormechanism is working properly). The reason we get the error is that we told Webtop to invoke thehello_world_component, but we have not yet defined the component. We will define the componentin the next two steps.


Hello Webtop

Step 3 — Configuring the Hello WorldComponentComponents usually have four elements — an XML configuration file, one or more JSPs, a Javabehavior class, and a properties file listing the text strings used in the component (useful for NLS).Though it is possible for a component to share a configuration file, and it is possible for a JSP to embedits Java behaviors, it is generally considered a best practice to create three unique elements for eachcomponent. We will construct the Hello World component using an iterative process that lets us runthe application at different stages, gradually building more complex behaviors.

The XML configuration file binds together the elements of the component. For all intents andpurposes, you can think of the component as the XML configuration file that defines it. The elementsof the component may be used in more than one component, and a component can have more thanone JSP, so only the configuration file brings all of the elements together in one place.

We will create the component configuration file first, then build the elements ofthe component. Enter the following code in a text editor, then save the file as<WEBTOP_ROOT>\custom\config\hello_world_component.xml.<?xml version="1.0" encoding="ISO88591" standalone="no"?><config version="1.0"><scope><component id="hello_world_component"><pages><start>/custom/hello_world/hello_world.jsp</start>

</pages><class>com.mycompany.custom.HelloWebtop</class>


</config>

Table 3. Highlights from hello_world_component.xml

<component id=”hello_world_

component”>

This is the name of the component. It must beunique. It must match the name specified in thehello_world_action.xml file’s <component/> tag.

<pages><start>...hello_world.jsp</

start>

This defines the JSP files used by the component.

<class>com.mycompany.custom.

HelloWebtop</class>

This identifies the Java class that supports thecomponent.

To recap, we have created a menu item for the Hello World application. We have defined an actionthat is to invoke the hello_world_component. We have created the XML configuration that bindstogether the elements of the Hello World component. Next, we will create the JSP that provides theUser Interface for the component. At this point, there is no reason to restart the server and view thefile, because you will still get an error when you invoke the command.


Hello Webtop

Step 4 — Creating the Hello World JSPThe rest of the steps will primarily involve incrementally updating a JSP to provide the user interfacefor our component. You will start with the simplest of JSP files, then add more complex (notnecessarily more difficult) behaviors.

At the most basic level, a JSP is a page with HTMLmarkup. You can say “hello” by creating a standardweb page.

To create hello_world.jsp

1. In the <WEBTOP_ROOT>/custom directory, create the directory hello_world.

2. In <WEBTOP_ROOT>/custom/hello_world, create a new text file named hello_world.jsp.

3. Open hello_world.jsp with a text editor and enter the following text.<html><body><h1>Hello World</h1></body></html>

4. Save the file.You have now created the page that will be displayed when the hello world action is invoked. If thiswere a normal web page, it would be ready to go. However, you have defined hello_world as acomponent. Even though we have not implemented any controls or behavior, we need to supply abasic Java class to meet the minimal requirements for a component.

To create HelloWebtop.java

1. Use a text editor or your Java IDE to enter the following code.package com.mycompany.custom;

import com.documentum.web.common.ArgumentList;import com.documentum.web.formext.component.Component;

public class HelloWebtop extends Component public void onInit(ArgumentList arg)

super.onInit(arg);

2. Compile the code.

3. If necessary, copy HelloWebtop.class to the directory <WEBTOP_ROOT>\WEB_INF\classes\com\mycompany\custom\HelloWebtop.class

If you examine the code you entered, we have instantiated a component and provided a variable toaccept any arguments passed to the class by HttpServlet.request. The onInit() method accepts thevariables and passes them to its parent (super) class for processing.


Hello Webtop

You can now restart your application server. Enter the URL for your application (for example,http://localhost:8080/webtop).Choose Hello World from the Tools menu.

You are rewarded with a web page that says Hello World in big bold letters. You feel a great sense ofaccomplishment, and are anxious to continue with the implementation.

To recap, we have configured the hello_world component, installed a JSP and supporting Java class,run the application, and succeeded in displaying the component. At this point, it has been installed inthe Webtop framework, but it is not using Webtop controls or exposing Webtop functionality. In thenext step, we will transform the JSP into a Webtop form.


Hello Webtop

Step 5 — Adding Static Controls to the JSPThe hello_world JSP you created in step 4 demonstrates communication with the application server,but at this point the JSP is not communicating with the Webtop repository. To access the repository,you need to work with the Webtop API.

To make it easier for you to develop your own components, Webtop comes with predefined XMLlibraries (tag library definition files, or TLDs) that define special tags for the most common formcomponents. In this step, we will add an import statement to the JSP that provides access todmform_1_0.tld, then use label tags from that library to display static text values.

The correct way to store text values used by your applications is to use the National Language Support(NLS) framework, storing the strings in properties files. You can then configure the component toaccess the correct values at runtime. To add an NLS‑ready Label object to your JSP, you need to add aproperties file, make a minor change to the configuration file, and substantially revise the JSP.

To add the HelloWorldProp.properties file to Webtop

1. Open a new file in a text editor.

2. Enter the following code.MSG_STATIC_TEXT=Static text from the Properties File.

3. Save the file as <WEBTOP_ROOT>\custom\strings\com\mycompany\hello_world\HelloWorldProp.properties. (Create the additional folders in the path as necessary.)While it may seem unnecessary to create such a deep path to store your properties files, it is agood habit to keep a consistent, corresponding directory structure for your source files so that theyare easy for you and others to locate and maintain as your application grows.

We now have a string stored on the application server. Next, we will adjust thehello_world_component.xml configuration file to point to the string value at runtime.

To modify the hello_world_component.xml configuration file

1. Open the file <WEBTOP_ROOT>\custom\config\hello_world_component.xml.

2. Add the following line to the configuration file after the <class> tag.<nlsbundle>com.mycompany.hello_world.HelloWorldProp</nlsbundle>

3. Save the file. The final result should match the program listing below.<?xml version="1.0" encoding="ISO88591" standalone="no"?><config version="1.0"><scope><component id="hello_world_component"><pages><start>/custom/hello_world/hello_world.jsp</start>

</pages><class>com.mycompany.custom.HelloWebtop</class><nlsbundle>com.mycompany.hello_world.HelloWorldProp</nlsbundle>


Hello Webtop

</componeny></scope>

</config>

To add an NLSready Label object to hello_world.jsp

1. Open the file <WEBTOP_ROOT>\custom\hello_world\hello_world.jsp.

2. Replace the content of the file with the following code (it is probably easier to delete the existingmaterial than to modify it, but that would be up to you).

<%@ page contentType="text/html"%><%@ page errorPage="/wdk/errorhandler.jsp"%><%@ taglib uri="/WEBINF/tlds/dmform_1_0.tld" prefix="dmf" %><dmf:html><dmf:head><dmf:webform/>

</dmf:head><dmf:body><h1>Hello Webtop</h1><dmf:form><p><dmf:label nlsid="MSG_STATIC_TEXT" /></p></dmf:form>

</dmf:body></dmf:html>

3. Save your file.

Table 4. Highlights from hello_world.jsp

<%@ page contentType=”text/html”%>This is a standard JSP tag indicating that thisform contains HTML tags in plain text format.

<%@ page errorPage="/wdk/

errorhandler.jsp"%>

This tag identifies the page that the applicationserver will display if there are any errors whenrendering the JSP.

<%@ taglib uri="/WEBINF/tlds/dmform_

1_0.tld" prefix="dmf" %>

This tag identifies the location ofthe Documentum Form Tag Library(dmform_1_0.tld). Tag libraries are stored in the<WEBTOP_ROOT>\WEB‑INF\tlds\ folder. Youcan open up the tld files using a text editor tofind out more about the available tags and theirdefault settings. The prefix for the tag library isset to dmf. By specifying the dmf prefix, you canuse the Documentum Form tags in your JSPs.


Hello Webtop

<dmf:html> <dmf:head> ... <dmf:body>

... <dmf:form>

These tags are very much like their standardHTML counterparts. The advantage of using thetags from the Documentum Form library is thatthese tags will work both for Webtop JSPs and inportlets. Portlets are web components embeddedin HTML pages: using the same head and bodytags would cause conflicts in web browsers.Adding the dmf: prefix differentiates these tagsfrom the tags in the host HTML page, allowingthe portlet elements to display. Even if you donot currently plan on using portlets, it does nothurt to use the dmf: versions, and it may saveyou trouble should you decide to use portletsin the future.

<dmf:webform/>This tag identifies the JSP as a Documentum webform, providing a number of default behaviorsand allowing the Webtop application server tomake assumptions about the form that enhanceperformance.

<dmf:label nlsid="MSG_STATIC_TEXT" />The dmf:label tag creates a text label control onthe web form. The nlsid attribute identifies thestring in the properties file that is associated withthis tag. At runtime, Webtop parses the valuefrom the properties file and replaces this tag withthe parsed string.

Restart your application server, click the Classic tab, and choose File>Hello World. Your text stringfrom the properties file is now displayed.

Next, we will add a static label and populate it from the Java behavior class. This is not therecommended method of displaying static text values, but it makes a nice segue into creating dynamiccontrols.

To add a Javaready static label to hello_world.jsp

1. Open <WEBTOP_ROOT>\custom\hello_world\hello_world.jsp with a text editor.

2. Add the following line, after the existing <dmf:label/> tag.<p><dmf:label name="STATIC_TEXT" /></p>

3. Save the file. The file should now match the following program listing.<%@ page contentType="text/html"%><%@ page errorPage="/wdk/errorhandler.jsp"%><%@ taglib uri="/WEBINF/tlds/dmform_1_0.tld" prefix="dmf" %><dmf:html><dmf:head>


Hello Webtop

<dmf:webform/></dmf:head><dmf:body><h1>Hello Webtop</h1><dmf:form><p><dmf:label nlsid="MSG_STATIC_TEXT" /></p><p><dmf:label name="STATIC_TEXT" /></p></dmf:form>


We will take a look at the line you just added.

<dmf:label name="STATIC_TEXT” />The dmf:label tag creates a text label control onthe web form. The name attribute is the nameof the control, which will be passed to the Javaclass at runtime.

At the moment, the form would display a blank value for this label. We have created the label, whichis a placeholder for text, and given it a name. Next, we will modify the Java behavior class to accessand populate the value for the STATIC_TEXT label.

To update the Java class to populate the STATIC_TEXT label

1. Open the HelloWebtop.java file in a text editor or Java IDE.

2. Add the import statement for the Label class, as follows.import com.documentum.web.form.control.Label;

3. Add the onRender() method under the onInit() method as follows.public void onRender()

super.onRender();

Label staticText = (Label) getControl("STATIC_TEXT",Label.class);staticText.setLabel("A static text value from the Java class.");

4. Save and compile the class.

5. If necessary, copy HelloWebtop.class to <WEBTOP_ROOT>\WEB‑INF\classes\com\mycompany\hello_world\HelloWebtop.class.

The resulting Java file should be the same as the program listing below.package com.mycompany.custom;

import com.documentum.web.common.ArgumentList;import com.documentum.web.formext.component.Component;

import com.documentum.web.form.control.Label;


super.onInit(arg);


Hello Webtop

public void onRender() super.onRender();

Label staticText = (Label) getControl("STATIC_TEXT",Label.class);staticText.setLabel("A static text value from the Java class.");

We will take a look at a couple of key lines from the code.

onRender()This time you added the onRender() method,which is run every time the JSP is displayed.

Label staticText = (Label)

getControl("STATIC_TEXT",Label.

class);

This line creates a Label object that representsthe STATIC_TEXT control on the JSP, usingthe getControl method from the parent class(Component). It then creates the Label variablestaticText to represent the control.

staticText.setLabel("A static text

value from the Java class.");

This line uses the setLabel method to set thetext of the staticText variable to the value in theparentheses.

Restart your application server, log on to Webtop, click the Classic tab, and choose File>Hello World.


Hello Webtop

Your text string from the properties file is displayed, followed by the static value provided by the Javabehavior class.

To recap, you now have a component that displays static text values from a properties file and fromthe supporting Java class. You have been patient to this point, and your patience will now pay off.In the next three steps, we will add controls that demonstrate how to access and display dynamicinformation from the repository, which will give you the basis for just about any modifications youwill ever need to make to Webtop.


Hello Webtop

Step 6 — Adding Dynamic Controls to the JSPAs alluded to earlier, you generally will not use the Java class to display static text values (propertiesfiles are easier to maintain). Displaying dynamic information is a different matter entirely — you willoften want to create components that display information in a way that matches your company’s wayof doing business. In this step, we will gain access to the user’s repository connection and use it toobtain and display information about the user’s current work session. We will add a new control to theJSP and a new method to the Java behavior class.

To add a Javaready label to hello_world.jsp

1. Open the file <WEBTOP_ROOT>\custom\hello_world\hello_world.jsp in a text editor.

2. Add the following line after the second <dmf:label/> tag.<p>Current repository: <dmf:label name="CURRENT_REPOSITORY"/></p>

3. Save the file. It should now match the following program listing.<%@ page contentType="text/html"%><%@ page errorPage="/wdk/errorhandler.jsp"%><%@ taglib uri="/WEBINF/tlds/dmform_1_0.tld" prefix="dmf" %><dmf:html><dmf:head><dmf:webform/>

</dmf:head><dmf:body><h1>Hello Webtop</h1><dmf:form><p><dmf:label nlsid="MSG_STATIC_TEXT" /></p><p><dmf:label name="STATIC_TEXT" /></p><p>Current repository: <dmf:label name="CURRENT_REPOSITORY"/></p>

</dmf:form></dmf:body></dmf:html>

There is nothing new about that line of code. We added a new <dmf:label> object and named itCURRENT_REPOSITORY. Now, we will update the Java class to supply the value of the currentrepository. We will add a new method to retrieve the name of the repository, and change theonRender() method so that it updates the CURRENT_REPOSITORY label.

To update the Java class to provide dynamic information

1. Open the source file com.mycompany.custom.HelloWebtop.java.

2. Add the following import statements after the import statements at the top of the file.import com.documentum.fc.client.IDfSession;import com.documentum.fc.common.DfException;

3. Add the following method after the onRender() method.private String getCurrentRepositoryName()


Hello Webtop

String repositoryName = null;IDfSession dfSession = getDfSession();try

repositoryName = dfSession.getDocbaseName();catch (DfException e)

System.out.println("Error in HelloWebtop.java. Message:\n" + e);return repositoryName;

We will look at the code in more depth after editing the source file.

4. Add the following code to the end of the onRender() method.Label currentRepository = (Label) getControl("CURRENT_REPOSITORY",Label.class);currentRepository.setLabel(getCurrentRepositoryName());

5. Save and compile the file. It should match the following program listing.package com.mycompany.custom;

import com.documentum.web.common.ArgumentList;import com.documentum.web.formext.component.Component;import com.documentum.web.form.control.Label;import com.documentum.fc.client.IDfSession;import com.documentum.fc.common.DfException;


super.onInit(arg);public void onRender()

super.onRender();Label staticText = (Label) getControl("STATIC_TEXT",Label.class);staticText.setLabel("A static text value from the Java class.");

Label currentRepository = (Label)getControl("CURRENT_REPOSITORY",Label.class);

currentRepository.setLabel(getCurrentRepositoryName());

private String getCurrentRepositoryName()





Hello Webtop

6. Copy the complied class file to <WEBTOP_ROOT>\WEB_INF\classes\com\mycompany\custom\HelloWebtop.class.

Now we will take a look at the significant changes we made.

IDfSession dfSession =

getDfSession();

When a browser makes a request for acomponent that requires a connection to thedatabase, Webtop checks to see if there is anactive session and, if necessary, presents a logindialog. As a result, you do not have to doanything in your code to authenticate your usersunless you have special needs beyond the scopeof the security provided by Webtop. We cananticipate that the user will already have a validsession when accessing our component, and wecan use the existing session to set values in ourcomponent.

repositoryName = dfSession.

getDocbaseName();

Using the current session, we can get the nameof the current repository. In earlier releasesthe repository was referred to as the docbase,which is still reflected in the API (for backwardcompatibility).

Label currentRepository =

(Label) getControl("CURRENT_

REPOSITORY",Label.class);

currentRepository.setLabel(

getCurrentRepositoryName() );

These lines set the value in the label in muchthe same way as the earlier static text example.We create a reference to the control based on itsname, and set the text value. The only differenceis that rather than entering a static text string,we are calling the getCurrentRepositoryName()method, which returns a string with the name ofthe current repository.



Hello Webtop

The two static text labels you created earlier are displayed, followed by your new dynamic controlwith the name of the current repository.

To recap, we added a dmf:label object to the hello_world.jsp exactly like the earlier STATIC_TEXTlabel, but gave it the name CURRENT_REPOSITORY. We then added the getCurrentRepositorymethod to HelloWorld.class, which sends the retrieved value back to the form for display. We willexpand on this paradigm in the next step, and display a table of information rather than a single value.


Hello Webtop

Step 7 — Adding Databound Controls to theJSPThe <dmf:label/> controls you created in steps 5 and 6 are essentially “dumb” receptors of information.They will accept text values from any source and display them. Webtop also provides “smart” tags,which can be bound to tables and columns in the repository. These tags will then display the resultsof a Documentum Query Language (DQL) request, providing flexible and convenient access toinformation in and about your stored documents.

The first step is to add the bindable controls to the JSP, then add a query to the Java class to populatethe tables. We will use a datagrid to display a list of users from the current repository.

To add databound controls to the JSP

1. Open <WEBTOP_ROOT>\custom\hello_world\hello_world.jsp in a text editor.

2. Add the following code after the Current Repository line.<h1>List of Users</h1><dmf:datagrid name="mygrid" paged="true" pagesize="10"><tr>

<th>User Name</th><th>User Group Name</th>

</tr><dmf:datagridRow><td><dmf:label datafield="user_name" />

</td><td><dmf:label datafield="user_group_name" />

</td></dmf:datagridRow>

</dmf:datagrid>

3. Save your file. It should now match the following code listing.<%@ page contentType="text/html"%><%@ page errorPage="/wdk/errorhandler.jsp"%><%@ taglib uri="/WEBINF/tlds/dmform_1_0.tld" prefix="dmf" %><dmf:html><dmf:head><dmf:webform/>

</dmf:head><dmf:body><h1>Hello Webtop</h1><dmf:form><p><dmf:label nlsid="MSG_STATIC_TEXT" /></p><p><dmf:label name="STATIC_TEXT" /></p><p>Current repository: <dmf:label name="CURRENT_REPOSITORY"/></p><h1>List of Users</h1><dmf:datagrid name="mygrid" paged="true" pagesize="10"><tr><th>User Name</th>


Hello Webtop

<th>User Group Name</th></tr><dmf:datagridRow><td><dmf:label datafield="user_name" />

</td><td><dmf:label datafield="user_group_name" />


</dmf:datagrid></dmf:form>


We will take a look at some interesting details of the changes you just made.

<dmf:datagrid name=”mygrid”

paged=”true” pagesize=”10”>

To display a table of information from therepository, you can use a datagrid object. Aswith the label object, you give the object a namethat can be passed to the Java behavior class.By default, all of the results of the query arereturned and displayed. That would make for avery large result set in this case, so setting thepaged attribute to true and the pagesize to 10 willreturn only the first ten user records from therepository.

<dmf:datagridRow>

For the headings, you used a standard HTMLtable row and table heading tags. For the datarows, you used the dmf:datagridRow tag. Thelabel tags encapsulated by the dmf:datagridRowtags can be populated by data in the repository.

<dmf:label datafield=”user_name” />

<dmf:label datafield= "user_group_

name" />

Once again, you are using a dmf:label tag todisplay a string value. Rather than a singlevalue, though, this string is linked to a datafield,which is a column from a table in the repository.The table from which the rows are selected isspecified in the supporting Java class, but thecolumn names you specify here must match theirnames in the repository.

In this form, you are displaying only twocolumns of information, but you could displayall of the columns in the table if you chose to doso (there is not much to learn, and a great deal totype, when you add more columns, so stickingwith two is a good idea for this example).


Hello Webtop

Next, we need to modify the Java class. We need to enter a great deal of new code to use a databoundcontrol, but here is the good news: you can reuse the getDocbaseSession() method for most of yourdata retrieval needs in most of your components; also, the code is not complex, it is mostly a bunch“catch” clauses for the various exceptions that might be thrown.

To modify HelloWebtop.class to support a databound control

1. Open the Java source file com.mycompany.custom.HelloWebtop.java in a text editor or Java IDE.

2. Add the following import statements at the top of the file.import com.documentum.web.form.control.databound.Datagrid;

import com.documentum.web.formext.session.SessionManagerHttpBinding;

import com.documentum.fc.client.IDfSessionManager;

import com.documentum.fc.client.DfIdentityException;import com.documentum.fc.client.DfAuthenticationException;import com.documentum.fc.client.DfPrincipalException;import com.documentum.fc.client.DfServiceException;

3. Add the following method at the end of the class.IDfSession getRepositorySession()

IDfSessionManager sessionManager = null;SessionManagerHttpBinding httpBinding = null;IDfSession dfSession = null;try

sessionManager = SessionManagerHttpBinding.getSessionManager();String docbase = SessionManagerHttpBinding.getCurrentDocbase();dfSession = sessionManager.getSession(docbase);

catch(DfIdentityException dfe)

System.out.println("Error while obtaining Session. Id exception"+ dfe.getMessage());

catch(DfAuthenticationException ae)

System.out.println("Authentication exception while " +"getting client " + ae.getMessage());

catch(DfPrincipalException pe)

System.out.println("Principal exception " + pe.getMessage());catch(DfServiceException se)

System.out.println("Service exception " + se.getMessage());return (dfSession);

4. Add the following code to the onRender() method.Datagrid datagrid = null;

try


Hello Webtop

datagrid = (Datagrid) getControl("mygrid",Datagrid.class);catch(Exception ex)

if(datagrid == null)

datagrid = (Datagrid)createControl("mygrid",Datagrid.class);

datagrid.getDataProvider().setDfSession(getRepositorySession());datagrid.getDataProvider().setQuery("select user_name, user_group_name" +

" from dm_user where r_is_group = FALSE;");datagrid.getDataProvider().refresh();

5. Compile and save the file.

6. If necessary, copy the compiled class to <WEBTOP_ROOT>\WEB‑INF\classes\com\mycompany\custom\HelloWebtop.class. The file should now match the followingcode listing.package com.mycompany.custom;

import com.documentum.web.common.ArgumentList;import com.documentum.web.formext.component.Component;import com.documentum.web.form.control.Label;import com.documentum.web.form.control.databound.Datagrid;import com.documentum.web.formext.session.SessionManagerHttpBinding;import com.documentum.fc.client.IDfSession;import com.documentum.fc.client.IDfSessionManager;import com.documentum.fc.common.DfException;import com.documentum.fc.client.DfIdentityException;import com.documentum.fc.client.DfAuthenticationException;import com.documentum.fc.client.DfPrincipalException;import com.documentum.fc.client.DfServiceException;

public class HelloWebtop extends Component public void onInit(ArgumentList arg)super.onInit(arg);

public void onRender() super.onRender();Label staticText = (Label) getControl("STATIC_TEXT",Label.class);staticText.setLabel("A static text value from the Java class.");

Label currentRepository =(Label) getControl("CURRENT_REPOSITORY",Label.class);


Datagrid datagrid = null;try





Hello Webtop



private String getCurrentRepositoryName()




IDfSession getRepositorySession()

IDfSessionManager sessionManager = null;SessionManagerHttpBinding httpBinding = null;IDfSession dfSession = null;try



System.out.println("Error while obtaining Session. Id exception "+ dfe.getMessage());






We will take a closer look at the changes we just made to the Java class.


Hello Webtop

import com.documentum.web.form.

control.databound.Datagrid;

This is the Java representation of the Datagridcomponent. The onRender() method instantiatesand populates a Datagrid object, which is passedback to the JSP for display.

import com.documentum.web.formext.

session.SessionManagerHttpBinding;

import com.documentum.fc.client.

IDfSessionManager;

In step 6, you added code that indicates thata connection to the repository exists. You didnot actually use the connection to perform atransaction with the repository. In order topass information to and from the repository,you need to access the current session. TheIDfSessionManager class is used to manageidentities, pooled sessions, and transactions withthe repository. SessionManagerHttpBindingexposes the methods used to store and retrieve aconnection to a current repository.


DfIdentityException; import

com.documentum.fc.client.

DfAuthenticationException;

import com.documentum.fc.

client.DfPrincipalException;


DfServiceException;

These classes are used to trap a variety ofexceptions that may occur when your classattempts to access and use the current repositorysession.

Datagrid datagrid = null;

try datagrid = (Datagrid)

getControl("mygrid", Datagrid.

class); catch(Exception ex)

if(datagrid == null) datagrid =

(Datagrid)createControl("mygrid",

Datagrid.class);

The code you added to the onRender() methodcreates an empty datagrid object, then triesto associate it with the “mygrid” control youcreated on the JSP. If the “mygrid” datagridcontrol does not exist, the control is created inthe catch clause.

datagrid.getDataProvider().

setDfSession(

getRepositorySession());

datagrid.getDataProvider().setQuery(

"select user_name, user_group_name"

+ " from dm_user where

r_is_group = FALSE;");

datagrid.getDataProvider().refresh();

These lines populate the Datagrid object withinformation from the repository based on aquery. The first line gets the data provider forthe datagrid. It calls the getRepositorySession()method you created (described below) in orderto access the user’s current connection to therepository to complete the transaction.Thesecond line provides a DQL query that willlocate the information we want (in this case, wewant the user and group name from the dm_usertable, but only for users, not for groups).


Hello Webtop

The third line tells the datagrid control to refreshitself with the new data.


IDfSessionManager sessionManager

= null; IDfSession dfSession

= null; try sessionManager

= SessionManagerHttpBinding.

getSessionManager(); String docbase

= SessionManagerHttpBinding.

getCurrentDocbase(); dfSession =

sessionManager.getSession(docbase);

The getRepositorySession() method begins bycreating null instances of IDfSessionManagerand IDfSession. Using the methodsof SessionManagerHttpBinding, thesessionmanager and docbase variablesare set, which allows you to get the currentsession, returned in the dfSession variable.

The remainder of the method traps four differenttypes of exception. Otherwise, the currentsession is returned, and the onRender() methodis able to execute a query by accessing the user’scurrent connection.



Hello Webtop

The three text labels we created earlier are displayed, followed by a table listing the first 10 users fromthe dm_user table (the names have been purposely obscured).

To recap, we have created controls that display values from both the application server and from therepository. The final step in this whirlwind tour of Webtop customization is to not only retrieveinformation from the repository, but also use the information as the basis for a second query thatopens a new form.


Hello Webtop

Step 8 — Linking to a Second JSPThis final step simulates a common need when working with data repositories — to find a pieceof information, then to find additional information based on the results of the first query. We willadd a second JSP to the application, then link to that form from a modified version of the datagridwe just created.

To add a new JSP to your Webtop instance

1. Open a blank text document in any text editory.

2. Enter the following code.<%@ page contentType="text/html" %><%@ page errorPage="/wdk/errorhandler.jsp" %><%@ taglib uri="/WEBINF/tlds/dmform_1_0.tld" prefix="dmf" %><dmf:html><dmf:head><dmf:webform />

</dmf:head><dmf:body><dmf:form><h1>Documents modified by <dmf:label name="modifierLabel" />

</h1><dmf:datagrid name="my_doc_list_grid" paged="true" pagesize="10" bordersize="1"><tr><th>Document Name

</th><th>

Modification Date</th>

</tr><dmf:datagridRow><td><dmf:label datafield="object_name" />

</td><td><dmf:datevalueformatter type="short">

<dmf:label datafield="r_modify_date" /></dmf:datevalueformatter>


</dmf:datagrid></dmf:form></dmf:body></dmf:html>

3. Save the file as <WEBTOP_ROOT>\custom\hello_world\hello_detail.jsp.

4. Close the file.We will take a look at some highlights from the JSP we just created.


Hello Webtop

<h1> Documents modified by <dmf:label

name="modifierLabel" /> </h1>

The label component can be used to placedynamic text anywhere in the form. You canformat the results of the query as you would anyother text on the form (in this case, using the<h1> tag).

<dmf:datagrid name="my_doc_list_grid"

paged="true" pagesize="10"

bordersize="1">

We created a datagrid object similar to thedatagrid in hello_world.jsp. You can give thecontrol any name you like, provided it is uniquewithin the context of the form.

<dmf:datagridRow> <td> <dmf:label

datafield="object_name" /> </td> <td>

<dmf:datevalueformatter type="short">

<dmf:label datafield="r_modify_date"

/> </dmf:datevalueformatter> </td>

</dmf:datagridRow>

The datagridRow is similar to the one youcreated for hello_world.jsp. The one twist isthat you are accessing a field with a date value.As passed from the repository, the date isrepresented as the number of milliseconds thathave passed since January 1, 1970 00:00:00.000GMT; this is convenient for storage, but lessso for your users. To display the value as ahuman‑readable date, you wrap date valuesin <datevalueformatter> tags. You can set theformat type attribute to “short,” “medium,” or“long.”

In order to use the hello_detail.jsp with the component, we need to update thehello_world_component.xml configuration file.

To update the hello_world_component.xml configuration file

1. Using a text editor, open <WEBTOP_ROOT>\custom\config\hello_world_component.xml.

2. Add the following line after the <start> tag<detail>/custom/hello_world/hello_detail.jsp</detail>

3. Save your work. The configuration file should now match the following listing.<?xml version="1.0" encoding="ISO88591" standalone="no"?><config version="1.0">

<scope><component id="hello_world_component">

<pages><start>/custom/hello_world/hello_world.jsp</start><detail>/custom/hello_world/hello_detail.jsp</detail>

</pages><class>com.mycompany.custom.HelloWebtop</class><nlsbundle>com.mycompany.hello_world.HelloWorldProp</nlsbundle>


Hello Webtop


</config>

Next, we will update the hello_world.jsp to display the user_name as a link rather than a label.

To update hello_world.jsp to display user_name as a link

1. Using a text editor, open <WEBTOP_ROOT>\custom\hello_world\hello_world.jsp

2. Replace this line<dmf:label datafield="user_name" />

with<dmf:link datafield="user_name" onclick="onClickLink" ><dmf:argument name="user_name" datafield="user_name" />

</dmf:link>

3. Save your work. The file should now match the following program listing.<%@page contentType="text/html"%><%@ page errorPage="/wdk/errorhandler.jsp" %><%@ taglib uri="/WEBINF/tlds/dmform_1_0.tld" prefix="dmf" %>

<html><dmf:head>

<dmf:webform /></dmf:head>

<body><dmf:form><p><dmf:label nlsid="MSG_STATIC_TEXT" /><p><dmf:label name="STATIC_TEXT"/></p><p>Current repository: <dmf:label name="CURRENT_REPOSITORY"/></p><h1>List of Users</h1><dmf:datagrid name="mygrid" paged="true" pagesize="10"><tr>

<th>User Name</th><th>User Group Name</th>

</tr><dmf:datagridRow>

<td><dmf:link datafield="user_name" onclick="onClickLink" >

<dmf:argument name="user_name" datafield="user_name"/></dmf:link>

</td><td>

<dmf:label datafield="user_group_name"/></td>

</dmf:datagridRow></dmf:datagrid>

</dmf:form></body></html>

We have created a link, which will send the user_name to the Java behavior class. Now we need tocreate the onClickLink() method so that the class will know what to do with the user_name once itis received.


Hello Webtop

To update the Java behavior class with the onClickLink() method

1. Using a text editor or Java IDE, open the Java source file com.mycompany.custom.HelloWebtop.java.

2. Add an import statement for the Link class at the top of the file.import com.documentum.web.form.control.Link;

3. Enter the following code after the onRender() method.public void onClickLink(Link theLink, ArgumentList arg)this.setComponentPage("detail");

Label label = null;try label = (Label) getControl("modifierLabel", Label.class);

catch (Exception ex) if(label == null) label = (Label)createControl("modifierLabel", Label.class);

label.setLabel(arg.get("user_name"));Datagrid datagrid = null;trydatagrid = (Datagrid) getControl("my_doc_list_grid",Datagrid.class);

catch (Exception ex)if(datagrid == null)datagrid = (Datagrid)createControl("my_doc_list_grid",Datagrid.class);

datagrid.getDataProvider().setDfSession(getRepositorySession());datagrid.getDataProvider().setQuery("select object_name, " +"r_modify_date, r_modifier from dm_document where " +"r_modifier = \'" + arg.get("user_name") + "\';");


4. Save and compile the file. It should now match the following code listing.package com.mycompany.custom;

import com.documentum.web.common.ArgumentList;import com.documentum.web.formext.component.Component;import com.documentum.web.form.control.Label;import com.documentum.web.form.control.Link;import com.documentum.web.form.control.databound.Datagrid;import com.documentum.web.formext.session.SessionManagerHttpBinding;import com.documentum.fc.client.IDfSession;import com.documentum.fc.client.IDfSessionManager;import com.documentum.fc.common.DfException;import com.documentum.fc.client.DfIdentityException;import com.documentum.fc.client.DfAuthenticationException;import com.documentum.fc.client.DfPrincipalException;import com.documentum.fc.client.DfServiceException;

public class HelloWebtop extends Component public void onInit(ArgumentList arg)super.onInit(arg);


Hello Webtop

public void onRender() super.onRender();Label staticText = (Label) getControl("STATIC_TEXT",Label.class);staticText.setLabel("A static text value from the Java class.");

Label currentRepository =(Label) getControl("CURRENT_REPOSITORY",Label.class);








public void onClickLink(Link theLink, ArgumentList arg)

this.setComponentPage("detail");

Label label = null;try

label = (Label) getControl("modifierLabel", Label.class);catch (Exception ex)

if(label == null) label = (Label)createControl("modifierLabel", Label.class);

label.setLabel(arg.get("user_name"));


datagrid = (Datagrid) getControl("my_doc_list_grid",Datagrid.class);

catch (Exception ex)if(datagrid == null)

datagrid = (Datagrid)createControl("my_doc_list_grid",Datagrid.class);datagrid.getDataProvider().setDfSession(getRepositorySession());

datagrid.getDataProvider().setQuery("select object_name, " +"r_modify_date, r_modifier from dm_document where " +"r_modifier = \'" + arg.get("user_name") + "\';");

datagrid.getDataProvider().refresh();private String getCurrentRepositoryName()



Hello Webtop

repositoryName = dfSession.getDocbaseName();

catch (DfException e)



IDfSessionManager sessionManager = null;IDfSession dfSession = null;try



System.out.println("Error while obtaining Session. Id exception"+ dfe.getMessage());






We will look at a couple of interesting lines of code from the new method you entered.

public void onClickLink(Link theLink,

ArgumentList arg)

The onRender() method takes no arguments.When the user clicks the link, we need theselected user_name for your query. Allarguments are passed to the Java class in a singleArgumentList object. The onClickLink methodrequires the name of the component that madethe call, followed by the list of arguments.

this.setComponentPage("detail");When the user clicks a link, the first thingthe code does is set the current page for thecomponent to the new detail page we justcreated.


Hello Webtop

label = (Label)

getControl("modifierLabel",

Label.class); ...

label.setLabel(arg.get("user_name"));

We create an instance of Label and use it torepresent the modifierLabel control on detail.jsp.(The omitted code is the catch clause that createsa new control if for some reason the getControlmethod fails). Once we have a label control, wecan populate it with the user_name argument.

datagrid = (Datagrid) getControl("my_

doc_list_grid",Datagrid.class);

We use the same syntax to create a Datagridcontrol that we used to create the Label control,only changing the class and specific name of thecontrol we want to create.

datagrid.getDataProvider().

setDfSession(

getRepositorySession());

datagrid.getDataProvider().setQuery(

"select object_name, r_modify_date,

" + "r_modifier from dm_document

where " + "r_modifier = \'" +arg.get("user_name") + "\';");


These lines are similar to the query used topopulate the user_list datagrid. Rather than usea static argument, though, we have created adynamic query based on the selected user_name.Webtop refreshes the datagrid and displays theresults.



Hello Webtop

The user names are now displayed as links (note the underscores beneath the obscured names).


Hello Webtop

Click one of the names to display a list of documents modified by that user.

To recap, we have done the following:• configured the Webtop menubar to display a custom command• configured the action triggered by selecting the custom command• configured a component that can be launched by the custom action• created a custom JSP using WDK/Webtop controls• populated controls with static values from a properties file and from a Java class• populated controls with dynamic values based on DQL queries


Hello Webtop

• used the results of one query to open a second component page with detail informationThat is a lot of ground to cover in a Hello World example, but when you extend Webtop, you will findthat most of the work has been done for you.


Chapter 5Creating a Start Page for a New WDKApplication

Creating aWDK application from the ground up is a massive undertaking. It is strongly recommendedthat you customize the Webtop application rather than attempt to create a completely new userinterface. However, if you have examined the features of Webtop and have determined that you

Most Web applications are accessed through an index.html or default.html page. This is the startingpoint of your application. WDK does not require an index page, but it’s a best practice to have one.

In this tutorial, you define a welcome page with a JavaScript function that redirects to the drilldowncomponent. The drilldown component is a navigation component that will be the starting point of thenew application. If the user has not logged in to the application, then the login component will beinvoked from the drilldown component class, and the user will be prompted to log in.

Note: Any component that requires a session will launch the login dialog if the user does not have asession. You do not need to call the login component explicitly.

Use the following procedure to create an index.html start page for your application.

To create a start page:

1. Create a new file called index.html in the tomcat_home/webapps/virtual_dir directory, wheretomcat_home is the directory in which Tomcat is installed, and virtual_dir is the virtual directoryinto which you installed WDK.

2. Add the following text:<html><head><script>function redirect()var strPath = window.location.pathname;var nIndex1 = strPath.indexOf("/");var nIndex2 = strPath.indexOf("/", nIndex1 + 1);var strVirtualDir = strPath.substring(nIndex1 + 1, nIndex2);window.location.replace("/" + strVirtualDir +"/component/drilldown?Reload=" +

new Date().getTime());


Creating a Start Page for a New WDK Application

</script>

</head>

This JavaScript defines a function called redirect, which gets the root URL for the Web application,adds to it the drilldown component URL, then tacks on an argument with the current date andtime, which will force a reload of the page every time it is accessed.

3. Add the following <body> tag:<body onload="redirect()"></body></html>

This tag contains a call to the JavaScript function that you just created.

4. Save the file.

5. Test your page by starting a browser and entering the following address (after ensuring thatTomcat is running):http://server_name:port_number/virtual_dir/index.html

The address should immediately change tohttp://server_name:port_number/virtual_dir/component/drilldown

If you have not previously logged in, the login page will be displayed. After log in, you see thedrilldown page, shown in the following figure.



Figure 13. PostLogin Drilldown Page

If you see a blank page instead of the login screen, check for typos in the index.html file.

Variations on This TutorialInstead of redirecting to the drilldown component, you could redirect to the doclist component, whichcombines folders and their contents in a single view.



Instead of redirecting directly to doclist or drilldown, you could have the start page redirect to themain component. Since the WDK main component is a blank page, you would need to configure orcustomize the main component to display the views that you choose.


Chapter 6Adding a Logout Link

The following tutorial shows you how to add a Logout link to the drilldown page. The tutorialcontains the following sections:• Task Objective, page 73• Technical Overview, page 74• Creating the Custom Layer Files, page 75• Extending the Drilldown Component, page 76• Modifying the Generic Actions XML File, page 76• Creating a Custom Resource File, page 77• Testing the Logout Link, page 78• Extending the Logout Action, page 78• Variations on This Tutorial, page 79

Task ObjectiveWebtop and other WDK client applications have Logout buttons, but WDK has no logout link orbutton in the UI out of the box. Suppose that you want to add a Logout link to the drilldown pagesin a WDK application, which will return the user to the start page with a login screen. The Logoutlink should appear as in the upper right of the following figure.


Adding a Logout Link

Figure 14. Drilldown Page with Logout Link

Technical OverviewThe drilldown component (used by default in WDK) is defined in the XML resource filedrilldown_component.xml, which points to the start page drilldown.jsp. The drilldown.jsp itselfpoints to drilldown_body.jsp, and drilldown_body.jsp contains an actionlinklist control to which youwill add the Logout link. First, you must change the logout action.

The logout action is defined in session_actions.xml in the WDK layer. It includes a <homeurl> element,which points to a post‑logout location. In Webtop and Web Publisher, this <homeurl> element callsthe logoff component, a sessionless component in the WDK layer that invalidates the current sessionand calls the drilldown component, with the login screen appearing first. The logoff component isimportant for controlling the number of open sessions.

Once the user clicks the Logout link, the LogoutAction class calls /wdk/logout.jsp, and logout.jspredirects to dologout.jsp, which contains a client‑side initialization containing an onLogout clientevent. This onLogout client event fires only if an onLogout event handler is registered. If none isregistered, then the onInit() JavaScript function in logout.jsp changes the location of the top frame towhatever is configured in the <homeurl> parameter of the logout action:/** Clientside Initialization */function onInit()

var homeUrl = "<%=session.getAttribute("_logoutactionurl")%>";if (isClientEventHandlerRegistered("onLogout"))

fireClientEvent("onLogout", homeUrl);else

getTopLevelWnd().location.replace(homeUrl);

(The script that tests whether a handler for a given client event has been registered is invirtual_dir/wdk/include/events.js.)



In Webtop and in the Webtop layer of applications that are based on Webtop, the client‑side eventhandler, onLogout, is defined in main.js:function onLogout(homeURL)if (homeURL != null && homeURL != "")document.location.replace(homeURL);

In this tutorial, the <homeurl> element will be configured so that it calls the logoff component, similarto Webtop and other client applications.

This tutorial involves the following procedures:• Creating the files in the custom layer• Extending the drilldown component XML definition to point to a custom properties file that

contains text for the Logout link• Modifying the list of actions displayed by the actionlinklist control to include a Logout link• Extending the properties file that contains the resource strings for the drilldown component so

that it contains the Logout link text• Extending the logout action to call the logoff component

Creating the Custom Layer FilesUse the following procedure to set up the custom layer.

To create the files for the customization:

1. Copy the following file:virtual_dir/wdk/config/session_actions.xml

to the following location:virtual_dir/custom/config

2. Copy the following file:virtual_dir/webcomponent/config/navigation/drilldown/drilldown_component.xml

to the following location:virtual_dir/custom/config

3. Copy the following file:virtual_dir/webcomponent/config/actions/generic_actions.xml

to the following location:



virtual_dir/custom/config

4. Create a new text file named MyDrillDownNlsProp.properties in the following location (creatingthe directory structure if necessary):virtual_dir/WEBINF/classes/com/mycompany/drilldown

Extending the Drilldown ComponentThe following procedure extends the drilldown component to point to the custom properties file.

To modify the XML resource file:

1. Open the following file:virtual_dir/custom/config/drilldown_component.xml

2. Change the <component> start tag as follows:<component id="drilldown" extends="drilldown:webcomponent/config/navigation/drilldown/drilldown_component.xml">

This will extend the drilldown component that is defined in the default resource file.

3. Change the <nlsbundle> element as follows:<nlsbundle>com.mycompany.drilldown.MyDrillDownNlsProp</nlsbundle>

This points to the empty properties file you created in the custom layer.

4. Save the file and close it.

Tip: When you make modifications to an XML file, check to see that the XML is well formed so itdoes not cause problems later. One easy way to do this is to open the XML file in MicrosoftInternet Explorer.

Modifying the Generic Actions XML FileThere are two JSP pages involved with the drilldown component, which is displayed after login:drilldown.jsp calls drilldown_body.jsp. The drilldown_body.jsp file includes an actionlinklist controlthat displays the available actions:<dmfx:actionlinklist listid='containeractions' name='container_action_list'

cssclass='actions' separatorhtml='</nobr><nobr>'><! arguments passed to folder actions><dmfx:argument name='objectId' contextvalue='objectId'/><dmfx:argument name='folderId' contextvalue='parentId'/><dmf:argument name='startworkflowId' value='startworkflowdrilldown'/>

</dmfx:actionlinklist>



The listid attribute of the actionlinklist (id=’container‑actions’) corresponds to the name of an actionlist in generic_actions.xml. To add the Logout action, update the container‑actions actionlist in acustom version of generic_actions.xml.

To modify generic_actions.xml:

1. Open the following file:virtual_dir/custom/config/generic_actions.xml

2. Locate the beginning of the container‑actions actionlist element and change it as follows:<actionlist id="containeractions"

extends="containeractions:webcomponent/config/actions/generic_actions.xml">

3. Add the Logout action immediately before the closing tag for the <actionlist> element:<action id='logout' nlsid='MSG_LOGOUT'/>

</actionlist>


Creating a Custom Resource FileThe resource string that you specified in the actionlink, namely MSG_LOGOUT, is defined in someWDK resource files, but not in DrillDownNlsProp. You must define this string in the customproperties file you created in the custom layer and pointed to from the XML resource file.

To define a custom resource string:

1. Open the following file:virtual_dir/WEBINF/classes/com/mycompany/drilldown/

MyDrillDownNlsProp.properties

2. Add the following two lines. (The first two lines shown here should be on one line in your file.)NLS_INCLUDES=com.documentum.webcomponent.navigation.drilldown.DrillDownNlsPropMSG_LOGOUT=Logout

These lines include the DrillDownNlsProp.properties file in the default location and define oneadditional resource string, which is referenced in the nlsid attribute MSG_LOGOUT for the actionthat you added to the actionlist definition.




Testing the Logout LinkThe Logout link should now be functional, and you can test it before making other changes.

To test the Logout link:

1. Stop and restart the application server. (You must restart the application server to pick up changesto .properties files.)

2. Enter the following address:http://http://server_name:port_number/virtual_dir/index.html

After you log in, the drilldown page should appear, with the new Logout link in the upperright‑hand corner as shown below.

3. Click the Logout link. For now, this should result in the display of a generic Action canceledbrowser page.

Extending the Logout ActionThe following procedure extends the logout action to call the logoff component.

To extend the logout action:

1. Open the following file:virtual_dir/custom/config/session_actions.xml

2. Change the logout <action> start tag as follows:<action id="logout" extends="wdk/config/session_actions.xml">

3. Change the <homeurl> element as follows:<homeurl>/component/logoff</homeurl>

This will call the logoff component when the logout action is invoked.




5. Refresh the configuration service and test the Logout link as in the previous procedure.This time when you click the Logout button, you should see a logout message with a link toreturn to the login page.

Variations on This TutorialAdding a Logout link is not necessary in Webtop or Web Publisher, since the default applications useLogout buttons. However, you could use this tutorial as the basis for modifying other action controls.For example, you could change any actionbutton to an actionlink or vice versa. You could also changethe actionlinklist to an actionbuttonlist in drilldown_body.jsp The actionbutton control requiresadditional attributes related to the button image and the placement of text on the button. For moreinformation, see theWeb Development Kit and Webtop Reference Guide.


Chapter 7Creating an Action List Component

This tutorial requires both configuration and customization to display a list of all actions configured inyour Web application. Each action has a link to an information page about the action that displaysthe action class, parent action definition, container and component launched, if any, parameters, andother configurable elements.

The full source code for this customization is located on the Documentum developer site,developer.documentum.com.

The tutorial contains the following sections:• Task Objective, page 81• Technical Overview, page 83• Creating the Component Definition, page 83• Creating the Component Layout, page 84• Creating the Component Class, page 86• Supporting Navigation Between Pages, page 87• Creating the Action List Datagrid, page 88• Creating the Action Info Datagrid, page 91• Creating the Resource Bundle, page 95• Testing the Customization, page 96• Variations on This Tutorial, page 96

Task ObjectiveIn this tutorial, you will create a simple action list component that reads information from all of theaction definition files in your application and displays them in two UI pages: a list of actions, and adrilldown page that displays info for an action.

After customization, the action list component start page will look similar to the one shown in thefollowing figure:


http://developer.documentum.com

Creating an Action List Component

Figure 15. Action List Page

When you click on an individual action in the list, the info page will look similar to the one shown inthe following figure:

Figure 16. Action Info Page



Technical OverviewWDK contains a componentlist component that gets and displays a list of all component definitions inmemory and information for each component.

You will use the componentlist component as a model for a new actionlist component.

Creating the Component DefinitionTo create a new WDK actionlist component, you must create a component definition. The best way tocreate a component definition is to copy the configuration file for a similar component, then makeany necessary changes.

To create the actionlist definition:

1. Copy the componentlist component configuration file from /webcomponent/config/componentList/component_list.xml to the following location :/custom/config

2. Rename the file to actionlist_component.xml.

3. Open the file and locate the <desc> element. Change it to the following content:Action list: Displays outline information on all ofthe defined actions in the application

4. Locate the <component> element. Change it to the following content:<component id="actionlist">

5. Change the value for the <pages><start> element to the following:/custom/actionlist/actionList.jsp

6. Locate the <pages> element and replace the <componentinfo> element and contents with thefollowing element and contents:<actioninfo>/custom/actionlist/actionInfo.jsp</actioninfo>

7. Locate the <class> element and change the value to the following class that you will create:com.mycompany.actionlist.ActionList

8. Locate the <nlsbundle> element and change the value to the following NLS resource that youwill create:com.mycompany.actionlist.ActionListNlsProp

9. Save and close the file.



Creating the Component LayoutYou can modify the componentlist layout pages to provide a similar layout for the action list.

To create the layout for the action list:

1. Copy the componentlist JSP page from /webcomponent/componentList/componentlist.jsp to/custom/actionlist. Create a /custom/actionlist directory if one does not exist.

2. Rename the file to actionlist.jsp, and open the file.

3. Locate the following file import tag:<%@ page import="com.documentum.webcomponent.componentList.ComponentList" %>

Change the imported class to the following:com.mycompany.actionlist.ActionList

4. Locate the following tag:<dmf:label nlsid='MSG_NUM_COMPONENTS'/>: <%= "" +ComponentList.getNumberOfComponents()%>\

Change the tag contents to the following:<dmf:label nlsid='MSG_NUM_ACTIONS'/>: <%= "" +ActionList.getNumberOfActions()%>\

5. Locate following tag:<dmf:datagrid name='<%=ComponentList.COMPLIST_GRID%>'...>

Change the name of the datagrid from ComponentList.COMPLIST_GRID toActionList.ACTIONLIST_GRID

6. Remove the table header rows (<th ...> ...</th>) that contain the following labels (for example,dmf:label nlsid=):MSG_ISCONTAINERMSG_ISCONFIGURABLEMSG_DESCRIPTION

Reason: These columns are not relevant for actions.

7. Locate the label tag (<dmf:label...>) with the following nlsid attribute value:MSG_COMPONENT_ID

Change the nlsid value to the following:MSG_ACTION_ID

8. Locate the <dmf:link> tag with the onclick event handler value onClickCompId.Change the onclick event handler value to onClickActionId. Change the datafield value fromcompid to actionid. The action ID will be displayed for the link.Change the inner <dmf:argument> name from compcfgid to actioncfgid. Change the datafieldfrom compcfgid to actioncfgid. The indexed action ID will be passed to the event handler.



9. Locate the <dmf:label> tag whose name attribute value is compscope.Change the name attribute value to actionscope and the datafield value to actionscope.

10. Locate the <dmf:link> tag whose onclick event handler is onClickXML.Change the datafield value from compxml to actionxml, which is the base URL for the action.The link will display the base URL.Change the inner <dmf:argument> name from compxmlurl to actionxmlurl and the datafield fromcompxmlurl to actionxmlurl. This inner argument will pass the full URL to the event handler.

11. Remove the table cells (<td>...</td>) for isContainer, isConfigurable, and description. These labelsare not applicable to an action definition. Do not delete the cells between the label isconfigurableand the label desc. In other words, delete the following lines only:<td nowrap=""><dmf:label name="iscontainer" datafield="iscontainer"/></td><td nowrap=""><dmf:label name="isconfigurable" datafield="isconfigurable"/></td>...//leave these lines in<td nowrap=""><dmf:label name="desc" datafield="desc"/></td>

12. Save and close the JSP file.

To create the layout for action info:

1. Copy the componentinfo JSP page from /webcomponent/componentList/componentinfo.jsp to thefollowing location: /custom/actionlist

2. Rename the file actionInfo.jsp and open the file in the editor.

3. Locate the following file import tag:<%@ page import="com.documentum.webcomponent.componentList.ComponentList" %>

Change the imported class to the following:com.mycompany.actionlist.ActionList

4. Locate following tag:<dmf:datagrid name='<%=ComponentList.COMPINFO_GRID%>'...>

Change the name of the datagrid from ComponentList.COMPINFO_GRID toActionList.ACTIONINFO_GRID.

5. Locate the <dmf:link> tag whose name is lnkback.Change the value of the onclick attribute from onClickCompList to onClickActionList




Creating the Component ClassThe following procedure uses the ComponentList class as a model for the actionlist componentbehavior class.

Caution: You can copy and paste code from the PDF tutorial, but certain symbols may bechanged when you paste them into your IDE. For example, the symbol “&” may be changed to& and the “<” symbol may be changed to <. The single quote (') may be changed toa curly quote. The NetBeans IDE compiler will show the line containing the error. You mustensure that these symbols are correct in your IDE before you compile.

You can get the full source code for this tutorial on the Documentum developer site,developer.documentum.com.

To create the component class:

1. In the NetBeans IDE, create a directory /WEB‑INF/classes/com/mycompany/actionlist. .

2. Create a new Java class by right‑clicking on the directory WEB‑INF/classes/mycompany/actionlistand selecting New?Java Class.

3. Name the object ActionList and click Finish.The file will be created with the following lines:package com.mycompany.actionlist;public class ActionListpublic ActionList()

Note: If the package line appears different from that shown above, then either the WEB‑INFclasses directory was not mounted correctly, or you created the file within the wrong directory.

4. In the Source Editor window, following the package declaration, add the following importstatements:import com.documentum.web.common.ArgumentList;import com.documentum.web.form.control.Link;import com.documentum.web.form.control.databound.Datagrid;import com.documentum.web.form.control.databound.TableResultSet;import com.documentum.web.formext.component.Component;import com.documentum.web.formext.config.ConfigFile;import com.documentum.web.formext.config.ConfigService;import com.documentum.web.formext.config.IConfigElement;import java.util.ArrayList;import java.util.Arrays;import java.util.HashMap;import java.util.Iterator;




5. Next, edit the class definition that was created by NetBeans, adding an extends clause and someclass variables:public class ActionList extends Componentpublic static final String ACTIONLIST_GRID = "_actionlist_grid";public static final String ACTIONINFO_GRID = "_actioninfo_grid";private HashMap m_hashCfgElementLookup;private HashMap m_hashCfgScopeLookup;public ActionList()

6. Within the class constructor that was provided by NetBeans IDE when you created the class,instantiate hash maps to hold the action IDs and scopes:public ActionList()m_hashCfgElementLookup = new HashMap(23);m_hashCfgScopeLookup = new HashMap(23);

7. After the constructor, add an onInit() implementation that gets or creates the datagrids on both ofthe JSP pages:public void onInit(ArgumentList args)super.onInit(args);getControl("_actionlist_grid", com.documentum.web.form.control.databound.Datagrid.class);

getControl("_actioninfo_grid", com.documentum.web.form.control.databound.Datagrid.class);

//updateActionList();

The last call is to the updateActionList() method, which has not yet been created. This call must becommented out for now. See Creating the Action List Datagrid, page 88 for information on theupdateActionList() method, which creates or updates the actionlist datagrid.

8. Add a method that counts the number of actions that are defined in the application:public static int getNumberOfActions()return ConfigService.getPrimaryElementIds("action").length;

9. Compile your class file. Note any errors in the output window and resolve them. The exactlocation of the error is noted by the compiler.

Supporting Navigation Between PagesThe actionlist JSP page lists all actions, and each action contains a link to the info page. The linkrequires an event handler, onClickActionId().



The actioninfo page displays information for an action and contains a link to return to the actionlistpage. This link requires an event handler, onClickActionList().

To add navigation support between layout pages:

1. Within the class implementation, add an event handler for the onClickActionId event that islaunched by a link on the actionlist.jsp page. This event handler gets the selected action ID, calls amethod that gets the info for the selected action, and navigates to the actioninfo JSP page:public void onClickActionId(Link link, ArgumentList arg)String strCfgid = arg.get("actioncfgid");//updateActionInfo(strCfgid);setComponentPage("actioninfo");

Note: You will uncomment the call to the updateActionInfo() method after you have createdthat method and its helper methods.

2. Add an event handler for the onClickActionList event that is launched by a link on theactioninfo.jsp page. This event handler navigates back to the actionlist JSP page:public void onClickActionList(Link link, ArgumentList arg)setComponentPage("start");

3. Right‑click and compile your class file. Note any errors in the output window and resolve them.The exact location of the error is noted by the compiler.

Creating the Action List DatagridIn the ActionList class, you must add several methods that populate or update the action list datagrid.(The datagrid displays a list of all actions.) The main method, updateActionList(), gets the data, andseveral helper methods get information to provide to the datagrid.

To update the action list:

1. Uncomment the following line from the onInit() method by removing the “//” symbols://updateActionList();

2. Create the update method signature and get all action IDs from the ConfigService in‑memorytables:protected void updateActionList()String strActionIds[] = ConfigService.getPrimaryElementIds("action");

Arrays.sort(strActionIds);



3. Create datafields for values of elements in the action definitions: a datafield for indexed action ID,action ID, scope, base action definition URL, and full path to the action definition URL. Add thefollowing lines to the unfinished method updateActionList():String strDataFields[] ="actioncfgid", "actionid", "actionscope", "actionxml", "actionxmlurl";

4. Create a TableResultSet to provide the data to the datagrid. Add the following line to theunfinished method updateActionList():TableResultSet rsList = new TableResultSet(strDataFields);

5. Iterate through the array of action IDs. Put the definition for each action ID into an array andput the scope for each definition into another array. Add the following lines to the unfinishedmethod updateActionList():for(int idxActionId = 0; idxActionId < strActionIds.length; idxActionId++)String strActionId = strActionIds[idxActionId];IConfigElement icfgEls[] = ConfigService.getPrimaryElements("action[id=" + strActionId + "]");

String strScopes[] = ConfigService.getPrimaryElementScopes("action[id=" + strActionId + "]");

6. Iterate through the array of configuration definitions and put each action ID and scope into a hashmap. Add the following lines to the unfinished method updateActionList():for(int idxEl = 0; idxEl < icfgEls.length; idxEl++)ArrayList listRow = new ArrayList(strDataFields.length);String strCfgElId = strActionId + "." + idxEl;m_hashCfgElementLookup.put(strCfgElId, icfgEls[idxEl]);m_hashCfgScopeLookup.put(strCfgElId, strScopes[idxEl]);

7. Add to the unfinished updateActionList() method list rows for the following data, as shownin the code snippet below:• Indexed action ID (strCfgElId), because there are duplicate action IDs when they have

multiple scopes• Action ID (for display; uses indexed ID for retrieval)• Scope• Configuration file link text (for display; uses full path to configuration file for retrieval)• Full path to configuration filelistRow.add(strCfgElId);listRow.add(strActionId);listRow.add(strScopes[idxEl]);listRow.add(getConfigFilePath(icfgEls[idxEl]));listRow.add(getConfigFileUrl(icfgEls[idxEl]));

You will see red error symbols next to the lines that call getConfigFilePath() and getConfigFileUrl().You have not yet created these helper methods.



8. Add the row of data for the unique action definition to the result set, and after iteration set theresult set on the datagrid. Add the following lines to the unfinished method updateActionList():

rsList.add(listRow);

((Datagrid)getControl("_actionlist_grid", com.documentum.web.form.control.databound.Datagrid.class)).getDataProvider().setResultSet(rsList, null);

Note: Do not compile your class file. You must add some supporting methods before your classwill compile properly.

Three methods are used to generate the configuration file path for display and the configuration fileURL for the link target. Add these methods after the closing bracket of the updateActionList() method:

To support the action list update:

1. getConfigFile() returns the configuration file for the primary element. Add the following methodafter the updateActionList() method:private ConfigFile getConfigFile(IConfigElement icfgEl)ConfigFile file;for(file = null; file == null && icfgEl != null;icfgEl = icfgEl.getParent())

if(icfgEl instanceof ConfigFile)file = (ConfigFile)icfgEl;

return file;

2. getConfigFilePath() uses ConfigFile.getPathName() to read the path to the configuration file onthe file system:

private String getConfigFilePath(IConfigElement icfgEl)ConfigFile file = getConfigFile(icfgEl);String strXMLFileName = file.getPathName().replace('\\', '/');return strXMLFileName;

3. getConfigFileUrl returns the URL that will launch the configuration file in the browser when theuser clicks the config file link (browser must be IE to display an XML file)private String getConfigFileUrl(IConfigElement icfgEl)String strBaseAppDir =getPageContext().getServletContext().getRealPath("");

if(strBaseAppDir != null)strBaseAppDir = strBaseAppDir.replace('\\', '/');



elsestrBaseAppDir = "";

String strXMLFileName = getConfigFilePath(icfgEl);int idxBaseAppDir = strXMLFileName.indexOf(strBaseAppDir);String strUrl = strXMLFileName;if(idxBaseAppDir == 0)strUrl = strXMLFileName.substring(strBaseAppDir.length());strUrl = getBaseUrl() + strUrl;

return strUrl;

4. At this point, you should have no red markers for errors in your class file. If you do, check yourcode against the class file on the Developer Web site and correct your errors. Right‑click andcompile your class file. Note any errors in the output window and resolve them. The exactlocation of the error is noted by the compiler.

Creating the Action Info DatagridContinuing the same action class from the previous section, you must add several methods thatpopulate or update the action info datagrid. The main method, updateActionInfo(), gets the data, andseveral helper methods get information to provide to the datagrid.

To update the action info page:

1. Uncomment the following line from the method onClickActionId():updateActionInfo(strCfgid)

2. Create the update method signature and get the selected action ID from the hash table that waspopulated by updateActionList():protected void updateActionInfo(String strCfgId)IConfigElement cfgel = (IConfigElement)m_hashCfgElementLookup.get(strCfgId);

3. Create a datafield string array and a TableResultSet to provide the data to the datagrid. Add thefollowing lines to the unfinished updateActionInfo() method:String strDataFields[] =

"propname", "propvalue";TableResultSet rsList = new TableResultSet(strDataFields);

4. Add list rows for the following data, as shown in the code snippet below. (Helper methods thatprovide the data are described in the next procedure.). Add the following lines to the unfinishedupdateActionInfo() method:



• Action ID• Scope• Action execution class• Component launched by the action, if any• Container launched by the action, if any• XML file that contains the action definition• List of parameters, with optional or required labeladdRowFromAttribute(rsList, cfgel, "MSG_ACTION_ID", "id");rsList.add(new String[] getString("MSG_SCOPES"), (String)m_hashCfgScopeLookup.get(strCfgId));

rsList.add(new String[] getString("MSG_EXTENDS"), getExtends(cfgel));

rsList.add(new String[] getString("MSG_CLASS"), getActionClass(cfgel));

rsList.add(new String[] getString("MSG_EXECCOMP"), getLaunchedComponent(cfgel));

rsList.add(new String[] getString("MSG_EXECCONTAINER"), getLaunchedContainer(cfgel));

rsList.add(new String[] getString("MSG_XML_FILE"), getConfigFilePath(cfgel));

addParameterRows(rsList, cfgel);

You will see red error symbols next to the lines containing calls to nonexistent methods. You willadd those methods later. The getConfigFilePath() method was created in an earlier procedure.

5. Set the result set on the datagrid by adding the following lines to finish the method:((Datagrid)getControl("_actioninfo_grid",

com.documentum.web.form.control.databound.Datagrid.class)).getDataProvider().setResultSet(rsList, null);

Note: Do not compile your class file. You must add some supporting methods before the classwill compile properly

Several methods are used to generate row data for the info datagrid. Add the following methods afterthe closing bracket of the updateActionInfo() method:

To support the action info update

1. Add the method addRowFromAttribute(), which adds a row containing the value of the suppliedattribute.private void addRowFromAttribute(TableResultSet rsList, IConfigElement cfgAction, String strTitleNlsId,String strAttributeName)

String strValue = cfgAction.getAttributeValue(strAttributeName);if(strValue != null && strValue.length() > 0)rsList.add(new String[] getString(strTitleNlsId), strValue);



2. Ad the method getExtends(), which gets the value of the extends attribute. This will display thename of the action that the current action extends.private String getExtends(IConfigElement icfgEl)String strExtends = icfgEl.getAttributeValue("extends");if(strExtends != null)return strExtends;

elsereturn getString("MSG_NONE");

3. Add the method getActionClass(), which gets the fully qualified action class name.private String getActionClass(IConfigElement icfgEl)IConfigElement cfgExec = icfgEl.getChildElement("execution");if(cfgExec != null)String strClass = cfgExec.getAttributeValue("class");if(strClass != null)return strClass;



4. Add the method getLaunchedComponent(), which gets the name of the component that islaunched by the action, if any.private String getLaunchedComponent(IConfigElement icfgEl)IConfigElement cfgExec = icfgEl.getChildElement("execution");if(cfgExec != null)String strComp = cfgExec.getChildValue("component");if(strComp != null)return strComp;


else



return getString("MSG_NONE");

5. Add the method getLaunchedContainer(), which gets the name of the container that is launchedby the action, if any.private String getLaunchedContainer(IConfigElement icfgEl)IConfigElement cfgExec = icfgEl.getChildElement("execution");if(cfgExec != null)String strContnr = cfgExec.getChildValue("container");if(strContnr != null)return strContnr;



6. Add the method addParameterRows(), which reads the parameters from the XML file.private void addParameterRows(TableResultSet rsList, IConfigElement cfgAction)

IConfigElement iParams = getApplicableChildElement(cfgAction, "params");String strNlsParams = getString("MSG_PARAMS");if(iParams != null)int nParams = 0;for(Iterator itParams = iParams.getChildElements("param"); itParams.hasNext();)

IConfigElement iParamEl = (IConfigElement)itParams.next();String strParam = iParamEl.getAttributeValue("name");String strRequired = iParamEl.getAttributeValue("required");if(strRequired != null)strParam = strParam + (strRequired.equalsIgnoreCase("true") ? " (required)" : " (optional)");

rsList.add(new String[] strNlsParams, strParam );nParams++;

7. Add the method getApplicableChildElement(), which is a helper method that gets multipleparameter values:



private IConfigElement getApplicableChildElement(IConfigElement cfgAction,String strCfgElementName)

IConfigElement el;for(el = null; cfgAction != null && el == null;cfgAction = ConfigService.getExtendedElement(cfgAction))

el = cfgAction.getChildElement(strCfgElementName);

return el;

8. At this point, you should have no red markers for errors in your class file. If you do, check yourcode against the class file on the Developer Web site and correct your errors. Right‑click andcompile your class file. Note any errors in the output window and resolve them. The exactlocation of the error is noted by the compiler.

Creating the Resource BundleIn Creating the Component Definition, page 83 you specified an NLS resource bundle that will containthe strings for your component: com.mycompany.actionlist.ActionListNlsProp.

To create a properties file in the new directory

1. Open theNetBeans explorer Filesystems tab.

2. Create the directory /custom/strings/com/mycompany/actionlist.

3. Right‑click the mycompany directory, and select New?All Templates.

4. Open the Other templates group and click Text File.

5. Click Next and name the file ActionListNlsProp.

6. Click Next and add the properties extension.

7. Click Finish.Because you added the properties extension, NetBeans displays a page for editing property values.You can also open this page as a text file by right‑clicking the file in the tree and selecting Edit.

8. Add each of the following key and value pairs by clicking the New Property button and filling inthe dialog box that appears:MSG_NUM_ACTIONS = Number of Action DefinitionsMSG_ACTION_ID=Action IDMSG_SCOPES=ScopesMSG_ISCONFIGURABLE=Is configurableMSG_XML_FILE=XML fileMSG_DESCRIPTION=DescriptionMSG_EXECCOMP=Execution ComponentMSG_YES = YesMSG_NO = No



MSG_NONE = NoneMSG_BACKTO_LIST = Back To Action ListMSG_PARAMS = ParametersMSG_EXTENDS = ExtendsMSG_CLASS=ClassMSG_EXECCONTAINER=Execution ContainerMSG_NLSCLASS=NLS ClassMSG_NLSBUNDLE=NLS Bundle


Testing the CustomizationThe full source code for this customization is located on the Documentum developer site,developer.documentum.com.

To refresh files and test the actionlist component:

1. If you have changed only XML files, refresh the configuration service by navigating tohttp://server_name:8080/virtual_dir/wdk/refresh.jsp.

2. If you have created and compiled (or edited and recompiled) the ActionList class, or if you havemade changes to the properties file, stop and restart the Tomcat server.

3. Log in and navigate to the actionlist component with the following URL:http://localhost:8080/virtual_dir/component/actionlist

During your development, changes to a JSP page or changes to a Java class that provides values tothe JSP page, require that you delete the generated Java class file that represents the compiled JSPpage in order to see your changes. Changes to an NLS resource bundle require that you reload theWeb application in the server.

If the strings do not display properly, for example, xxMSG_NUM_ACTIONSxx instead of Number ofActions, check the path to the properties file that you created. It must match the fully qualified NLSproperty resource bundle in the actionlist component definition.

Variations on This TutorialYou could simplify the string that is displayed for the action definition file on the actionlist page.Because the link passes the full URL, the full path to the file does not need to be displayed.

In a more extensive customization, you could extend this component to test action definitions bypassing required and optional parameters. You could add a text input tag for each parameter andadd a test action button whose action is the name of the action itself. Because many action IDs have




variations based on scope, you could add a scope field to the test, but this can present problems if theuser enters a scope that is not compatible with one of the input parameters.


Chapter 8Creating a Content Transfer Listener

This tutorial requires both configuration and customization to create a listener component that wrapsa content transfer operation. Specifically, this component gets the map of object IDs for new objectsthat are imported by UCF content transfer.


The tutorial contains the following sections:• Task Objective, page 99• Technical Overview, page 100• Creating the Component Definition, page 100• Creating the Component Layout, page 100• Creating the Component Class, page 101• Creating the Resource Bundle, page 103• Testing the Customization, page 104• Variations on This Tutorial, page 104

Task ObjectiveIn this tutorial, you will create a content transfer listener component that calls the import actionand gets the new object IDs after import. If your custom component will perform some operationoutside of content transfer, it is better to create a listener component rather than extend the contenttransfer component itself.



Creating a Content Transfer Listener

Technical OverviewWDK provides results to a listener for each content transfer operation. For the import container, theresults are the new object IDs for the imported objects.

This content transfer listener component has a simple JSP page with a button whose onclick eventhandler in the component class calls the import action. This method must supply a destination folderID for the import action. In this first exercise, the destination folder is hard‑coded. As a refinementto this first exercise, the import destination folder will be supplied by additional code that gets theuser’s home cabinet ID.

Creating the Component DefinitionTo create a new WDK testlistener component, you must create a component definition.

To create the testlistener definition:

1. Create an empty text file in /custom/config named testlistener_component.xml.

2. Open the file and add the following content:<config version="1.0">

<scope><component id="testlistener">

<pages><start>/custom/test/testListener.jsp</start>

</pages><class>com.mycompany.test.TestListener</class><nlsbundle>com.mycompany.test.TestListenerProp</nlsbundle>


</config>


Creating the Component LayoutYou can present your component in several ways. The simplest way is to simply create the JSP pageand then address the component by URL. The JSP page will then be presented.

To create the layout for the content transfer listener:

1. Create a /custom/test directory if one does not exist.

2. Create a text file testListener.jsp in this directory, and open the file.



3. Add the following content:<%@ page contentType="text/html; charset=UTF8" %><%@ page errorPage="/wdk/errorhandler.jsp" %><%@ page import="com.mycompany.test.TestListener" %><%@ taglib uri="/WEBINF/tlds/dmform_1_0.tld" prefix="dmf"%>

<html><head><dmf:webform/>

</head><body><dmf:form><table><tr><td><dmf:button nlsid="MSG_IMPORT_LISTENER"onclick="onImportListener"/></td></tr>

</table></dmf:form></body>

</html>

4. Save and close the JSP file.In your component class, you will create the button onclick event handler method onImportListener().

Creating the Component ClassThe following procedure creates the component behavior class.




1. In the NetBeans IDE, create a directory /WEB‑INF/classes/com/mycompany/test.

2. Create a new Java class by right‑clicking on the directory WEB‑INF/classes/mycompany/test andselecting New?Java Class.

3. Name the object TestListener and click Finish.The file will be created with the package declaration, class definition, and class constructor:package com.mycompany.test;




public class TestListenerpublic TestListener()


4. In the Source Editor window, following the package declaration, add the following importstatements:import com.documentum.web.common.ArgumentList;import com.documentum.web.form.Control;import com.documentum.web.formext.action.ActionService;import com.documentum.web.formext.action.CallbackDoneListener;import com.documentum.web.formext.component.Component;import com.documentum.webcomponent.library.contenttransfer.importcontent.ImportContentContainer;

import java.util.*;

5. Next, edit the class definition that was created by NetBeans, adding an extends clause. You candelete the constructor:public class TestListener extends Component

6. Within the class definition, create the button event handler with the method name specified inthe JSP page. This method creates a new argument list with a hard‑coded value for the onlyparameter that is required for the import action. Substitute a valid folder ID in your repository forthe highlighted value. The method then calls the import action and registers the listener:public TestListener extends Componentpublic void onImportListener(Control ctrl, ArgumentList args)ArgumentList componentArgs = new ArgumentList();componentArgs.add("objectId", "0c000001801de8bc");

ActionService.execute("import", componentArgs, this.getContext(), this, new CallbackDoneListener(this, "onComplete"));

7. Create the onComplete method that is specified in the call to the import action. This methodshould get the new object IDs after import and do whatever it is you want to do with them:public void onComplete(String strAction, boolean bSuccess, Map map)System.out.println("onComplete called");List newObjectIdList = (List) ImportContentContainer.retrieveReturnObjectIds(map);



if (newObjectIdList != null)System.out.println("newObjectIdList has content");Iterator itNewIds =newObjectIdList.iterator();while (itNewIds.hasNext() == true)String strNewId = itNewIds.next().toString();System.out.println(strNewId);

8. Compile your class and correct any errors that are signalled by the compiler. You can compareagainst the code that is on the developer site.

Creating the Resource BundleIn Creating the Component Definition, page 100 you specified an NLS resource bundle that willcontain the string for your component button label: com.mycompany.test.TestListenerNlsProp. (Ifyou enter a button label value instead of nlsid attribute value in your JSP page, you do not need aresource bundle.)

To create a properties file in the new directory

1. Open the NetBeans explorer Filesystems tab.

2. Create the directory /custom/strings/com/mycompany/test.

3. Right‑click the mycompany directory, and select New?All Templates.

4. Open the Other templates group and click Text File.

5. Click Next and name the file TestListenerNlsProp.

6. Click Next and add the properties extension.

7. Click Finish.Because you added the properties extension, NetBeans displays a page for editing property values.You can also open this page as a text file by right‑clicking the file in the tree and selecting Edit.

8. Add the following key and value pair by clicking the New Property button and filling in thedialog box that appears:MSG_IMPORT_LISTENER = Test Import Listener





To refresh files and test the testlistener component:


2. If you have created and compiled (or edited and recompiled) the TestListener class, or if you havemade changes to the properties file, stop and restart the Tomcat server.

3. Log in and navigate to the testlistener component with the following URL:http://localhost:8080/virtual_dir/component/testlistener

You should see a simple page with a test button. Click the button, and you should see the AddFiles import dialog. After import, you should see the debugging statements in your Tomcatconsole and log, similar to the following:

Figure 17. Testlistener Console Output


If the strings do not display properly, for example, xxMSG_NUM_ACTIONSxx instead of Number ofActions, check the path to the properties file that you created. It must match the fully qualified NLSproperty resource bundle in the testlistener component definition.

Variations on This TutorialThe import destination folder will not be hard‑coded in a production component. The followingexercise adds code that gets the current user’s home cabinet and uses that folder ID as the destination.

Getting the User’s Home Cabinet

1. Open the class file TestListener.java and add the following import statements:mport com.documentum.web.formext.docbase.FolderUtil;import com.documentum.web.formext.session.SessionManagerHttpBinding;




import com.documentum.fc.client.*;import com.documentum.fc.common.DfException;import com.documentum.fc.common.DfId;

2. Add an initialization method. We add this so that we can create a simple action that is availablefrom a menu, rather than having to call the component by URL. This initialization will simply callthe onImportListener() method. (Always call super.onInit() so that your component is initializedproperly.)public void onInit(ArgumentList arg)super.onInit(arg);onImportListener(null, arg);

3. Change the onImportListener() method to add the code that gets the user home cabinet ID.Locate the following line:componentArgs.add("objectId", "0c000001801de8bc");

Replace with these lines:IDfSessionManager sessionManager = null;IDfSession dfSession = null;

trysessionManager = SessionManagerHttpBinding.getSessionManager();String strCurrentDocbase = SessionManagerHttpBinding.getCurrentDocbase();dfSession = sessionManager.getSession(strCurrentDocbase);String strUserName = dfSession.getLoginUserName();System.out.println("User name: " + strUserName);IDfUser dfUser = dfSession.getUser(strUserName);

String strUserHomeCabinetName = dfUser.getDefaultFolder();System.out.println("User home cabinet name is" +strUserHomeCabinetName);m_strFolderId= FolderUtil.getFolderId(strUserHomeCabinetName);

System.out.println("Home cabinet ID is " + m_strFolderId);

componentArgs.add("objectId", m_strFolderId);

4. Locate the following line:ActionService.execute("import", componentArgs, this.getContext(), this, new CallbackDoneListener(this, "onComplete"));

Add the following catch and finally blocks to close the session:

catch (DfException e)

finallyif (dfSession != null)



sessionManager.release(dfSession);

5. After the methods, add a class member variable to hold the value of the destination folder ID:private String m_strFolderId;

6. In this example, we created a new action, myimport, that calls the testlistener component. Weadded a menu item (My import) for the action in our custom Webtop menubar component (stepsnot shown). We then added a call to the onComplete method to return to the calling component.After the closing bracket of the if statement, add the following line:setComponentReturn();

7. Save and compile your class. Correct any errors that are found by the compiler and restart theapplication server.

Test the component by exercising the new menu item as shown below:

Figure 18. New Menu Item Calls the Listener Component

The menu item loads the Add Files dialog, bypassing the component JSP page, and after the fileshave been successfully imported, the user is returned to the Webtop objectlist. The console outputshows the successful import:



Figure 19. TestListener Console Output, Enhanced


Chapter 9Limiting Import Types

This tutorial requires both configuration and customization to customize the UCf import componentand limit the list of object types for import.



Task ObjectiveIn this tutorial, you will create a custom import component that extends UCF import and limits the listof available object types for import. Note that you can already limit the list of types to one type and itssubtypes through the <document‑docbase‑type> element of the import component definition. Thistutorial fulfills the requirement of providing a limited set of types that do not derive from the sametype or the requirement of making subtypes visible.



Limiting Import Types

Technical OverviewThe UCF import component provides a list of all the object types in the repository for the object tobe imported. Some applications may need to limit the object types that are available. This customcomponent extends the UCF component definition and provides a custom class that reads the availableobject types from the component definition rather than from the repository data dictionary.

No UI changes are required for this component, so the WDK import pages are used.

Creating the Component DefinitionTo create a new WDK import component, you must create a component definition.

To create the component definition:

1. Create an empty text file named myimport_component.xml in /custom/config.

2. Open the file and add the following content:<?xml version="1.0" encoding="UTF8" standalone="no"?><config version='1.0'><scope><component id="import" extends="import:webcomponent/config/

library/contenttransfer/importcontent/import_component.xml">

<class>com.mycompany.test.MyImportContent</class></component>

</scope></config>

3. After the closing </class> element, add custom elements that will be used to configure the list ofavailable object types. Substitute actual object types that are valid for your repository as thevalue of the <docbase_type>.<value> elements:<! specify the commaseparated list of types and subtypes)that will be available for import ><includetypes>

<docbase_type><value>dm_document</value><label>Document</label>

</docbase_type><docbase_type>

<value>dm_xml_style_sheet</value><label>XML Stylesheet</label>

</docbase_type></includetypes>




Creating the Component LayoutBecause this custom component provides the result set for the import type dropdown list, you do notneed to customize the layout.

In your component class, you will create the button onclick event handler method onImportListener().





1. In the NetBeans IDE, create a directory /WEB‑INF/classes/com/mycompany/test.

2. Create a new Java class by right‑clicking on the directory WEB‑INF/classes/mycompany/test andselecting New?Java Class.

3. Name the object MyImportContent and click Finish.The file will be created with the package declaration, class definition, and class constructor:package com.mycompany.test;public class MyImportContentpublic MyImportContent()


4. In the Source Editor window, following the package declaration, add the following importstatements:import com.documentum.web.form.control.databound.ScrollableResultSet;import com.documentum.web.form.control.databound.TableResultSet;import com.documentum.web.formext.config.IConfigElement;




import com.documentum.webcomponent.library.contenttransfer.importcontent.ImportContent;

import java.util.Iterator;

5. Next, edit the class definition that was created by NetBeans, adding an extends clause. You candelete the constructor:public class MyImportContent extends ImportContent

6. Within the class definition, add a method createTypesResultSet() that overrides thecreateTypesResultSet method of the import component. If you examine the source code (providedby the WDK installer) for the WDK import component, you see that this the method providescontent to the import type dropdown list. It is called by the initTypeListControl() method:public class MyImportContent extends ImportContentprotected ScrollableResultSet createTypesResultSet()if (isDirectory() == false)TableResultSet rsTypes = getDocbaseTypes();return rsTypes;

return super.createTypesResultSet();

7. Now create the getDocbaseTypes() method that you called in the createTypesResultSet method.This method will read the object types that you have configured in your component definition andprovide them as a ScrollableResultSet to the createTypesResultSet method.The TableResultSet is built by adding a String array for each type that is defined in the componentdefinition. The string array consists of a value for type_name and label_text that correspond to thelist options as defined in the importContent.jsp page:<dmf:datadropdownlist name="objectTypeList"...onselect="onSelectType" ...><dmf:dataoptionlist><dmf:option datafield="type_name" labeldatafield="label_text"/>

</dmf:dataoptionlist></dmf:datadropdownlist>

The getDocbaseTypes() method is shown below. The lines that are commented out could be usedto get a default value that you have added to the component definition.public TableResultSet getDocbaseTypes()

TableResultSet rs = new TableResultSet(new String[]"type_name","label_text");

IConfigElement elemDocbaseTypes = lookupElement("includetypes");

if (elemDocbaseTypes != null)System.out.println( "\n****************************\n" +



"* includetypes is not null *\n"+"****************************\n");

//Retrieve each type and add to the result listIterator iterTypes = elemDocbaseTypes.getChildElements("docbase_type");

while (iterTypes.hasNext())//Retrieve the value and labelIConfigElement elemType = (IConfigElement)iterTypes.next();//Specify a default entry in case the sub tag is missing.String strValue = elemType.getValue();String strLabel = strValue;

//Get configured type and labelIConfigElement elemValue = elemType.getChildElement("value");IConfigElement elemLabel = elemType.getChildElement("label");

if (elemValue != null && elemValue.getValue() != null && elemValue.getValue().length() > 0)

strValue = elemValue.getValue();System.out.println("Docbase type: " + strValue);

if (elemLabel != null && elemLabel.getValue() != null && elemLabel.getValue().length() > 0)

strLabel = elemLabel.getValue();

//if no label, use type name as labelif (strLabel == null || strLabel.length() == 0)

strLabel = strValue;

//Add type and label to result setrs.add(new String[]strValue, strLabel);

return rs;


Creating the Resource BundleIn your custom component definition, you did not specify an NLS resource bundle. If youwant to externalize the labels for your object types, you can add an <nlsid> element within the<docbase_type>.<label> element, and then create a properties file with the nlsid keys and values. Notethat you will need to copy in the WDK import NLS file contents to your properties file.






2. If you have created and compiled (or edited and recompiled) the MyImportContent class, or if youhave made changes to a properties file, stop and restart the Tomcat server.

3. Log in and click the Import link in the UI.You should see the Add Files import dialog. After you have selected files for import, you shouldsee your restricted list of file types in the UI.




Figure 20. Restricted file types in Webtop Import UI

You should also see the output of your debugging statements in the standard output log.

Figure 21. Statements in standard output log

***************************** includetypes is not null *****************************

Docbase type: dm_documentDocbase type: dm_xml_style_sheet




If the strings do not display properly, for example, xxMSG_NUM_ACTIONSxx instead of Number ofActions, check the path to the properties file that you created. It must match the fully qualified NLSproperty resource bundle in the testlistener component definition.

Variations on This TutorialYou could add a default type to be selected when the user opens the import type dropdown list. To dothis, you would need to add an element to the component definition that sets the default type, thenread the element in your getDocbaseTypes() method. Store the value in a class member variable.Override the method that initializes the type list control and set the default value from your membervariable, similar to the following:protected void initTypeListControl()super.initTypeListControl();if (isDirectory() == false)// set your default typeDataDropDownList typeList = getTypeListControl(true);String strDefaultType = getConfigDefaultType();typeList.setValue(strDefaultType);System.out.println("Default type: " + strDefaultType);

protected String getConfigDefaultType()//Retrieve the default from an element called defaulttypeIConfigElement elemDefaultType = lookupElement("defaulttype");m_strDefaultType = elemDefaultType.getValue();System.out.println("Default type reset to: " + m_strDefaultType);return m_strDefaultType;

private String m_strDefaultType = "dm_sysobject";


Chapter 10Using Tracing and Logging in aComponent

This tutorial demonstrates how to add tracing and logging to your component to make it easier todetect runtime errors..


The tutorial contains the following sections:• Task Objective, page 117• Technical Overview, page 118• Creating the Tracing Class, page 118• Adding Tracing to the Component Class, page 119• Adding Custom Tracing to the List, page 120• Turning on Tracing, page 120• Examining the Trace Log, page 121• Testing the Customization, page 121• Variations on This Tutorial, page 122

Task ObjectiveIn this tutorial, you will create a tracing class for your custom code and add a tracing flag to yourcode, then turn on tracing and inspect the log.



Using Tracing and Logging in a Component

Technical OverviewWDK tracing flags trace the following types of operations or content manipulation: sessions, JSPrequests, locales, actions, configuration, roles, preferences, resources, clipboard, controls, controltags, form navigation and history, validation, repository attributes, content transfer, components,containers, object caching, virtual links, and failover. For the full list of tracing flags and their usage,seeWeb Development Kit Development Guide.

You can add your own tracing flags to trace operations that are used in more than one class. After youenable tracing, tracing statements will be written to the wdk.log file in your The default location forthe log is <user.dir>/documentum/logs: user.dir resolves to the application server binary executablesdirectory (for example, Tomcat/bin).

WDK tracing flags are enumerated in the WDK resource file TraceProp.properties located in/WEB‑INF/classes/com/documentum/debug. This file contains all tracing flags that are defined inyour application. If there is an unknown flag in this file, the Trace class initialization will generate awarning message but will continue.

Note: You must enable tracing for the current session using one of the following methods:• Set the SESSION flag (mandatory) and another other flags you require in TraceProp.properties and

then restart the application server.• Use a browser to navigate to /wdk/tracing.jsp and check the boxes that enable tracing.You can enable tracing for all sessions for setting SESSIONENABLEDBYDEFAULT to true in/WEB‑INF/classes/com/documentum/debug/TraceProp.properties.

The open source Apache logging library log4j is installed by the DFC installer. This package allowsyou to enable logging at runtime without modifying the application library or incurring a significantperformance impact. The Apache log4j library is used by the DFC logger class DfLogger. Each log4jLogger class method such as debug() and warn() is wrapped by a DfLogger method. The WDK Traceclass uses DfLogger to write the log file for all enabled traces.

The log file location is specified in a log4j.properties file, which is installed by the WDK andclient applications installers to DOCUMENTUM_HOME/config. By default, the log file name (notpath) is specified in log4j.properties as the value of the key log4j.appender.file.File, for example,C\:\\Documentum\\logs\\trace.log (the double backslashes indicates an escaped backward slash).

Creating the Tracing Class

Caution: You can copy and paste code from the PDF tutorial, but certain symbols may bechanged when you paste them into your IDE. For example, the symbol “&” may be changed to& and the “<” symbol may be changed to <. The single quote (') may be changed toa curly quote. TheNetBeans compiler will show the line containing the error. You must ensure



that these symbols are correct in your IDE before you compile. Instead of copying and pasting,type in the content or get it from the code zip file on the developer Web site.


1. Create a new Java class by right‑clicking on the directory WEB‑INF/classes/mycompany andselecting New?Java Class.

2. Name the class “Trace” and click Finish.The file will be created with the following line:package com.mycompany;


3. Edit the class definition that was created by NetBeans, adding an extends clause:public class Trace extends com.documentum.web.common.Trace

4. After the constructor, add the following tracing flag:public static boolean ACTIONLIST;

5. Compile your class file. Note any errors in the output window and resolve them. The exactlocation of the error is noted by the compiler.

Adding Tracing to the Component ClassAdd tracing statements for the main methods in your component class or for methods that may throwexceptions. In this tutorial you will add tracing statements to the ActionList class that you created inthe previous tutorial. You will add tracing statements to the update method and to the methods thathandle links and navigation.

Note: For this example to work, you must create all of the files required for the tutorial actionlistcomponent. Alternatively, you can create a tracing flag that is appropriate for one of your customclasses, and add it to your class.

To Add Tracing to the Update Method:

1. Open ActionList.java in your IDE and locate the method updateActionList().

2. Import your Trace class by adding the following import statement:import com.mycompany.Trace;

3. Locate the following line in the method:TableResultSet rsList = new TableResultSet(strDataFields);

4. Add the following lines:



if (Trace.ACTIONLIST)

if (rsList != null)Trace.println("Result set successfully created");

elseTrace.println("Result set not created");

To Add Tracing to the Navigation Event Handler:

1. Locate the method onClickActionList(). This event handler handles the onclick event for thelnkback link on actionInfo.jsp.

2. Before the first line in the method, add the following lines:if (Trace.ACTIONLIST)Trace.println("Returning to start page");

Adding Custom Tracing to the ListTo make your tracing flags accessible, so that you can turn them on or off, you mustadd them to a tracing properties file. Open the properties file TraceProp.properties in/WEB‑INF/classes/com/documentum/debug

Add your flag on the last line, as shown in the following example:com.mycompany.Trace.ACTIONLIST=true

Turning on TracingYou must restart your application server to apply changes to a properties file.

There are two ways to turn on tracing in your application:• Set the appropriate tracing flags to true in /WEB‑INF/classes/com/documentum/debug/

TraceProp.properties.• Navigate to /wdk/tracing.jsp and select the first checkbox, Tracing is enabled for current session.

Then check relevant tracing flags, such as ACTIONLIST. See the example below.



Figure 22. Tracing JSP Page

...


To refresh files and test tracing:

1. Because you have added a new class, stop and restart the Tomcat server.

2. Log in and navigate to the actionlist component:http://localhost:8080/virtual_dir/component/actionlist

3. Exercise the actionlist component by clicking on an action, returning to the start page, and thenclicking on the XML file link.

If you add tracing statements to you behavior class, you must recompile and stop and restart theserver to see your tracing statements in the log.

Examining the Trace LogTrace statements are written to the Tomcat console, so you can see them as you exercise yourcomponent. After you stop the application server, you can examine the log file for your tracestatements.

Open the tracing log in the location specified in your DOCUMENTUM_HOME/config/log4j.propertiesfile. By default, this file has the value of log4j.appender.file.File=$user.dir/documentum/logs/documentum.log. This value is resolved to the subdirectory /documentum/logs under the applicationserver executable directory, for example, TOMCAT_HOME/bin/documentum/logs.log4j.appender.file.File=C\:/Documentum/logs/wdk.log

The following except from wdk.log shows the statements added in this tutorial:




20050315 15:41:48,704 105468 [http8080Processor25]DEBUG com.documentum.web.common.Trace Result set successfully created

20050315 15:42:02,545 119309 [http8080Processor25]DEBUG com.documentum.web.common.Trace Returning to start page

The resulting trace statements are also written to the Tomcat console, as shown below.

Figure 23. Tracing Output

Variations on This TutorialYou can add JavaScript tracing for client‑side functions. The trace JavaScript file trace.js is referencedin every HTML page that is output by the WebformTag class.

To output client‑side tracing messages to a popup browser window, call the Trace_println function,passing in the message as the sole parameter. The following example is added to the actionList.jsppage to output JavaScript tracing when the user clicks the link to the action configuration file:function onClickXML(obj, xmlurl)Trace_println ("You are now viewing the XML configuration file");window.open(xmlurl);

A popup browser window opens with the tracing statement:

Figure 24. JavaScript Tracing


Chapter 11Customizing UCF Export

UCF export displays a dialog on export that allows the user to choose an export target location,as shown below:

Figure 25. Export Location Dialog

This tutorial demonstrates how to customize UCF export to perform silently for simple export of oneor more files (not a virtual document or XML document with inline entities).


Customizing UCF Export



Task ObjectiveIn this tutorial, you will create a class that extends the UCF export container in Webtop and overridesthe methods that supply the export location. You will create a method that reads the default locationfrom the component definition file and another that sets the location based on the user home directory.

Technical OverviewThe UCF export container calls the file selector applet to allow the user to select the export location. Ifyou have installed WDK, you have the source code for the class UcfExportContainer in the directory/webcomponent/src/com/documentum/webcomponent/library/contenttransfer/export. When youexamine this class, you can determine that the container onInit() method redirects to the componentpage (“selectfolder”) that contains the file selector applet:public void onInit(ArgumentList args)

super.onInit(args);setComponentPage("selectfolder");

You can override this method so that the page is not loaded.

You will create a configurable default location in the component definition and read it into the customexport class. You will use this default if the system home directory is not available.

You examine the parent class again to determine where the destination folder is passed from theapplet. You see in the javadocs for onSelectDestinationFolder() the following:Handler called when returning from selection of exportdestination folder on the client.




You can override this method to supply the destination folder.

Creating the Component DefinitionTo create a new WDK silent export component, you must create a component definition.

To create the actionlist definition:

1. Copy the file exportcontainer_component.xml in /webcomponent/config/library/contenttransfer/export to t /custom/config.

2. Open the file and add or change the highlighted content:...<component id="exportcontainer" extends="exportcontainer:application='webcomponent' type='dm_sysobject' ">...<class>com.mycompany.export.MyUcfExportContainer</class><nlsbundle>

com.documentum.webcomponent.library.contenttransfer.export.ExportContainerNlsProp

</nlsbundle>

<! Default silent export location ><silentexportpath>C:\temp\testexport</silentexportpath>

</component>


Creating the Component LayoutNo modifications to the component layout are required for silent export because no JSP page ispresented to the user.


Caution: If you copy code from this PDF tutorial, certain symbols may be changed when youpaste them into your IDE. For example, the symbol “&” may be changed to & and the “<”symbol may be changed to <. The single quote (') may be changed to a curly quote. TheNetBeans IDE compiler will show the line containing the error. You must ensure that thesesymbols are correct in your IDE before you compile.





1. In the NetBeans IDE, create a directory /WEB‑INF/classes/com/mycompany/export.

2. Create a new Java class by right‑clicking on the directory WEB‑INF/classes/mycompany/exportand selecting New?Java Class.

3. Name the object MyExportContainer and click Finish.The file will be created with the package declaration, class definition, and class constructor. Addthe highlighted import statements and extends clause:package com.mycompany.export;

import com.documentum.web.common.ArgumentList;import com.documentum.webcomponent.common.WebComponentErrorService;import com.documentum.webcomponent.library.contenttransfer.export.UcfExportContainer;

public class MyUcfExportContainer extends UcfExportContainer


4. Create a class member variable to hold the export target location:private String m_strExportDir = null;

5. Override onInit() to call two methods that you will create to get the user home directory andthe default export directory from the config file,and then pass this export directory variable tothe method that sets the destination folder:public void onInit(ArgumentList args)

super.onInit(args);// You can hardcode path here, or read from component def with readExportPath// Depending on your configuration policies, the user home directory may// not always return a convenient path for your users.//String strPath = "C:\\temp\\testexport";String strDir = getUserHome();if (strDir != null)

m_strExportDir = strDir;else

strDir = readExportPath();m_strExportDir = strDir;

onSelectDestinationFolder(strDir);




6. Create the method that reads the default export directory from the configuration file. This methodreplaces back slashes with forward slashes:protected String readExportPath()String strPath = lookupString("silentexportpath");String strEscapedPath = strPath.replace('\\', '/');System.out.println("path from config is " + strEscapedPath);return strEscapedPath;

7. Create the method that gets the user home (system) directory:protected String getUserHome()String strHomeDir = System.getProperty("user.home");return strHomeDir;

8. Override onSelectionDestinationFolder() to bypass the fileselector applet. If the destination folderdoes not exist, an error message from the export container NLS resource bundle is returned:public void onSelectDestinationFolder(String strDestFolder)trysuper.setDestFolderSelection(strDestFolder);setComponentPage("start");super.tryCommitChanges();

catch(Exception e)WebComponentErrorService.getService().setNonFatalError(this, "MSG_ERR_DEST_CLIENT_FOLDED_EMPTY", null);

setComponentReturn();


Creating the Resource BundleThis example uses the resource bundle from the parent component and does not require anyadditional strings.






2. If you have created and compiled (or edited and recompiled) the ExportContainer class, or if youhave made changes to the properties file, stop and restart the Tomcat server.

3. Log in to Webtop and go to your home cabinet.

4. Check the box next to one or more documents on which you have view permissions and clickExport in the File menu.If the document is not virtual or XML, you should see only a progress bar during export, thena success message in the status bar. The documents exported will be found in your user homedirectory. If the document is virtual or XML, you will be presented with a dialog asking whetheryou wish to download the descendants.

Variations on This TutorialYou could bypass the descendants dialog for virtual documents and XML files if you do not wantusers to download descendants. In this case, you would extend the export component and removethe download descendants control initialization from the configuration file. In your custom Exportclass, you would override initStandardOptionsControls(), which makes the checkbox visible forvirtual and XML documents. You then override getDownloadDescendantsSelection() to hard‑code theselection value.



Chapter 12Troubleshooting

If your customization does not appear as you intended, you can try some of the procedures belowto troubleshoot:• Did you precompile your Java class?, page 129• Did you refresh the Configuration Service?, page 129• Did you remove generated files?, page 130• Did you clear the browser cache?, page 130• Did you check the name and location of the XML resource file?, page 130For more troubleshooting tips, see the PDF manual Troubleshooting WDK 5 Applications.

Did you precompile your Java class?If you create a new Java file, you should remember to compile it in Forte for Java. (Make sure it iscompiled into the right directory) On the other hand, you should allow Tomcat 4 to compile your JSPpages automatically, because Forte for Java supports Tomcat 3.

Did you refresh the Configuration Service?If you make changes to an XML resource file, you need to restart the configuration service, either bynavigating to http://server_name:port_number/virtual_dir/wdk/refresh.jsp or by stopping and restartingthe application server.


Troubleshooting

Did you remove generated files?Normally, the application server picks up changes to JSP files. However, JSP pages maynot be updated when they are called from a container. If you edit JSP files and the changesare not reflected in the display, you may need to clear the cache by deleting the directorytomcat_home_directory/work/Standalone/localhost/virtual_dir.

Did you clear the browser cache?If you make changes to JavaScript, you should try clearing your browser cache, as described in thefollowing procedure.

To clear the browser cache in Internet Explorer:

1. In Internet Explorer, choose Tools?Internet Options.

2. In the Temporary Internet files pane, click Delete Files.

3. Check the box to delete offline content and click OK.

Did you check the name and location of theXML resource file?All customized XML resource files should be located in the tomcat_home_directory/webapps/virtual_dir/custom/config directory, where tomcat_home_directory is the directory in which Tomcat is installed, andvirtual_dir is the name of the virtual directory that was provided when WDK was installed.

One way to test whether this resource file is being recognized is to make a copyof it in the same directory, then refresh the configuration service by navigating tohttp://server_name:port_number/virtual_dir/wdk/refresh.jsp. You should get an error message thatthere is a duplicate element, and the name of this copied file will be mentioned near the end of theerror message. This shows that your XML resource file is being read. Delete the copy and continuetroubleshooting.


Troubleshooting

If your XML resource file is being read, then you can assume that you will get a 404 error if thebrowser does not find the JSP file in the specified location, and a Java error if it does not find the classfile in the specified location.


Troubleshooting


Index

Aactionmenuitem, 20application start page, 69ArgumentList object, 64

Bbrowser cache

clearing, 130

Ccaches

clearing, 12clearing caches, 12column

adding, 31configuration, 30rearrange, 33remove, 32visible, 31

componentconfiguration, 38

configurationdefined, 9XML file, 38

Configuration Servicerefreshing, 129

content transferlistener, 99

conventionstypographical, 11

custom layer, 13inheritances and overrides, 14

customizationdefined, 9

Ddatabound control, 51datafield, 52

datagrid, 65JSP tag, 52

DatagridJava object, 56

datevalueformatter tag, 60Docbases

limiting selection, 81DQL

sample query, 57drilldown component

extending, 76drilldown, changing generic_actions.

xml, 76

Eenvironment, 12

FForte for Java

setting up, 15

Ggenerated files

removing, 130getDataProvider, 65getRepositorySession, 57

IIDE

setting up, 15IDfSessionManager, 56import

limiting types, 109

JJava class files

precompiling, 129


Index

JSPadding static controls, 41simple, 39Tag Library Definitions (TLDs), 41

Llabel, 65

with dynamic Java text, 47with NLS text, 42

label objectwith static Java text, 44

linkJSP tag, 61

logging, 117logout action

extending, 78logout link

adding, 73

Mmenu

add command, 17rearrange commands, 22remove command, 21remove menu, 25replace command, 24

menubarconfiguration, 35

menubar_component.xml, 35

NNational Language Support (NLS), 41NLS, 41

in label object, 42

OonClickLink, 62, 64onRender, 64

Ppreparing for the tutorials, 11project

creating, 15

Rredirect, 70refreshing the Configuration Service, 129

Ssession management, 56SessionManagerHttpBinding, 56showifinvalid, 20start page, 69Sun ONE Studio

setting up, 15

TTag Library Definitions (TLDs), 41TLDs, 41Tomcat application server

stopping, 16tracing, 117troubleshooting, 129typographical conventions, 11

Uunexpected behavior, 27

XXML

configuration file, 38XML resource file

checking name and location, 130
