| The Lotus Domino Toolkit (LDT) for WSAD provides a set of JSP tag libraries that allow creation of JSP-based Web applications from existing Domino databases. The toolkit contains the Domino JSP tag libraries introduced with Domino R6 and installs into WSAD as a feature plug-in, thus providing the WSAD developer with the means to easily create Domino-based Web applications without having to leave the WSAD environment. In this section, we will cover how to install the LDT and make use of the Domino JSP tag libraries to create Web applications. We take the point of view of an experienced J2EE and WSAD developer who may be less familiar with Domino function. We highlight the considerations relating to Domino that the J2EE developer may need to take into account when writing a Web application using the LDT. Installation and Setup The LDT install file is shipped as part of the Domino product beginning with the Domino 6.02 release. It can be found in the Applications directory of the Domino Designer install CD. The Domino 6.02 version of the LDT only works with WSAD 5.0. You must use the LDT version shipped with Domino 6.5 with WSAD 5.1. In case you may be wondering, the LDT does not work with any version of the basic Eclipse IDE, since it requires certain support provided only with WSAD. The LDT installs to the WSAD root directory. It installs the Domino JSP tag libraries, the Domino Java jar files, and a set of documentation files that integrate into the WSAD help system. The LDT files are installed to subdirectories under the [WSAD_Root]/wstools/eclipse/plugins directory. In particular, the Domino Java jar files are placed in the com.ibm.lotus.lib subdirectory. Note that the 6.02 version of the LDT contains the NCSOW.jar for remote Domino sessions. This jar file is an older version of the CORBA/IIOP support that is not compatible with Domino R6 servers and should not be used. You should use the NCSO.jar file, which can be found in the R6 versions of either the Notes client or Domino server installations. As with the Domino Classes for Java, the Notes.jar and NCSO.jar files must be made available to the application server on which the JSPs using the Domino tag libraries are run. Once the LDT has been installed, the help documentation is available via the main WSAD help window and a new "Domino" view is shown as part of the Web perspective (see Figure 10-5). Figure 10-5. Domino view in WSAD. 
Using this Domino view, the WSAS programmer can access any local or remote Domino database (to which they are authorized) and construct JSP elements from the Domino database design elements such as forms, views, or actions. We'll examine just how to use this view to access Domino databases and use their design elements, but, first, let's look at how to set up a Web project to use the Domino JSP tag libraries and how to create a JSP with Domino tags. Using the LDT Within WSAD Assuming we have a Web project already created, we can set up the project to use the Domino JSP tag libraries via the properties dialog for the project. Open the properties dialog for the Web project, select the Web property page, and then select the Include Domino Custom Tags Library feature, as shown in Figure 10-6. Figure 10-6. Web Project properties. 
The Domino tags feature results in WSAD copying the Notes.jar, NCSO.jar, and domtags.jar files to the Web project's WEB-INF library path for deployment and to its build library path for compilation, as shown in Figure 10-7. Figure 10-7. Web Project library files. 
If the Web project is created, the creation wizard allows selection of the Domino Custom Tags Library feature in the same way. Note that the Notes.jar or NCSO.jar files may already have been added to the project's build library path if they were required by other project components such as other servlets. In this case, the duplicate versions can be removed. Also, the Notes.jar or NCSO.jar files can be removed from the WEB-INF library path if the target WAS server has these files in its runtime classpath. As with the Domino Java objects, the Notes.jar file can be removed if only remote Domino sessions will be established and vice versa for the NCSO.jar file. On creating a JSP, the WSAD wizard allows selection of JSP tag libraries to be included in the page. Selecting Add Tag Library in the dialog shown in Figure 10-8 brings up the selection dialog shown in Figure 10-9. Figure 10-8. Selection of JSP tag libraries. 
Figure 10-9. Adding JSP tag libraries. 
Since the Domino JSP tag libraries were made available to our project, they appear in this dialog and we can select them. We can specify a tag library prefix for each library by highlighting the library, then entering the prefix name in the Prefix: input field. The prefix names associate the JSP tags with a tag library definition statement in the JSP page. We will use a prefix of "domino" to refer to the tags contained in the domtags.tld and "util" for the domutil.tld. When finished specifying the prefix names , selecting the OK button takes us back to the previous dialog from which we can select the tag libraries for our JSP, as shown in Figure 10-10. Figure 10-10. Selecting Domino tag libraries. 
Now that we have our JSP created with the ability to use the Domino JSP tag libraries, we can access the Domino database from which we can obtain the design elements to include in our page. Display the Domino view (refer back to Figure 10-5) and either select the left-most icon on the right side of the title bar or the menu drop-down next to it, or right click in the view window and select New database connection . In this dialog, you specify the Domino server TCP/IP host name on which the database resides (or leave this field blank for local database access), the user under which to access the database (blank to use the default user ID file), and the path to the database. Selecting the Finish button results in the Domino database being shown in the WSAD Domino view as an expandable tree with the database's forms, views, and agents as leaves (see Figure 10-11). Now the Domino design elements can be simply dragged and dropped on any JSP set up to use the Domino tag libraries. Figure 10-11. WSAD Domino view with database. 
Note that a JSP can be set up to use Domino tag libraries either via the creation wizard as shown above, or by explicitly specifying the taglib JSP directives for the Domino tag libraries. This setup is not done by dragging/dropping the Domino elements to a JSP page created without the Domino tag libraries, and JSP compilation errors will result until the directives are added. (The capitalized names shown next to the form and view names are alias names for the forms and views. They are used in Domino application code to avoid having to change code when a display name is changed.) Let's now create two JSPs, one based on the By Title view from the sample_musiclib.nsf database and the other from the Library Item form. This will give us a feel for working with the Domino JSP tags. We create the JSPs as above using the New>JSP Wizard and select the domtags.tld and domutil.tld tag libraries to be added to the page. We create the first JSP, domview.jsp, in this way, then select the By Title view and drag it into the body of the JSP. Looking at the JSP source at this point (see the following listing), we see that the domino:view , domino:viewloop , and domino :viewitem tags have been added by the drag and drop of the view element (in bold below):
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <HTML> <HEAD> <%@ taglib uri="/WEB-INF/domtags.tld" prefix="domino" %> <%@ taglib uri="/WEB-INF/domutil.tld" prefix="util" %> <%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1" %> <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <META name="GENERATOR" content="IBM WebSphere Studio"> <TITLE>domview.jsp</TITLE> </HEAD> <BODY> <P><B>All Documents by Title:<BR> <domino:view viewname="By Title" dbserver="" dbname="c:/lotus/domino/data/sample_musiclib.nsf" user="" password="" > <table> <tr> <td>Title</td> </tr> <domino:viewloop> <tr> <td> <domino:viewitem col="1"/> </td> </tr> </domino:viewloop> </table> </domino:view> </B></P> </BODY> </HTML>
Those familiar with Domino views will see that the viewloop tag iterates over the contents of the first column of the view, which in this case consists of the Title field of the documents using the Library Item form. Note also that, by default, the domino:view tag is generated with scripting variables for the user and password attribute values as such:
user="<%username%>" password="<%password%>"
We can remove these variables to make it easier to test against a local Domino database via the WTE. With the dbserver , user , and password attributes all set to empty strings, a local Domino session is established under the default Notes ID file for the local server configuration. The second JSP, domform.jsp, is created in the same way, except we drag and drop the Library Item form element to the page. This results in the following JSP source:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <HTML> <HEAD> <%@ taglib uri="/WEB-INF/domtags.tld" prefix="domino" %> <%@ taglib uri="/WEB-INF/domutil.tld" prefix="util" %> <%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1" %> <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <META name="GENERATOR" content="IBM WebSphere Studio"> <TITLE>domform.jsp</TITLE> </HEAD> <BODY> <P><B>Library Item</B> <domino:form name="formname" dbname="c:/lotus/domino/data/sample_musiclib.nsf" dbserver="" user="" password="" schema="Library Item"> <table> <tr> <td>Date Acquired</td> <td><domino:input name="DateAcquired" type="date"/></td> </tr> <tr> <td>Comments</td> <td><domino:input name="Comments" type="text"/></td> </tr> <tr> <td>Media</td> <td><domino:input name="Media" type="text"/></td> </tr> <tr> <td>Artist</td> <td><domino:input name="Artist" type="text"/></td> </tr> <tr> <td>Title</td> <td><domino:input name="Title" type="text"/></td> </tr> <tr> <td>Category</td> <td><domino:input name="Category" type="text"/></td> </tr> </table> <BR> <domino:savedoc showdisabled="false" text="Submit"/> </domino:form> </P> </BODY> </HTML>
Dragging and dropping the form design element adds the domino:form and domino:input tags to the JSP. The domino:form tag acts as a container for the domino:input tags and establishes the Domino session. To provide the submit function, we manually added the domino:savedoc tag (as shown in bold above), which will result in either the creation of a new document or the update of an existing document in the Domino database. We'll see how this same JSP can be used for both document creation or update by enhancing the domview.jsp. As we saw, domview.jsp displays a simple static text list of the Title fields of the documents in the database. We embellish the list by changing the text rows into active links, which will display the document contents using the domform.jsp. We also add a "Create New Document" link at the bottom of the table. These changes are shown in bold:
<domino:view viewname="By Title" dbserver="" dbname="c:/lotus/domino/data/sample_musiclib.nsf" user="" password="" > <table> <tr> <td>Title</td> </tr> <domino:viewloop> <tr> <td> <domino:formlink href="/PublishingHouseWeb/domform.jsp"> <domino:viewitem col="1"/> </domino:formlink> </td> </tr> </domino:viewloop> </table> </domino:view> </B></P> <P><A href="/PublishingHouseWeb/domform.jsp" target="_self"> Create New Document </A></P> </BODY>
The domino:formlink tag creates an HTML link to an existing Domino document by passing the document's unique identifier (UNID) to the specified URL reference. The URL reference is assumed to contain either a domino:document or domino:form tag, which uses the UNID to access the document. In our JSP, the domino:formlink tag passes the UNID of the documents in the view to our domform.jsp, which then displays the document's contents. We used a simple hyperlink (<A> ) referencing the same domform.jsp to present a page for creating a new document. Since no UNID is passed to the domform.jsp in this link, the domino:form (and domino:input ) tag generates the field elements as HTML input tags, allowing the field values to be input by the user. Note that apart from adding a submit action, we did not have to modify the domform.jsp to provide this dual function. Structure of the Domino JSP Tag Library Now that we have seen a basic example of using the Domino JSP tags, we'll examine the overall structure of the tags and their function. By understanding the structure, we will be better able to use the tags to create efficient JSPs to access Domino databases and functions. The set of Domino JSP tags can be divided into the following categories: the core tags, data tags, action tags, navigation tags, and control tags. The core tags are those that provide access to the basic Domino database or server functions by establishing an underlying Domino Java Objects session from the JSP container to the Domino server. The data tags are those that allow access to and manipulation of data items in the Domino databases. Action tags provide means to invoke Domino server-side processing. Navigation tags enable the JSP user to navigate to other Web pages, especially other Domino JSPs. The control tags simplify adding conditional processing to the JSP, where the conditions are based on Domino attributes. Apart from the core tags, these categories are our own definitions and are not used in the Domino Help documentation. As JSP tags, they have XML structure so that the tags can be written hierarchically ”where the sub-element tags can take on the attributes of the parent element tag. A parent tag that contains sub-element tags is referred to as the context of the sub-element tags. The function of several of the Domino JSP tags often depends on their context. Since they are most important, let's look at the core tags more closely. As mentioned earlier, they establish the underlying Domino Java session from the JSP to the Domino server. Each of the core tags ” view , document , form , ftsearch , mailto , and runagent ”defines attributes allowing specification of the host, user, and password, which, as we saw in the section on Domino Java Classes, are the primary parameters for creating a Domino Java session. Since creating a Domino session is relatively expensive, we want to create only a single Domino session per JSP. If more than one of the core tags is required on a single page, the session tag can be used as their parent and the Domino session established only once. Similarly, if a single Domino database needs to be accessed via separate core tags (say from view/viewloop and ftsearch tags), then the db tag can be used to wrap the tags referring to the database so that the database open is done only once. The following tables list the Domino JSP tags in the categories we defined here. Table 10-3. Domino JSP Core Tags | Core Tags | Context | Description | | view | [db, session] | Displays a Domino view, which is a set of documents in a database and a set of fields for each document. | | document | [db, session] | Displays, edits, or creates a single Domino database document. Contains item or formula tags that display or edit document data. | | form | [db, session] | Displays, edits, or creates a single Domino database document with optional client-side field validation. | | ftsearch | [db, session] | Performs full-text search of a database. | | mailto | [db, session] | Sends enclosed text as a Domino mail message. Sender is the user owning the current session. | | runagent | [db, session] | Runs a database agent on the server. |
Table 10-4. Domino JSP Data Tags | Data Tags | Context | Description | | attachmentlist | form | Displays attachments as list. Intended for Netscape Navigator/Mozilla. | | Attachments | form | Displays attachments as list. Intended for Internet Explorer; supports upload via ActiveX control. | | authors | viewloop, docloop, document, form | Displays Authors field of document. Document must have been saved. | | checkbox | form | Displays or edits list of item contents as checkbox. | | created | viewloop, docloop, document, form | Displays document creation date. | | dbfill | dbselect | Sets controls in page to values from document fields specified via dbselect . | | dbselect | form | Specifies a set of document values from a database view or of option or dbfill tags. Displays as a drop-down list. | | docloop | db, ftsearch, responses, page, view | Generates the tag body for each document in the context tag (for example, for each document in a view). | | fill | option | Sets client controls from specified target and value attributes. Used within select , dbselect tags. | | formula | viewloop, docloop, form, document | Displays results of formula specified in tag body. | | input | form | Allows editing of a document field. | | item | viewloop, docloop, form, document | Displays the value of a document field. Allows editing of a field in form context. | lastaccessed lastmodified
| viewloop, docloop, form, document | Displays last accessed/modified date and time of a document. (Forces reload of document.) | | option | select, dbselect | Displays single option in a drop-down list control. | | profiledocument | form | Obtains fields from user profile documents. | | radio | form | Displays or edits list of item values as radio buttons . | | richtext | form | Allows editing of a rich text item via Java RichText applet or Internet Explorer rich text control. | | select | form | Specifies set of list values via option tags. Displays as drop-down list. | | selectedloop | [view] | Generates the tag body for each document in the context tag (for example, for each document in a view). | | selectentry | viewloop | Displays loop item with checkbox. | | setitem | document, form | Sets item in document. Item not saved until document is saved. | | textarea | form | Displays text item as HTML textarea control. | unid user
| viewloop, docloop, form, document | Displays document UNID/current user. | | viewitem | viewloop, selectentry | Displays item from specified view column. | | viewloop | view, page | Generates the tag body for each row in a view. |
Table 10-5. Domino JSP Action Tags | Action Tags | Context | Description | | action | form , view | Generates action link causing action performed on server. Action specified via ifserverevent tag. | | delete-attachment | attachmentlist, form | Deletes selected attachment from document. | | deletedoc | form | Deletes current document; displays next document. | | editdoc | form | Places form in edit mode (displayed only if in read mode). | | newdoc | form | Creates new document using current form. | | nextdoc | form | Displays next document in current document collection. | | saveclosedoc | form | Saves and closes the current document. | | savedoc | form | Saves current document (with validation). | | savenow | form | Saves current document immediately. |
Table 10-6. Domino JSP Navigation Tags | Navigation Tags | Context | Description | | docnavimg | form | Generates a navigation link from specified images, one showing the link enabled, and the other disabled. | | formlink | viewloop, docloop, form, document | Creates link between a document reference in a viewloop or docloop and a form or document page. Link is via UNID. | pextdoc prevdoc
| form | Creates navigation tag to display next, previous document in current document collection. | | pagebar | page | Provides for navigation to a particular page. | pagefirst pagelast pagenext pageprev
| page | Generates HTML to navigate to first, last, next, or previous page accessed in a session. | | parentlink | viewloop,docloop, form, document | Generates a link to a document's parent. |
Table 10-7. Domino JSP Control Tags | Control Tags | Context | Tags / Description | | Access Control | db, view, ftsearch, document, form | ifauthor, ifdbrole, ifdepositor, ifdesigner, ifeditor, ifmanager, ifnoaccess Generates body of tag only if session user has corresponding ACL access to the Domino database | | | Docloop, viewloop, document, form | ifdocauthor, ifdocreader Generates tag body only if session user has corresponding access to the document (via author, readers fields). | | View Control | viewloop | ifcategoryentry, ifconflictentry, ifdocumententry, iftotalentry Generates body of tag only if ViewItem corresponds to tag. | | Validation Control | form | validatecc, validatedate, validatelength, validatepattern, validaterange, validaterequired, validatesummary, validatewith Performs specified client-side validation on the specified input tag. clientvalidate attribute on input tag must be other than none and set to true on form tag. |
Hints and Tips for Using the Domino JSP Tags Here we highlight some hints and tips for using the Domino JSP tags, especially within WSAD. Hopefully these items will be useful to you in becoming comfortable with the Domino tags so that you can quickly start generating quality Domino-based Web applications. The items are in no particular order. -
Tags generate client-side as well as server-side code . Although most Domino tags generate server-side (Java) code, keep in mind that several Domino tags result in purely client-side function (HTML or JavaScript). Examples of client-side tags are select , option , fill , and the set of validate * tags. -
Certain tags might force a page reload . Several of the Domino tags require that the current page be refreshed in order to function. Be aware of this possibility when designing the page flow to avoid delays in user interaction. -
Not all document item types are fully rendered when using the LDT in WSAD . When using the Lotus Domino Toolkit plug-in for WSAD, the drag-and-drop feature for creating JSPs from Domino forms and views, all of the Domino item (field) types are generated as simple (Domino) input tags. For certain field types, such as "Dialog list," "Checkbox," and "Radio," this results in JSP fields that are displayed as single text input controls rather than drop-down list selection controls or checkboxes or radio buttons. In the case of "Dialog list" (keyword) fields, rendering them as input tags results in the alias values for the list items being displayed and provides no way to make a list selection in edit mode. You need to enhance the JSP by using the Domino select , option , and fill tags to generate a drop-down list control for these fields. For example, in the domform.jsp we used to show the results of dragging-dropping a Domino form to create a JSP, the Category field is defined in the Domino database design as a "Dialog list." We can change the input tag generated for this field to the following source: <tr> <td>Category</td> <td> <%--domino:input name="Category" type="text"/--%> <%-- Drop-down list selections for Category item dialog list --%> <domino:select name="Category"> <domino:option value="1" display="Book"> <domino:fill target="Category" value="1"/> </domino:option> <domino:option value="2" display="Music"> <domino:fill target="Category" value="2"/> </domino:option> <domino:option value="3" display="Film"> <domino:fill target="Category" value="3"/> </domino:option> <domino:option value="4" display="Software"> <domino:fill target="Category" value="4"/> </domino:option> </domino:select> </td> </tr> The select tag generates the drop-down list and identifies the form item target. The option tags are used to associate the list item display names with the dialog list alias values. The fill tags are used to set the alias value of the item when a list selection is made. -
Drag/drop of a Domino form to a JSP page does not preserve form layout . A JSP page created by dragging and dropping a Domino form via the Domino view often does not match the layout of the Domino form. For example, the order of fields within a table is reversed . -
JSPs can be generated from Domino Designer XML (DXL) using XSLT . One way to overcome the limitations of the LDT with generating JSPs from Domino database designs is to generate the JSPs from the DXL for the design documents via XML stylesheet transforms. Since the DXL captures the exact content and structure of the design document, transforming from DXL will produce a truer rendering of the Domino design. The LDT rendering problems mentioned in tips 3 and 4 can be overcome this way. For example, here is an XSL template for converting a Domino form field from DXL into the appropriate Domino JSP tags.
<xsl:template match="dxl:field[@type]"> <xsl:choose> <xsl:when test="self::node()[@type='keyword']"> <!-- We have a keyword type field... Generate a Domino select tag with option and fill tags set to the keywords  given by the dxl:keywords tag. --> <xsl:element name="domino:select"> <xsl:attribute name="name"> <xsl:value-of select="@name"/> </xsl:attribute> <!-- Look for the keyword values in text elements. The values are generated as: "display-namevalue-name", so we need to parse the values using XPath string functions as below. --> <xsl:for-each select=".//dxl:text"> <xsl:element name="domino:option"> <xsl:attribute name="display"> <xsl:value-of select="substring-before(string(),'')"/> </xsl:attribute> <xsl:attribute name="value"> <xsl:value-of select="substring-after(string(),'')"/> </xsl:attribute> <xsl:element name="domino:fill"> <xsl:attribute name="target"> <xsl:value-of select="ancestor::node()/dxl:field/@name"/> </xsl:attribute> <xsl:attribute name="value"> <xsl:value-of select="substring-after(string(),'')"/> </xsl:attribute> </xsl:element> </xsl:element> </xsl:for-each> </xsl:element> </xsl:when> <xsl:otherwise> <!-- Generate a Domino input tag, with name and type attributes taken directly from the corresponding dxl:field attributes. --> <xsl:element name="domino:input"> <xsl:attribute name="name"> <xsl:value-of select="@name"/> </xsl:attribute> <xsl:attribute name="type"> <xsl:value-of select="@type"/> </xsl:attribute> </xsl:element> </xsl:otherwise> </xsl:choose> </xsl:template>
Note that this XSL is general enough to generate the correct Domino tags for most field types in the DXL (it would need to be enhanced to generate the correct tags for checkbox and radio fields). It will generate simple Domino input tags for most field types and will generate the select , option , and fill tags for keyword field types. For example, it would generate the JSP tags shown in hint 3 for a keyword field. Admittedly, this is sophisticated XSL, but would be well worthwhile if there were a need to generate many JSPs from a Domino application. Writing and testing XSL such as this is made even easier by using the XML/XSL development tools offered by WSAD. |
