Customize the eClient, Part 3: Customize the Content Manager eClient Edit Attributes window

This article provides a demonstration of some of the customization possible with sample codes, giving you a better understanding of what and how you can customize eClient for your business needs.

Guang Xu (xuguang@cn.ibm.com), Software Engineer, IBM Content Manager Development, IBM

Author Photo: Xu GuangXu Guang works as a Content Manager eClient developer in IBM China Software Development Lab (CSDL).



Wei-Dong Zhu, Project Leader, IBM

Wei-Dong (Jackie) Zhu is a Project Leader in Content Management for the International Technical Support Organization at the Almaden Research Center in San Jose, Calif. She has more than 10 years of software development experience in document search systems, image workflow processing, and digital media distribution. She holds a Master of Science degree in Computer Science from the University of Southern California.



Mike Grasselt (grasselt@de.ibm.com), Technical Lead, IBM

Mike Grasselt is a senior software engineer who has worked for IBM since 1997. Currently, he leads an Information Platform and Solutions development team focusing on solutions integrating Master Data Management and SAP. In earlier roles, he integrated text analysis technology with content management and was an author of the IBM Redbooks publication "eClient 101 Customization and Integration." He has presented university lectures on software development for IBM mainframe servers. He developed an SQL extension for the Business Processes Execution Language (BPEL) and published several papers on data-aware business processes and web services. He was responsible for the service-oriented architecture (SOA) alignment of InfoSphere Information Server to allow integration with WebSphere Portal, WebSphere Process Server, and InfoSphere Master Data Management Server. In addition to his technical responsibilities, he is a mentor in the IBM technical community.



Alan Mayer, I/T Architect, IBM

Alan Mayer is an I/T Architect in IBM Global Services in U.S. He has 10 years of experience implementing Content Manager for various clients. His areas of expertise include application development and document imaging.



Lijing Zhang, Software Engineer, IBM

Lijing Zhang is a software engineer for IBM. He has worked for IBM since 2001 in the Content Management field. His areas of expertise include Content Manager, Information Integrator for Content, and VideoCharger. He is a co-author of the "Content Manager V8 Certification Study Guide."



05 June 2008

The material in this article was originally published as part of an IBM Redbooks® publication, eClient 101 Customization and Integration. It has been updated to include details for eClient, Version 8, Release 3, Fixpack 8.

Customize the look and feel using style sheets

Cascading style sheets (CSSs) are one of the ways you can change the look and feel of eClient.

What are CSSs?

CSSs are an industry-standard method of changing the appearance of elements of HTML pages, such as labels, text, entry fields, links, and buttons. A CSS allows you to specify the margins and the background images such as a company logo for a document. HTML specifies the content and structure of the document, including fields, captions, links, and tables. The style sheet defines the appearance in terms of fonts, point size, colors, highlighting, and background images.

A style sheet is a text file (eClient uses eclient81.css) containing a list of tags and a set of display properties for each tag. Style sheet definitions can be embedded in HTML, but a more common use of style sheets is to define them in an external style sheet file with a .css extension. A link statement is used in the HTML to tell the browser the name of the CSS file. When the browser processes the HTML and finds the link tag for a style sheet, it reads the style sheet file and applies the formatting rules to the HTML document.

In the HTML document, the style sheet formatting options are specified for an element of an HTML document (such as label, field, or table) by using the CLASS parameter. The HTML author can identify the CLASS that is required for different formatting style and place the formatting rule for each CLASS in the CSS file.

The following section describes how the eClient JavaServer Pages (JSPs) files use the style sheets and give some examples of how to modify the appearance of the eClient.

Use CSS for eClient

In the eClient, HTML is generated when the JSPs execute on the server. Each JSP in the eClient has a section in it that creates HTML to send to the Web browser. In the HTML portion of each eClient JSP, a line similar to line 3 in Listing 1 specifies the name of the style sheet to use:

Listing 1. Sample code specifying the name of the style sheet
<head>
<title><%=cub.getIdmResourcesString("LogonJSP_Title")%><\/title>
<link rel="STYLESHEET" type="text\/css" href="<%amp;= webAppName%amp;>\/eclient81.css">

The above sample code is taken from IDMLogon2.jsp.

All of the eClient JSPs use the eclient81.css file, which is normally located in the C:\Program Files\IBM\db2cmv8\CMeClient\installedApps\eClient.ear\eclient.war directory.

Most of the tags in eclient81.css are used for various types of standard HTML elements. There are a few interesting examples that are a little different:

  • The BODY tag

    There is no period at the beginning of this tag. The BODY tag is used as the default if there is no specific class specified for the body of an HTML document. That is, if the JSP uses <body> instead of <body class="MY_BODY_TAG">. Here you can specify defaults, such as background color.

  • The .BODY tags (.BODYLOGON, .BODYHOME, .BODYMINI)

    These tags are used in specific JSPs that need different BODY styles. These different tags are used primarily to specify a different background image for different type of windows, such as log-on and search windows.

  • The .ODD and .EVEN tags

    An interesting example of style sheet usage is how the eClient gets the alternating lines in the search results to have a blue or white background.

The HTML for the search results uses the following code to specify a CLASS of ODD or EVEN to the odd and even lines in the search results. The variable is the row number that is used to determine odd or even number of the row. The row type is even if "i" is divisible by 2; otherwise, the row type is odd. The tag for the class="<tag>" line is then set to odd or even depending on the row type.

<%rowType=(i%2==0) ? "EVEN":"ODD"; i++; %>
<TR class="<%= rowType %>">
<TD nowrap class="<%= rowType %>">
...

The browser sets the colors according to the .EVEN or .ODD tags in the eclient81.css file. The above sample code is taken from the IDMItemTypeList.jsp file.


Customize the Edit Attributes window

The Edit Attributes window allows a user to view and modify the metadata associated with a document. This section shows you how to customize the Edit Attributes window (IDMEditAttributes.jsp) of eClient through sample codes.

The following customization to the Edit Attributes window is described:

  • Implementing a combo box for specific attributes
  • Making selected attributes read-only or hidden
  • Modifying the order of the attributes in the window
  • Modifying the display name of the item type and attributes
  • Re-loading the window when a combo box value is selected

Overview

The edit attributes window can be invoked from either a search results window or from a document viewer. When invoked, it displays a window, such as the one in Figure 1, with the item type and attributes for a document.

Figure 1. Standard Edit Attributes window for Content Manager sample data
Standard Edit Attributes window for Content Manager sample data

The Edit Attributes window allows a user to change the item type and the attribute values for a document. Note the following:

  • The native attribute names and values for the back-end datastore are displayed. If you use a federated log-on and specify different attribute display names in the IBM® DB2® Information Integrator for Content entities and search templates, they will not be displayed in this window because eClient gets the attribute names and values directly from the back-end connector.
  • The edit attributes window does not support index class subsets. Access to specific fields cannot be restricted as they can in the Content Manager thick client.
  • The attributes are displayed in the order they are defined in the back-end system.

You may want to modify this window to use combo boxes, add field-level security, re-order the fields, and hide some fields. In the following sections, through sample codes, you can see how to make these types of changes to the Edit Attributes window by customizing IDMEditAttributes.jsp. Figure 2 is an example of what the same data looks like when using a customized version of IDMEditAttributes.jsp described in this article.

Figure 2. Sample customized Edit Attributes window
Sample customized edit attributes window

Figure 2 displays the same documents as Figure 1. If you compare the two figures, you see the following differences in the Figure 2:

  • The Item type is now replaced with a shorter display name. Everything in parentheses is removed.
  • You cannot see it in Figure 2, but all of the other Item type values in the combo box are modified to remove the information in parentheses.
  • The attribute names are now replaced with shorter display names that do not include the information in the parentheses.
  • The policy number field is now read-only.
  • The license plate number field is now converted into a combo box.
  • The adjuster and claimant's first and last names are re-ordered so the last name comes first in the list.
  • The adjustment date field are removed from the display.
  • The adjuster's first and last names are turned into combo boxes. In addition, when the last name is changed, the list of first names is updated.

The sample code found in the Download section of this article includes customization designed to work with the sample data that can be created using the Content Manager First Steps application. The Content Manager sample data includes item types and sample documents for the fictitious XYZ Insurance company, which maintains policy and claim documents in Content Manager.

Using the Content Manager sample data makes it easier to configure your system to use the sample code, because you do not have to create your own sample data. Some of the sample data item types and attributes for the examples may not always be logical. For example, the use of combo boxes are demonstrated for the insurance adjuster's last name and first name attributes, which do not represent a real-world scenario. However, it gets across the point of how to make this type of modification while making it easy on you to get up and running with the example.

Configure and use customization

There are several components of this customization example. The source files can be downloaded from the Web. The following files are required for this example:

  • IDMEditAttributes.jsp: The customization uses the user exit feature to keep much of the customer-specific code in Java files instead of in the JSP. By moving as much custom code as possible out of the JSP file, it is easier to apply your customization to future versions of the eClient.

  • XYZEditAttrMethods.java and XYZEditAttrData.java: A majority of the customization is in these Java files. Again,you want to keep the JSP changes as little and as simple as possible. The following methods are implemented in XYZEditAttrMethods.java:

    • getDisplayName: Displays the name for each item type.
    • updateAttributeList: For each field being displayed, sets various attributes, such as read-only, combo box, or hidden. More details later are provided on this later.

The following example uses Content Manager, Version 8, Release 3, Fix pack 8. To use the customization on your system, you need to:

  1. Meet the prerequisites:
    • Install Content Manager, V8.3.
    • Install II4C and eClient, V8.3 with the latest Fix pack.
  2. Import the source code and properties files into your environment. Using Rational Application Developer, complete the following steps:
    1. Start IBM Rational Software Development Platform.
    2. Open the IDMEditAttributes.jsp with the Rational Application Developer editor and replace the contents by cutting and pasting the contents of the IDMEditAttributes.jsp file found in the Download section of this article.
    3. Press Ctrl+S in the Rational Application Developer editor to save the file.
    4. Select File > Import from the main menu.
    5. Select File System from the list, and click Next. Figure 3 appears.
      Figure 3. Importing Java files into the eClient project
      Importing Java files into the eClient project
    6. Navigate to the directory containing the com directory with the source files. The com directory should have a subdirectory named XYZUtils, which should contain the Java files.
    7. Browse to, or enter, eclient\JavaSource in the destination field.
    8. Click Finish. The files are displayed in Rational Application Developer, as shown in Figure 4.
      Figure 4. Custom Java files in Rational Application Developer Navigator view after import
      Custom Java files in Rational Application Developer Navigator view after import
  3. Test the changes:
    1. Start eClient and log on directly to the Content Manager, Version 8 server. Do not use a federated connector.
    2. Select Search.
    3. Select the Adjuster Report search template. If you do not see this search template, then the Content Manager, Version 8 sample data is not installed correctly.
    4. Enter * in the claim number field, and click Search. You should get three hits in the search results window.
    5. Mark the check box for the first document. In this scenario, the claim number is 6-987654.
    6. Select Edit Item Attributes from the combo box in the search results.
    7. It should display the Edit Attributes window you see in Figure 2.

Edit Attributes window customization overview

The following sections describe how the standard out-of-the-box IDMEditAttributes.jsp file works. Specifically, they cover how it is invoked, how it interacts with the IDMChangeAttributes servlet, and how the Java, HTML, and JavaScript processing in the JSP work.

In addition, it also describes how the changes for the article sample are implemented. There were 13 snippets of code that are added to the JSP, along with several methods in a new Java file called XYZEditAttrMethods.java. All of the changes are covered in detail and describe how they can be used together or independently.

1. Understand IDMEditAttributes.jsp

This section covers how the standard IDMEditAttributes.jsp works.

Invoke the IDMChangeAttributes servlet

The Edit Attributes window can be invoked in two ways by an eClient user:

  • Invoke the Edit Attributes window from the search results window.

    You can mark the check box next to a document in the search results window and select the Edit Attributes option from the combo box in the search results window.

    This invokes the IDMChangeAttributes servlet from the openUpdate() JavaScript function in PageComponents\heading.jsp.

  • Invoke the edit attributes window from the standard or the applet viewer.

    The edit attributes window can also be invoked by choosing the edit attributes icon on the toolbar of either viewer.

To invoke the Edit Attributes window, the eClient invokes the IDMChangeAttributes servlet with the following parameters:

  • srKey=<SRKey>
  • action=display
  • itemid=<pid string>

The following code snippet from heading.jsp shows how the eClient invokes the IDMChangeAttributes servlet:

var itemId = selectedItems[0];
var url = '<%= webAppName %> /IDMChangeAttributes?srKey=<%= 
URLUTF8Encoder.encode(srKey) %>itemid='+itemId + 'action=display';
wn=generateWindowname();
setWindowname(wn);
window.open( url, wn, 'resizable=1,scrollbars=1,height=500,width=550');

The srKey is the search results key. It is a string containing the timestamp of the folder that was created for the search results. The JSP and servlet can use it to find out what is in the search results window. action=display informs the servlet and JSP that the user is requesting to view the attributes window. The itemid is the PID string of the selected document.

What the servlet does

The servlet queries the attributes for the document, the minimum and maximum size of each attribute, whether each attribute is required, the item type for the document, the list of all entities the user has access to, and other information. (Note that entity and item type are interchangeable. The code often uses entity when referring to the item type of the document.) It then invokes the JSP, which pulls the various data elements from the request. For example, the following lines are used to get the CMBItem object for the document, the entity (item type) for the document, and the ArrayList containing a list of all entities the user has access to:

<jsp:useBean id="item" scope="request" class="com.ibm.mm.beans.CMBItem"/>
<jsp:useBean id="entity" scope="request" class="java.lang.String"/>
<jsp:useBean id="entities" scope="request" class="java.util.ArrayList"/>

The JSP then goes on to build the HTML for the display of the attributes. This includes the HTML for the display as well as the JavaScript functions that are sent to the browser in the HTML.

Change the item type name

If you modify the item type from the Edit Attributes window's item type list combo box, the JavaScript function reindex is called. This builds a URL to the IDMChangeAttributes servlet with an additional parameter of ?entity="<new entity name>. Control is passed to the servlet, which gets the attribute information for the new entity and calls the JSP again with action=display.

Save the changes

If you make changes and click Save changes, the JavaScript validate() function is called to validate user changes. If the validation succeeds, the form is submitted to the IDMChangeAttributes servlet, which then updates the back-end repository.

2. Modify IDMEditAttributes.jsp

At a high level, the JSP file is modified in general to support different functional enhancements. The customer-specific logic is all contained in the XYZEditAttrMethods.java class. The JSP file calls two methods in the class to determine how the display should be modified.

The two methods that a JSP file calls are as follows:

  • getItemTypeDisplayName(): It passes an item type and returns a display name for each item type. In the example code, this method strips the first left parenthesis and anything after it. For this example, it changes "Adjuster Report (Content Manager V8.3 Sample Item Type)" to "Adjuster Report." For your business application, you can modify the method to do other customization.
  • updateAttributeList(): It controls the display of the attributes. When IDMEditAttributes.jsp builds a list of attributes to display, it first builds an ArrayList of XYZEditAttrData structures for each field. See Listing 2 for the XYZEditAttrData class.
Listing 2. XYZEditAttrData class
public class XYZEditAttrData
{
  public String   strAttrNameNative;    // Native attribute name
  public String   strAttrNameDisplay;   // Attribute display name
  public String   strAttrValue;         // Attribute value - Don't change!
  public int      intFieldDataType;     // Field data type
  // DK_CM_DECIMAL, DK_CM_DATE, etc.
  // Hidden/read only fields    
  public int      intHideField;         // Do not display the field
  public int      intReadOnly;          // Set to 1 to make field read-only
  // Combo box related fields    
  public int      intComboBox;          // Display combo box for this field?
  public String[] astrComboBoxValues;   // Values for combo box
  // Set to 1 to reload edit attr window when value selected
  public int      intReloadWhenComboValueChanges;  
}

The JSP builds an ArrayList with one of the structures in Listing 2 for each field to be displayed. It sets the first four fields in the structure before calling the updateAttributeList() method in XYZEditAttrMethods.java. If this method does nothing, then the Edit Attributes window appears just as it does out of the box. Otherwise, this method can update the ArrayList to make one of many types of changes including the following:

  • To hide a field:

    Set intHideField = 1

    In this example, the sample code hides the Adjustment Date field.

  • To set a field read-only:

    Set intReadOnly = 1

    In this example, the sample code sets the Policy Number field to read-only.

  • To make a field a combo box:

    Set intComboBox = 1

    In this example, the sample code sets astrComboBoxValues to a list of values for a combo box.

The sample code makes VIN, License Number, Adjuster First Name, and Adjuster Last name all combo box fields and provides a list of values for each combo box. The values for the combo boxes are hardcoded in this example. However, this can be replaced with a database lookup in your business application. For example, the Adjuster First Name and Adjuster Last Name can come from an employee database. Also, the VIN number combo box can be loaded from a database that keeps track of VIN numbers of insured under the policy number and the VIN numbers related to claim numbers.

  • To re-invoke the JSP file if the combo box value changes:

    Set intReloadWhenComboValueChanges = 1

The sample code uses this for Adjuster Last Name. When the user selects a different Adjuster Last Name from the combo box, it calls the servlet and JSP again so that a corresponding list of the Adjuster First Name values in relation to the selected Adjuster Last Name can be placed in the Adjuster First Name combo box. Again, for our example, these values are hardcoded. You can customize it by looking up values from a corresponding database.

  • To re-order the fields:

    Reorder the elements in the ArrayList

    In this example, the sample code swaps the order of the adjuster and claimant's first and last names.

After returning from updateAttributeList(), the JSP code uses the ArrayList to control how each attribute is displayed. The entire source code is not included here, since it is too large to embed in the article.

To find the changes in the JSP file, search for XYZ_CHG_BEGIN in IDMEditAttributes.jsp. Each snippet of the source code is easy to find using this way and the source code is fully documented.

3. IDMEditAttributes.jsp code change details

There are so many code changes that they cannot all be included in this article. This section describes each major piece of code. While reading this section, you should open the following source files in an editor:

  • XYZEditAttrData.java
  • XYZEditAttrMethods.java
  • IDMEditAttributes.jsp

As described in the previous section, XYZEditAttrData.java contains the data structure that is used to control how each field is displayed. IDMEditAttributes.jsp creates an ArrayList of these structures containing the field information retrieved from the back-end system. The ArrayList is then passed to the updateAttributeList() method in XYZEditAttrMethods.java, where it can be modified to specify how each field should be displayed. For example, it can specify whether the field should be hidden, marked as read-only, or should be a combo box.

Each code change in the JSP file is documented with a comment containing the text XYZ_CHG_BEGIN CHGxx at the beginning and XYZ_CHG_END CHGxx at the end, where xx is the change number. You can search for these strings to see the changes, or use a graphical file comparison utility. There are 13 places where the source code is changed. Some are small changes and others add up to 100 lines of new code. Table 1 describes the changes.

Table 1. List of changes made to IDMEditAttribute.jsp
Change NumberDescription
CHG01Additional import statements for new Java classes.
CHG02Initialization and debug options.
CHG03JavaScript validate() function: Gets selected values from the combo box field and places them in the right fields before passing control to IDMChangeAttributes servlet.
CHG04JavaScript reindex() function: This function is called when the user changes the item type. Added subaction=reindex to the URL so that when the JSP is called again, you can tell if it changes the item type.
CHG05New JavaScript function reload_when_combo_box_changes(): This new function is called when the user modifies a combo box with the intReloadWhencomboValueChanges flag set in XYZEditAttrData structure. It is similar to reindex and causes the servlet and JSP to be invoked again so that combo box values can be refreshed.
CHG06New Java code to process new parameters from the URLs created in CHG04 and CHG05.
CHG07Calls getItemTypeDisplayName and changes the name of the item type displayed in the combo box. In the sample, it removes everything after the parenthesis in the item type names.
CHG08Creates the ArrayList of XYZEditAttrData structures and pass to the updateAttributeList() method, which can then control how each field is displayed.
CHG09Adds a new loop for processing the array of attributes.
CHG10Ensures that the inner loop only processes the current field from the new loop coded in CHG09.
CHG11Adds debug messages to stdout.
CHG12Prevents the code from creating the labels for hidden fields.
CHG13Creates each field as specified by the call to updateAttributeList in CHG08.
CHG14Adds closing bracket for the new loop level created in CHG09.

The most interesting changes are CHG05, CHG08, and CHG13.

  • CHG05 is important because it allows the form to be reloaded with different combo box values when a specific combo box value is modified.
  • CHG08 is where the modification to the user interface is specified through the call to updateAttributeList. This is where the source code specifies that particular fields are read-only, hidden, or combo boxes.
  • CHG13 contains the source code that creates the fields of the right type: hidden, read-only, or a combo box.

Conclusion

This article showed you how to customize eClient with sample code. It demonstrated in detail how to customize the look and feel using CSSs, how to customize the Edit Attributes window, and display the explanation on the sample code. The next article in the series will show you other kinds of customization with sample code, which includes adding custom functions to the search results window.


Download

DescriptionNameSize
Sample JSP and Java codejsp_java_code.zip22KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=319086
ArticleTitle=Customize the eClient, Part 3: Customize the Content Manager eClient Edit Attributes window
publish-date=06052008