Documentum Web Development Kit Tutorial

Transcription

1 Documentum Web Development Kit Tutorial Version 4.2 April 2001 DOC3-WDKTUT-0401 *DOC3-WDKTUT-0401*

2 Copyright 2000, 2001 Documentum, Inc Koll Center Parkway Pleasanton, CA All Rights Reserved. Documentum, Documentum 4i, Docbase, Documentum econtent Server, Documentum Server, Documentum Desktop Client, Documentum Intranet Client, Documentum WebPublisher, Documentum ftpintegrator, Documentum RightSite, Documentum Administrator, Documentum Developer Studio, Documentum Web Development Kit, Documentum Web Gear, Documentum WebCache, Documentum ContentCaster, AutoRender Pro, Documentum iteam, Documentum Reporting Gateway, Documentum Content Personalization Services, Documentum Site Delivery Services, Documentum Content Authentication Services, Documentum Dynamic Content Assembler, Documentum DocControl Manager, Documentum Corrective Action Manager, Documentum econnector for BEA WebLogic (BEA and WebLogic are registered trademarks of BEA Systems), Documentum econnector for JDBC, Documentum econnector for CAD, Documentum econnector for SAP (SAP is a trademark of SAP AG), Documentum econnector for Lotus Notes (Lotus Notes is a registered trademark of Lotus Development Corporation), DocInput, Documentum DocViewer, GMPharma, Virtual Document Manager, Docbasic, Documentum WorkSpace, Documentum SmartSpace, and Documentum ViewSpace are trademarks or registered trademarks of Documentum, Inc. in the United States and throughout the world. All other company and product names are used for identification purposes only and may be trademarks of their respective owners.

3 C ONTENTS Preface 1 What is the Web Development Kit? What WDK Is and What it Can Do Compliance With Java Specifications Dependencies on Other Software Fitting the Pieces Together Summary JavaServer Pages in the WDK Anatomy of a Typical WDK Server Page HTML Generated by JSP Handling Errors Developing an Application Prepare Your Environment Plan the Application Create the Application Directory Locate the Tutorial Files Create a Page Add the Toolbar Add Event Handlers Enable Actions on Docbase Contents Extra Investigation: Use Cascading Style Sheets to Customize the Look of Your Application Customizing WDK Components Modify a Menu Before you begin Remove the menu items Extra investigation: Add a menu item Add a Column to a View Before you begin Add the column to the view Displaying Properties of a Custom Object Type Display Custom Properties of a Custom Object Type Before you begin Display the custom properties Documentum Web Development Kit Tutorial iii

4 Extra Investigation: Searching for Properties of a Custom Object Type A Solution Code wdkskeletonpage.jsp A-2 wdktutorial0_finished.jsp A-3 wdktutorial1_finished.jsp A-4 toolbartutorial_finished.jsp A-5 wdktutorial2_finished.jsp A-7 wdktutorial3_finished.jsp A-9 foldercontents.jsp A-11 iv Documentum Web Development Kit Tutorial

5 P REFACE Purpose of the Manual This manual provides an introduction to the basic features of the Documentum Web Development Kit (WDK) using both conceptual information and hands-on examples. For detailed WDK information, including installation instructions, information on developing and configuring web applications with the WDK, and reference material, see: Installation and Release Notes Online Help API Documentation (Javadoc) All of these documents are available in the docs directory that resides in the WDK installation directory. Intended Audience This manual is designed for web developers and designers who will use the WDK to add Documentum functionality to web applications. It assumes that you are familiar with JavaServer Pages, web applications, JavaScript, and HTML. Numerous books that cover these topics are available commercially, and you can also consult the following documents at Java Servlet Specification, version 2.2 JavaServer Pages Specification, version 1.1 Organization of the Manual The following table describes the contents of the chapters and appendixes of this book. Documentum Web Development Kit Tutorial v

6 Chapter Chapter 1, What is the Web Development Kit? Chapter 2, JavaServer Pages in the WDK Chapter 3, Developing an Application Chapter 4, Customizing WDK Components Chapter 5, Displaying Properties of a Custom Object Type Appendix A, Solution Code Contents Describes the contents of the WDK and how it works with your HTTP server and application server. Describes how JavaServer Pages are used to drive WDK-based web applications. Contains step-by-step examples of how to build a simple web application based on the WDK. Contains step-by-step examples of how to customize a menu and a view. Contains step-by-step examples of how to display the properties of a custom object type in the properties page of WDK. Lists the solutions for each tutorial exercise. Conventions This manual uses the following conventions: Convention italics typewriter Description Represents a pop-up or pull-down menu. Indicates the introduction to a procedure. Represents a variable name for which you must provide a value, or a defined term. Represents code samples, user input, and computer output. [] square brackets Indicates an optional argument. braces (curly brackets) Indicates an optional argument that can be repeated more than once. vi Documentum Web Development Kit Tutorial

7 Using Links in PDF Files If you are reading this document as a Portable Display Format (PDF) file, cross-references and page numbers in the index are clickable blue hypertext links. Table of contents page numbers are also clickable links, but they appear in black. Each server book contains many clickable cross-references to the other server books. Cross-references to manuals other than the one you are reading only work if the PDF files are all in the same directory and have the same file names that they have on the server release CD. To follow a link: 1. Move the pointer over a linked area. The pointer changes to a pointing finger when positioned over a link. The finger pointer displays a W when moved over a Weblink. 2. Click to follow the link. Note: To follow Web links, your Weblink preferences must specify a Web browser. See Setting Weblink preferences in your Adobe Acrobat Help for more information. Bug Lists and Documentation Online Applying for Access Customers with a software support agreement can read our product documentation and, after commercial release of a product, view lists of fixed bugs on our Technical Support web pages. To view this information you must apply for access to the Technical Support area. To apply for access: 1. In your browser, open 2. Choose the Customer Service Technical Support link. Documentum Web Development Kit Tutorial vii

8 Fixed Bugs List 3. Click the Request Access link. 4. Complete the form and submit it. Documentum will respond to your request within two business days. Within two weeks from the date of this release, Documentum places a list of fixed bugs in the Technical Support area of documentum.com. The list includes all customer-related bugs that the current release corrects. For information about obtaining access to the Technical Support area of the Web site, refer to Applying for Access on page vii. You must have Adobe Acrobat Reader or Acrobat Exchange installed to view the lists of fixed bugs. To view the list of fixed bugs: 1. In your browser, open 2. Choose the Customer Service Support Logon link. 3. Log on to the Technical Support site. 4. In the Troubleshooting section, click Fixed Bugs Lists. 5. Click the product name link for a product s bug list. Product Documentation Customers with a software support agreement can read our product documentation at documentum.com. To view the documentation, you must have a user name and password, and Adobe Acrobat Exchange or Acrobat Reader installed. To obtain a user name and password, refer to Applying for Access on page vii. To view a document: 1. In your browser, open 2. Choose the Customer Service Support Logon link. 3. Log on to the Technical Support site. 4. In the left pane, click Documentation. viii Documentum Web Development Kit Tutorial

9 5. To list documents, select a sorting method in the List Documentation By field, and click List. 6. Click the name of the document you wish to view. Purchasing Bound Paper Manuals Our product documentation is available for purchase as bound paper manuals. To place an order, call the Documentation Order Line at (925) You can pay with a purchase order, check, or credit card. Documentum Web Development Kit Tutorial ix

10 x Documentum Web Development Kit Tutorial

11 1 What is the Web Development Kit? 1 This chapter provides a basic introduction to the Documentum Web Development Kit (WDK), the development environment that it uses, and the web applications that it allows you to build. There are no tutorial exercises in this chapter, but this information is essential to understanding the WDK. This chapter contains the following sections: What WDK Is and What it Can Do on page 1-1 Compliance With Java Specifications on page 1-2 Dependencies on Other Software on page 1-3 Fitting the Pieces Together on page 1-3 Summary on page 1-6 What WDK Is and What it Can Do The WDK is a set of tools with which you can build custom web applications that include Documentum functionality and run on a Java application server. A web application is a collection of JavaServer Pages, servlets, classes, HTML pages, JAR files, and any other resources that can be bundled together and deployed as a standalone application on a Java application server. Users launch and use the web application in a web browser. With WDK, your web applications can include document management features such as checkout and checkin, workflows, lifecycles, and virtual documents. The WDK consists of the following tools: Java classes that conduct Docbase operations. These classes include: Documentum Web Development Kit Tutorial 1 1

12 What is the Web Development Kit? Compliance With Java Specifications Command classes that conduct Docbase operations. Content transfer classes that manage checkout, checkin, import, and export of documents and XML between clients and a Docbase. The content transfer classes install and use content transfer applets in the client browser. The command classes and content transfer classes rely on the Documentum Foundation Classes (DFC) to provide basic Docbase functionality. Java classes for models and views of Documentum objects, such as models and views of the folder hierarchy in a Docbase or the document hierarchy in a virtual document. Java classes that manage configuration, context, menus, localization, events, and exceptions. JavaServer Pages that provide Documentum functionality by instantiating objects based on the Java classes and creating standard user interfaces. JSP pages can contain both server-side Java code and client-side HTML and JavaScript code, allowing you to generate dynamic content on the server and control its presentation and behavior on the client. You can customize these JSP pages as desired for your application. JavaScript functions and event handlers that support the user interfaces in the JSP pages. Some JavaScript functions reside in associated JSP pages, while others reside in files that contain only JavaScript. Services that allow you to configure your application and its components with XML, which reduces the amount of time and programming expertise required to develop your application. API documentation (Javadocs) for the WDK and DFC classes, and online help (Javahelp) that contains documentation for the JavaServer pages and application development tasks. Compliance With Java Specifications The tools in WDK conform to the following specifications, available at java.sun.com: Java Servlet Specification, version 2.2 JavaServer Pages Specification, version Documentum Web Development Kit Tutorial

13 What is the Web Development Kit? Dependencies on Other Software To deploy and run a web application that is built on WDK, you require a Java application server that supports both of these specifications. Dependencies on Other Software Before you develop a web application using WDK, you must install and configure the following server software: An HTTP server, which can reside on your development machine or on a separate machine. A Java application server, which communicates with the HTTP server and typically (but not always) resides on the same machine as the HTTP server. The Java application server must support both the Java Servlet Specification, version 2.2, and the JavaServer Pages Specification, version 1.1. A Documentum econtent server and Docbase, which is accessed through a Docbroker and can reside on any machine. These products are separate from the WDK. To install and configure these products, refer to their installation instructions and documentation. To conduct the exercises in this tutorial, you need: The server software described above. A text editor on your development machine that reads and writes plain ASCII by default and does not reformat or automatically wrap lines that you type. You can optionally use a J2EE-compliant integrated development environment (IDE) for Java on your development machine. Fitting the Pieces Together As you develop your web application, you typically work with local files and a development server, and you revise and add files as the application evolves. When your web application is complete and ready to deploy on a production application server, you use Java archive tools to package all of the files and Documentum Web Development Kit Tutorial 1 3

14 What is the Web Development Kit? Fitting the Pieces Together resources into a single Web Archive (WAR) file. You then use the tools provided by your Java application server to deploy the WAR file as an application on your production server. Deployment procedures differ among application servers. For deployment details, consult the documentation for your application server. For a detailed description of web applications and the WAR file format, refer to the Java Servlet Specification, version 2.2, available at After a web application is deployed on the application server, a user launches the application by requesting the application s start page in a web browser. The following steps describe what happens when a user requests the application s start page. Figure 1-1 illustrates these steps. 1. User launches a web browser and requests the application s start page, for example, Appserver is the name of your application server and appname is the name of your WDK-powered application. 2. The browser sends this request to the HTTP server. 3. The HTTP server recognizes that this is a request for a JSP page, not an HTML page, and it passes the request to the Java application server. 4. The Java application server then retrieves the JSP page and compiles it into a servlet if necessary. JSP pages are compiled the first time they are requested. The application server then saves the compiled servlet for use by subsequent requests. 5. The Java application server runs the compiled servlet, executing the server-side Java instructions and accessing the Docbase as necessary. The servlet produces a response that consists solely of HTML and JavaScript. 6. The Java application server sends the response (HTML + JavaScript) to the HTTP server. 7. The HTTP server sends the response to the user s browser, which processes any JavaScript in the response and displays the HTML in the response. 1 4 Documentum Web Development Kit Tutorial

15 What is the Web Development Kit? Fitting the Pieces Together Figure 1-1 Displaying an Application s Start Page in a Browser W eb server machine (hardware) W AR file wdkspace.jsp Java application server (software) Server machine (hardware) Docbase 5 Compile the JSP into a servlet 4 Run the servlet; generate HTML/JavaScript Get the JSP file 6 3 HTTP server (software) 7 2 Client machine (hardware) Browser (software) Address: 1 Java Virtual Machine (software) Documentum Web Development Kit Tutorial 1 5

16 What is the Web Development Kit? Summary Summary The WDK is a set of tools with which you can build a web application that has Documentum functionality. A web application is a collection of pages, classes, and any other resources that constitute a standalone application on a Java application server. Web applications are described in the Java Servlet Specification, version 2.2. To develop and deploy a web application with WDK, you need an HTTP server, a Java application server, and a Documentum econtent Server and Docbase. 1 6 Documentum Web Development Kit Tutorial

17 2 JavaServer Pages in the WDK 2 WDK functionality is presented primarily via JavaServer Pages, also known as JSP pages. (The term JSP pages seems redundant, but this is the terminology used in the JavaServer Pages Specification.) You can think of a JSP page as the source code for a servlet whose sole function is to produce an HTTP response object from an HTTP request object. For example, a web browser requests a JSP page and includes any information that the JSP requires, such as IDs of objects in the Docbase. The request goes to the HTTP server, which passes it to the application server. The application server compiles the requested JSP into a servlet (in many cases, the JSP is already compiled) and runs the servlet using the information provided with the request. The output from the servlet is the response, which consists of HTML and JavaScript. This response is returned to the browser and displayed. Detailed information on servlets and JSP pages is available in Java Servlet Specification, version 2.2, and the JavaServer Pages Specification, version 1.1. These specifications are available at This chapter describes how JSP pages are used in the WDK. It contains the following sections: Anatomy of a Typical WDK Server Page on page 2-1 HTML Generated by JSP on page 2-3 Handling Errors on page 2-3 Anatomy of a Typical WDK Server Page Most JSP pages in the WDK have the following general structure: 1. Page language and page info directives, which typically specify the content type, encoding, language, error page, and application name. For example: Documentum Web Development Kit Tutorial 2 1

18 JavaServer Pages in the WDK Anatomy of a Typical WDK Server Page <%@ page contenttype="text/html; charset=utf-8"%> <%@ page language="java" errorpage="/wdk/component/error/error.jsp"%> <%@ page info="wdk Application"%> 2. Import the Java classes required by the page. Most JSP pages in the WDK use the following classes: com.documentum.wc.env.jsp.dwjsppagecontext DwJSPPageContext is the page context object, which binds to the WDK namespace and reads the application configuration file. Use the page context object to acquire all of the persistent objects needed for the page, such as the web application (DwApplication), application session (DwAppSession), and page set (DwPageSet). com.documentum.wc.env.dwpageset DwPageSet is used to store state information for a group of pages that are used in a single business transaction. For example, the task manager page set caches queue item IDs, work item IDs, the document list model, the object ID of a selected document, and the package ID for that document. com.documentum.wc.env.dwappsession DwAppSession is the web application session object. The application session checks the login requirements. If the user has no active session, the login page specified in the config.xml for the application is presented. To create or acquire a DwAppSession, use the method DwJSPPageContext.acquireSession. com.documentum.wc.env.dwapplication DwApplication is the application object, which is used to create other application-level objects or to get a URL to the root folder of the application. 3. Create the DwJSPPageContext object. For example: DwJSPPageContext wdkpagecontext = new DwJSPPageContext(pageContext.getServletContext(), request, response, true); 4. The try block. Most of the code on each WDK server page is enclosed in a Java try...catch block. 5. Create the application object, page set, and application session. For example: DwApplication app = DwApplication.getApplication(); DwPageSet pageset = wdkpagecontext.getpageset(); DwAppSession appsession = wdkpagecontext.acquiresession(); 6. Java code. 7. The HTML block, including any JavaScript. Most WDK server pages include the following JavaScript files in the HTML block: 2 2 Documentum Web Development Kit Tutorial

19 JavaServer Pages in the WDK HTML Generated by JSP events.js, which contains functions that support cross-frame events and manage the propagation of events. url.js, which contains functions that add, remove, and retrieve URL arguments. history.js, which contains functions that that are used by the event handlers in WDK to call or return to a JSP page. 8. Release the application session: wdkpagecontext.releasesession(); 9. The catch block, which handles exceptions that were thrown in the try block and ensures that the application session is released. HTML Generated by JSP The output of a JSP page (more accurately, the output of the servlet that that is created from the JSP page) consists of HTML and JavaScript that is returned to the web browser. This HTML and JavaScript has two sources: Static HTML and JavaScript, which are hard-coded in the JSP page. Dynamic HTML and JavaScript, which are generated by the Java code in the JSP page and by Java classes that are called by the JSP page. These two sources are not distinguishable in the HTML and JavaScript that is returned to the browser. As far as the web browser is concerned, it is simply static HTML and JavaScript to process and display. This distinction between static and dynamic content supports a convenient separation of roles on your web development team. A page design team can develop the static elements, and a programming team can develop the dynamic elements. Handling Errors Java classes in the WDK throw Java exceptions when critical errors occur, for example, when a Docbase is not available. The code in the JSP page must handle these exceptions, or page execution halts completely. Documentum Web Development Kit Tutorial 2 3

20 JavaServer Pages in the WDK Handling Errors In the JSP pages in WDK, the code in the page is enclosed in a Java try...catch block. For example: try page code catch(exception err) error-handling code At the end of the try block, release any established application session to free session objects that are no longer in use. For example: DwJSPPageContext.releaseSession(); In the catch block, handle any exceptions that were raised in the try block. Minimally, the catch block must: Catch the exception. Release the application session. For example, DwJSPPageContext.releaseSession(); Set attributes on the request object. For example, request.setattribute( ErrorDescription, <error-text> ) Re-throw the caught exception, which triggers the intrinsic JSP/Servlet error handling mechanism. Control is then redirected to the active error page. The WDK error page is error.jsp, which uses the class DwExceptionView to report the error. 2 4 Documentum Web Development Kit Tutorial

21 3 Developing an Application 3 This chapter describes how to create a simple application that uses components of the Web Development Kit. The application will allow you to log in and out of a Docbase, view your Inbox, and browse Docbase contents. The chapter contains the following sections: Prepare Your Environment on page 3-1 Plan the Application on page 3-2 Create the Application Directory on page 3-3 Locate the Tutorial Files on page 3-5 Create a Page on page 3-5 Add the Toolbar on page 3-7 Add Event Handlers on page 3-10 Enable Actions on Docbase Contents on page 3-12 Extra Investigation: Use Cascading Style Sheets to Customize the Look of Your Application on page 3-13 Prepare Your Environment Before you begin the exercises in this chapter, you must install WDK and the sofware on which it depends. You must also ensure that you can load JSP pages successfully. The following procedure describes all of these tasks. To prepare and test your web application environment: 1. Ensure that your HTTP server, Java application server, and Documentum econtent server and Docbases are installed and configured. For more information, see Dependencies on Other Software on page 1-3. Although these software packages are not part of the WDK, the WDK relies on their correct configuration. Documentum Web Development Kit Tutorial 3 1

22 Developing an Application Plan the Application 2. To test your application server, load a JSP page in your browser. Most application servers include sample JSP pages for testing purposes. 3. Install the Web Development Kit and deploy the wdkspace sample application in exploded directory format. In exploded directory format, the.war file is expanded as a collection of files that use a directory structure. The exercises in this manual rely on successful installation and configuration of the WDK. The Documentum Web Development Kit Installation and Release Notes contains critical information for configuring WDK. Follow the instructions closely to deploy the wdkspace sample application and test the installation. Plan the Application In the following sections, you will create a simple application named wdktutorial. This application allows you to log in and browse available Docbases, view your Documentum Inbox, and log out of a Docbase. The user interface includes a Docbase tree frame on the left, a folder browsing frame on the right, and a toolbar frame across the top: 3 2 Documentum Web Development Kit Tutorial

23 Developing an Application Create the Application Directory Create the Application Directory In this section, you will create a new web application root directory named wdktutorial, and then you will copy files from the wdkspace sample application into the new wdktutorial application root directory. Copying files from the wdkspace sample application will ensure that the WDK framework is available to the wdktutorial application. Before you begin, ensure that the wdkspace sample application is deployed in exploded directory format. In exploded directory format, the.war file is expanded as a collection of files that use a directory structure. For instructions on deploying the wdkspace sample application, see the Documentum Web Development Kit Installation and Release Notes. Documentum Web Development Kit Tutorial 3 3

24 Developing an Application Create the Application Directory To create the directory for the wdktutorial application: 1. Create a new, empty web application and corresponding root directory named wdktutorial. How you create a new web application and root directory depends on your application server and operating system. For specific instructions, refer to the documentation for your application server. 2. Copy the contents of the deployed wdkspace sample application directory to your new wdktutorial application directory. (Ensure that you copy from the deployed wdkspace sample application, not the WDK installation location.) Your wdktutorial application directory now has the following structure: \wdktutorial config.dtd config.xml \wdk \wdkspace \WEB-INF 3. Rename the wdkspace directory to wdktutorial. This wdktutorial subdirectory will contain the files that are specific to the wdktutorial application. Your wdktutorial application directory now has the following structure: \wdktutorial config.dtd config.xml \wdk \wdktutorial \WEB-INF 4. Navigate to the css directory below the wdktutorial directory. Rename the two files as follows: Rename wdkspace.css to wdktutorial.css. Rename wdkspacebase.css to wdktutorialbase.css. 5. If necessary, restart your application server to activate the wdktutorial application. 3 4 Documentum Web Development Kit Tutorial

25 Developing an Application Locate the Tutorial Files Locate the Tutorial Files The files that you will use in this tutorial are packaged in the archives WDK_Tutorial_42_Files.zip (for Windows) and WDK_Tutorial_42_Files.tar.gzip (for Unix). These archives reside in the docs directory in your WDK installation directory. Locate the archive for your system and extract its files to the \wdktutorial\wdktutorial directory. (This is the wdktutorial subdirectory, not the wdktutorial main directory.) Create a Page In this section, you will create the first page of the wdktutorial application by adding a title, style sheet references, and a frameset to an existing skeletal WDK server page. If you encounter problems during the procedure, refer to the solution page wdktutorial0_finished.jsp. To create the page: 1. In a plain ASCII editor, open and examine the file wdkskeletonpage.jsp. (In the previous section, you extracted this file from an archive to your \wdktutorial\wdktutorial directory.) The file wdkskeletonpage.jsp contains the basic elements that are common to most WDK server pages. For explanations of these elements, refer to Anatomy of a Typical WDK Server Page on page Save the file as wdktutorial0.jsp. 3. To add the title, find the following line: <title>todo: Add title here</title> Replace TODO: Add title here with WDK 4.2 Tutorial Application (omit the quotes). 4. To specify the style sheets, add the following two lines immediately after the title line that you edited in Step 3: Documentum Web Development Kit Tutorial 3 5

26 Developing an Application Create a Page <link rel='stylesheet' type='text/css' href='/css/wdktutorialbase.css'> <link rel='stylesheet' type='text/css' href='/css/wdktutorial.css'> These are the style sheets that you copied from wdkspace sample application and renamed. They specify styles for both standard HTML elements and for the custom style classes used by the Java classes in WDK. 5. To create the frameset, add the following lines between the </head> and </ html> tags. <frameset rows='30,*,0' border='0' framespacing='0' frameborder='no'> <frame name='header' frameborder='no' marginwidth=0 marginheight=0 noresize scrolling='no'> <frame name='view' frameborder='no' marginwidth=0 marginheight=0 noresize scrolling='auto' src='/wdktutorial/wdk/component/browse/browse.jsp'> <frame name='actions' scrolling='no' frameborder='0'> </frameset> This frameset contains three frames: An empty header frame. In a later section, you will add the toolbar in this frame. A view frame that displays the WDK page browse.jsp. This page contains two frames of its own: a frame on the left that allows you to display multiple Docbase hierarchies as a single tree, and a frame on the right that displays the contents of the cabinets and folders in a Docbase. An actions frame that you will use in a subsequent section. The actions frame is not visible. 6. Save wdktutorial0.jsp and view it in a browser. Typically its URL is localhost/wdktutorial/wdktutorial/wdktutorial0.jsp. The top frame is empty, and the view frame displays a Docbase tree frame on the left and a list of available docbases on the right. Your list of available Docbases will differ from the list in the illustration. Docbase browsing is not fully functional yet. If you click links in the page and log in to a Docbase, you cannot view documents correctly and you cannot log out. 3 6 Documentum Web Development Kit Tutorial

27 Developing an Application Add the Toolbar Add the Toolbar In this section, you will create the page for the toolbar frame. The toolbar buttons will reside in an HTML table. You will then specify this page as the source for the header frame in the page wdktutorial0.jsp, and save it as wdktutorial1.jsp. If you encounter problems during the procedure, refer to the solution pages toolbartutorial_finished.jsp and wdktutorial1_finished.jsp. To create the toolbar page: 1. Open the file wdkskeletonpage.jsp and save it as toolbartutorial.jsp. You will edit this file to create the toolbar page. 2. In the page import section, remove the imports of DwPageSet and DwApplication. Then add the import of DwCustToolbarInputButtonView. Your page import section is now: page import="com.documentum.wc.env.jsp.dwjsppagecontext"%> page import="com.documentum.wc.env.dwappsession"%> page import="com.documentum.wc.widget.dwcusttoolbarinputbuttonview"%> DwCustToolbarInputButtonView is the class from which the toolbar buttons will be created. Documentum Web Development Kit Tutorial 3 7

28 Developing an Application Add the Toolbar 3. To create the view that will generate the toolbar buttons, add the following line just before the try block: DwCustToolbarInputButtonView custtoolbarbuttonview = new DwCustToolbarInputButtonView(); 4. Remove the following lines from the try block. These lines are not required by the toolbar page: DwPageSet pageset = wdkpagecontext.getpageset(); DwApplication app = wdkpagecontext.getapplication(); 5. In the same location as the two lines that you deleted, add the following line because the toolbar page needs to connect to the current application session. DwAppSession appsession = DwAppSession.getAppSession(); 6. In the <head> section, do the following: a. Add a title and links to the style sheets as you did in wdktutorial0.jsp: <title>wdk 4.2 Tutorial Application</title> <link rel='stylesheet' type='text/css' href='./css/wdktutorialbase.css'> <link rel='stylesheet' type='text/css' href='./css/wdktutorial.css'> Note: In this case, include the leading dot (.) in the path names of the style sheets. b. Change the event source name from wdktutorial0 to toolbartutorial. c. Remove the following lines. They will not be used by the toolbar page. <script language="javascript" src="/wdktutorial/wdk/component/history/ history.js"></script> <script language="javascript" src="/wdktutorial/wdktutorial/ eventhandlers.js"></script> 7. After the </head> tag, create the HTML body and the table that will contain the toolbar buttons: <body class="contentbackground" topmargin="0" leftmargin="10" rightmargin="0" bottommargin="0" marginheight="0" marginwidth="0"> <table width="100%" border="0" cellpadding="0" cellspacing="0" height="30"> </table> </body> 8. To create the toolbar buttons, add the following row and cells to the table. <tr> <td align=middle width="20%"> <%=custtoolbarbuttonview.generateeventbutton("docbase","viewdocbase", "", "")%> </td> <td align=middle width="20%"> <%=custtoolbarbuttonview.generateeventbutton("inbox", "viewinbox", "", "")%> 3 8 Documentum Web Development Kit Tutorial

29 Developing an Application Add the Toolbar </tr> </td> <td align=middle width="20%"> <%=custtoolbarbuttonview.generateeventbutton("logout", "logout", "", "")%> </td> Each toolbar button is created with the method DwCustToolbarInputButtonView.generateEventButton, which takes four parameters: the button label, the event name, and two optional parameters to pass to the event. 9. Save toolbartutorial.jsp and view it in a browser. (The URL is localhost/wdktutorial/wdktutorial/toolbartutorial.jsp, replacing localhost with your server name if necessary.) You see the row of toolbar buttons: The buttons are not yet functional. You will activate them in the Add Event Handlers section. To specify the toolbar page in the frameset of the application page: 1. Open the file wdktutorial0.jsp and save it as wdktutorial1.jsp. 2. In the JavaScript section, change the event source name from wdktutorial0 to wdktutorial1. 3. Find the line that begins with <frame name='header' and add a src parameter that specifies toolbartutorial.jsp: <frame name='header' frameborder='no' marginwidth=0 marginheight=0 noresize scrolling='no' src='/wdktutorial/wdktutorial/toolbartutorial.jsp'> 4. Save wdktutorial1.jsp and view it in a browser. You see the toolbar in the header frame: Documentum Web Development Kit Tutorial 3 9

30 Developing an Application Add Event Handlers Add Event Handlers In this section, you will add event handlers to wdktutorial1.jsp and save the page as wdktutorial2.jsp. The new event handlers will handle the events that are fired by the toolbar buttons. If you encounter problems during the procedure, refer to the solution page wdktutorial2_finished.jsp. To add the event handlers: 1. Open the file wdktutorial1.jsp and save it as wdktutorial2.jsp. 2. In the JavaScript section, change the event source name from wdktutorial1 to wdktutorial2. 3. At the end of the JavaScript section, add a new, empty JavaScript element: <script language="javascript"> </script> 4. Within the new JavaScript element, add the event handler for the viewdocbase event. This event is fired by the Docbases button in the toolbar page Documentum Web Development Kit Tutorial

31 Developing an Application Add Event Handlers /** Handle viewdocbase event from Docbase button on toolbar */ function eventhandler_viewdocbase( strsender, strfolderid) var strurl = strcontextpath + "/wdk/component/browse/browse.jsp"; strurl = urladdexclusiveparam(strurl, "folderid", strfolderid); strurl = urlmakeforcedreload(strurl); window.frames.view.location.href = strurl; setcomponentframe(window.frames.view.frames[1]); 5. Within the same JavaScript element, add the event handler for the viewinbox event. This event is fired by the Inbox button in the toolbar page. /** Handle viewinbox event from Inbox button on toolbar */ function eventhandler_viewinbox() var strurl = strcontextpath + "/wdk/component/inbox/inbox.jsp"; strurl = urlmakeforcedreload( strurl ); window.frames.view.location.href = strurl; setcomponentframe(window.frames.view); 6. Within the same JavaScript element, add the event handler for the logout event. This event is fired by the Logout button in the toolbar page. /** Handle logout event from Logout button on toolbar */ function eventhandler_logout() var strurl = strcontextpath + "/wdk/component/logout/logout.jsp"; strurl = urlmakeforcedreload(strurl); window.location.href = strurl; 7. Within the same JavaScript element, add the following function that ensures correct behavior when the browser window is resized in Netscape: /** Handle resize of the browser window */ function handleresize() if ( window.navigator.appname.tolowercase() == "netscape" ) window.location.reload(false); 8. Add the parameters onresize and onload to the frameset element. <frameset rows='30,*,0' border='0' framespacing='0' frameborder='no' onresize='handleresize()' onload="setcomponentframe(window.frames.view.folderdetail)"> Documentum Web Development Kit Tutorial 3 11

32 Developing an Application Enable Actions on Docbase Contents The onresize parameter ensures correct behavior when the browser window is resized in Netscape. The onload parameter ensures that WDK components (the login page, for example) are displayed in the frame on the right in the window. This is the folderdetail frame in browse.jsp, which resides in the view frame of wdktutorial2.jsp. 9. Save wdktutorial2.jsp and view it in a browser. Test your toolbar buttons: a. Click the Inbox button and log in when prompted. You see your Documentum Inbox. b. Click the Docbases button. You return to the Docbase view. (You cannot view Docbase content successfully if you click the links to cabinets, folders, and documents in the Docbase. You will add this functionality in the next section.) c. Click the Logout button and log out of the Docbase as prompted. Enable Actions on Docbase Contents In this section, you will enable actions on Docbase contents so that you can view, edit, and conduct other standard Documentum operations on the documents in a Docbase. You will start with wdktutorial2.jsp, set up an events dictionary, load the WDK action dispatcher page into the invisible frame, and save the page as wdktutorial3.jsp. If you encounter problems during the procedure, refer to the solution page wdktutorial3_finished.jsp. To enable actions on Docbase contents: 1. Open the file wdktutorial2.jsp and save it as wdktutorial3.jsp. 2. In the JavaScript section, change the event source name from wdktutorial2 to wdktutorial3. 3. Add the following classes to the page import section: <%@ page import="com.documentum.wc.env.docbase.dwdocbasetypeddictionary"%> <%@ page import="com.documentum.wc.widget.docbase.dwdocopenlinkevent"%> You will use these classes to create a dictionary of events that are fired by links to cabinets, folders, and documents in the Docbase. These links and events allow you to browse and navigate the Docbase Documentum Web Development Kit Tutorial

33 Developing an Application Extra Investigation: Use Cascading Style Sheets to Customize the Look of Your Application 4. After the line that begins with DwApplication app, create the dictionary: // Set up an events dictionary used for edit/view links DwDocbaseTypedDictionary eventsdictionary = (DwDocbaseTypedDictionary) app.get("dictionary_events"); if (eventsdictionary == null) // Build and populate the events dictionary. eventsdictionary = new DwDocbaseTypedDictionary(); eventsdictionary.put("dm_folder", "viewfolder"); DwDocOpenLinkEvent docopenlinkevent = new DwDocOpenLinkEvent(); eventsdictionary.put("dm_document", docopenlinkevent); app.put("dictionary_events", eventsdictionary); // Set up a readonly version of the events dictionary used for view links DwDocbaseTypedDictionary eventsdictionaryreadonly = (DwDocbaseTypedDictionary) app.get("dictionary_events_readonly"); if (eventsdictionaryreadonly == null) // Build and populate the readonly events dictionary. eventsdictionaryreadonly = new DwDocbaseTypedDictionary(); eventsdictionaryreadonly.put("dm_folder", "viewfolder"); DwDocOpenLinkEvent docopenlinkeventreadonly = new DwDocOpenLinkEvent(); docopenlinkeventreadonly.setreadonly(true); eventsdictionaryreadonly.put("dm_document", docopenlinkeventreadonly); app.put("dictionary_events_readonly", eventsdictionaryreadonly); 5. Find the line that begins with <frame name='actions' and add a src parameter that specifies actiondispatchercontainer.jsp: <frame name='actions' src='/wdktutorial/wdk/action/actiondispatchercontainer.jsp' scrolling='no' frameborder='0'> 6. Save wdktutorial3.jsp and view it in a browser. To test Docbase browsing, click a Docbase name, log in, navigate to a folder, select a document, and choose View from the drop-down menu. Extra Investigation: Use Cascading Style Sheets to Customize the Look of Your Application Cascading Style Sheets allow you to alter the look and feel of your applications significantly without changing any code in the page. This tutorial assumes that you are familiar with Cascading Style Sheets; detailed information is available at In WDK, you can use Cascading Style Sheets to specify style property values for: Standard style classes such as BODY, P, and A:link. Custom style classes that you create for your application. Documentum Web Development Kit Tutorial 3 13

34 Developing an Application Extra Investigation: Use Cascading Style Sheets to Customize the Look of Your Application Style classes that are specific to WDK. Many of the widgets and UI elements in WDK use their own custom style classes. These WDK style classes are described in the Custom Styles section of the WDK Online Help. Your tutorial application (wdktutorial3.jsp) uses the style sheet files that reside in the css subdirectory of the wdktutorial directory. You can experiment by modifying the style property values in these style sheets, and you can add more styles if desired. Additionally, you can use the Branding section in the file config.xml to override WDK styles. For details, search for Branding in the WDK Online Help Documentum Web Development Kit Tutorial

35 4 Customizing WDK Components 4 This chapter describes two common ways to customize WDK components: Editing XML configuration files. Using methods provided by WDK classes. You will modify the document menu by editing XML files, and you will add a column to a table view using a method of the DwTableView class. This chapter contains the following sections: Modify a Menu on page 4-1 Add a Column to a View on page 4-3 Modify a Menu Before you begin When you select a document in the tutorial application, you see a drop-down menu from which you can select actions to conduct on the selected document, such as Checkout, View, and Edit. You can change the items on this menu by making simple edits to the XML files in the WDK configuration folder. In this section, you will remove three items from the menu. An extra investigation section then describes how to add an item to the menu. Open wdktutorial3.jsp (or the solution file wdktutorial3_finished.jsp). Log in to a Docbase, open a folder or cabinet in the Docbase, and select a document. Click the drop-down menu above the list of documents and examine the Documentum Web Development Kit Tutorial 4 1

36 Customizing WDK Components Modify a Menu available choices. Near the bottom of the menu, you see the items Send To, Start Workflow, and Attach Document Lifecycle. In the following procedure, you will remove these three items from the menu. Remove the menu items To remove the three menu items: 1. Open the wdk directory that is a sibling of the wdktutorial directory, and then open the config directory. Make a backup copy of the file document_menus.xml, and save this backup copy in a location outside of the config directory. 2. Return to the config directory and open the file document_menus.xml for editing. 3. Remove the following lines from the file. These are the lines that correspond to the three menu items that you want to remove: <menuitem> <name><nlsid>msg_sendto_menu</nlsid></name> <actionid>sendto</actionid> </menuitem> <menuitem> <name><nlsid>msg_startworkflow_menu</nlsid></name> <actionid>startworkflow</actionid> </menuitem> <menuitem> <name><nlsid>msg_attach_policy_menu</nlsid></name> <actionid>attachpolicy</actionid> <disableifmultipleselections/> </menuitem> 4. Save document_menus.xml. 5. Restart your application server to activate the changes to the XML file. Once again, open wdktutorial3.jsp (or the solution file wdktutorial3_finished.jsp). Log in to a Docbase, open a folder or cabinet in the Docbase, and select a document. Click the drop-down menu above the list of documents and examine the available choices. You no longer see the items Send To, Start Workflow, and Attach Document Lifecycle. 4 2 Documentum Web Development Kit Tutorial

37 Customizing WDK Components Add a Column to a View Extra investigation: Add a menu item In the config folder, the files document_actions.xml and document_menus.xml work together to configure the available menu items and the corresponding actions that they perform when a document is selected: document_actions.xml specifies the possible actions to perform on a document. document_menus.xml specifies the menu items that are available when a document is selected, and the corresponding action to perform. The actionid values in document_menus.xml correspond to the id values in document_actions.xml. To add a new action and a corresponding new menu item, specify the new action in document_actions.xml, and then specify the new menu item in document_actions.xml. For detailed information on actions and menus, see the WDK Online Help. Add a Column to a View Before you begin To display a list of documents in a cabinet or folder, the server pages in WDK use the class DwTableView. DwTableView provides methods that allow you to specify the columns that are displayed in the table. In this section, you will use a method of DwTableView to add a column that displays the object type. Open wdktutorial3.jsp (or the solution file wdktutorial3_finished.jsp). Log in to a Docbase and open a folder or cabinet in the Docbase. In the table of documents, you see the columns Name, Last Modified, and Lock Owner. In the following procedure, you will add a column named Type that displays the object type. Important! For simplicity and clarity, the following exercise asks you to edit the WDK server page foldercontents.jsp. This is contrary to the recommended best practices to follow when you develop your own WDK- Documentum Web Development Kit Tutorial 4 3

38 Customizing WDK Components Add a Column to a View powered web applications. When you develop your own applications, put custom functionality solely in custom server pages. Edit the WDK server pages solely to call your custom pages. If you edit the WDK server pages directly, the resulting pages can be difficult to migrate to future versions of WDK. Add the column to the view If you encounter problems during this procedure, refer to the solution page foldercontents.jsp. To add the Type column to the view: 1. Open the wdk directory below the main wdktutorial directory, open the component subdirectory, and then open the contents subdirectory. Make a backup copy of the file foldercontents.jsp. 2. Open foldercontents.jsp for editing. 3. Locate the following line: <jsp:usebean id="foldercontentsview" class="com.documentum.wc.widget.dwtableview" scope="session" /> This line creates foldercontentsview, which is a table view bean based on the class DwTableView. The next three lines set the model to use with the view (the model was created earlier on the page), specify how to align the rows, and whether to display row dividers. The subsequent set of statements specifies the columns in foldercontentsview. In the next step, you will add a line that specifies the new Type column. 4. Between the lines for Name and Modification Date, insert the following line: foldercontentsview.addformattedcolumn("type", "Type", strobjtype, "15%"); 5. In the line that specifies the Name column, change 55% to 40%. 6. Add a line that obtains values for strobjtype: a. Scroll up to the section with the comment Define useful format strings. b. Add the following line: String strobjtype = "r_object_type"; 4 4 Documentum Web Development Kit Tutorial