EMC Documentum Web Development Kit

Transcription

1 EMC Documentum Web Development Kit Version Tutorial EMC Corporation Corporate Headquarters: Hopkinton, MA

2 Legal Notice Copyright EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED "AS IS." EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS 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. Adobe and Adobe PDF Library are trademarks or registered trademarks of Adobe Systems Inc. in the U.S. and other countries. All other trademarks used herein are the property of their respective owners. Documentation Feedback Your opinion matters. We want to hear from you regarding our product documentation. If you have feedback about how we can make our documentation better or easier to use, please send us your feedback directly at ECD.Documentation.Feedback@emc.com

3 Table of Contents Preface... 9 Chapter 1 Tutorial Preparation and Basics Typographical Conventions Used in the Tutorials Setting Up the Environment for the WDK Tutorials Tutorial Basics Clearing Caches and Refreshing Overview of the Custom Layer Custom Layer Definition Inheritances and Overrides Setting Up an IDE Creating a Project in NetBeans Mounting the WDK Directories Mounting the DFC JAR Files Stopping the Internal Tomcat Server Chapter 2 Configuring the Webtop Menubar Finding the files Adding a command to a menu Removing a command from a menu Rearranging commands in a menu Replacing a command in a menu Removing an entire menu When the application behaves in an unexpected manner Small changes, big impact Chapter 3 Configuring Columns in a Webtop List Control Areas of personal confusion Finding the Files Adding a column Removing a column Rearranging Columns Chapter 4 Hello Webtop Step 1 Configuring the MenuBar Step 2 Configuring the Hello World Action Step 3 Configuring the Hello World Component Step 4 Creating the Hello World JSP Step 5 Adding Static Controls to the JSP Step 6 Adding Dynamic Controls to the JSP EMC Documentum Web Development Kit Version Tutorial 3

4 Table of Contents Step 7 Adding Databound Controls to the JSP Step 8 Linking to a Second JSP Chapter 5 Creating a Start Page for a New WDK Application Variations in this tutorial Chapter 6 Adding a Logout Link Task Objective Technical Overview Creating the Custom Layer Files Extending the Drilldown Component Modifying the Generic Actions XML File Creating a Custom Resource File Testing the Logout Link Extending the Logout Action Variations in this tutorial Chapter 7 Creating an Action List Component Task Objective Technical Overview Creating the Component Definition Creating the Component Layout Creating the Component Class Supporting Navigation Between Pages Creating the Action List Datagrid Creating the Action Info Datagrid Creating the Resource Bundle Testing the Customization Variations in this tutorial Chapter 8 Creating a Content Transfer Listener Task Objective Technical Overview Creating the Component Definition Creating the Component Layout Creating the Component Class Creating the Resource Bundle Testing the Customization Variations in this tutorial Chapter 9 Limiting Import Types Task Objective Technical Overview Creating the Component Definition Creating the Component Layout Creating the Component Class EMC Documentum Web Development Kit Version Tutorial

5 Table of Contents Creating the Resource Bundle Testing the Customization Variations in this tutorial Chapter 10 Using Tracing and Logging in a Component Task Objective Technical Overview Creating the Tracing Class Adding Tracing to the Component Class Adding Custom Tracing to the List Turning on Tracing Testing the Customization Examining the Trace Log Variations in this tutorial Chapter 11 Customizing UCF Export Task Objective Technical Overview Creating the Component Definition Creating the Component Layout Creating the Component Class Creating the Resource Bundle Testing the Customization Variations in this tutorial Chapter 12 Troubleshooting Did you precompile your Java class? Did you refresh the Configuration Service? Did you remove generated files? Did you clear the browser cache? Did you check the name and location of the XML resource file? EMC Documentum Web Development Kit Version Tutorial 5

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

7 Table of Contents List of Tables Table 1. Directory Structure of the Custom Layer Table 2. Highlights from hello_world_action.xml Table 3. Highlights from hello_world_component.xml Table 4. Highlights from hello_world.jsp EMC Documentum Web Development Kit Version Tutorial 7

8 Table of Contents 8 EMC Documentum Web Development Kit Version Tutorial

9 Preface The EMC Documentum Web Development Kit (WDK) is a huge, daunting, powerful, intimidating (etc.) development platform. It can be hard to figure out where to get started. That s where this guide comes in. The purpose of this manual is to give smart, capable programmers (like you) insight into the design decisions and practical use of WDK so that you can move on to solving 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 JSPs to add new functionality. Customization requires a 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 action methods XML To customize WDK-based applications, you should be familiar with the above-mentioned technologies in addition to the following additional languages and standards. Java 1.7 and 1.8 J2EE Java Servlet technology, in the version supported by your application server Portlet Specification (JSR 168) (WDK for Portlets only) EMC Documentum Web Development Kit Version Tutorial 9

10 Preface Revision History Revision Date December 2015 Description Initial publication. 10 EMC Documentum Web Development Kit Version Tutorial

11 Tutorial Preparation and Basics Chapter 1 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 Tutorials This guide uses italics for replaceable parts of a path or URL. For example: In the above URL, server_name should be replaced with the host name, the port_number should be replaced with the port number defined for your application server (the default port number for a Tomcat application server is 8080), and virtual_dir should be replaced with the virtual directory that was created during installation of WDK or a WDK application. If you are accessing the application through 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 within quotes (in which case they simply need to match). In this exercise, double quotes are used for new entries, unless single quotes are required. The use of quotation marks in existing files is largely up to the whim of the original developer, and is not significant. Setting Up the Environment for the WDK Tutorials The procedures in this guide are based on the environment as discussed : JDK 1.7 and 1.8 Tomcat and EMC Documentum Web Development Kit Version Tutorial 11

12 Tutorial Preparation and Basics Note: The tutorial procedures are based on the Tomcat J2EE application server, selected because it is a free download. You can use any application server that is certified for WDK. WDK 6.8 The EMC Documentum Web Development Kit Release Notes contains the information on hardware and software requirements. The EMC Documentum Web Development Kit and Webtop Deployment Guide contains instructions on installing WDK and verifying your installation on an application server. (Optional) Webtop or another WDK client application, with WDK installed to customize that application (See EMC Documentum Web Development Kit and Webtop Deployment Guide for the procedure on installing WDK to customize a WDK client application.) A Java IDE Note: You can use any J2EE-compliant IDE to compile the Java code for the customization tasks. Tutorial Basics The 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. An easy way to do this is to open a browser, log into the WDK application, and navigate to (You must have a session before refreshing the configuration definitions in memory.) If you add a new JSP file, the page will be compiled automatically by the application server. If you change a JSP file that contains server-side generated content or included JSP files, or if you modify any JavaScript function, you should clear the java and class files by deleting the folder tomcat_home/work/standalone/localhost/virtual_dir or navigating within the folder to the files themselves and deleting them. Repeat the process if necessary for tomcat_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 clear the data dictionary cache to see your changes. You must wait until the dictionary change has been published to the Content Server, which is usually done by a job running at regular intervals on the Server. If you have access to the application server, you can delete the data dictionary files yourself, forcing the 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 replace any existing class files. 12 EMC Documentum Web Development Kit Version Tutorial

13 Tutorial Preparation and Basics Overview of the Custom Layer WDK and WDK applications make use of a customization layer, which allows you to keep configurations and customizations in a location separate from the installed product. This allows the custom layer to be easily migrated after an upgrade or reinstallation. A default custom directory is installed with the product in the following location: virtual_dir/custom This directory is installed with the subdirectories and files shown in the following figure. Figure 1. Custom Directory Contents after Installation The custom layer usually contains the directories shown above. The directory contents, and additional directories for your custom components, are described in the table below. Table 1. Directory Structure of the Custom Layer Directory of File Name custom/config custom/component_name custom/strings custom/theme app.xml Contents XML resource files JSP pages. Recommended one folder per component. Custom resource strings Custom themes (to change the look and feel of the UI) File for changes to app.xml settings Custom Layer Definition Inheritances and Overrides When you extend a definition in a configuration file in WDK or a WDK application, any element that is defined in the custom definition will override that same element in the definition that has been extended. If the element is not specified in the custom definition, that element will be inherited from the component that has been extended in the XML resource file. For example, suppose you want to extend the docbaseattributelist control definition, which includes the section below: <config version="1.0"> <scope>... <category> EMC Documentum Web Development Kit Version Tutorial 13

14 Tutorial Preparation and Basics <name><nlsid>msg_info</nlsid></name> <attributes> <attribute name="object_name"/> <attribute name="title"/> <attribute name="authors"/> <attribute name="keywords"/> <attribute name="subject"/> <attribute name="r_version_label"/> <attribute name="owner_name"/> <attribute name="r_creation_date"/> <attribute name="r_modify_date"/> <attribute name="r_content_size"/> </attributes> <moreattributes> <attribute name="a_status"/> <attribute name="i_is_reference"/> <attribute name="i_is_replica"/>... </moreattributes> </category>... </scope> </config> In this example, if you include the category element in your extended definition, this will overwrite all <category> elements. This means that you must repeat any <attribute> elements that you want to include in your override. If you want to add a single element, in your extended definition you must repeat the entire list of attributes plus add the one additional attribute. Setting Up an IDE When you create a custom class, you compile it using either an IDE, such as the NetBeans IDE, or an external compiler. This section contains information on creating a project in the NetBeans IDE. If you use another IDE, consult the IDE documentation for the proper way to set the classpath and reference the external libraries. This guide uses the NetBeans IDE version 3.6 for the customization tutorials that require compiling Java classes. You can use it as your text editor for the configuration tutorials as well. Creating a Project in NetBeans To create a new project in NetBeans 1. Open the NetBeans IDE. 2. Choose Project > Project Manager. 3. Click New. 4. Create a name for your project, such as wdk6, and click OK. 14 EMC Documentum Web Development Kit Version Tutorial

15 Tutorial Preparation and Basics Mounting the WDK Directories Mounting the WDK Java archives effectively sets the classpath for your project. To mount the WDK directories: 1. Select File > Mount Filesystem from the NetBeans IDE menu bar. 2. Select Local Directory as the filesystem type, then click Next. 3. Navigate to the directy in which you have installed the Tomcat application server, and open the /webapps subdirectory. Highlight the virtual directory in which you installed WDK (for example, wdk53), then click Finish. Note: If you see a message that an alternate view is available, you can safely ignore it. 4. Select File > Mount Filesystem from the NetBeans menu bar. Mounting the DFC JAR Files Use the following procedure to mount the DFC JAR files necessary for the project. To mount the DFC JAR files: 1. Select File > Mount Filesystem from the NetBeans IDE menu bar. 2. Select Archive Files as the filesystem type, then click Next to move to the next page. 3. Navigate to the Shared subdirectory of the DFC program root. (The default location on Microsoft Windows is C:\Program Files\Documentum\Shared.) Highlight all the JAR files listed, and then click Finish. Stopping the Internal Tomcat Server If you are running NetBeans, stop the internal Tomcat server instance before starting an external Tomcat server. Use the following procedure. To stop the NetBeans IDE server instance: 1. Click the Runtime tab in the Explorer frame. 2. Expand the tree to Server Registry > Tomcat 5 Servers > 3. Right-click on to see whether the server has been started. If the status is running, select Stop Server. EMC Documentum Web Development Kit Version Tutorial 15

16 Tutorial Preparation and Basics Caution: Do not start an internal or external Tomcat server from within the IDE using the default command arguments. The default start script will not use the environment settings required by WDK. 16 EMC Documentum Web Development Kit Version Tutorial

17 Configuring the Webtop Menubar Chapter 2 A good place to start configuring and customzing WDK applications is to make simple changes to the menubar to address your users specific business requirements. Finding the files The first step in any configuration or customization is to locate the files we want to modify. This takes 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 is defined as shown in. Figure 2. Fragment of /webtop/config/menubar_component.xml as shipped <component id = "menubar" extends="menubar:/webcomponent/config/library/menubar/menubar_component.xml"> That tells us that the actual configuration information is extended from the lower-level definition in the 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 configuration information files that come with the product as shipped. That approach still works. However, since Version 6, you have the option of modifying the user interface by adding, removing, or replacing individual configuration elements. The new approach makes it more likely that your customizations will continue to work with future releases without having to make modifications. Adding a command to a menu We will insert the Rename command to the File menu, just after the Save As... command. EMC Documentum Web Development Kit Version Tutorial 17

18 Configuring the Webtop Menubar Figure 3. File menu before modification To insert the Rename command to the File menu: 1. Using any text editor, create a new file named menu_configuration_1.xml in the <webtop root>/custom/config directory. 2. Enter the following code: <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 in your browser. 18 EMC Documentum Web Development Kit Version Tutorial

19 Configuring the Webtop Menubar Figure 4. File menu with Rename command Now we will take a closer look at the elements of the file you just created. <config> <scope>... </scope> </config> <menuconfig modifies= "menubar_file_ menu: webcomponent/config/library/ menubar/menubar_component.xml">... </menuconfig> The primary element in the configuration file is the <config> tag. The <scope> tag is required, whether or not you re restricting the configuration to a specific scope. This tag identifies the primary element in the configuration file we want to modify. Note that the modifies attribute string begins with the ID of the element we will modify. This is not an arbitrary value (as with namespaces) but the specific ID of the element as it appears in the referenced configuration file.the portion after the colon gives the location of the configuration file to be modified, relative to the <webtop_root> directory. EMC Documentum Web Development Kit Version Tutorial 19

20 Configuring the Webtop Menubar <insertafter path= "menu[name=file_ menu]. actionmenuitem[name=file_ saveas]" >... </insertafter> <actionmenuitem dynamic = "singleselect" id = "file_rename" name = "file_rename" value = "Rename" action = "rename" showifinvalid = "true" /> This tag identifies the type of modification. In this case, we will insert a new menu item and have it appear after an existing item. The path argument uses dot notation to identify the location to be modified in the referenced XML configuration file.our new menu item is added to the menu definition named file_menu. It appears after the actionmenuitem tag with the name file_save_as. We need to create a new action menu item object and set its custom attributes. You can use the command descriptions in the menubar_component.xml configuration file as a guide for creating your own action menu item. This is a dynamic control, meaning that it can be automatically enabled or disabled based on selections in a content component such as a file list. By setting it to singleselect, the command will be enabled when one and only one item is selected in a list control. The name attribute is used internally by the server controls with names are cached automatically. The value is the text string displayed on the menu. Usually, you will use an NLSID to point to an entry in the strings directory. For this example, we just enter the value directly as a text string. The action called by this menu option will be the rename action. showifinvalid is a boolean value. If the command is not valid for the selected items, the command will be displayed in grey on the menu. Setting this attribute to false hides this command when the selection is an invalid target for this command. You may notice a difference in the way I format the tags. Since the whitespace is ignored, I find it easier to read tags that have one attribute per line. This has no impact on the application, but makes it easier for humans to read. 20 EMC Documentum Web Development Kit Version Tutorial

21 Configuring the Webtop Menubar Removing a command from a menu Removing a command from a menu follows a similar pattern to adding a menu item. We create a configuration file that identifies the <menuconfig> tag to modify, then use a <remove> element to hide the <actionmenuitem> element we do not want to display. As an example, we will remove the Cancel Checkout command (for no particular reason, just a random target for illustrative purposes). To remove a menu item from a menu 1. Using any text editor, create the file <webtop_root>/custom/config/remove_cancel_checkout_ command.xml 2. Enter the code as shown. <config> <scope> <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. 4. Refresh the configuration by opening in your browser. Figure 5. File menu with Cancel Checkout command removed The only way this file differs from the configuration file for adding a menu is the <remove> element. <remove path= "menu[name=file_menu].actionmenuitem[name=file_cancelcheckout]" /> EMC Documentum Web Development Kit Version Tutorial 21

22 Configuring the Webtop Menubar Since we are not adding anything new to the menu, we just have to provide the dot path to the cancelcheckout actionmenuitem in a single closed tag. Nothing is actually lost or changed in the underlying application the command is just hidden at runtime. Rearranging commands in a menu To rearrange items in a menu, remove the item from its current position, then insert it at the new position. To move a menu item to a new location on the same menu: 1. Using any text editor, create the file <webtop_root>/config/menubar_configuration_3.xml 2. Enter the code as shown <config> <scope> <menuconfig modifies="menubar_file_menu:webcomponent/ config/library/menubar/menubar_component.xml"> <remove path="menu[name=file_menu].actionmenuitem [name=file_cancelcheckout]"/> <insertbefore path="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. 4. Refresh the configuration by opening in your browser. 22 EMC Documentum Web Development Kit Version Tutorial

23 Configuring the Webtop Menubar Figure 6. File menu with Cancel Checkout command moved before Delete command In that example we used the <insertbefore> element to make the command appear above the Delete command in the menu. It is interesting to note that it does not actually matter in which order you add or remove items from the menu. The changes you make in the configuration modification file only affect the items in the original configuration file, not the items in your configuration modification file. There is no conflict when you say remove and insert the same command on the same menu, because you are removing from the original configuration file and inserting to the original configuration file. Replacing a command in a menu You can also replace an existing command in a menu with a version of your own. One use case would be changing the attributes of an existing command to one better suited for your organization. For example, you might be concerned that your users could inadvertently delete the wrong file when deleting a multiple selection from what should be a stable, archival repository. We can redefine the delete menu item with the dynamic attribute set to singleselect, forcing users to carefully delete one file at a time. When changing an element this way, the easiest thing to do is to copy the original element from the configuration file that ships with the product, create a new configuration file that modifies the original, paste the element into a <replace> element, and make the modifications there. To replace a menu item: 1. Using any text editor, create the file <webtop_root>/config/menubar_configuration_4.xml EMC Documentum Web Development Kit Version Tutorial 23

24 Configuring the Webtop Menubar 2. Enter the following code: <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 in your browser In Webtop, when you select one item in a file list, the Delete command is still enabled. If you select more than one item at a time, the Delete command is now disabled. Removing an entire menu You can use a configuration modification file to add, move, or remove entire menus on the menubar. In this case, you reference the primary element <component> and modify the <menuconfigids> element. These elements do not have a name or ID attribute you modify the configuration of the menus by copying the entire configuration element to your modification file to make your changes. You can add, rearrange, or remove menus in your modification file. Just as an illustration, we will remove the View menu from the menubar. To remove the View menu from the menubar: 1. Using any text editor, open the file <webtop_root>/webcomponent/config/library/menubar/ menubar_component.xml. 2. In the <config> element, locate the <menuconfigids> element. 3. Select the entire <menuconfigids> element and copy it. 4. Create a new configuration file, <webtop_root>/custom/config/remove_view_menu.xml 5. Enter the following code in the configuration file. <config version="1.0"> <scope> <component modifies="menubar:webcomponent/config/library/ menubar/menubar_component.xml"> <replace path="menuconfigids"> </replace> </component> </scope> </config> 6. Paste the current <menuconfigids> information inside the <replace> element. <config version="1.0"> <scope> 24 EMC Documentum Web Development Kit Version Tutorial

25 Configuring the Webtop Menubar <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> </replace> </component> </scope> </config> 8. Save your work. 9. Refresh the configuration. Figure 7. Webtop menubar with the View menu removed EMC Documentum Web Development Kit Version Tutorial 25

26 Configuring the Webtop Menubar When the application behaves in an unexpected manner There are times when you change the configuration of your application, but your changes are not reflected when you open the browser. There are many possible explanations, none of which really matters, since what you want to do is see your application work the way you defined it. Any parent knows that when a baby will not stop crying, you strip it, diaper it, dress it, feed it, burp it, hold it and sing to it. When your application will not pick up your changes, close your browser, restart the application server, open your browser, delete all offline content, then open Webtop, and your changes should display. When you modify a configuration file, you can refresh your configuration by opening in your browser. When you modify a JSP, the change is automatically picked up by the application server the next time 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 with a sample file from the developer site, the date of the sample file will likely be older than the date on your installed file, and the change will not be picked up. The simplest way to fix this problem is to make an innocuous change to the file, such a adding and deleting a space at the end of the file, and re-saving the file to give it a new modification date. If you change Java code, you need to restart the application server in order for the system to pick up your changes. Small changes, big impact As you can see, rather minor updates to the configuration of a component can tailor the interface to meet the specific needs of your users. The complex programming that supports these controls has largely been handled for you. Before you contemplate creating your own components, be sure you have explored the options that ship with our product to see if the behavior is either already available or easily configured. 26 EMC Documentum Web Development Kit Version Tutorial

27 Chapter 3 Configuring Columns in a Webtop List Control In this lesson, we are going to add, move, and remove columns from the My Files classic list component. We will need to: Identify the configuration files to modify. Create a modification file in the /custom/config directory. Edit the column elements and attributes in the configuration modification file. Refresh the configuration to see the results. Areas of personal confusion There are a couple of potential points of confusion when you are refreshing column configuration, so I will talk about those here, before we get started. When I was preparing these examples, everything was working fine, then suddenly the configuration stopped updating after my changes. Now, I shut everything down and brought it all back up and the changes appeared as they should. But that is the brute force approach; the actual solution to my confusion 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 are picked up by the browser automatically. If a user has set column preferences, the user can open the Column Preferences dialog and click Reset to defaults to return the new default settings. However, it is important to note that Reset to defaults does not clear the user s settings: it stores the default list of visible columns. If the defaults change, the user will need to return to the Column Preferences dialog every time s/he wants to pick up the changes. If the user clears the browser s cookies, that enables the browser to pick up any changes going forward. To save trouble, I cleared my cookies so that I could see the changes reflected immediately after I refreshed the configuration, but that is a decision I will leave up to you. Finding the Files Once again, there is some detective work required to track down where columns are actually defined, due to the clever reuse and extension of the default Webtop components that come into play. All of the EMC Documentum Web Development Kit Version Tutorial 27

28 Configuring Columns in a Webtop List Control file paths given in this example are relative to the <webtop_root> directory on your application server. Looking in the /webtop/config/myfiles_component.xml configuration file, we see that it extends the /webcomponent/config/library/myobjects/myobjects_list_component.xml configuration file. Then, we can copy the entire <columns> element from /webcomponent/config/library/myobjects/ myobjects_list_component.xml and paste it into our new configuration modification file. To create the myfiles component column configuration file 1. Using any text editor, create the file /custom/config/myfiles_configuration_modification.xml 2. Enter the following code in the file you just created: <config version="1.0"> <scope> <component modifies="my_object_list:webcomponent/config/ library/myobjects/myobjects_list_component.xml"> <replace path="columns"> </replace> </component> </scope> </config> 3. Using any text editor, open the file webcomponent/config/library/myobjects/myobjects_list_ component.xml 4. Copy the entire <columns> element. (You need to copy and override the entire element, because the 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> element into 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> 28 EMC Documentum Web Development Kit Version Tutorial

29 Configuring Columns in a Webtop List Control </columns> </replace> </component> </scope> </config> 7. Save the file myfiles_configuration_modification.xml. That is a large amount of code to reproduce, but if you modify any column, you have to copy not just that element but all of its siblings as well. Adding a column What is nice is that the default list of all available columns is already included in the columns element. The <visible> element determines whether or not the column is displayed. When we talk about adding a column, we are really just talking about making the column visible to the user. To make a column visible: 1. Locate the title definition (second <column> element from the top). 2. Comment out the existing <visible> element; a best practice is to include your name and the date you made the change. 3. Create a new <visible> tag set and set the value to true, as shown:... <column> <attribute>title</attribute> <label> <nlsid>msg_attr_title</nlsid> </label> <!-- Changed to true by Dennis Dawson July 2007 <visible>false</visible> --> <visible>true</visible> </column> Refresh the configuration by opening EMC Documentum Web Development Kit Version Tutorial 29

30 Configuring Columns in a Webtop List Control Figure 8. My Files page with Title column displayed Removing a column Remove a column from the display by changing its visible attribute to false. For no particular reason, we will remove the Name column, just because it is easy to find this is not a practical example. To make a column visible: 1. Locate the object_name column definition (the first <column> element). 2. Comment out the existing <visible> element; a best practice is to include your name and the date you made the change. 3. Create a new <visible> tag set and set the value to false, as shown:... <column> <attribute>object_name</attribute> <label> <nlsid>msg_name</nlsid> </label> <!-- Changed to false by Dennis Dawson July 2007 <visible>true</visible> --> <visible>false</visible> </column> Refresh the configuration by opening 30 EMC Documentum Web Development Kit Version Tutorial

31 Configuring Columns in a Webtop List Control Figure 9. My Files page with Name column hidden Rearranging Columns You 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 the configuration file. Figure 10. Rearranging columns by moving column elements... <!-- Rearranged Size and Version columns Dennis Dawson July > <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>... EMC Documentum Web Development Kit Version Tutorial 31

32 Configuring Columns in a Webtop List Control Figure 11. Size column moved in front of the Version column When you refresh the configuration, the columns are reversed. At this point you can see that you can quickly make useful updates to your Webtop application without burrowing through page after page of spaghetti code. The kinds of changes that are most important to your users are, by design, quick and convenient to implement. Once you understand the configuration paradigm, updating your application can be a (comparatively) painless process. 32 EMC Documentum Web Development Kit Version Tutorial

33 Hello Webtop Chapter 4 This lesson provides a complete, if not terribly useful, example of Webtop customization. In this lesson, you will configure the Webtop menubar to display a custom command, configure a custom action 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 query in one component page to open another page to display detailed information. Step 1 Configuring the MenuBar We will begin by performing a series of configurations. Many of the most common changes reported by our customers are not so much customizations (involving massive redesign and modification of Java code) as minor changes to existing behavior (changing the layout of components, adding or removing options, 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 a modification to the menubar_component.xml configuration file. To insert the Hello World command to the Tools menu: 1. Using any text editor, create a new file named helloworld_menu_configuration.xml in the <webtop root>/custom/config directory. 2. Enter the following code: <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> </menuconfig> </scope> </config> 3. Save the file. EMC Documentum Web Development Kit Version Tutorial 33

34 Hello Webtop Step 2 Configuring the Hello World Action In Step 1, you modified an existing configuration file, making a minor adjustment to include our custom command. For this step, you will configure a completely new component. We will add a new XML file. We will name the file <webtop_root>\custom\config\hello_world_action.xml. Note that the file name is not significant, but it can be helpful to include the word action in the title to distinguish the file from other configuration files in the same folder. Here is the text of hello_world_action.xml. Enter this code in a text editor, then save the file in as <webtop_root>\custom\config\hello_world_action.xml. <config version = "1.0"> <scope> <action id = "hello_world_action"> <execution class="com.documentum.web.formext.action.launchcomponent"> <component>hello_world_component</component> <container>dialogcontainer</container> </execution> </action> </scope> </config> Table 2. Highlights from hello_world_action.xml <action id = "hello_world_action"> <execution class="com... LaunchComponent"> <component>hello_world_component</ component> <container>dialogcontainer</ container> This is the name of the action. It must be unique. It must match the name we gave the command in the menubar.jsp file in order to work with our example. You can call any Webtop class from the action, including your own custom classes. In our example, we will use one of the built-in WDK classes to launch the component. This is the name of the component we will launch with the action. It needs to match the component name in the component XML file that we will create in the next step. This tag is optional for the hello_world example. It tells Webtop to display the output from the component wrapped in a container that adds OK, Cancel, and Help buttons. 34 EMC Documentum Web Development Kit Version Tutorial

35 Hello Webtop Figure 12. Tools menu with inserted Hello World command To recap, you have now defined the Hello World menu command, and configured a new action that will be invoked by your menu command. Just for fun, you can restart your application server and look at the Tools menu. You can select the command, and get an exciting error message (always nice to know that the error mechanism is working properly). The reason we get the error is that we told Webtop to invoke the hello_world_component, but we have not yet defined the component. We will define the component in the next two steps. Step 3 Configuring the Hello World Component Components usually have four elements an XML configuration file, one or more JSPs, a Java behavior 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 embed its Java behaviors, it is generally considered a best practice to create three unique elements for each component. We will construct the Hello World component using an iterative process that lets us run the application at different stages, gradually building more complex behaviors. The XML configuration file binds together the elements of the component. For all intents and purposes, you can think of the component as the XML configuration file that defines it. The elements of the component may be used in more than one component, and a component can have more than one JSP, so only the configuration file brings all of the elements together in one place. We will create the component configuration file first, then build the elements of the 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="iso " standalone="no"?> <config version="1.0"> <scope> EMC Documentum Web Development Kit Version Tutorial 35

36 Hello Webtop <component id="hello_world_component"> <pages> <start>/custom/hello_world/hello_world.jsp</start> </pages> <class>com.mycompany.custom.hellowebtop</class> </component> </scope> </config> Table 3. Highlights from hello_world_component.xml <component id= hello_world_ component > <pages><start>...hello_world.jsp</ start> <class>com.mycompany.custom. HelloWebtop</class> This is the name of the component. It must be unique. It must match the name specified in the hello_world_action.xml file s <component/> tag. This defines the JSP files used by the component. This identifies the Java class that supports the component. To recap, we have created a menu item for the Hello World application. We have defined an action that is to invoke the hello_world_component. We have created the XML configuration that binds together the elements of the Hello World component. Next, we will create the JSP that provides the User Interface for the component. At this point, there is no reason to restart the server and view the file, because you will still get an error when you invoke the command. Step 4 Creating the Hello World JSP The rest of the steps will primarily involve incrementally updating a JSP to provide the user interface for our component. You will start with the simplest of JSP files, then add more complex (not necessarily more difficult) behaviors. At the most basic level, a JSP is a page with HTML markup. You can say hello by creating a standard web page. To create hello_world.jsp: 1. In the <WEBTOP_ROOT>/custom directory, create the directory hello_world. 2. In <WEBTOP_ROOT>/custom/hello_world, create a new text file named hello_world.jsp. 3. Open hello_world.jsp with a text editor and enter the following text. <html> <body> <h1>hello World</h1> </body> </html> 4. Save the file. You have now created the page that will be displayed when the hello world action is invoked. If this were a normal web page, it would be ready to go. However, you have defined hello_world as a 36 EMC Documentum Web Development Kit Version Tutorial

37 Hello Webtop component. Even though we have not implemented any controls or behavior, we need to supply a basic Java class to meet the minimal requirements for a component. To create HelloWebtop.java: 1. Use a text editor or your Java IDE to enter the following code. package com.mycompany.custom; import com.documentum.web.common.argumentlist; import com.documentum.web.formext.component.component; public class HelloWebtop extends Component public void oninit(argumentlist arg) super.oninit(arg); 2. Compile the code. 3. If necessary, copy HelloWebtop.class to the directory <WEBTOP_ROOT>\WEB_ INF\classes\com\mycompany\custom\HelloWebtop.class If you examine the code you entered, we have instantiated a component and provided a variable to accept any arguments passed to the class by HttpServlet.request. The oninit() method accepts the variables 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, Choose Hello World from the Tools menu. EMC Documentum Web Development Kit Version Tutorial 37

38 Hello Webtop You are rewarded with a web page that says Hello World in big bold letters. You feel a great sense of accomplishment, 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 in the Webtop framework, but it is not using Webtop controls or exposing Webtop functionality. In the next step, we will transform the JSP into a Webtop form. Step 5 Adding Static Controls to the JSP The 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. 38 EMC Documentum Web Development Kit Version Tutorial

39 Hello Webtop To make it easier for you to develop your own components, Webtop comes with predefined XML libraries (tag library definition files, or TLDs) that define special tags for the most common form components. In this step, we will add an import statement to the JSP that provides access to dmform_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 to access the correct values at runtime. To add an NLS-ready Label object to your JSP, you need to add a properties file, make a minor change to the configuration file, and substantially revise the JSP. To add the HelloWorldProp.properties file to Webtop: 1. Open a new file in a text editor. 2. Enter the following code. MSG_STATIC_TEXT=Static text from the Properties File. 3. Save the file as <WEBTOP_ROOT>\custom\strings\com\mycompany\hello_world\HelloWorldProp. properties. (Create the additional folders in the path as necessary.) While it may seem unnecessary to create such a deep path to store your properties files, it is a good habit to keep a consistent, corresponding directory structure for your source files so that they are 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 the hello_world_component.xml configuration file to point to the string value at runtime. To modify the hello_world_component.xml configuration file: 1. Open the file <WEBTOP_ROOT>\custom\config\hello_world_component.xml. 2. Add the following line to the configuration file after the <class> tag. <nlsbundle>com.mycompany.hello_world.helloworldprop</nlsbundle> 3. Save the file. The final result should match the program listing below. <?xml version="1.0" encoding="iso " 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> </componeny> </scope> </config> To add an NLS-ready 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 existing material than to modify it, but that would be up to you). <%@ page contenttype="text/html"%> <%@ page errorpage="/wdk/errorhandler.jsp"%> <%@ taglib uri="/web-inf/tlds/dmform_1_0.tld" prefix="dmf" %> <dmf:html> <dmf:head> EMC Documentum Web Development Kit Version Tutorial 39

40 Hello Webtop <dmf:webform/> </dmf:head> <dmf:body> <h1>hello Webtop</h1> <dmf:form> <p><dmf:label nlsid="msg_static_text"/></p> </dmf:form> </dmf:body> </dmf:html> 3. Save your file. Table 4. Highlights from hello_world.jsp page contenttype= text/html %> page errorpage="/wdk/ errorhandler.jsp"%> taglib uri="/web-inf/tlds/dmform_ 1_0.tld" prefix="dmf"%> This is a standard JSP tag indicating that this form contains HTML tags in plain text format. This tag identifies the page that the application server will display if there are any errors when rendering the JSP. This tag identifies the location of the Documentum Form Tag Library (dmform_1_0.tld). Tag libraries are stored in the <WEBTOP_ROOT>\WEB-INF\tlds\ folder. You can open up the tld files using a text editor to find out more about the available tags and their default settings. The prefix for the tag library is set to dmf. By specifying the dmf prefix, you can use the Documentum Form tags in your JSPs. <dmf:html> <dmf:head> <dmf:form> <dmf:body> These tags are very much like their standard HTML counterparts. The advantage of using the tags from the Documentum Form library is that these tags will work both for Webtop JSPs and in portlets. Portlets are web components embedded in HTML pages: using the same head and body tags would cause conflicts in web browsers. Adding the dmf: prefix differentiates these tags from the tags in the host HTML page, allowing the portlet elements to display. Even if you do not currently plan on using portlets, it does not hurt to use the dmf: versions, and it may save you trouble should you decide to use portlets in the future. 40 EMC Documentum Web Development Kit Version Tutorial

41 Hello Webtop <dmf:webform/> <dmf:label nlsid="msg_static_text"/> This tag identifies the JSP as a Documentum web form, providing a number of default behaviors and allowing the Webtop application server to make assumptions about the form that enhance performance. The dmf:label tag creates a text label control on the web form. The nlsid attribute identifies the string in the properties file that is associated with this tag. At runtime, Webtop parses the value from the properties file and replaces this tag with the parsed string. Restart your application server, click the Classic tab, and choose File>Hello World. Your text string from the properties file is now displayed. Next, we will add a static label and populate it from the Java behavior class. This is not the recommended method of displaying static text values, but it makes a nice segue into creating dynamic controls. To add a Java-ready static label to hello_world.jsp: 1. Open <WEBTOP_ROOT>\custom\hello_world\hello_world.jsp with a text editor. 2. Add the following line, after the existing <dmf:label/> tag. <p><dmf:label name="static_text"/></p> 3. Save the file. The file should now match the following program listing. <%@ page contenttype="text/html"%> <%@ page errorpage="/wdk/errorhandler.jsp"%> <%@ taglib uri="/web-inf/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 on the web form. The name attribute is the name of the control, which will be passed to the Java class at runtime. At the moment, the form would display a blank value for this label. We have created the label, which is a placeholder for text, and given it a name. Next, we will modify the Java behavior class to access and populate the value for the STATIC_TEXT label. EMC Documentum Web Development Kit Version Tutorial 41

42 Hello Webtop To update the Java class to populate the STATIC_TEXT label: 1. Open the HelloWebtop.java file in a text editor or Java IDE. 2. Add the import statement for the Label class, as follows. import com.documentum.web.form.control.label; 3. Add the onrender() method under the oninit() method as follows. public void onrender() super.onrender(); Label statictext = (Label) getcontrol("static_text",label.class); statictext.setlabel("a static text value from the Java class."); 4. Save and compile the class. 5. If necessary, copy HelloWebtop.class to <WEBTOP_ROOT>\WEB- INF\classes\com\mycompany\hello_world\HelloWebtop.class. The resulting Java file should be the same as the program listing below. package com.mycompany.custom; import com.documentum.web.common.argumentlist; import com.documentum.web.formext.component.component; import com.documentum.web.form.control.label; public class HelloWebtop extends Component public void oninit(argumentlist arg) super.oninit(arg); public void onrender() super.onrender(); Label statictext = (Label) getcontrol("static_text",label.class); statictext.setlabel("a static text value from the Java class."); We will take a look at a couple of key lines from the code. onrender() Label statictext = (Label) getcontrol("static_text",label. class); statictext.setlabel("a static text value from the Java class."); This time you added the onrender() method, which is run every time the JSP is displayed. This line creates a Label object that represents the STATIC_TEXT control on the JSP, using the getcontrol method from the parent class (Component). It then creates the Label variable statictext to represent the control. This line uses the setlabel method to set the text of the statictext variable to the value in the parentheses. Restart your application server, log on to Webtop, click the Classic tab, and choose File > Hello World. 42 EMC Documentum Web Development Kit Version Tutorial

43 Hello Webtop Your text string from the properties file is displayed, followed by the static value provided by the Java behavior class. To recap, you now have a component that displays static text values from a properties file and from the 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 dynamic information from the repository, which will give you the basis for just about any modifications you will ever need to make to Webtop. Step 6 Adding Dynamic Controls to the JSP As alluded to earlier, you generally will not use the Java class to display static text values (properties files are easier to maintain). Displaying dynamic information is a different matter entirely you will EMC Documentum Web Development Kit Version Tutorial 43

44 Hello Webtop often want to create components that display information in a way that matches your company s way of doing business. In this step, we will gain access to the user s repository connection and use it to obtain and display information about the user s current work session. We will add a new control to the JSP and a new method to the Java behavior class. To add a Java-ready label to hello_world.jsp: 1. Open the file <WEBTOP_ROOT>\custom\hello_world\hello_world.jsp in a text editor. 2. Add the following line after the second <dmf:label/> tag. <p>current repository: <dmf:label name="current_repository"/></p> 3. Save the file. It should now match the following program listing. <%@ page contenttype="text/html"%> <%@ page errorpage="/wdk/errorhandler.jsp"%> <%@ taglib uri="/web-inf/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 it CURRENT_REPOSITORY. Now, we will update the Java class to supply the value of the current repository. We will add a new method to retrieve the name of the repository, and change the onrender() 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(); try repositoryname = dfsession.getdocbasename(); catch (DfException e) System.out.println("Error in HelloWebtop.java. Message:\n" + e); return repositoryname; We will look at the code in more depth after editing the source file. 44 EMC Documentum Web Development Kit Version Tutorial

45 Hello Webtop 4. Add the following code to the end of the onrender() method. Label currentrepository = (Label) getcontrol("current_repository",label.class); currentrepository.setlabel(getcurrentrepositoryname()); 5. Save and compile the file. It should match the following program listing. package com.mycompany.custom; import com.documentum.web.common.argumentlist; import com.documentum.web.formext.component.component; import com.documentum.web.form.control.label; import com.documentum.fc.client.idfsession; import com.documentum.fc.common.dfexception; public class HelloWebtop extends Component public void oninit(argumentlist arg) super.oninit(arg); public void onrender() super.onrender(); Label statictext = (Label) getcontrol("static_text",label.class); statictext.setlabel("a static text value from the Java class."); Label currentrepository = (Label) getcontrol("current_repository",label.class); currentrepository.setlabel(getcurrentrepositoryname()); private String getcurrentrepositoryname() String repositoryname = null; IDfSession dfsession = getdfsession(); try repositoryname = dfsession.getdocbasename(); catch (DfException e) System.out.println("Error in HelloWebtop.java. Message:\n" + e); return repositoryname; 6. Copy the complied class file to <WEBTOP_ROOT>\WEB_ INF\classes\com\mycompany\custom\HelloWebtop.class. Now we will take a look at the significant changes we made. IDfSession dfsession = getdfsession(); When a browser makes a request for a component that requires a connection to the database, Webtop checks to see if there is an active session and, if necessary, presents a login dialog. As a result, you do not have to do anything in your code to authenticate your users unless you have special needs beyond the scope of the security provided by Webtop. We can anticipate that the user will already have a valid session when accessing our component, and we EMC Documentum Web Development Kit Version Tutorial 45

46 Hello Webtop repositoryname = dfsession. getdocbasename(); Label currentrepository = (Label) getcontrol("current_ REPOSITORY",Label.class); currentrepository.setlabel( getcurrentrepositoryname() ); can use the existing session to set values in our component. Using the current session, we can get the name of the current repository. In earlier releases the repository was referred to as the docbase, which is still reflected in the API (for backward compatibility). These lines set the value in the label in much the same way as the earlier static text example. We create a reference to the control based on its name, and set the text value. The only difference is that rather than entering a static text string, we are calling the getcurrentrepositoryname() method, which returns a string with the name of the current repository. Restart your application server, log on to Webtop, click the Classic tab, and choose File>Hello World. 46 EMC Documentum Web Development Kit Version Tutorial

47 Hello Webtop The two static text labels you created earlier are displayed, followed by your new dynamic control with the name of the current repository. To recap, we added a dmf:label object to the hello_world.jsp exactly like the earlier STATIC_TEXT label, but gave it the name CURRENT_REPOSITORY. We then added the getcurrentrepository method to HelloWorld.class, which sends the retrieved value back to the form for display. We will expand on this paradigm in the next step, and display a table of information rather than a single value. Step 7 Adding Databound Controls to the JSP The <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 EMC Documentum Web Development Kit Version Tutorial 47

48 Hello Webtop smart tags, which can be bound to tables and columns in the repository. These tags will then display the results of a Documentum Query Language (DQL) request, providing flexible and convenient access to information in and about your stored documents. The first step is to add the bindable controls to the JSP, then add a query to the Java class to populate the tables. We will use a datagrid to display a list of users from the current repository. To add databound controls to the JSP 1. Open <WEBTOP_ROOT>\custom\hello_world\hello_world.jsp in a text editor. 2. Add the following code after the Current Repository line. <h1>list of Users</h1> <dmf:datagrid name="mygrid" paged="true" pagesize="10"> <tr> <th>user Name</th> <th>user Group Name</th> </tr> <dmf:datagridrow> <td> <dmf:label datafield="user_name" /> </td> <td> <dmf:label datafield="user_group_name" /> </td> </dmf:datagridrow> </dmf:datagrid> 3. Save your file. It should now match the following code listing. <%@ page contenttype="text/html"%> <%@ page errorpage="/wdk/errorhandler.jsp"%> <%@ taglib uri="/web-inf/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" /> </td> </dmf:datagridrow> </dmf:datagrid> </dmf:form> </dmf:body> </dmf:html> We will take a look at some interesting details of the changes you just made. 48 EMC Documentum Web Development Kit Version Tutorial

49 Hello Webtop <dmf:datagrid name= mygrid paged= true pagesize= 10 > <dmf:datagridrow> <dmf:label datafield= user_name /> <dmf:label datafield= "user_group_ name" /> To display a table of information from the repository, you can use a datagrid object. As with the label object, you give the object a name that can be passed to the Java behavior class. By default, all of the results of the query are returned and displayed. That would make for a very large result set in this case, so setting the paged attribute to true and the pagesize to 10 will return only the first ten user records from the repository. For the headings, you used a standard HTML table row and table heading tags. For the data rows, you used the dmf:datagridrow tag. The label tags encapsulated by the dmf:datagridrow tags can be populated by data in the repository. Once again, you are using a dmf:label tag to display a string value. Rather than a single value, though, this string is linked to a datafield, which is a column from a table in the repository. The table from which the rows are selected is specified in the supporting Java class, but the column names you specify here must match their names in the repository. In this form, you are displaying only two columns of information, but you could display all of the columns in the table if you chose to do so (there is not much to learn, and a great deal to type, when you add more columns, so sticking with two is a good idea for this example). Next, we need to modify the Java class. We need to enter a great deal of new code to use a databound control, but here is the good news: you can reuse the getdocbasesession() method for most of your data retrieval needs in most of your components; also, the code is not complex, it is mostly a bunch catch clauses for the various exceptions that might be thrown. To modify HelloWebtop.class to support a databound control: 1. Open the Java source file com.mycompany.custom.hellowebtop.java in a text editor or Java IDE. 2. Add the following import statements at the top of the file. import com.documentum.web.form.control.databound.datagrid; import com.documentum.web.formext.session.sessionmanagerhttpbinding; import com.documentum.fc.client.idfsessionmanager; import com.documentum.fc.client.dfidentityexception; import com.documentum.fc.client.dfauthenticationexception; import com.documentum.fc.client.dfprincipalexception; import com.documentum.fc.client.dfserviceexception; 3. Add the following method at the end of the class. IDfSession getrepositorysession() IDfSessionManager sessionmanager = null; EMC Documentum Web Development Kit Version Tutorial 49

50 Hello Webtop SessionManagerHttpBinding httpbinding = null; IDfSession dfsession = null; try SessionManager = SessionManagerHttpBinding.getSessionManager(); String docbase = SessionManagerHttpBinding.getCurrentDocbase(); dfsession = sessionmanager.getsession(docbase); catch(dfidentityexception dfe) System.out.println("Error while obtaining Session. Id exception" + dfe.getmessage()); catch(dfauthenticationexception ae) System.out.println("Authentication exception while " + "getting client " + ae.getmessage()); catch(dfprincipalexception pe) System.out.println("Principal exception " + pe.getmessage()); catch(dfserviceexception se) System.out.println("Service exception " + se.getmessage()); return(dfsession); 4. Add the following code to the onrender() method. Datagrid datagrid = null; try datagrid = (Datagrid) getcontrol("mygrid",datagrid.class); catch(exception ex) if(datagrid == null) datagrid = (Datagrid)createControl("mygrid",Datagrid.class); datagrid.getdataprovider().setdfsession(getrepositorysession()); datagrid.getdataprovider().setquery("select user_name, user_group_name" + " from dm_user where r_is_group = FALSE;"); datagrid.getdataprovider().refresh(); 5. Compile and save the file. 6. If necessary, copy the compiled class to <WEBTOP_ROOT>\WEB- INF\classes\com\mycompany\custom\HelloWebtop.class. The file should now match the 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.databound.datagrid; import com.documentum.web.formext.session.sessionmanagerhttpbinding; import com.documentum.fc.client.idfsession; import com.documentum.fc.client.idfsessionmanager; import com.documentum.fc.common.dfexception; import com.documentum.fc.client.dfidentityexception; import com.documentum.fc.client.dfauthenticationexception; import com.documentum.fc.client.dfprincipalexception; import com.documentum.fc.client.dfserviceexception; public class HelloWebtop extends Component public void oninit(argumentlist arg) 50 EMC Documentum Web Development Kit Version Tutorial

51 Hello Webtop super.oninit(arg); public void onrender() super.onrender(); Label statictext = (Label) getcontrol("static_text",label.class); statictext.setlabel("a static text value from the Java class."); Label currentrepository = (Label) getcontrol("current_repository",label.class); currentrepository.setlabel(getcurrentrepositoryname()); Datagrid datagrid = null; try datagrid = (Datagrid) getcontrol("mygrid",datagrid.class); catch(exception ex) if(datagrid == null) datagrid = (Datagrid)createControl("mygrid",Datagrid.class); datagrid.getdataprovider().setdfsession(getrepositorysession()); datagrid.getdataprovider().setquery("select user_name, user_group_name" + " from dm_user where r_is_group = FALSE;"); datagrid.getdataprovider().refresh(); private String getcurrentrepositoryname() String repositoryname = null; IDfSession dfsession = getdfsession(); try repositoryname = dfsession.getdocbasename(); catch (DfException e) System.out.println("Error in HelloWebtop.java. Message:\n" + e); return repositoryname; IDfSession getrepositorysession() IDfSessionManager sessionmanager = null; SessionManagerHttpBinding httpbinding = null; IDfSession dfsession = null; try sessionmanager = SessionManagerHttpBinding.getSessionManager(); String docbase = SessionManagerHttpBinding.getCurrentDocbase(); dfsession = sessionmanager.getsession(docbase); catch(dfidentityexception dfe) System.out.println("Error while obtaining Session. Id exception " + dfe.getmessage()); catch(dfauthenticationexception ae) System.out.println("Authentication exception while " + "getting client " + ae.getmessage()); catch(dfprincipalexception pe) System.out.println("Principal exception " + pe.getmessage()); catch(dfserviceexception se) EMC Documentum Web Development Kit Version Tutorial 51

52 Hello Webtop 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. import com.documentum.web.form. control.databound.datagrid; import com.documentum.web.formext. session.sessionmanagerhttpbinding; import com.documentum.fc.client. IDfSessionManager; import com.documentum.fc.client. DfIdentityException; import com.documentum.fc.client. DfAuthenticationException; import com.documentum.fc. client.dfprincipalexception; import com.documentum.fc.client. DfServiceException; Datagrid datagrid = null; try datagrid = (Datagrid) getcontrol("mygrid", Datagrid. class); catch(exception ex) if(datagrid == null) datagrid = (Datagrid)createControl("mygrid", Datagrid.class); datagrid.getdataprovider(). setdfsession( getrepositorysession()); datagrid.getdataprovider().setquery( "select user_name, user_group_name" + " from dm_user where r_is_group = FALSE;"); datagrid.getdataprovider().refresh(); This is the Java representation of the Datagrid component. The onrender() method instantiates and populates a Datagrid object, which is passed back to the JSP for display. In step 6, you added code that indicates that a connection to the repository exists. You did not actually use the connection to perform a transaction with the repository. In order to pass information to and from the repository, you need to access the current session. The IDfSessionManager class is used to manage identities, pooled sessions, and transactions with the repository. SessionManagerHttpBinding exposes the methods used to store and retrieve a connection to a current repository. These classes are used to trap a variety of exceptions that may occur when your class attempts to access and use the current repository session. The code you added to the onrender() method creates an empty datagrid object, then tries to associate it with the mygrid control you created on the JSP. If the mygrid datagrid control does not exist, the control is created in the catch clause. These lines populate the Datagrid object with information from the repository based on a query. The first line gets the data provider for the datagrid. It calls the getrepositorysession() method you created (described below) in order to access the user s current connection to the repository to complete the transaction.the second line provides a DQL query that will locate the information we want (in this case, we want the user and group name from the dm_user table, but only for users, not for groups). 52 EMC Documentum Web Development Kit Version Tutorial

53 Hello Webtop IDfSession getrepositorysession() IDfSessionManager sessionmanager = null; IDfSession dfsession = null; try sessionmanager = SessionManagerHttpBinding. getsessionmanager(); String docbase = SessionManagerHttpBinding. getcurrentdocbase(); dfsession = sessionmanager.getsession(docbase); The third line tells the datagrid control to refresh itself with the new data. The getrepositorysession() method begins by creating null instances of IDfSessionManager and IDfSession. Using the methods of SessionManagerHttpBinding, the sessionmanager and docbase variables are set, which allows you to get the current session, returned in the dfsession variable. The remainder of the method traps four different types of exception. Otherwise, the current session is returned, and the onrender() method is able to execute a query by accessing the user s current connection. Restart your application server, log on to Webtop, click the Classic tab, and choose File>Hello World. EMC Documentum Web Development Kit Version Tutorial 53

54 Hello Webtop The three text labels we created earlier are displayed, followed by a table listing the first 10 users from the 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 the repository. The final step in this whirlwind tour of Webtop customization is to not only retrieve information from the repository, but also use the information as the basis for a second query that opens a new form. Step 8 Linking to a Second JSP This final step simulates a common need when working with data repositories to find a piece of information, then to find additional information based on the results of the first query. We will 54 EMC Documentum Web Development Kit Version Tutorial

55 Hello Webtop add a second JSP to the application, then link to that form from a modified version of the datagrid we just created. To add a new JSP to your Webtop instance: 1. Open a blank text document in any text editory. 2. Enter the following code. <%@ page contenttype="text/html" %> <%@ page errorpage="/wdk/errorhandler.jsp" %> <%@ taglib uri="/web-inf/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> </td> </dmf:datagridrow> </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. <h1> Documents modified by <dmf:label name="modifierlabel" /> </h1> The label component can be used to place dynamic text anywhere in the form. You can format the results of the query as you would EMC Documentum Web Development Kit Version Tutorial 55

56 Hello Webtop <dmf:datagrid name="my_doc_list_grid" paged="true" pagesize="10" bordersize="1"> <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> any other text on the form (in this case, using the <h1> tag). We created a datagrid object similar to the datagrid in hello_world.jsp. You can give the control any name you like, provided it is unique within the context of the form. The datagridrow is similar to the one you created for hello_world.jsp. The one twist is that you are accessing a field with a date value. As passed from the repository, the date is represented as the number of milliseconds that have passed since January 1, :00: GMT; this is convenient for storage, but less so for your users. To display the value as a human-readable date, you wrap date values in <datevalueformatter> tags. You can set the format type attribute to short, medium, or long. In order to use the hello_detail.jsp with the component, we need to update the hello_world_component.xml configuration file. To update the hello_world_component.xml configuration file: 1. Using a text editor, open <WEBTOP_ROOT>\custom\config\hello_world_component.xml. 2. Add the following line after the <start> tag <detail>/custom/hello_world/hello_detail.jsp</detail> 3. Save your work. The configuration file should now match the following listing. <?xml version="1.0" encoding="iso " 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> </component> </scope> </config> Next, we will update the hello_world.jsp to display the user_name as a link rather than a label. 56 EMC Documentum Web Development Kit Version Tutorial

57 Hello Webtop To update hello_world.jsp to display user_name as a link: 1. Using a text editor, open <WEBTOP_ROOT>\custom\hello_world\hello_world.jsp. 2. Replace this line: <dmf:label datafield="user_name" /> with: <dmf:link datafield="user_name" onclick="onclicklink" > <dmf:argument name="user_name" datafield="user_name" /> </dmf:link> 3. Save your work. The file should now match the following program listing. <%@page contenttype="text/html"%> <%@ page errorpage="/wdk/errorhandler.jsp" %> <%@ taglib uri="/web-inf/tlds/dmform_1_0.tld" prefix="dmf" %> <html> <dmf:head> <dmf:webform /> </dmf:head> <body> <dmf:form> <p><dmf:label nlsid="msg_static_text" /> <p><dmf:label name="static_text"/></p> <p>current repository: <dmf:label name="current_repository"/></p> <h1>list of Users</h1> <dmf:datagrid name="mygrid" paged="true" pagesize="10"> <tr> <th>user Name</th> <th>user Group Name</th> </tr> <dmf:datagridrow> <td> <dmf:link datafield="user_name" onclick="onclicklink" > <dmf:argument name="user_name" datafield="user_name"/> </dmf:link> </td> <td> <dmf:label datafield="user_group_name"/> </td> </dmf:datagridrow> </dmf:datagrid> </dmf:form> </body> </html> We have created a link, which will send the user_name to the Java behavior class. Now we need to create the onclicklink() method so that the class will know what 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) this.setcomponentpage("detail"); EMC Documentum Web Development Kit Version Tutorial 57

58 Hello Webtop Label label = null; try label = (Label) getcontrol("modifierlabel", Label.class); catch (Exception ex) if(label == null) label = (Label)createControl("modifierLabel", Label.class); label.setlabel(arg.get("user_name")); Datagrid datagrid = null; try datagrid = (Datagrid) getcontrol("my_doc_list_grid",datagrid.class); catch (Exception ex) if(datagrid == null) datagrid = (Datagrid)createControl("my_doc_list_grid",Datagrid.class); datagrid.getdataprovider().setdfsession(getrepositorysession()); datagrid.getdataprovider().setquery("select object_name, " + "r_modify_date, r_modifier from dm_document where " + "r_modifier = \'" + arg.get("user_name") + "\';"); datagrid.getdataprovider().refresh(); 4. Save and compile the file. It should now match the following code listing. package com.mycompany.custom; import com.documentum.web.common.argumentlist; import com.documentum.web.formext.component.component; import com.documentum.web.form.control.label; import com.documentum.web.form.control.link; import com.documentum.web.form.control.databound.datagrid; import com.documentum.web.formext.session.sessionmanagerhttpbinding; import com.documentum.fc.client.idfsession; import com.documentum.fc.client.idfsessionmanager; import com.documentum.fc.common.dfexception; import com.documentum.fc.client.dfidentityexception; import com.documentum.fc.client.dfauthenticationexception; import com.documentum.fc.client.dfprincipalexception; import com.documentum.fc.client.dfserviceexception; public class HelloWebtop extends Component public void oninit(argumentlist arg) super.oninit(arg); 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; try datagrid = (Datagrid) getcontrol("mygrid",datagrid.class); catch(exception ex) if(datagrid == null) datagrid = (Datagrid)createControl("mygrid",Datagrid.class); 58 EMC Documentum Web Development Kit Version Tutorial

59 Hello Webtop 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; try label = (Label) getcontrol("modifierlabel", Label.class); catch (Exception ex) if(label == null) label = (Label)createControl("modifierLabel", Label.class); label.setlabel(arg.get("user_name")); Datagrid datagrid = null; try datagrid = (Datagrid) getcontrol("my_doc_list_grid",datagrid.class); catch (Exception ex) if(datagrid == null) datagrid = (Datagrid)createControl("my_doc_list_grid",Datagrid.class); datagrid.getdataprovider().setdfsession(getrepositorysession()); datagrid.getdataprovider().setquery("select object_name, " + "r_modify_date, r_modifier from dm_document where " + "r_modifier = \'" + arg.get("user_name") + "\';"); datagrid.getdataprovider().refresh(); private String getcurrentrepositoryname() String repositoryname = null; IDfSession dfsession = getdfsession(); try repositoryname = dfsession.getdocbasename(); catch (DfException e) System.out.println("Error in HelloWebtop.java. Message:\n" + e); return repositoryname; IDfSession getrepositorysession() IDfSessionManager sessionmanager = null; IDfSession dfsession = null; try sessionmanager = SessionManagerHttpBinding.getSessionManager(); String docbase = SessionManagerHttpBinding.getCurrentDocbase(); dfsession = sessionmanager.getsession(docbase); catch(dfidentityexception dfe) System.out.println("Error while obtaining Session. Id exception" + dfe.getmessage()); catch(dfauthenticationexception ae) System.out.println("Authentication exception while " + "getting client " + ae.getmessage()); catch(dfprincipalexception pe) EMC Documentum Web Development Kit Version Tutorial 59

60 Hello Webtop 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. public void onclicklink(link thelink, ArgumentList arg) this.setcomponentpage("detail"); label = (Label) getcontrol("modifierlabel", Label.class);... label.setlabel(arg.get("user_name")); datagrid = (Datagrid) getcontrol("my_ doc_list_grid",datagrid.class); datagrid.getdataprovider(). setdfsession( getrepositorysession()); datagrid.getdataprovider().setquery( "select object_name, r_modify_date, " + "r_modifier from dm_document where " + "r_modifier = \'" + arg.get("user_name") + "\';"); datagrid.getdataprovider().refresh(); The onrender() method takes no arguments. When the user clicks the link, we need the selected user_name for your query. All arguments are passed to the Java class in a single ArgumentList object. The onclicklink method requires the name of the component that made the call, followed by the list of arguments. When the user clicks a link, the first thing the code does is set the current page for the component to the new detail page we just created. We create an instance of Label and use it to represent the modifierlabel control on detail.jsp. (The omitted code is the catch clause that creates a new control if for some reason the getcontrol method fails). Once we have a label control, we can populate it with the user_name argument. We use the same syntax to create a Datagrid control that we used to create the Label control, only changing the class and specific name of the control we want to create. These lines are similar to the query used to populate the user_list datagrid. Rather than use a static argument, though, we have created a dynamic query based on the selected user_name. Webtop refreshes the datagrid and displays the results. Restart your application server, log on to Webtop, click the Classic tab, and choose File>Hello World. 60 EMC Documentum Web Development Kit Version Tutorial

61 Hello Webtop The user names are now displayed as links (note the underscores beneath the obscured names). EMC Documentum Web Development Kit Version Tutorial 61

62 Hello Webtop Click one of the names to display a list of documents modified by that user. To recap, we have done the following: configured the Webtop menubar to display a custom command configured the action triggered by selecting the custom command configured a component that can be launched by the custom action created a custom JSP using WDK/Webtop controls populated controls with static values from a properties file and from a Java class populated controls with dynamic values based on DQL queries used the results of one query to open a second component page with detail information 62 EMC Documentum Web Development Kit Version Tutorial

63 Hello Webtop That is a lot of ground to cover in a Hello World example, but when you extend Webtop, you will find that most of the work has been done for you. EMC Documentum Web Development Kit Version Tutorial 63

64 Hello Webtop 64 EMC Documentum Web Development Kit Version Tutorial

65 Chapter 5 Creating a Start Page for a New WDK Application Creating a WDK application from the ground up is a massive undertaking. It is strongly recommended that you customize the Webtop application rather than attempt to create a completely new user interface. Most Web applications are accessed through an index.html or default.html page. This is the starting point of your application. WDK does not require an index page, but it s a best practice to have one. In this tutorial, you define a welcome page with a JavaScript function that redirects to the drilldown component. The drilldown component is a navigation component that will be the starting point of the new application. If the user has not logged in to the application, then the login component will be invoked from the drilldown component class, and the user will be prompted to log in. Note: Any component that requires a session will launch the login dialog if the user does not have a session. You do not need to call the login component explicitly. Use the following procedure to create an index.html start page for your application. To create a start page: 1. Create a new file called index.html in the tomcat_home/webapps/virtual_dir directory, where tomcat_home is the directory in which Tomcat is installed, and virtual_dir is the virtual directory into which you installed WDK. 2. Add the following text: <html> <head> <script> function redirect() var strpath = window.location.pathname; var nindex1 = strpath.indexof("/"); var nindex2 = strpath.indexof("/", nindex1 + 1); var strvirtualdir = strpath.substring(nindex1 + 1, nindex2); window.location.replace("/" + strvirtualdir + "/component/drilldown?reload=" + new Date().getTime()); </script> </head> This JavaScript defines a function called redirect, which gets the root URL for the Web application, adds to it the drilldown component URL, then tacks on an argument with the current date and time, which will force a reload of the page every time it is accessed. EMC Documentum Web Development Kit Version Tutorial 65

66 Creating a Start Page for a New WDK Application 3. Add the following <body> tag: <body onload="redirect()"> </body> </html> This tag contains a call to the JavaScript function that you just created. 4. Save the file. 5. Test your page by starting a browser and entering the following address (after ensuring that Tomcat is running): The address should immediately change to If you have not previously logged in, the login page will be displayed. After log in, you see the drilldown page, shown in the following figure. Figure 13. Post-Login Drilldown Page If you see a blank page instead of the login screen, check for typos in the index.html file. 66 EMC Documentum Web Development Kit Version Tutorial

67 Creating a Start Page for a New WDK Application Variations in this tutorial Instead of redirecting to the drilldown component, you could redirect to the doclist component, which combines folders and their contents in a single view. Instead of redirecting directly to doclist or drilldown, you could have the start page redirect to the main component. Since the WDK main component is a blank page, you would need to configure or customize the main component to display the views that you choose. EMC Documentum Web Development Kit Version Tutorial 67

68 Creating a Start Page for a New WDK Application 68 EMC Documentum Web Development Kit Version Tutorial

69 Chapter 6 Adding a Logout Link The following tutorial shows you how to add a Logout link to the drilldown page. The tutorial contains the following sections: Task Objective, page 69 Technical Overview, page 70 Creating the Custom Layer Files, page 71 Extending the Drilldown Component, page 71 Modifying the Generic Actions XML File, page 72 Creating a Custom Resource File, page 72 Testing the Logout Link, page 73 Extending the Logout Action, page 73 Variations in this tutorial, page 74 Task Objective Webtop and other WDK client applications have Logout buttons, but WDK has no logout link or button in the UI out of the box. Suppose that you want to add a Logout link to the drilldown pages in a WDK application, which will return the user to the start page with a login screen. The Logout link should appear as in the upper right of the following figure. Figure 14. Drilldown Page with Logout Link EMC Documentum Web Development Kit Version Tutorial 69

70 Adding a Logout Link Technical Overview The drilldown component (used by default in WDK) is defined in the XML resource file drilldown_component.xml, which points to the start page drilldown.jsp. The drilldown.jsp itself points to drilldown_body.jsp, and drilldown_body.jsp contains an actionlinklist control to which you will add the Logout link. First, you must change the logout action. The logout action is defined in session_actions.xml in the WDK layer. It includes a <homeurl> element, which points to a post-logout location. In Webtop and Web Publisher, this <homeurl> element calls the logoff component, a sessionless component in the WDK layer that invalidates the current session and calls the drilldown component, with the login screen appearing first. The logoff component is important for controlling the number of open sessions. Once the user clicks the Logout link, the LogoutAction class calls /wdk/logout.jsp, and logout.jsp redirects to dologout.jsp, which contains a client-side initialization containing an onlogout client event. This onlogout client event fires only if an onlogout event handler is registered. If none is registered, then the oninit() JavaScript function in logout.jsp changes the location of the top frame to whatever is configured in the <homeurl> parameter of the logout action: /** Client-side Initialization */ function oninit() var homeurl = "<%=session.getattribute("_logoutactionurl")%>"; if (isclienteventhandlerregistered("onlogout")) fireclientevent("onlogout", homeurl); else gettoplevelwnd().location.replace(homeurl); (The script that tests whether a handler for a given client event has been registered is in virtual_dir/wdk/include/events.js.) In Webtop and in the Webtop layer of applications that are based on Webtop, the client-side event handler, onlogout, is defined in main.js: function onlogout(homeurl) if (homeurl!= null && homeurl!= "") document.location.replace(homeurl); In this tutorial, the <homeurl> element will be configured so that it calls the logoff component, similar to Webtop and other client applications. This tutorial involves the following procedures: Creating the files in the custom layer Extending the drilldown component XML definition to point to a custom properties file that contains text for the Logout link Modifying the list of actions displayed by the actionlinklist control to include a Logout link 70 EMC Documentum Web Development Kit Version Tutorial

71 Adding a Logout Link Extending the properties file that contains the resource strings for the drilldown component so that it contains the Logout link text Extending the logout action to call the logoff component Creating the Custom Layer Files Use the following procedure to set up the custom layer. To create the files for the customization: 1. Copy the following file: virtual_dir/wdk/config/session_actions.xml to the following location: virtual_dir/custom/config 2. Copy the following file: virtual_dir/webcomponent/config/navigation/drilldown/ drilldown_component.xml to the following location: virtual_dir/custom/config 3. Copy the following file: virtual_dir/webcomponent/config/actions/generic_actions.xml to the following location: virtual_dir/custom/config 4. Create a new text file named MyDrillDownNlsProp.properties in the following location (creating the directory structure if necessary): virtual_dir/web-inf/classes/com/mycompany/drilldown Extending the Drilldown Component The following procedure extends the drilldown component to point to the custom properties file. To modify the XML resource file: 1. Open the following file: virtual_dir/custom/config/drilldown_component.xml 2. Change the <component> start tag as follows: <component id="drilldown" extends="drilldown:webcomponent/ config/navigation/drilldown/drilldown_component.xml"> This will extend the drilldown component that is defined in the default resource file. EMC Documentum Web Development Kit Version Tutorial 71

72 Adding a Logout Link 3. Change the <nlsbundle> element as follows: <nlsbundle>com.mycompany.drilldown.mydrilldownnlsprop</nlsbundle> This points to the empty properties file you created in the custom layer. 4. Save the file and close it. Tip: When you make modifications to an XML file, check to see that the XML is well formed so it does not cause problems later. One easy way to do this is to open the XML file in Microsoft Internet Explorer. Modifying the Generic Actions XML File There are two JSP pages involved with the drilldown component, which is displayed after login: drilldown.jsp calls drilldown_body.jsp. The drilldown_body.jsp file includes an actionlinklist control that displays the available actions: <dmfx:actionlinklist listid='container-actions' name='container_action_list' cssclass='actions' separatorhtml='</nobr><nobr>'> <!-- arguments passed to folder actions--> <dmfx:argument name='objectid' contextvalue='objectid'/> <dmfx:argument name='folderid' contextvalue='parentid'/> <dmf:argument name='startworkflowid' value='startworkflowdrilldown'/> </dmfx:actionlinklist> The listid attribute of the actionlinklist (id= container-actions ) corresponds to the name of an action list in generic_actions.xml. To add the Logout action, update the container-actions actionlist in a custom version of generic_actions.xml. To modify generic_actions.xml: 1. Open the following file: virtual_dir/custom/config/generic_actions.xml 2. Locate the beginning of the container-actions actionlist element and change it as follows: <actionlist id="container-actions" extends="container-actions:webcomponent/config/actions/ generic_actions.xml"> 3. Add the Logout action immediately before the closing tag for the <actionlist> element: <action id='logout' nlsid='msg_logout'/> </actionlist> 4. Save the file and close it. Creating a Custom Resource File The resource string that you specified in the actionlink, namely MSG_LOGOUT, is defined in some WDK resource files, but not in DrillDownNlsProp. You must define this string in the custom properties file you created in the custom layer and pointed to from the XML resource file. 72 EMC Documentum Web Development Kit Version Tutorial

73 Adding a Logout Link To define a custom resource string: 1. Open the following file: virtual_dir/web-inf/classes/com/mycompany/drilldown/ MyDrillDownNlsProp.properties 2. Add the following two lines. (The first two lines shown here should be on one line in your file.) NLS_INCLUDES=com.documentum.webcomponent.navigation. drilldown.drilldownnlsprop MSG_LOGOUT=Logout These lines include the DrillDownNlsProp.properties file in the default location and define one additional resource string, which is referenced in the nlsid attribute MSG_LOGOUT for the action that you added to the actionlist definition. 3. Save the file and close it. Testing the Logout Link The Logout link should now be functional, and you can test it before making other changes. To test the Logout link: 1. Stop and restart the application server. (You must restart the application server to pick up changes to.properties files.) 2. Enter the following address: After you log in, the drilldown page should appear, with the new Logout link in the upper right-hand corner as shown below. 3. Click the Logout link. For now, this should result in the display of a generic Action canceled browser page. Extending the Logout Action To extend the logout action:, page 74 extends the logout action to call the logoff component. EMC Documentum Web Development Kit Version Tutorial 73

74 Adding a Logout Link To extend the logout action: 1. Open the following file: virtual_dir/custom/config/session_actions.xml 2. Change the logout <action> start tag as follows: <action id="logout" extends="wdk/config/session_actions.xml"> 3. Change the <homeurl> element as follows: <homeurl>/component/logoff</homeurl> This will call the logoff component when the logout action is invoked. 4. Save the file and close it. 5. Refresh the configuration service and test the Logout link as in the previous procedure. This time when you click the Logout button, you should see a logout message with a link to return to the login page. Variations in this tutorial Adding a Logout link is not necessary in Webtop or Web Publisher, since the default applications use Logout buttons. However, you could use this tutorial as the basis for modifying other action controls. For example, you could change any actionbutton to an actionlink or vice versa. You could also change the actionlinklist to an actionbuttonlist in drilldown_body.jsp The actionbutton control requires additional attributes related to the button image and the placement of text on the button. For more information, see the EMC Documentumm Web Development Kit and Webtop Reference Guide. 74 EMC Documentum Web Development Kit Version Tutorial

75 Chapter 7 Creating an Action List Component This tutorial requires both configuration and customization to display a list of all actions configured in your Web application. Each action has a link to an information page about the action that displays the action class, parent action definition, container and component launched, if any, parameters, and other configurable elements. The full source code for this customization is located on the Documentum developer site, developer.documentum.com. The tutorial contains the following sections: Task Objective, page 75 Technical Overview, page 76 Creating the Component Definition, page 77 Creating the Component Layout, page 77 Creating the Component Class, page 79 Supporting Navigation Between Pages, page 81 Creating the Action List Datagrid, page 81 Creating the Action Info Datagrid, page 84 Creating the Resource Bundle, page 87 Testing the Customization, page 88 Variations in this tutorial, page 89 Task Objective In this tutorial, you will create a simple action list component that reads information from all of the action definition files in your application and displays them in two UI pages: a list of actions, and a drilldown page that displays info for an action. After customization, the action list component start page will look similar to the one shown in Figure 15, page 76. EMC Documentum Web Development Kit Version Tutorial 75

76 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 in the following figure: Figure 16. Action Info Page Technical Overview WDK contains a componentlist component that gets and displays a list of all component definitions in memory and information for each component. You will use the componentlist component as a model for a new actionlist component. 76 EMC Documentum Web Development Kit Version Tutorial

77 Creating an Action List Component Creating the Component Definition To create a new WDK actionlist component, you must create a component definition. The best way to create a component definition is to copy the configuration file for a similar component, then make any necessary changes. To create the actionlist definition: 1. Copy the componentlist component configuration file from /webcomponent/config/ componentlist/component_list.xml to the following location :/custom/config 2. Rename the file to actionlist_component.xml. 3. Open the file and locate the <desc> element. Change it to the following content: Action list: Displays outline information on all of the defined actions in the application 4. Locate the <component> element. Change it to the following content: <component id="actionlist"> 5. Change the value for the <pages><start> element to the following: /custom/actionlist/actionlist.jsp 6. Locate the <pages> element and replace the <componentinfo> element and contents with the following element and contents: <actioninfo>/custom/actionlist/actioninfo.jsp</actioninfo> 7. Locate the <class> element and change the value to the following class that you will create: com.mycompany.actionlist.actionlist 8. Locate the <nlsbundle> element and change the value to the following NLS resource that you will create: com.mycompany.actionlist.actionlistnlsprop 9. Save and close the file. Creating the Component Layout You can modify the componentlist layout pages to provide a similar layout for the action list. To create the layout for the action list: 1. Copy the componentlist JSP page from /webcomponent/componentlist/componentlist.jsp to /custom/actionlist. Create a /custom/actionlist directory if one does not exist. 2. Rename the file to actionlist.jsp, and open the file. 3. Locate the following file import tag: <%@ page import="com.documentum.webcomponent.componentlist.componentlist" %> Change the imported class to the following: com.mycompany.actionlist.actionlist EMC Documentum Web Development Kit Version Tutorial 77

78 Creating an Action List Component 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 to ActionList.ACTIONLIST_GRID 6. Remove the table header rows (<th...>...</th>) that contain the following labels (for example, dmf:label nlsid=): MSG_ISCONTAINER MSG_ISCONFIGURABLE MSG_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 from compid to actionid. The action ID will be displayed for the link. Change the inner <dmf:argument> name from compcfgid to actioncfgid. Change the datafield from 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 from compxmlurl 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 labels are not applicable to an action definition. Do not delete the cells between the label isconfigurable and 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. 78 EMC Documentum Web Development Kit Version Tutorial

79 Creating an Action List Component To create the layout for action info: 1. Copy the componentinfo JSP page from /webcomponent/componentlist/componentinfo.jsp to the following 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 to ActionList.ACTIONINFO_GRID. 5. Locate the <dmf:link> tag whose name is lnkback. Change the value of the onclick attribute from onclickcomplist to onclickactionlist 6. Save and close the file. Creating the Component Class The following procedure uses the ComponentList class as a model for the actionlist component behavior class. Caution: You can copy and paste code from the PDF tutorial, but certain symbols may be changed 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 (&apos;) may be changed to a curly quote. The NetBeans IDE compiler will show the line containing the error. You must ensure that these symbols are correct in your IDE before you compile. You can get the full source code for this tutorial on the Documentum developer site, developer.documentum.com. To create the component class: 1. In the NetBeans IDE, create a directory /WEB-INF/classes/com/mycompany/actionlist.. 2. Create a new Java class by right-clicking on the directory WEB-INF/classes/mycompany/actionlist and selecting New > Java Class. 3. Name the object ActionList and click Finish. The file will be created with the following lines: package com.mycompany.actionlist; public class ActionList public ActionList() EMC Documentum Web Development Kit Version Tutorial 79

80 Creating an Action List Component Note: If the package line appears different from that shown above, then either the WEB-INF classes directory was not mounted correctly, or you created the file within the wrong directory. 4. In the Source Editor window, following the package declaration, add the following import statements: import com.documentum.web.common.argumentlist; import com.documentum.web.form.control.link; import com.documentum.web.form.control.databound.datagrid; import com.documentum.web.form.control.databound.tableresultset; import com.documentum.web.formext.component.component; import com.documentum.web.formext.config.configfile; import com.documentum.web.formext.config.configservice; import com.documentum.web.formext.config.iconfigelement; import java.util.arraylist; import java.util.arrays; import java.util.hashmap; import java.util.iterator; 5. Next, edit the class definition that was created by NetBeans, adding an extends clause and some class variables: public class ActionList extends Component public static final String ACTIONLIST_GRID = "_actionlist_grid"; public static final String ACTIONINFO_GRID = "_actioninfo_grid"; private HashMap m_hashcfgelementlookup; private HashMap m_hashcfgscopelookup; public ActionList() 6. Within the class constructor that was provided by NetBeans IDE when you created the class, instantiate hash maps to hold the action IDs and scopes: public ActionList() m_hashcfgelementlookup = new HashMap(23); m_hashcfgscopelookup = new HashMap(23); 7. After the constructor, add an oninit() implementation that gets or creates the datagrids on both 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 must be commented out for now. See Creating the Action List Datagrid, page 81 for information on the updateactionlist() method, which creates or updates the actionlist datagrid. 8. Add a method that counts the number of actions that are defined in the application: public static int getnumberofactions() return ConfigService.getPrimaryElementIds("action").length; 80 EMC Documentum Web Development Kit Version Tutorial

81 Creating an Action List Component 9. Compile your class file. Note any errors in the output window and resolve them. The exact location of the error is noted by the compiler. Supporting Navigation Between Pages The actionlist JSP page lists all actions, and each action contains a link to the info page. The link requires an event handler, onclickactionid(). The actioninfo page displays information for an action and contains a link to return to the actionlist page. 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 is launched by a link on the actionlist.jsp page. This event handler gets the selected action ID, calls a method 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 created that method and its helper methods. 2. Add an event handler for the onclickactionlist event that is launched by a link on the actioninfo.jsp page. This event handler navigates back to the actionlist JSP page: public void onclickactionlist(link link, ArgumentList arg) setcomponentpage("start"); 3. Right-click and compile your class file. Note any errors in the output window and resolve them. The exact location of the error is noted by the compiler. Creating the Action List Datagrid In 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, and several 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(); EMC Documentum Web Development Kit Version Tutorial 81

82 Creating an Action List Component 2. Create the update method signature and get all action IDs from the ConfigService in-memory tables using the following syntax: 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 the following 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 the unfinished 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 and put the scope for each definition into another array. Add the following lines to the unfinished method 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 hash map. 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 shown in 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 file listrow.add(strcfgelid); listrow.add(stractionid); listrow.add(strscopes[idxel]); listrow.add(getconfigfilepath(icfgels[idxel])); listrow.add(getconfigfileurl(icfgels[idxel])); 82 EMC Documentum Web Development Kit Version Tutorial

83 Creating an Action List Component 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 the result set on the datagrid. Add the following lines to the unfinished method updateactionlist(): rslist.add(listrow); ((Datagrid)getControl( "_actionlist_grid", com.documentum.web.form.control.databound. Datagrid.class)).getDataProvider().setResultSet(rsList, null); Note: Do not compile your class file. You must add some supporting methods before your class will compile properly. Three methods are used to generate the configuration file path for display and the configuration file URL 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 method after 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 on the 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 the user 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('\\', '/'); else strbaseappdir = ""; EMC Documentum Web Development Kit Version Tutorial 83

84 Creating an Action List Component 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 your code against the class file on the Developer Web site and correct your errors. Right-click and compile your class file. Note any errors in the output window and resolve them. The exact location of the error is noted by the compiler. Creating the Action Info Datagrid Continuing the same action class from the previous section, you must add several methods that populate or update the action info datagrid. The main method, updateactioninfo(), gets the data, and several 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 was populated 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 the following 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 that provide the data are described in the next procedure.). Add the following lines to the unfinished updateactioninfo() method: Action ID Scope Action execution class Component launched by the action, if any Container launched by the action, if any 84 EMC Documentum Web Development Kit Version Tutorial

85 Creating an Action List Component XML file that contains the action definition List of parameters, with optional or required label addrowfromattribute(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 will add those methods later. The getconfigfilepath() method was created in an earlier procedure. 5. Set the result set on the datagrid by adding the following lines to finish the method: ((Datagrid)getControl("_actioninfo_grid", com.documentum.web.form.control.databound.datagrid.class)). getdataprovider().setresultset(rslist, null); Note: Do not compile your class file. You must add some supporting methods before the class will compile properly Several methods are used to generate row data for the info datagrid. Add the following methods after the 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 supplied attribute. 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 the name of the action that the current action extends. private String getextends(iconfigelement icfgel) String strextends = icfgel.getattributevalue("extends"); if(strextends!= null) return strextends; else return getstring("msg_none"); EMC Documentum Web Development Kit Version Tutorial 85

86 Creating an Action List Component 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; else return getstring("msg_none"); else return getstring("msg_none"); 4. Add the method getlaunchedcomponent(), which gets the name of the component that is launched by the action, if any. private String getlaunchedcomponent(iconfigelement icfgel) IConfigElement cfgexec = icfgel.getchildelement("execution"); if(cfgexec!= null) String strcomp = cfgexec.getchildvalue("component"); if(strcomp!= null) return strcomp; else return getstring("msg_none"); else return getstring("msg_none"); 5. Add the method getlaunchedcontainer(), which gets the name of the container that is launched by 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; else return getstring("msg_none"); 86 EMC Documentum Web Development Kit Version Tutorial

87 Creating an Action List Component else return getstring("msg_none"); 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 multiple parameter 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 your code against the class file on the Developer Web site and correct your errors. Right-click and compile your class file. Note any errors in the output window and resolve them. The exact location of the error is noted by the compiler. Creating the Resource Bundle In Creating the Component Definition, page 77 you specified an NLS resource bundle that will contain the strings for your component: com.mycompany.actionlist.actionlistnlsprop. EMC Documentum Web Development Kit Version Tutorial 87

88 Creating an Action List Component To create a properties file in the new directory: 1. Open thenetbeans explorer Filesystems tab. 2. Create the directory /custom/strings/com/mycompany/actionlist. 3. Right-click the mycompany directory, and select New > All Templates. 4. Open the Other templates group and click Text File. 5. Click Next and name the file ActionListNlsProp. 6. Click Next and add the properties extension. 7. Click Finish. Because you added the properties extension, NetBeans displays a page for editing property values. You can also open this page as a text file by right-clicking the file in the tree and selecting Edit. 8. Add each of the following key and value pairs by clicking the New Property button and filling in the dialog box that appears: MSG_NUM_ACTIONS = Number of Action Definitions MSG_ACTION_ID=Action ID MSG_SCOPES=Scopes MSG_ISCONFIGURABLE=Is configurable MSG_XML_FILE=XML file MSG_DESCRIPTION=Description MSG_EXECCOMP=Execution Component MSG_YES = Yes MSG_NO = No MSG_NONE = None MSG_BACKTO_LIST = Back To Action List MSG_PARAMS = Parameters MSG_EXTENDS = Extends MSG_CLASS=Class MSG_EXECCONTAINER=Execution Container MSG_NLSCLASS=NLS Class MSG_NLSBUNDLE=NLS Bundle 9. Save and close the file. Testing the Customization The full source code for this customization is located on the Documentum developer site, developer.documentum.com. To refresh files and test the actionlist component: 1. If you have changed only XML files, refresh the configuration service by navigating to 2. If you have created and compiled (or edited and recompiled) the ActionList class, or if you have made changes to the properties file, stop and restart the Tomcat server. 3. Log in and navigate to the actionlist component with the following URL: 88 EMC Documentum Web Development Kit Version Tutorial

89 Creating an Action List Component During your development, changes to a JSP page or changes to a Java class that provides values to the JSP page, require that you delete the generated Java class file that represents the compiled JSP page in order to see your changes. Changes to an NLS resource bundle require that you reload the Web application in the server. If the strings do not display properly, for example, xxmsg_num_actionsxx instead of Number of Actions, check the path to the properties file that you created. It must match the fully qualified NLS property resource bundle in the actionlist component definition. Variations in this tutorial You 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 by passing required and optional parameters. You could add a text input tag for each parameter and add 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 the user enters a scope that is not compatible with one of the input parameters. EMC Documentum Web Development Kit Version Tutorial 89

90 Creating an Action List Component 90 EMC Documentum Web Development Kit Version Tutorial

91 Chapter 8 Creating a Content Transfer Listener This tutorial requires both configuration and customization to create a listener component that wraps a content transfer operation. Specifically, this component gets the map of object IDs for new objects that are imported by UCF content transfer. The full source code for this customization is located on the Documentum developer site, developer.documentum.com. The tutorial contains the following sections: Task Objective, page 91 Technical Overview, page 91 Creating the Component Definition, page 92 Creating the Component Layout, page 92 Creating the Component Class, page 93 Creating the Resource Bundle, page 94 Testing the Customization, page 95 Variations in this tutorial, page 96 Task Objective In this tutorial, you will create a content transfer listener component that calls the import action and gets the new object IDs after import. If your custom component will perform some operation outside of content transfer, it is better to create a listener component rather than extend the content transfer component itself. Technical Overview WDK provides results to a listener for each content transfer operation. For the import container, the results are the new object IDs for the imported objects. This content transfer listener component has a simple JSP page with a button whose onclick event handler in the component class calls the import action. This method must supply a destination folder ID for the import action. In this first exercise, the destination folder is hard-coded. As a EMC Documentum Web Development Kit Version Tutorial 91

92 Creating a Content Transfer Listener refinement to this first exercise, the import destination folder will be supplied by additional code that gets the user s home cabinet ID. Creating the Component Definition To create a new WDK testlistener component, you must create a component definition. To create the testlistener definition: 1. Create an empty text file in /custom/config named testlistener_component.xml. 2. Open the file and add the following content: <config version="1.0"> <scope> <component id="testlistener"> <pages> <start>/custom/test/testlistener.jsp</start> </pages> <class>com.mycompany.test.testlistener</class> <nlsbundle>com.mycompany.test.testlistenerprop</nlsbundle> </component> </scope> </config> 3. Save and close the file. Creating the Component Layout You can present your component in several ways. The simplest way is to simply create the JSP page and 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=utf-8" %> <%@ page errorpage="/wdk/errorhandler.jsp" %> <%@ page import="com.mycompany.test.testlistener" %> <%@ taglib uri="/web-inf/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> 92 EMC Documentum Web Development Kit Version Tutorial

93 Creating a Content Transfer Listener </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 Class The following procedure creates the component behavior class. Caution: You can copy and paste code from the PDF tutorial, but certain symbols may be changed 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 (&apos;) may be changed to a curly quote. The NetBeans IDE compiler will show the line containing the error. You must ensure that these symbols are correct in your IDE before you compile. You can get the full source code for this tutorial on the Documentum developer site, developer.documentum.com. To create the component class: 1. In the NetBeans IDE, create a directory /WEB-INF/classes/com/mycompany/test. 2. Create a new Java class by right-clicking on the directory WEB-INF/classes/mycompany/test and selecting New > Java Class. 3. Name the object TestListener and click Finish. The file will be created with the package declaration, class definition, and class constructor: package com.mycompany.test; public class TestListener public TestListener() Note: If the package line appears different from that shown above, then either the WEB-INF classes directory was not mounted correctly, or you created the file within the wrong directory. 4. In the Source Editor window, following the package declaration, add the following 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.*; EMC Documentum Web Development Kit Version Tutorial 93

94 Creating a Content Transfer Listener 5. Next, edit the class definition that was created by NetBeans, adding an extends clause. You can delete the constructor: public class TestListener extends Component 6. Within the class definition, create the button event handler with the method name specified in the JSP page. This method creates a new argument list with a hard-coded value for the only parameter that is required for the import action. Substitute a valid folder ID in your repository for the highlighted value. The method then calls the import action and registers the listener: public TestListener extends Component public void onimportlistener(control ctrl, ArgumentList args) ArgumentList componentargs = new ArgumentList(); componentargs.add("objectid", "0c de8bc"); 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 method should get the new object IDs after import and do whatever it is you want to do with them: public void oncomplete(string straction, boolean bsuccess, Map map) System.out.println("onComplete called"); List newobjectidlist = (List) ImportContentContainer. retrievereturnobjectids(map); if (newobjectidlist!= null) System.out.println("newObjectIdList has content"); Iterator itnewids =newobjectidlist.iterator(); while (itnewids.hasnext() == true) String strnewid = itnewids.next().tostring(); System.out.println(strNewId); 8. Compile your class and correct any errors that are signalled by the compiler. You can compare against the code that is on the developer site. Creating the Resource Bundle In Creating the Component Definition, page 92 you specified an NLS resource bundle that will contain the string for your component button label: com.mycompany.test.testlistenernlsprop. (If you enter a button 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. Open the NetBeans explorer Filesystems tab. 94 EMC Documentum Web Development Kit Version Tutorial

95 Creating a Content Transfer Listener 2. Create the directory /custom/strings/com/mycompany/test. 3. Right-click the mycompany directory, and select New > All Templates. 4. Open the Other templates group and click Text File. 5. Click Next and name the file TestListenerNlsProp. 6. Click Next and add the properties extension. 7. Click Finish. Because you added the properties extension, NetBeans displays a page for editing property values. You can also open this page as a text file by right-clicking the file in the tree and selecting Edit. 8. Add the following key and value pair by clicking the New Property button and filling in the dialog box that appears: MSG_IMPORT_LISTENER = Test Import Listener 9. Save and close the file. Testing the Customization The full source code for this customization is located on the Documentum developer site, developer.documentum.com. To refresh files and test the testlistener component: 1. If you have changed only XML files, refresh the configuration service by navigating to 2. If you have created and compiled (or edited and recompiled) the TestListener class, or if you have made changes to the properties file, stop and restart the Tomcat server. 3. Log in and navigate to the testlistener component with the following URL: You should see a simple page with a test button. Click the button, and you should see the Add Files import dialog. After import, you should see the debugging statements in your Tomcat console and log, similar to the following: Figure 17. Testlistener Console Output During your development, changes to a JSP page or changes to a Java class that provides values to the JSP page, require that you delete the generated Java class file that represents the compiled JSP page in order to see your changes. Changes to an NLS resource bundle require that you reload the Web application in the server. EMC Documentum Web Development Kit Version Tutorial 95

96 Creating a Content Transfer Listener If the strings do not display properly, for example, xxmsg_num_actionsxx instead of Number of Actions, check the path to the properties file that you created. It must match the fully qualified NLS property resource bundle in the testlistener component definition. Variations in this tutorial The import destination folder will not be hard-coded in a production component. The following exercise adds code that gets the current user s home cabinet and uses that folder ID as the destination. To get the User s Home Cabinet 1. Open the class file TestListener.java and add the following import statements: mport com.documentum.web.formext.docbase.folderutil; import com.documentum.web.formext.session.sessionmanagerhttpbinding; import com.documentum.fc.client.*; import com.documentum.fc.common.dfexception; import com.documentum.fc.common.dfid; 2. Add an initialization method. We add this so that we can create a simple action that is available from a menu, rather than having to call the component by URL. This initialization will simply call the onimportlistener() method. (Always call super.oninit() so that your component is initialized properly.) 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", "0c de8bc"); Replace with these lines: IDfSessionManager sessionmanager = null; IDfSession dfsession = null; try sessionmanager = 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. 96 EMC Documentum Web Development Kit Version Tutorial

97 Creating a Content Transfer Listener getcontext(), this, new CallbackDoneListener( this, "oncomplete")); Add the following catch and finally blocks to close the session: catch (DfException e) finally if (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. We added a menu item (My import) for the action in our custom Webtop menubar component (steps not 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 the application 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 files have been successfully imported, the user is returned to the Webtop objectlist. The console output shows successful import as illustrated in Figure 19, page 98. EMC Documentum Web Development Kit Version Tutorial 97

98 Creating a Content Transfer Listener Figure 19. TestListener Console Output, Enhanced 98 EMC Documentum Web Development Kit Version Tutorial

99 Chapter 9 Limiting Import Types This tutorial requires both configuration and customization to customize the UCf import component and limit the list of object types for import. The full source code for this customization is located on the Documentum developer site, developer.documentum.com. The tutorial contains the following sections: Task Objective, page 99 Technical Overview, page 99 Creating the Component Definition, page 100 Creating the Component Layout, page 100 Creating the Component Class, page 100 Creating the Resource Bundle, page 103 Testing the Customization, page 103 Variations in this tutorial, page 105 Task Objective In this tutorial, you will create a custom import component that extends UCF import and limits the list of available object types for import. Note that you can already limit the list of types to one type and its subtypes through the <document-docbase-type> element of the import component definition. This tutorial fulfills the requirement of providing a limited set of types that do not derive from the same type or the requirement of making subtypes visible. Technical Overview The UCF import component provides a list of all the object types in the repository for the object to be imported. Some applications may need to limit the object types that are available. This custom component extends the UCF component definition and provides a custom class that reads the available object 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. EMC Documentum Web Development Kit Version Tutorial 99

100 Limiting Import Types Creating the Component Definition To create a new WDK import component, you must create a component definition. To create the component definition: 1. Create an empty text file named myimport_component.xml in /custom/config. 2. Open the file and add the following content: <?xml version="1.0" encoding="utf-8" standalone="no"?> <config version='1.0'> <scope> <component id="import" extends="import:webcomponent/config/ library/contenttransfer/importcontent/import_component.xml"> <class>com.mycompany.test.myimportcontent</class> </component> </scope> </config> 3. After the closing </class> element, add custom elements that will be used to configure the list of available object types. Substitute actual object types that are valid for your repository as the value of the <docbase_type>.<value> elements: <!-- specify the comma-separated list of types and subtypes) that will be available for import --> <includetypes> <docbase_type> <value>dm_document</value> <label>document</label> </docbase_type> <docbase_type> <value>dm_xml_style_sheet</value> <label>xml Stylesheet</label> </docbase_type> </includetypes> 4. Save and close the file. Creating the Component Layout Because this custom component provides the result set for the import type dropdown list, you do not need to customize the layout. In your component class, you will create the button onclick event handler method onimportlistener(). Creating the Component Class The following procedure creates the component behavior class. 100 EMC Documentum Web Development Kit Version Tutorial

101 Limiting Import Types Caution: You can copy and paste code from the PDF tutorial, but certain symbols may be changed 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 (&apos;) may be changed to a curly quote. The NetBeans IDE compiler will show the line containing the error. You must ensure that these symbols are correct in your IDE before you compile. You can get the full source code for this tutorial on the Documentum developer site, developer.documentum.com. To create the component class: 1. In the NetBeans IDE, create a directory /WEB-INF/classes/com/mycompany/test. 2. Create a new Java class by right-clicking on the directory WEB-INF/classes/mycompany/test and selecting New > Java Class. 3. Name the object MyImportContent and click Finish. The file will be created with the package declaration, class definition, and class constructor: package com.mycompany.test; public class MyImportContent public MyImportContent() Note: If the package line appears different from that shown above, then either the WEB-INF classes directory was not mounted correctly, or you created the file within the wrong directory. 4. In the Source Editor window, following the package declaration, add the following 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 NetBeans, adding an extends clause. You can delete the constructor: public class MyImportContent extends ImportContent 6. Within the class definition, add a method createtypesresultset() that overrides the createtypesresultset method of the import component. If you examine the source code (provided by the WDK installer) for the WDK import component, you see that this the method provides content to the import type dropdown list. It is called by the inittypelistcontrol() method: public class MyImportContent extends ImportContent protected ScrollableResultSet createtypesresultset() if (isdirectory() == false) TableResultSet rstypes = getdocbasetypes(); return rstypes; EMC Documentum Web Development Kit Version Tutorial 101

102 Limiting Import Types return super.createtypesresultset(); 7. Now create the getdocbasetypes() method that you called in the createtypesresultset method. This method will read the object types that you have configured in your component definition and provide 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 component definition. The string array consists of a value for type_name and label_text that correspond to the list 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 used to 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 list Iterator itertypes = elemdocbasetypes.getchildelements( "docbase_type"); while (itertypes.hasnext()) //Retrieve the value and label IConfigElement 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 label IConfigElement 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 label if (strlabel == null strlabel.length() == 0) 102 EMC Documentum Web Development Kit Version Tutorial

103 Limiting Import Types strlabel = strvalue; //Add type and label to result set rs.add(new String[]strValue, strlabel); return rs; 8. Compile your class and correct any errors that are signalled by the compiler. You can compare against the code that is on the developer site. Creating the Resource Bundle In your custom component definition, you did not specify an NLS resource bundle. If you want to externalize the labels for your object types, you can add an <nlsid> element within the <docbase_type>.<label> element, and then create a properties file with the nlsid keys and values. Note that you will need to copy in the WDK import NLS file contents to your properties file. Testing the Customization The full source code for this customization is located on the Documentum developer site, developer.documentum.com. To refresh files and test the testlistener component: 1. If you have changed only XML files, refresh the configuration service by navigating to 2. If you have created and compiled (or edited and recompiled) the MyImportContent class, or if you have 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 should see your restricted list of file types in the UI. EMC Documentum Web Development Kit Version Tutorial 103

104 Limiting Import Types 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_document Docbase type: dm_xml_style_sheet During your development, changes to a JSP page or changes to a Java class that provides values to the JSP page, require that you delete the generated Java class file that represents the compiled JSP page in order to see your changes. Changes to an NLS resource bundle require that you reload the Web application in the server. 104 EMC Documentum Web Development Kit Version Tutorial

105 Limiting Import Types If the strings do not display properly, for example, xxmsg_num_actionsxx instead of Number of Actions, check the path to the properties file that you created. It must match the fully qualified NLS property resource bundle in the testlistener component definition. Variations in this tutorial You could add a default type to be selected when the user opens the import type dropdown list. To do this, you would need to add an element to the component definition that sets the default type, then read the element in your getdocbasetypes() method. Store the value in a class member variable. Override the method that initializes the type list control and set the default value from your member variable, similar to the following: protected void inittypelistcontrol() super.inittypelistcontrol(); if (isdirectory() == false) // set your default type DataDropDownList typelist = gettypelistcontrol(true); String strdefaulttype = getconfigdefaulttype(); typelist.setvalue(strdefaulttype); System.out.println("Default type: " + strdefaulttype); protected String getconfigdefaulttype() //Retrieve the default from an element called defaulttype 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"; EMC Documentum Web Development Kit Version Tutorial 105

106 Limiting Import Types 106 EMC Documentum Web Development Kit Version Tutorial

107 Using Tracing and Logging in a Component Chapter 10 This tutorial demonstrates how to add tracing and logging to your component to make it easier to detect runtime errors.. The full source code for this customization is located on the Documentum developer site, developer.documentum.com. The tutorial contains the following sections: Task Objective, page 107 Technical Overview, page 107 Creating the Tracing Class, page 108 Adding Tracing to the Component Class, page 109 Adding Custom Tracing to the List, page 110 Turning on Tracing, page 110 Examining the Trace Log, page 111 Testing the Customization, page 110 Variations in this tutorial, page 111 Task Objective In this tutorial, you will create a tracing class for your custom code and add a tracing flag to your code, then turn on tracing and inspect the log. Technical Overview WDK tracing flags trace the following types of operations or content manipulation: sessions, JSP requests, locales, actions, configuration, roles, preferences, resources, clipboard, controls, control tags, 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, see EMC Documentum Web Development Kit Development Guide. EMC Documentum Web Development Kit Version Tutorial 107

108 Using Tracing and Logging in a Component You can add your own tracing flags to trace operations that are used in more than one class. After you enable tracing, tracing statements will be written to the wdk.log file in your The default location for the log is <user.dir>/documentum/logs: user.dir resolves to the application server binary executables 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 in your application. If there is an unknown flag in this file, the Trace class initialization will generate a warning message but will continue. Note: You must enable tracing for the current session using one of the following methods: Set the SESSION flag (mandatory) and another other flags you require in TraceProp.properties and then restart the application server. Use a browser to navigate to /wdk/tracing.jsp and check the boxes that enable tracing. You can enable tracing for all sessions for setting SESSIONENABLEDBYDEFAULT to true in /WEB-INF/classes/com/documentum/debug/TraceProp.properties. The open source Apache logging library log4j is installed by the DFC installer. This package allows you to enable logging at runtime without modifying the application library or incurring a significant performance impact. The Apache log4j library is used by the DFC logger class DfLogger. Each log4j Logger class method such as debug() and warn() is wrapped by a DfLogger method. The WDK Trace class uses DfLogger to write the log file for all enabled traces. The log file location is specified in a log4j.properties file, which is installed by the WDK and client applications installers to DOCUMENTUM_HOME/config. By default, the log file name (not path) is specified in log4j.properties as the value of the key log4j.appender.file.file, for example, C\:\\Documentum\\logs\\trace.log (the double backslashes indicates an escaped backward slash). Creating the Tracing Class Caution: You can copy and paste code from the PDF tutorial, but certain symbols may be changed 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 (&apos;) may be changed to a curly quote. TheNetBeans compiler will show the line containing the error. You must ensure that these symbols are correct in your IDE before you compile. Instead of copying and pasting, type in the content or get it from the code zip file on the developer Web site. To create the component class: 1. Create a new Java class by right-clicking on the directory WEB-INF/classes/mycompany and selecting New > Java Class. 2. Name the class Trace and click Finish. The file will be created with the following line: package com.mycompany; Note: If the package line appears different from that shown above, then either the WEB-INF classes directory was not mounted correctly, or you created the file within the wrong directory. 108 EMC Documentum Web Development Kit Version Tutorial

109 Using Tracing and Logging in a Component 3. Edit the class definition that was created by NetBeans, adding an extends clause: public class Trace extends com.documentum.web.common.trace 4. After the constructor, add the following tracing flag: public static boolean ACTIONLIST; 5. Compile your class file. Note any errors in the output window and resolve them. The exact location of the error is noted by the compiler. Adding Tracing to the Component Class Add tracing statements for the main methods in your component class or for methods that may throw exceptions. In this tutorial you will add tracing statements to the ActionList class that you created in the previous tutorial. You will add tracing statements to the update method and to the methods that handle links and navigation. Note: For this example to work, you must create all of the files required for the tutorial actionlist component. Alternatively, you can create a tracing flag that is appropriate for one of your custom classes, and add it to your class. To add tracing to the Update Method: 1. Open ActionList.java in your IDE and locate the method updateactionlist(). 2. Import your Trace class by adding the following import statement: import com.mycompany.trace; 3. Locate the following line in the method: TableResultSet rslist = new TableResultSet(strDataFields); 4. Add the following lines: if (Trace.ACTIONLIST) if (rslist!= null) Trace.println("Result set successfully created"); else Trace.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 the lnkback 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"); EMC Documentum Web Development Kit Version Tutorial 109

110 Using Tracing and Logging in a Component Adding Custom Tracing to the List To make your tracing flags accessible, so that you can turn them on or off, you must add them to a tracing properties file. Open the properties file TraceProp.properties in /WEB-INF/classes/com/documentum/debug Add your flag on the last line, as shown in the following example: com.mycompany.trace.actionlist=true Turning on Tracing You must restart your application server to apply changes to a properties file. There are two ways to turn on tracing in your application: Set the appropriate tracing flags to true in /WEB-INF/classes/com/documentum/debug/ TraceProp.properties. Navigate to /wdk/tracing.jsp and select the first checkbox, Tracing is enabled for current session. Then check relevant tracing flags, such as ACTIONLIST. See the example below. Figure 22. Tracing JSP Page... Testing the Customization The full source code for this customization is located on the Documentum developer site, developer.documentum.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 navigate to the actionlist component: 3. Exercise the actionlist component by clicking on an action, returning to the start page, and then clicking on the XML file link. 110 EMC Documentum Web Development Kit Version Tutorial

111 Using Tracing and Logging in a Component If you add tracing statements to you behavior class, you must recompile and stop and restart the server to see your tracing statements in the log. Examining the Trace Log Trace statements are written to the Tomcat console, so you can see them as you exercise your component. After you stop the application server, you can examine the log file for your trace statements. Open the tracing log in the location specified in your DOCUMENTUM_HOME/config/log4j.properties file. 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 application server executable directory, for example, TOMCAT_HOME/bin/documentum/logs. log4j.appender.file.file=c\:/documentum/logs/wdk.log The following except from wdk.log shows the statements added in this tutorial: :41:48, [http-8080-processor25] DEBUG com.documentum.web.common.trace - Result set successfully created :42:02, [http-8080-processor25] DEBUG com.documentum.web.common.trace - Returning to start page The resulting trace statements are also written to the Tomcat console, as shown below. Figure 23. Tracing Output Variations in this tutorial You can add JavaScript tracing for client-side functions. The trace JavaScript file trace.js is referenced in 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.jsp page 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); EMC Documentum Web Development Kit Version Tutorial 111

112 Using Tracing and Logging in a Component A popup browser window opens with the tracing statement: Figure 24. JavaScript Tracing 112 EMC Documentum Web Development Kit Version Tutorial

113 Chapter 11 Customizing UCF Export UCF export displays a dialog on export that allows the user to choose an export target location, as shown below: Figure 25. Export Location Dialog This tutorial demonstrates how to customize UCF export to perform silently for simple export of one or more files (not a virtual document or XML document with inline entities). The full source code for this customization is located on the Documentum developer site, developer.documentum.com. The tutorial contains the following sections: Task Objective, page 114 Technical Overview, page 114 EMC Documentum Web Development Kit Version Tutorial 113