Creating a New UI Handler

There are two basic steps to creating your own UI Handler:

Step 1. Register the UI Handler Information Using an XML File in the \plugins\eGuide Directory

When the eGuide server is started, it searches the \plugins\eGuide directory for XML files. The files located in this directory define what UIHandlers are available in the eGuide Administration Utility. Therefore, you can create or modify existing UI Handlers by adding or editing the files in this directory. Note that the file can have any name but must have the .XML extention.

Basically, you need to define the UI Handler, an ID, name, and description. You also need to specify the association to the Temple Key or attribute syntax. This is done using the attribute-name or syntax-name tags.

You can also specify which clients can use this handler. By using the eGuide Administration Utility you can easily tell if the handler is capable of running various devices. You can also specify multi-valued-enabled, single-valued-enabled, read-write-enabled, and read-only-enabled if desired.

You will also need to define the class-name for the Data Handler. Data Handlers give you the capability of changing the way the information is retrieved and stored using Java classes. You could, for example, query a completely separate database to retrieve some information. However, most of the time you will be specifying the Default Data Handler as shown in the example below.

Use the following handler definition as an sample data to create the User Type handler. Note that these examples can be found in the Customuihandler.XML document located in the \eGuide\WEB-INF\plugins\eGuide folder. You need only to un-comment the lines and restart eGuide to make them work:

<!-- ATTRIBUTE : User Type Selector --> 
<ui-attribute-handler> 
   <id>SVUserType</id> 
   <attribute-name>USERTYPE</attribute-name> 
   <class-name>com.novell.eguide.handler.LabeledURIDataHandler</class-name> 
 
   <client>browser</client> 
   <client>pocket</client> 
 
   <multi-valued-enabled/> 
   <single-valued-enabled/> 
   <read-write-enabled/> 
   <read-only-enabled/> 
 
   <display-name-key>User Type Selector</display-name-key> 
   <resource-properties-file>eguideresources</resource-properties-file> 
</ui-attribute-handler>

After you have defined the same information in the XML file, you will need to restart the eGuide server. At this point you can go and select the custom UI Handler. However, when viewing the handler in the client, you will get a warning message for the associated attribute. You need to complete step 2 to finish the process.

Step 2. Define Behavior of UI Handler in UIHandlers.XSL File

Using HTML, JavaScript, CSS, and other browser languages, you define the way your information is displayed and/or edited.

For this example, uncomment the following xsl from the UIHandlers.xsl file located in the eGuide\WEB-INF\templates\xsl\default\browser directory:

<!-- SV Employee Type --> 
<xsl:when test="@uihandler='SVEmployeeType'"> 
    <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="Contract"><xsl:if test="value = 'Contract'"><xsl:attribute name="selected">true</xsl:attribute></xsl:if>Contract</option> 
                        <option value="Full Time"><xsl:if test="value = 'Full Time'"><xsl:attribute name="selected">true</xsl:attribute></xsl:if>Full Time</option> 
                        <option value="Internship"><xsl:if test="value = 'Internship'"><xsl:attribute name="selected">true</xsl:attribute></xsl:if>Internship</option> 
                        <option value="Part Time"><xsl:if test="value = 'Part Time'"><xsl:attribute name="selected">true</xsl:attribute></xsl:if>Part Time</option> 
                        <option value=""><xsl:if test="value = ''"><xsl:attribute name="selected">true</xsl:attribute></xsl:if>(None)</option> 
                    </select> 
                </td> 
            </xsl:when> 
            <xsl:otherwise> 
                <xsl:call-template name="MSV_GenericTextShowTD"/> 
            </xsl:otherwise> 
        </xsl:choose> 
    </tr> 
</xsl:when>

NOTE:  In order for these changes to reflect in a currently running system, you must either restart the server or enable XML Debug from the eGuide Administration Utility under the Reporting - Debug settings. XML Debug is used for two reasons: To disable caching of the templates and to cause the XML output of eGuide to be written to the console screen as well as the log files. It will, on the other hand, slow down the server in order to accomidate for these two features.

At this point you can select the UI Handler for the EMPLOYEETYPE attribute, or any attribute with the Template Key mapped to EMPLOYEETYPE.