emc documentum webdevelopmentkit documentum® webdevelopmentkit version6 tutorial...

EMC® Documentum®

Web Development KitVersion 6

TutorialP/N 300005262A02

EMC CorporationCorporate Headquarters:

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

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

Published November 2007

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 .............................................. 11Tutorial basics .................................................................................................. 12Clearing caches and refreshing ...................................................................... 12Overview of the custom layer ........................................................................ 13Custom layer inheritance and overrides ..................................................... 13

Setting up an IDE ............................................................................................. 14Creating a project in Eclipse .......................................................................... 14

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 ....................................................................... 23Removing an entire menu ................................................................................. 24When the application behaves in an unexpected manner..................................... 26Small changes, big impact ................................................................................. 27

Chapter 3 Configuring Columns in a Webtop List Control ........................................... 29Areas of 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.............................................. 37Step 4 — Creating the Hello World JSP page....................................................... 38Step 5 — Adding static controls to the JSP page .................................................. 40Step 6 — Adding dynamic controls to the JSP page ............................................. 45Step 7 — Adding databound controls to the JSP page.......................................... 49Step 8 — Linking to a second JSP page ............................................................... 57

EMC Documentum Web Development Kit Version 6 Tutorial 3

Table of Contents

Chapter 5 Starting in a Specific Component ................................................................ 67Task objective ................................................................................................... 67Technical overview ........................................................................................... 67Modifying the main component definition ......................................................... 68Extending the main component class ................................................................. 69Testing the configuration................................................................................... 70Variations on this tutorial .................................................................................. 70

Chapter 6 Creating an Action List Component ............................................................ 71Task objective ................................................................................................... 71Technical overview ........................................................................................... 72Creating the component definition..................................................................... 73Creating the component layout.......................................................................... 73Creating the component class ............................................................................ 75Supporting navigation between pages................................................................ 77Creating the action list datagrid......................................................................... 78Creating the action info datagrid ....................................................................... 80Creating the resource bundle............................................................................. 84Testing the customization.................................................................................. 85Variations on this tutorial .................................................................................. 85

Chapter 7 Creating a Content Transfer Listener .......................................................... 87Task objective ................................................................................................... 87Technical overview ........................................................................................... 88Creating the component definition..................................................................... 88Creating the component layout.......................................................................... 88Creating the component class ............................................................................ 89Creating the resource bundle............................................................................. 91Testing the customization.................................................................................. 91Variations on this tutorial .................................................................................. 92

Chapter 8 Limiting Import Types .................................................................................. 95Task objective ................................................................................................... 95Technical overview ........................................................................................... 96Creating the component definition..................................................................... 96Creating the component layout.......................................................................... 97Creating the component class ............................................................................ 97Creating the resource bundle............................................................................. 99Testing the customization................................................................................ 100Variations on this tutorial ................................................................................ 102

Chapter 9 Using Tracing and Logging in a Component ............................................. 105Task objective ................................................................................................. 105Technical overview ......................................................................................... 106Creating the tracing class ................................................................................ 106

4 EMC Documentum Web Development Kit Version 6 Tutorial

Table of Contents

Adding tracing to the component class ............................................................ 107Adding custom tracing to the actionlist component .......................................... 108Turning on tracing .......................................................................................... 108Testing the customization................................................................................ 109Examining the trace log................................................................................... 109Variations on this tutorial ................................................................................ 110

Chapter 10 Customizing UCF for Silent Export ............................................................ 111Task objective ................................................................................................. 112Technical overview ......................................................................................... 112Modifying the component definition................................................................ 113Creating the component class .......................................................................... 113Testing the customization................................................................................ 115Variations on this tutorial ................................................................................ 116

Chapter 11 Troubleshooting ........................................................................................ 117Did you compile your Java class?..................................................................... 117Did you refresh the configuration service?........................................................ 117Did you remove generated JSP class files? ........................................................ 117Did you clear the browser cache?..................................................................... 118Did you check the name and location of the XML resource file? ......................... 118


Table of Contents

List of Figures

Figure 1. Custom directory contents after deployment .......................................................... 13Figure 2. Finished project in Eclipse package explorer........................................................... 15Figure 3. Project properties ................................................................................................. 16Figure 4. Fragment of /webtop/config/menubar_component.xml as shipped .......................... 17Figure 5. File menu before modification. .............................................................................. 18Figure 6. File menu with Rename command ........................................................................ 19Figure 7. File menu with Cancel Checkout command removed ............................................. 21Figure 8. File menuwithCancel Checkout commandmoved beforeDelete command ............ 23Figure 9. Webtop menubar with the Viewmenu removed..................................................... 26Figure 10. My Files page with Title column displayed ............................................................ 32Figure 11. My Files page with Name column hidden .............................................................. 33Figure 12. Rearranging columns by moving column elements ................................................. 33Figure 13. Size column moved in front of the Version column ................................................. 34Figure 14. Tools menu with inserted Hello World command ................................................... 37Figure 15. Action list page .................................................................................................... 72Figure 16. Action info page ................................................................................................... 72Figure 17. Test listener console output ................................................................................... 91Figure 18. New menu item calls the listener component.......................................................... 94Figure 19. Enhanced test listener console output .................................................................... 94Figure 20. Restricted file types in Webtop Import UI............................................................. 101Figure 21. Statements in standard output log ....................................................................... 101Figure 22. Tracing JSP page ................................................................................................. 108Figure 23. JavaScript tracing................................................................................................ 110Figure 24. Export location dialog......................................................................................... 111


Table of Contents

List of Tables

Table 1. Directory structure of the custom layer .................................................................. 13Table 2. Modification file elements ..................................................................................... 19Table 3. Highlights from hello_world_action.xml ................................................................ 36Table 4. Highlights from hello_world_component.xml ........................................................ 38Table 5. Highlights from hello_world.jsp ............................................................................ 41Table 6. Code walkthrough................................................................................................ 44Table 7. Code walkthrough................................................................................................ 48Table 8. JSP page elements................................................................................................. 51Table 9. Code walkthrough................................................................................................ 55Table 10. JSP page elements................................................................................................. 58Table 11. Code walkthrough................................................................................................ 64


Table of Contents


Preface

The EMC DocumentumWeb Development Kit (WDK) is a large development platform. It can be hardto figure out where to get started. That is where this guide comes in. The purpose of this manual isto give you insight into the design decisions and practical use of WDK so that you can move on tosolving your own business problems.

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 JSP pages 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.5.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 2007 Initial release.

November 2007 A02, Service pack 1 release: Corrections, added new tutorial on starting in aspecific component, removed tutorial on logout link


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 11• Tutorial basics, page 12

Typographical conventions used in the tutorialsThis 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 tutorial, double quotes are used for newentries unless single quotes are required. Existing files use both forms of quotation marks.

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/


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

Tutorial Preparation and Basics

• 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 or Webtop 6

See the WDK release notes for hardware requirements and software certifications. See theWebDevelopment Kit and Webtop Deployment Guidefor information on deploying WDK and verifyingyour deployment on an application server. Webtop 6 contains WDK 6.

• 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.

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.


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


Overview of the custom layer

WDK‑based applications make use of a customization layer, which allows you to keep configurationsand customizations in a location separate from the installed product. This allows the custom layer tobe easily migrated after an upgrade or redeployment.

A default custom directory is included in the product WAR file in the following location:virtual_dir/custom

This directory cotnains the subdirectories and files shown in the following figure.

Figure 1. Custom directory contents after deployment

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

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

app.xml File for changes to app.xml settings

Custom layer inheritance and overrides

When you extend a definition in a configuration file in a WDK‑based 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.



Simple modifications can be made without extending an action or component definition. With amodification file, you can insert, replace, or delete an element from a specific configuration file.

The extension and modification file syntax is described in the tutorials in that use them. Moreinformation on the syntax can be found inWeb Development Kit Development Guide.

Setting up an IDEWhen you create a custom class, you compile it using either an IDE such as the Eclipse IDE or anexternal compiler. This section contains information on creating a project in the Eclipse IDE. If you useanother IDE, consult the IDE documentation for the proper way to set the classpath and referencethe external libraries.

This guide uses the Eclipse IDE version 3.2.2 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 Eclipse

You must first expand the WDK or Webtop WAR file into a working directory. You will point tothis working directory for your Eclipse project.

Open the expanded directory structure and make the directory WEB‑INF/classes/com/documentumand its subdirectories read‑only so that Eclipse will not delete Documentum class files.

To create a new project in Eclipse

1. Open the Eclipse IDE.

2. Choose File > New > Project.

3. Choose Java Project and click Next.

4. Create a name for your project, such as webtop6, and click Create project from existing source.

5. Browse to the working directory in which you expanded the WDK or Webtop WAR file, clickOK, and then click Finish.

To configure the project

1. Right‑click the new project from the Package Explorer tree and click New > Folder. For Foldername, typeWDKclasses.Click Advanced > Link to folder in the file system. Navigate to WEB‑INF/classes in your workingdirectory and then click Finish.

2. Right‑click the new project from the Package Explorer tree and choose Properties.



3. Expand the Java Compiler properties and click Enable project specific settings.Choose Building and uncheck Scrub output folders when cleaning projects.

4. In the left tree, click Java Build Path and then click the Source tab on the right.Remove the three src directories that Eclipse detected, as you do not want them on the build path.

5. Still in the Source tab, click Add Folder and then click Create New Folder. Type custom/src. Thesrc directory will be added to the custom directory and will have a check mark in the SourceFolder Selection dialog. Click OK.Click Add Folder again and navigate to WEB‑INF/classes, check it and click OK. (Do not selectWDKclasses. You will use this as an output folder.)

6. Click the Librairies tab and then click Add External JARs. The JAR Selection dialog opens to theTomcat common/lib directory. Select servlet‑api.jar and jsp‑api.jar and then click Open.Click Add Class Folder, select WDKclasses, and then click OK.

7. Click OK and the project will be built.

Figure 2. Finished project in Eclipse package explorer



Figure 3. Project properties

Now that you have created a project, you can add configuration files to custom/config, properties filesto custom/strings, and source files to custom/src. The compiled class files from custom/src will go toWDKclasses, which maps to WEB‑INF/classes. The examples in the tutorials will use the packagestructure com.mycompany, so you create a directory structure of custom/src/com/mycompany inwhich to create the tutorial Java classes.


Chapter 2Configuring the Webtop menubar

A good place to start configuring and customizing 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 you 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 4. 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 5. File menu before modification.

To insert the Rename command to the File menu:

1. Using your IDE, 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]"><actionmenuitem dynamic="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 6. File menu with Rename command

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

Table 2. Modification file elements

Element Description

<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>

Identifies the primary element in theconfiguration file we want to modify. Themodifies attribute string begins with the ID of theelement we will modify. This is the specific IDattribute value of the element as it appears inthe referenced configuration file. The text afterthe colon gives the location of the configurationfile to be modified relative to the <webtop_root>directory.



Element Description

<insertafter path= "menu[name=file_

menu]. actionmenuitem[name=file_

saveas]"> ... </insertafter>

Identifies the type of modification. In this case,we will insert a new menu item and have itappear after an existing item. The path argumentuses dot notation to identify the location to bemodified in the referenced XML configurationfile. The 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"/>

Creates a new action menu item object andsets its custom attributes. Use the commanddescriptions in the menubar_component.xmlconfiguration file as a guide. This is a dynamiccontrol: it can be automatically enabled ordisabled based on selections in a contentcomponent such as a file list. “singleselect”means that the command will be enabled whenone and only one item is selected in a list control.• The name attribute is used internally, andnamed controls are cached.

• The value is the text string displayed on themenu. Usually, you will use an NLSID topoint to an entry in the strings directory. Forthis example, we enter the value directly asa text string

• The action called by this menu option will bethe “rename” action.

• showifinvalid is a boolean value. If thecommand is not valid for the selected items,the command will be displayed in grey on themenu.

Since the whitespace is ignored, it is easier toread tags that have one attribute per line. Thishas no impact on the application but makes iteasier 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 your IDE, create the file <webtop_root>/custom/config/remove_cancel_checkout_command.xml

2. Enter the code as shown.<config><scope><menuconfig modifies="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.


Figure 7. 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 your IDE, create the file <webtop_root>/config/menubar_configuration_3.xml

2. Enter the code as shown<config>

<scope><menuconfig

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

><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>

</menuconfig></scope>

</config>

3. Save the file.




Figure 8. 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 remove a command from the first location and insert the same command to thesecond location in the same menu, because you are removing from the original configuration fileand 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 your IDE, create the file <webtop_root>/config/menubar_configuration_4.xml

2. Enter the code as shown<config><scope><menuconfig modifies="menubar_file_menu:webcomponent/config/library/menubar/menubar_component.xml"><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></menuconfig></scope></config>

3. Save the file.

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

Removing an entire menuYou can use a configuration modification file to add, move, or remove entire menus on the menubar. Inthis 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 the menus bycopying the entire configuration element to your modification file to make your changes. You canadd, rearrange, or remove menus in your modification file. Just as an illustration, we will removethe View menu from the menubar.

To remove the View menu from the menubar

1. Using your IDE, 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 modifies="menubar:webcomponent/config/library/menubar/menubar_component.xml"><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 modifies="menubar:webcomponent/config/library/menubar/menubar_component.xml"><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>


8. Save your work.

9. Refresh the configuration.



Figure 9. 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. When your application will not pick up your changes, closeyour browser, restart the application server, open your browser, delete all offline content, then openWebtop, and your 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 page, the change is automatically picked up by the application server the nexttime you access the page, but only if the modification date on the file is later than the previous version.For example, if you replace your JSP page with a sample file from the developer site, the date of thesample file will likely be older than the date on your installed file, and the change will not be pickedup. The simplest way to fix this problem is to make an innocuous change to the file, such a adding anddeleting a space at the end of the file, and re‑save the file to give it a new modification date.

If you change Java code or Java properties files, you need to restart the application server in order forthe system to pick up 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 create your own components, be sure you have explored theoptions that ship with our product to see if the behavior is either already available or 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 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 afteryou have customized them.

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 see your changes to the default columns, you can clear your cookies after you refresh theconfiguration.


Configuring Columns in a Webtop List Control

Finding the filesOnce again, there is some detective work required to track down where columns are actuallydefined, due to the way the Webtop components are extended. All of the file paths given in thisexample are relative to the <webtop_root> directory on your application server. Looking in the<webtop_root>/webtop/config/myfiles_component.xml configuration file, we see that it extends thewebcomponent/config/library/myobjects/myobjects_list_component.xml configuration file.

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 your IDE, 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>


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><component modifies="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>


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 columnThe 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 adding a column, weare 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><visible>true</visible>

</column>. . .

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



Figure 10. 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 invisible

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><visible>false</visible>

</column>. . .

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



Figure 11. 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 12. Rearranging columns by moving column elements

. . .<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 13. Size column moved in front of the Version column

When you refresh the configuration, the columns are reversed.

The kinds of changes that are most important to your users are, by design, quick and convenient toimplement. Once you understand the configuration paradigm, updating your application can be acomparatively 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 your IDE, create a new file named “helloworld_menu_configuration.xml” in the <webtoproot>/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]"><actionmenuitem dynamic = "genericnoselect"name = "hello_world_menu_item"id = "hello_world_menu_item"value = "Hello World"action = "hello_world_action"showifinvalid = "true"/>

</insert>


Hello Webtop

</menuconfig></scope></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 3. 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.

<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.


Hello Webtop

Figure 14. 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.

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.


Hello Webtop

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>


Table 4. 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.

Step 4 — Creating the Hello World JSP pageThe 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.


Hello Webtop

<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 Componentpublic 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.

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.


Hello Webtop

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.

Step 5 — Adding static controls to the JSP pageThe 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 your IDE.

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>


Hello Webtop

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>


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 5. 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.


Hello Webtop

<%@ 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.

<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 and choose File > Hello World. Your text string from the propertiesfile 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 Eclipse.


Hello Webtop

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><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></dmf:body></dmf:html>

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 Eclipse.

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.


Hello Webtop

package com.mycompany.custom;

import com.documentum.web.common.ArgumentList;import com.documentum.web.formext.component.Component;import com.documentum.web.form.control.Label;


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.

Table 6. Code walkthrough

Snippet Description

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, 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.

Step 6 — Adding dynamic controls to the JSPpageAs 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 your IDE.

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.


Hello Webtop

<%@ 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()String repositoryName = null;IDfSession dfSession = getDfSession();tryrepositoryName = 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;


Hello Webtop

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;


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()String repositoryName = null;IDfSession dfSession = getDfSession();tryrepositoryName = dfSession.getDocbaseName();

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

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.


Hello Webtop


Snippet Description

IDfSession dfSession =

getDfSession();

When a browsermakes a request for a componentthat requires a connection to the database, WDKchecks to see if there is an active session and, ifnecessary, presents a login dialog. As a result,you do not have to do anything in your code toauthenticate your users unless you have specialneeds beyond the scope of the security providedby Webtop. We can anticipate that the user willalready have a valid session when accessing ourcomponent, and we can use the existing sessionto set values in our component.

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.

Step 7 — Adding databound controls to theJSP pageThe <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 page, then add a query to the Java class topopulate the tables. We will use a datagrid to display a list of users from the current repository.

To add databound controls to the JSP page

1. Open <WEBTOP_ROOT>\custom\hello_world\hello_world.jsp in your IDE.

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


Hello Webtop

<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><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>

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

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


Hello Webtop

Table 8. JSP page elements

Element Description

<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" />

The dmf:label tag displays a string value linkedto a datafield, which is a column from a table inthe repository. The table from which the rowsare selected is specified in the supporting Javaclass, but the column names you specify heremust match their names in the repository.

In this form, you are displaying only twocolumns of information, but you could displayall of the columns in the table if youchose to do so.

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;


Hello Webtop

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;trysessionManager = 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;

trydatagrid = (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();


Hello Webtop

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 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());

Datagrid datagrid = null;trydatagrid = (Datagrid) getControl("mygrid",Datagrid.class);


datagrid.getDataProvider().setDfSession(getRepositorySession());datagrid.getDataProvider().setQuery("select user_name, user_group_name" + " from dm_user where r_is_group = FALSE;");



Hello Webtop

private String getCurrentRepositoryName()String repositoryName = null;IDfSession dfSession = getDfSession();tryrepositoryName = dfSession.getDocbaseName();

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


IDfSession getRepositorySession()IDfSessionManager sessionManager = null;SessionManagerHttpBinding httpBinding = null;IDfSession dfSession = null;trysessionManager = 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(DfPrincipalException pe)System.out.println("Principal exception " + pe.getMessage());catch(DfServiceException se)System.out.println("Service exception " + se.getMessage());return (dfSession);

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


Hello Webtop


Snippet Description

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.


Hello Webtop

Snippet Description

datagrid.getDataProvider().

setDfSession(

getRepositorySession());

datagrid.getDataProvider().setQuery(

"select user_name, user_group_name"

+ " from dm_user where

r_is_group = FALSE;");


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) inorder to access the user’s current connectionto the repository to complete the transaction.The second 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).The third line tells the datagrid control to refreshitself with the new data.

IDfSession getRepositorySession()

IDfSessionManager sessionManager

= null; IDfSession dfSession

= null; try sessionManager

= SessionManagerHttpBinding.

getSessionManager(); String docbase

= SessionManagerHttpBinding.

getCurrentDocbase(); dfSession =

sessionManager.getSession(docbase);

The getRepositorySession() method be‑gins by creating null instances ofIDfSessionManager and IDfSession.Using the methods of SessionManager‑HttpBinding, the sessionmanager and docbasevariables are set, which allows you to get the cur‑rent session, 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.

Step 8 — Linking to a second JSP pageThis final step simulates a common need when working with data repositories — to find a piece ofinformation, then to find additional information based on the results of the first query. We will adda second JSP page 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" %>


Hello Webtop

<%@ 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.

Table 10. JSP page elements

Element Description

<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).


Hello Webtop

Element Description

<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 your IDE, 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>


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


Hello Webtop

<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"/>


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

We have created a link that will send the user_name to the Java behavior class. Now we need to createthe onClickLink() method so that the class will knowwhat to do with the user_name once it is received.

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)


Hello Webtop

this.setComponentPage("detail");

Label label = null;trylabel = (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;



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);

currentRepository.setLabel(getCurrentRepositoryName());

Datagrid datagrid = null;trydatagrid = (Datagrid) getControl("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();public void onClickLink(Link theLink, ArgumentList arg)this.setComponentPage("detail");

Label label = null;trylabel = (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);


Hello Webtop

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()String repositoryName = null;IDfSession dfSession = getDfSession();tryrepositoryName = dfSession.getDocbaseName();

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


IDfSession getRepositorySession()IDfSessionManager sessionManager = null;IDfSession dfSession = null;trysessionManager = 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(DfPrincipalException pe)System.out.println("Principal exception " + pe.getMessage());catch(DfServiceException se)System.out.println("Service exception " + se.getMessage());

return (dfSession);

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


Hello Webtop


Snippet Description

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.

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.)

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


Hello Webtop

• Populated controls with static values from a properties file and from a Java class• Populated controls with dynamic values based on DQL queries• 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 5Starting in a Specific Component

Most Web applications are accessed through an index.html or default.html page. This is the startingpoint of your application. In WDK 6 applications, the welcome file registered in web.xml has beenchanged to index.jsp in order to add the ability to detect tag pooling. In Webtop, this JSP pageredirects to the main component. In this tutorial, you will modify the main component to redirect to adifferent component.

The full source code for this customization is located on the EMC Developer Network site,developer.emccom.

The tutorial contains the following sections:• Task objective, page 67• Technical overview, page 67• Modifying the main component definition, page 68• Extending the main component class, page 69• Testing the configuration, page 70• Variations on this tutorial, page 70

Task objectiveYou will modify the application to redirect to the user’s My Files location. You must also suppress theuser preference for a starting component to see your customization applied to all users.

Technical overviewIn index.jsp, you see the redirect to the Webtop main component in the body onload event:<script src="index.js"></script><body onload='doRedirect("/component/main")'>


http://developer.emc.com

Starting in a Specific Component

The JavaScript function that is called, doRedirect(), is in the JavaScript file index.js, in the same rootdirectory as index.jsp:function doRedirect(whereTo)var strVirtualDir = __getVirtualDir();var dmfUrl = strVirtualDir + whereTo;window.location.replace(strVirtualDir + "/wdk/redirect.jsp?ReLoad=" +new Date().getTime() + "&__dmfUrl=" =" + dmfUrl);

The redirect is to a URL that ends with “/component/main”, which is evaluated by theComponentDispatcher servlet. This servlet is registered in web.xml and intercepts every URL that hasthe form /component/*. The component dispatcher looks up the component definition, in this case forthe main component, and launches its start JSP page.

You can’t simply redirect to another component here, unless that component sets up a nice frameset toreplace the one that is created by the main component. The solution is to modify the main component.

Modifying the main component definitionTo perform the redirect to another component, you could change the body onload event in index.jspto the following:<body onload='doRedirect("/component/myfiles_classic")'>

However, this would load the my files component into the entire frame, and you would lose the tree,titlebar, and other components of the frameset. You probably want to load the alternative componentinto the view frame. In this case, we move the customization to the main component. The maincomponent definition is in webtop/config, in the file mainex_component.xml. The only feature weneed to change is the class, which is specified as follows:<class>com.documentum.webtop.webcomponent.main.MainEx</class>

In your IDE, create a modification definition for the main component. Save the following contentas main_modifications.xml in custom/config:<?xml version="1.0" encoding="UTF8" standalone="no"?><config><scope><component modifies="main:webtop/config/mainex_component.xml"><replace path="class"><class>com.mycompany.main.MyMain</class>


You could modify the component to point to a new start page and then load a different component inthe view frame, but this will not apply to most users, because the start component is a preference. Youwill need to extend the main component to change the default start section. If you never want users to



set a different start component, you will also need to remove that option from the general_preferencescomponent JSP page.

Extending the main component classIn Eclipse, create a new directory under custom/src by right‑clicking com.mycompany and choosingNew > Folder. Name this folder main.

To create a custom MyMain class

1. Right‑click the main folder and choose New > Class. Name the class MyMain.

2. After the package declaration, add the following import statements:import com.documentum.web.common.ArgumentList;import com.documentum.web.formext.config.IPreferenceStore;import com.documentum.web.formext.config.PreferenceService;import com.documentum.webtop.webcomponent.main.MainEx;import com.documentum.webtop.app.AppSessionContext;import com.documentum.webtop.webcomponent.browsertree.BrowserTree;

3. Add the following onInit method. It will call a method setDefaultSection to change the default tomyfiles_classic:public void onInit(ArgumentList args)System.out.println("In MyMain component class");m_strAppType = AppSessionContext.getDefaultView();if (m_strAppType.equals("classic") == true)setDefaultSection(m_strAppType, "myfiles_classic");

super.onInit(args);

4. Add the setDefaultSection implementation. This resets the preference with every initialization ofthe main component:public static void setDefaultSection(String strView, String strSection)System.out.println("Writing " + strSection + "as default start section");if (strView.equals("classic"))IPreferenceStore preferenceStore = PreferenceService.getPreferenceStore();preferenceStore.writeString(("component[id=browsertree]." +BrowserTree.PREF_ENTRY_NODE), strSection);

5. Add the member variable:private String m_strAppType = null;



Testing the configurationRestart the application server and log in.

Variations on this tutorialBecause this customization does not remove the startup section preference, the user will be surprisedand probably annoyed that the preference does not happen. It would be best to remove the preferencefrom the general preferences component.

To do this, you will need to create a modifications definition for general_preferences_ex_component.xml located in webtop/config. You will replace the pages.start path with your custom <start> elementas follows:

Copy app_general_preferences_ex.jsp from webtop/environment/preferences to custom/preferences.(Make sure it is the same path that you have in your modifications file.) Then remove the followinglines:<tr><td class="fieldlabel rightAlignment nowrap" valign="top" scope="row" ><dmf:label nlsid="MSG_START_SECTION_HEADER"/></td>

<td class="defaultcolumnspacer leftAlignment" valign="top" >: </td><td class="leftAlignment" valign="top" style="paddingleft: 10px"><dmf:datadropdownlist name="<%=AppGeneralPreferences.CONTROL_SECTIONS%>" tooltipnlsid="MSG_START_SECTION_HEADER"><dmf:dataoptionlist><dmf:option datafield="id" labeldatafield="label"/>

</dmf:dataoptionlist></dmf:datadropdownlist><dmf:label nlsid="MSG_START_SECTION_DESCRIPTION" cssclass="noteWithoutPadding"/>

</td></tr>

Copy savedcredentials.jspf into custom/preferences, because this file is imported into the preferencesJSP page.

Refresh the configurations in memory by navigating to wdk/refresh.jsp. You do not need to restart theapplication server, because you have not changed a component class.


Chapter 6Creating 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 EMC Developer Network site,developer.emc.com.

The tutorial contains the following sections:• Task objective, page 71• Technical overview, page 72• Creating the component definition, page 73• Creating the component layout, page 73• Creating the component class, page 75• Supporting navigation between pages, page 77• Creating the action list datagrid, page 78• Creating the action info datagrid, page 80• Creating the resource bundle, page 84• Testing the customization, page 85• Variations on this tutorial, page 85

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:



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. Open the componentlist component configuration file component_list.xml, locatedin webcomponent/config/componentList. Save it to custom/config with the nameactionlist_component.xml

2. 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

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

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

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

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

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

8. 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 tocustom/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. This ensures that 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 changedto a curly quote. The compiler will show the line containing the error. You must ensure that thesesymbols are correct in your IDE before you compile.



You can get the full source code for this tutorial on the EMC Developer Network site,developer.emc.com.

To create the component class:

1. In Eclipse, expand the directory custom/src and select com.mycompany. Right‑click, chooseNew > Folder and name it actionlist. .

2. Create a new Java class by right‑clicking on the directory actionlist and selecting New > Class.

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

Note: If the package line appears different from that shown above, then you have not created thecorrect directory hierarchy, or you created the file within the wrong directory.

4. In the Source editor, following the package declaration, add the following import statements. Ifthe compiler flags errors, type them in instead of copying and pasting: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 Eclipse by 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 = new HashMap(23);private HashMap m_hashCfgScopeLookup = new HashMap(23);

6. Add an onInit() implementation that gets or creates the datagrids on both of the 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 mustbe commented out for now. See Creating the action list datagrid, page 78 for information on theupdateActionList() method, which creates or updates the actionlist datagrid.

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

8. Note any errors marked by a red X and correct them.

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");



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);

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: Several lines will have error markers for missing methods. You will add these supportingmethods and then the class will 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;



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

Creating the resource bundleIn Creating the component definition, page 73 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 Eclipse (or refresh), expand WEB‑INF/classes, and right‑click the directorycom.mycompany.actionlist. Select New®File. Name the file ActionListNlsProp.properties andthen click Finish

2. Add each of the following key and value pairs: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.emc.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 7Creating 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 87• Technical overview, page 88• Creating the component definition, page 88• Creating the component layout, page 88• Creating the component class, page 89• Creating the resource bundle, page 91• Testing the customization, page 91• Variations on this tutorial, page 92

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.TestListenerNlsProp</nlsbundle>

</component></scope>

</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.

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 compiler will show the line containing the error. You must ensure that thesesymbols are correct in your IDE before you compile.


To create the component class

1. In Eclipse, create a directory mycompany/test.

2. Create a new Java class by right‑clicking on the directory com.mycompany.test and choosingNew > Class.

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




4. In the Editor window, following the package declaration, add the following import statements: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, add an extends clause to the class definition:public class TestListener extends Component

6. Within the class definition, create the button event handler with the method name specified inthe JSP page (onImportListener). This method creates a new argument list with a hard‑codedvalue for the only parameter that is required for the import action. Substitute a valid folder ID inyour repository for the highlighted value. The method then calls the import action and registersthe listener:public 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. Correct any errors that are signalled by the compiler. You can compare against the code that ison the developer site.



Creating the resource bundleIn Creating the component definition, page 88 you specified an NLS resource bundle that will containthe string for your component button label: com.mycompany.test.TestListenerNlsProp. (If you enter abutton label value instead of nlsid attribute value in your JSP page, you do not need a resource bundle.)

To create a properties file in the new directory

1. In Eclipse, create the directory WEB‑INF/classes/com/mycompany/test.

2. Right‑click the mycompany.test directory and choose New > File.

3. Name the file TestListenerNlsProp.properties and click Finish.

4. Add the following key and value pair:MSG_IMPORT_LISTENER = Test Import Listener


Testing the customizationThe full source code for this customization is located on the EMC Developer Network site,developer.emc.com.

To refresh files and test the testlistener component

1. Stop and restart the application server.

2. 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. Test listener 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:import 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. Enhanced test listener console output


Chapter 8Limiting Import Types

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


The tutorial contains the following sections:• Task objective, page 95• Technical overview, page 96• Creating the component definition, page 96• Creating the component layout, page 97• Creating the component class, page 97• Creating the resource bundle, page 99• Testing the customization, page 100• Variations on this tutorial, page 102

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 import_modifications.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 modifies="import:webcomponent/config/

library/contenttransfer/importcontent/import_component.xml"><replace path="class"><class>com.mycompany.test.MyImportContent</class></replace>


3. After the closing </replace> element, insert the set of custom elements that will be used toconfigure the list of available object types. Substitute actual object types that are valid for yourrepository as the value of the <docbase_type>.<value> elements:<! specify the commaseparated list of types and subtypes)that will be available for import >

<insert><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>

</insert>




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().


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 Epic compiler will show the line containing the error.

You can get the full source code for this tutorial on the EMC developer network,developer.emc.com.


1. In Eclipse, create a directory WEB‑INF/classes/com/mycompany/test.

2. Create a new Java class by right‑clicking on the directory custom/src, in the packagecom.mycompany.test, t and selecting New > Class.

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

4. In the Editor window, following the package declaration, add the following import statements: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 Eclipse, adding an extends clause.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 forthe WDK import component, in the directory webcomponent/src/com/documentum/library/contenttransfer/import, you see that this the method provides content to the import typedropdown 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();

For now, ignore the compiler warning that the method getDocbaseTypes does not exist.

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;

8. The class is compiled on the fly as you add code. Fix any errors that are signalled by the compiler.You can compare against the code that is on the developer site.

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 of your component definition (XML file), and then create a propertiesfile with the nlsid keys and values. Note that you will need to copy in the contents of the WDKimport NLS file contents to your properties file.

Reference this NLS file in your component definition, and place it in the same directory as yourcompiled class: WEB‑INF/classes/com/mycompany/test.



Testing the customizationThe full source code for this customization is located on the EMC developer network,developer.emc.com.

To refresh files and test the testlistener 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 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. Todo this, you would need to add an element to the component definition that sets the default type,for example:</includetypes><defaulttype>dm_xml_style_sheet</defaulttype>

In your import class, type an additional import statement at the top:import com.documentum.web.form.control.databound.DataDropDownList;

Read the default type from the configuration in your getDocbaseTypes() method. Store the value in aclass member variable. Override the method that initializes the type list control and set the defaultvalue from your member variable, 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()IConfigElement 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 9Using 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 full source code for this customization is located on the EMC developer network,developer.emc.com.

The tutorial contains the following sections:• Task objective, page 105• Technical overview, page 106• Creating the tracing class, page 106• Adding tracing to the component class, page 107• Adding custom tracing to the actionlist component, page 108• Turning on tracing, page 108• Examining the trace log, page 109• Testing the customization, page 109• Variations on this tutorial, page 110

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, JSP pagerequests, 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. Afteryou enable tracing, tracing statements will be written to your wdk log file that you specified inlog4j.properties. If you do not specifiy a log file location in log4j.properties, he default location for thelog is <user.dir>/documentum/logs. The variable user.dir resolves to the application server binaryexecutables directory (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 included in the WAR file. This package allows youto 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.

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. The Eclipse compiler will show the line containing the error. Instead of copyingand 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/testand selecting New > Class.

2. Name the class MyTrac” and click Finish.Add an import statement after the package declaration:package com.mycompany.test;import com.documentum.web.common.Trace;

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

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

5. Note any compiler errors and resolve them. The exact location 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.test.MyTrace;

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

4. Add the following lines:if (MyTrace.ACTIONLIST)

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

else



MyTrace.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 actionlistcomponentTo 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 inWEB‑INF/classes/com/documentum/debug.

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

Turning on tracingYou must restart your application server to apply changes to a properties file and you tracing class.

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

...



Testing the customizationThe full source code for this customization is located on the EMC developer network,developer.emc.com.

To refresh files and test tracing:

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

2. Log in and turn on tracing as described in Turning on tracing, page 108.

3. Navigate to the actionlist component:http://localhost:8080/virtual_dir/component/actionlist

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

5. Examine the log to see your tracing statements.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 WAR_ROOT_DIR/WEB‑INF/classes/log4j.properties.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.

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:17:00:24,438 DEBUG [http80Processor23]com.documentum.web.common.Trace Result set successfully created17:00:39,163 DEBUG [http80Processor23]com.documentum.web.common.Trace Returning to start page

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);

The tracing statement:

Figure 23. JavaScript tracing


Chapter 10Customizing UCF for Silent Export

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

Figure 24. 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 for Silent Export

The full source code for this customization is located on the EMC Developer Networkd site,developer.emc.com.

The tutorial contains the following sections:• Task objective, page 112• Technical overview, page 112• Modifying the component definition, page 113• Creating the component class, page 113• Testing the customization, page 115• Variations on this tutorial, page 116

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.

This custom component requires no UI, so there will be no custom JSP page or NLS properties file.

Technical overviewThe UCF export container calls the file selector applet to allow the user to select the export location.In the Webtop WAR file, 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 see that the container onInit() method redirects to the component page(“selectfolder”). This JSP page 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.




Modifying the component definitionTo create a new WDK silent export component, you must modify the export component definition.

To modify the exportcontainer definition

1. In your IDE, create a file exportcontainer_modifications.xml in the directory custom/config.

2. Add the following content:<?xml version="1.0" encoding="UTF8" standalone="no"?><config version='1.0'><scope><component modifies="exportcontainer:webcomponent/config/library/contenttransfer/export/exportcontainer_component.xmlapplication='webcomponent' type='dm_sysobject' "><replace path="class"><class>com.mycompany.export.MyUcfExportContainer</class>

</replace>

<insert><silentexportpath>C:\temp\testexport</silentexportpath>

</insert></component>



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. TheEclipse compiler will show the line containing the error. You must ensure that these symbolsare correct in your IDE before you compile.



1. In Eclipse, 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 choosing New > Class.

3. Name the object MyExportContainer and click Finish.




The file will be created with the package declaration and class definition. Add the highlightedimport 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 MyExportContainer 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;

elsestrDir = 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();

9. Correct any errors that are signalled by the compiler. You can compare against the code that ison the developer site.

Testing the customizationThe full source code for this customization is located on the EMC Developer Network site,developer.emc.com.

To refresh files and test the testlistener component:

1. On your local file system, create the location for your exported files that you specified in the XMLmodifications file, for example, C:\temp\testexport.

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

3. 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 or in the default location specified in the configuration file. If the document is virtual orXML, you will be presented with a dialog asking whether you 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 11Troubleshooting

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

Did you compile your Java class?If you create a new Java file in Eclipse, it is automatically compiled. Make sure the compiled class goesto the right subdirectory of WEB‑INF/classes.

Did you refresh the configuration service?If you make changes to an XML resource file, you need to refresh the configuration files in memory,either by navigating to http://server_name:port_number/virtual_dir/wdk/refresh.jsp or by stoppingand restarting the application server.

Did you remove generated JSP class files?Normally, the application server picks up changes to JSP files. Certain changes such as underlyingdata that is supplied to the JSP page, or calling a JSP page from a container, will not trigger


Troubleshooting

an update in the application server. You may need to clear the cache by deleting the directorytomcat_home_directory/work/Catalina/localhost/virtual_dir.

Did you clear the browser cache?If you make changes to JavaScript or to a control that generates JavaScript, you should clear yourbrowser cache as described in the following 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.

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.


Index

Aactionmenuitem, 20application start page, 67ArgumentList object, 64

Bbrowser cache

clearing, 118

Ccaches

clearing, 12clearing caches, 12column

adding, 31configuration, 30rearrange, 33remove, 32visible, 31

componentconfiguration, 37

configurationdefined, 9XML file, 37

Configuration Servicerefreshing, 117

content transferlistener, 87

conventionstypographical, 11

custom layer, 13inheritances and overrides, 13

customizationdefined, 9

Ddatabound control, 49datafield, 51

datagrid, 64JSP tag, 51

DatagridJava object, 55

datevalueformatter tag, 59Docbases

limiting selection, 71DQL

sample query, 56

Eenvironment, 11

FForte for Java

setting up, 14

Ggenerated files

removing, 117getDataProvider, 64getRepositorySession, 56

IIDE

setting up, 14import

limiting types, 95

JJava class files

precompiling, 117JSP

adding static controls, 40simple, 38Tag Library Definitions (TLDs), 40


Index

Llabel, 64

with dynamic Java text, 45with NLS text, 41

label objectwith static Java text, 43

linkJSP tag, 59

logging, 105

Mmenu

add command, 17rearrange commands, 22remove command, 21remove menu, 24replace command, 23

menubarconfiguration, 35

menubar_component.xml, 35

NNational Language Support (NLS), 40NLS, 40

in label object, 41

OonClickLink, 60, 64onRender, 64

Ppreparing for the tutorials, 11

projectcreating, 14

Rrefreshing the Configuration Service, 117

Ssession management, 55SessionManagerHttpBinding, 55showifinvalid, 20start page, 67Sun ONE Studio

setting up, 14

TTag Library Definitions (TLDs), 40TLDs, 40tracing, 105troubleshooting, 117typographical conventions, 11

Uunexpected behavior, 26

XXML

configuration file, 37XML resource file

checking name and location, 118
