Novell Home

eGuide Customization

Novell Cool Solutions: Feature
By John Peacock

Digg This - Slashdot This

Posted: 17 May 2006
 

Introduction

One of the most powerful aspects of eGuide is that almost the entire user interface is under your control, by patching the various templates that generate the pages on the fly. This article discusses how to go about changing the way that your fields are displayed and edited.

Before you start, it is a good idea to back up all files before making any changes. You should have a basic understanding of how XML files are structured (which is very similar to HTML, in fact). You will be stopping and starting Tomcat at several points during this process, so alert anyone who is using a Tomcat-enabled application (such as eGuide or iManager) that there may be brief downtimes (usually no more than 5 minutes). If you have a test tree to play with, that would be best.

The first thing to understand is how the files are stored on disk and how they relate to what you actually see on the screen. We won't discuss every file (since they are all similar in operation), but focus on those files needed to make the example below functional. All of the files that we will be editing will be under the following directory:

tomcat\4\webapps\eGuide\WEB-INF

The actual location will vary depending on the operating system involved. In the case of Netware 6.5, that path will typically be located on the SYS:\ volume. I will use the string "...\" to refer to the above path; if you are running eGuide under Linux, obviously the base location will be different and the directory seperator will be the forward slash "/" instead. Similarly, all instructions for stopping and starting Tomcat will be based on running under Netware.

Examples

The following customization examples will be explained:

  1. Adding a Magnifying Glass to the Location Field
  2. Creating a Dropdown List for Locations

Example 1: Adding a Magnifying Glass to the Location Field

Here we will change the Location so that when a user is displayed, there will be a small magnifying glass next to the Location field, so you can quickly do a search for all other users with that matching value. (You may already see this if you populate the DEPARTMENT field). You will need to have at least some of your user objects have a value (or better yet, several different values) in the Location field (you can use ConsoleOne or iManager).

The first file to examine is:

...\plugins\eGuide\uihandlers.xml

which contains all of the actions for the default eGuide fields. It is useful to read through this entire file, to see how some of the composite fields (such as CombinedAddress). For the moment, however, use your editor to locate the following block:

 <!-- ATTRIBUTE : SV FindAttributes -->
 <ui-attribute-handler>
  <id>SVFindAttributes</id>
  <attribute-name>DEPARTMENT</attribute-name>
  <attribute-name>COSTCENTER</attribute-name>

  <class-name>com.novell.eguide.handler.DefaultDataHandler</class-name>

  <client>browser</client>
  <client>pocket</client>

  <default/>

  <multi-valued-enabled/>
  <single-valued-enabled/>
  <read-write-enabled/>
  <read-only-enabled/>

  <display-name-key>SV "Find Others" Search Link</display-name-key>
  <resource-properties-file>eguideresources</resource-properties-file>
  <description
    >Creates a link to a search other objects for the same attribute value. 
	The results will display in the list or navigation form. 
  When in edit mode, will dislpay a single-value textbox.</description>
 </ui-attribute-handler>

In order to make the Location attribute quick-searchable, just add a line like this:

<attribute-name>LOCATION</attribute-name>

with the lines for DEPARTMENT and COSTCENTER. Then stop and start Tomcat:

  tc4stop
  tomcat4

and browse to eGuide. You should now see the quick-search icon (small magnifying glass) next to the attribute value. Confirm that it brings up all other users. If you log in with an eGuide administer account, on the Attributes page under LDAP Data Sources, browse to the LOCATION line and click on the "More Options" link. You'll now see that instead of being defined as an 'Expanding Textbox' it will now be listed as 'SV "Find Others" Search Link' instead.

Example 2: Creating a Dropdown List for Locations

Next we'll change the Location attribute from being a freeform text field to a dropdown list of legal values. This makes it much easier to allow non-admin users to be able to update these attributes in a consistent fashion.

There are two files that have to be edited to make the Location attribute a multi-value dropdown box:

	...\plugins\eGuide\customhandlers.xml
	...\templates\xsl\default\browser\UIHandlers.xsl

The .xml file is used to enable a particular behavior for an attribute, and the .xsl file is used to implement that behavior. You can think of the code in the .xsl file as being little snippets that are added to the displayed page on the fly, based on their activation in the .xml files.

The first step is to create a new "attribute-handler" block for the Location attribute, which will give us an additional choice on the "More Options" form. Add a block like this to the customhandler.xml file:

 <!-- ATTRIBUTE : SV Location -->
 <ui-attribute-handler>
  <id>SVLocation</id>
  <attribute-name>LOCATION</attribute-name>

  <class-name>com.novell.eguide.handler.DefaultDataHandler</class-name>

  <client>browser</client>
  <client>pocket</client>

  <default/>

  <single-valued-enabled/>
  <read-write-enabled/>
  <read-only-enabled/>

  <display-name-key>SV "Location"</display-name-key>
  <resource-properties-file>eguideresources</resource-properties-file>
  <description>Display a drop-down list to edit 
  the internal Location names</description>
 </ui-attribute-handler>

Important: This block must be contained within the <plugins> </plugins> context to be well-formed XML. You can add your block directly after one of the commented out handlers that you will find in the customhandlers.xml file.

The next thing to do is to edit the template itself:

	...\templates\xsl\default\browser\UIHandlers.xsl

This file contains a number of blocks of the form:

   <xsl:when test="@uihandler='XXXXXXXXXXX'">
	<!-- a bunch of mostly normal HTML code here -->
   </xsl:when>

You can think of this file as a giant switch statement; when the web page is being rendered, each attribute (in the order you specified) is shown, and the block of code corresponding to the uihandler for that attribute is plugged into the web page at that point.

Find an open place in UIHandlers.xsl, such as directly after one of the existing blocks, and add the following code. Watch wrapping: each tag should be on a separate line.

   <xsl:when test="@uihandler='SVLocation'">
    <tr>
     <xsl:call-template name="LabelTD"/>
     <xsl:choose>
      <xsl:when test="edit='true'">
       <td class="ValueText">
        <input type="hidden" name="{name}" id="{name}">
         <xsl:attribute name="value">
          <![CDATA[<undefined><nochange></nochange></undefined>]]></xsl:attribute>
        </input>
        <select size="1" class="inputTextBox" name="_SV_CTRL_{name}" 
	value="{value}" onchange="updateSvXml('document.forms[0]._SV_CTRL_{name}')">
         <option value=""><xsl:if test="value = ''">
	 <xsl:attribute name="selected">true</xsl:attribute></xsl:if>(None)</option>
         <option value="Austin"><xsl:if test="value = 'Austin'">
          <xsl:attribute name="selected">true
		  </xsl:attribute></xsl:if>Austin</option>
         <option value="Provo"><xsl:if test="value = 'Provo'">
          <xsl:attribute name="selected">true
          </xsl:attribute></xsl:if>Provo</option>
         <option value="New York"><xsl:if test="value = 'New York'">
          <xsl:attribute name="selected">true
          </xsl:attribute></xsl:if>New York</option>
         <option value="Denver"><xsl:if test="value = 'Denver'">
          <xsl:attribute name="selected">true
          </xsl:attribute></xsl:if>Denver</option>
        </select>
       </td>
      </xsl:when>
      <xsl:otherwise>
       <!-- SHOW MODE -->
       <xsl:call-template name="SV_FindAttributeShowTD"/>
      </xsl:otherwise>
     </xsl:choose>
    </tr>
   </xsl:when>

Now I'll explain that a bit, so you can customize it to fit your application. The code we added to customhandlers.xml creates a new attribute type:

	<id>SVLocation</id>

which is what we reference at the top of this block:

   <xsl:when test="@uihandler='SVLocation'">

to enable this code. The next bit of important code is this:

     <xsl:choose>
      <xsl:when test="edit='true'">

It determines which block of the subsequent code appears, depending on whether the user has attempted to edit this record. By doing it this way, when a user is not logged in or has no rights to edit a record, this entire block of code is not included in the generated HTML page. Before we examine the contents of this block, let's skip to the end:

      <xsl:otherwise>
       <!-- SHOW MODE -->
       <xsl:call-template name="SV_FindAttributeShowTD"/>
      </xsl:otherwise>

You can probably guess that this means if the record is not being edited, then it calls another bit of XSL code "SV_FindAttributeShowTD", which is the code that displays the quick search (magnifying glass) icon.

Finally, let's look at the heart of this handler:

        <select size="1" class="inputTextBox" name="_SV_CTRL_{name}" 
value="{value}" onchange="updateSvXml('document.forms[0]._SV_CTRL_{name}')">
         <option value=""><xsl:if test="value = ''">
 <xsl:attribute name="selected">true</xsl:attribute></xsl:if>(None)</option>
         <option value="Austin"><xsl:if test="value = 'Austin'">
          <xsl:attribute name="selected">true
          </xsl:attribute></xsl:if>Austin</option>
         <option value="Provo"><xsl:if test="value = 'Provo'">
          <xsl:attribute name="selected">true
          </xsl:attribute></xsl:if>Provo</option>
         <option value="New York"><xsl:if test="value = 'New York'">
          <xsl:attribute name="selected">true
          </xsl:attribute></xsl:if>New York</option>
         <option value="Denver"><xsl:if test="value = 'Denver'">
          <xsl:attribute name="selected">true
          </xsl:attribute></xsl:if>Denver</option>
        </select>

This should be vaguely recognizable to anyone with HTML experience; it creates a <select> context (multi-value dropdown list). For each option value, the code checks to see if this is the existing value:

	...<xsl:if test="value = 'Austin'">...

If it is the existing value, then it is made the selected (display) value. There are other things going on here (stylesheet info, Javascript events, etc), but this is the heart of the matter. Just copy the sample code listed above and replace the values with the list of legal Locations for your organization. You must include the first line with the value="" so you can handle the case where the user object has no existing value.

Hopefully, this has given you enough to get started customizing your eGuide experience.


Novell Cool Solutions (corporate web communities) are produced by WebWise Solutions. www.webwiseone.com

© 2014 Novell