|
Published July
1999
Building Java Apps
with Lotus eSuite DevPack, Part II: DevPack in
Action
By Richard
Sinn
In "Building Java Apps with Lotus
eSuite DevPack, Part I: DevPack Overview," I introduced you to Lotus eSuite DevPack and
described the three key technologies that form the backbone of
DevPack in building Java applications: InfoBus, InfoCenter, and
Template Builder. In this article, I show you DevPack in action by
stepping you through the process of building a simple, yet elegant,
DevPack Java applet for subsequent integration and deployment on a
Domino server with Notes Designer.
Developing in DevPack
As I take you through building the sample application, the
following general steps will serve as a quick guide to the
process:
1. Create an applet template. A
template is an instance of an eSuite applet that you create and
save to a file by running the Template Builder.
2. Create an HTML page that will display multiple
applets on one page.
3. In the
newly created HTML page, set the AppletContainer applet's
InfoCenterVisible PARAM tag to "true" to display the
InfoCenter.
4. If necessary,
enable communications between an applet and an external data
source
5. Enable data
communications between applets.
Figure 1 shows what our sample application, a college
education report system, looks like. Using this application,
students can check their grades and view their standings in a
runtime-generated, three-dimensional chart. Teachers can use the
same application to generate quarter-end reports. Because the
application is Web based, students and teachers can access it from
the Internet or an intranet.
Here's how we go about building this
application:
Step
1. Execute the Template
Builder (tbuilder.bat) from directory eSuiteDP20\tools. On the
Template Builder's File menu, click the New Spreadsheet option. A
new (empty) spreadsheet will be displayed. Enter all the student
information as you would for a regular
spreadsheet.
Step
2. Next, select a range of
spreadsheet cells to be ported to a chart. To do so, you highlight
the cells you want to port, click the Range option on the
InfoCenter's action bar (which appears below the spreadsheet), and
then click Name. In the resulting panel's Name Range box, enter a
name -- say, "grade" -- for the range. Then click the Define button.
Figure 2 shows how to define a range.
Step 3. On
the Template Builder's File menu, click the Customize Applet
InfoCenter option. Scroll to the IDA_RANGEGROUP group check box,
clear it, and then click OK. This optional step prevents the Range
menu and action items from being displayed when an application loads
this InfoCenter.
Step
4. On the Template Builder's
File menu, click Save to save the template. Enter a name for the
template, such as "sinnSample". If you customized the applet's
InfoCenter, as we did in Step 3 for our sample application, the
Template Builder automatically saves the customized InfoCenter as
well, giving it the same file name as the template and a different
extension. Figure 3 shows, by applet type, the template and file
extensions that eSuite recognizes. In our example, the template is
saved with the file name
sinnSample.html-wk.
Step
5. To close the Template
Builder, click the File menu and then click
Exit.
Step
6. Next, create an HTML file
that loads the template. The file should look like Figure 4. This
code basically instantiates the Sheet and Chart applets in an
AppletContainer applet using the AppletContainer's
appletn PARAM tags -- in this case, applet0 and applet1. A
namen (e.g., name0, name1) PARAM tag can then be used to identify
an applet, making it possible to refer to that applet's properties,
methods, and PARAM tags and, in the case of the Chart applet, to
identify a data source. At B in Figure 4, the name0 tag is applied
to the instance of the Sheet applet to specify a name that is
subsequently used to access the applet's documentName PARAM tag to
load the Sheet template sinnSample.html-wk (at C). At D, the
dataInputItemName of the chart is set to the range name ("grade")
that we created for our template using the Template Builder. The
data in the appropriately named range in sinnSample.html-wk is
communicated to the Chart applet via the
InfoBus.
Because the value of
the AppletContainer's InfoCenterVisible PARAM tag is set to "true"
(at A), the InfoCenter appears at the bottom of the applet window.
The InfoCenter as it appears at runtime is appropriate to the applet
that has the focus: clicking in the spreadsheet displays the
InfoCenter for the Sheet applet, while clicking in the chart
displays the InfoCenter for the Chart applet.
The remainder of the code in Figure 4 is simply
standard use of Java in an HTML page. The following is a brief
description of the tags.
To
invoke one or more Java applets in an HTML page, a file might
contain one or more <APPLET>...</APPLET> blocks. Each
<APPLET>...</APPLET> block uses the following
tags:
- CODEBASE -- specifies a relative path
to a point in the source directory tree from which the application
can find the Java classes it needs to run successfully
- CODE -- specifies the name of the
class in which the applet is defined. The AppletContainer applet's
appletn PARAM tag performs this function for each
contained applet.
- ARCHIVE -- specifies the Java archive
(jar) file that contains the classes. Applications that use the
InfoCenter use an archive file called devpack_applet_app.jar. Applications that don't use the InfoCenter can
use the (smaller) file called devpack_applet_lite.jar.
- WIDTH and HEIGHT -- set the width and
height (in pixels) of the area where the applet is to be displayed
in the Web browser. In the AppletContainer applet, these tags
specify the display area for the contained applet or
applets.
- <PARAM NAME="cabinets"
VALUE="cabinet
file(s)"> -- specifies the
Java standard cabinet (cab) file or files that contain the classes
the application needs to run successfully under the Web browser (a
cabinet file is single, compressed file containing all the Java
classes needed to run the applet)
DevPack Deployment with Domino
In this section, I demonstrate how to deploy our
sample application on a Domino server using Notes Designer. There
are two ways to deploy DevPack applets on a Notes server. For
clients that use only Web browsers, the Notes server can be used as
a Web server to serve the DevPack applets. Users simply point to the
DevPack Web page location and access the DevPack applet. For
example, users can go to http://ffktst04.stl.ibm.com/DevPack+Demo.nsf to directly access the DevPack applet. Figures 5a
and 5b demonstrate this.
If
full integration -- that is, accessing your DevPack applets from
Domino clients -- is required, you can integrate DevPack applets
into Domino applications using Release 4.6.2 or later of Notes
Designer for Domino. Lotus provides the ability to insert DevPack
applets into forms, subforms, or documents. Lotus forms are database
design elements that give users a standard format for creating
documents in a database and for viewing existing documents. Subforms
are database design elements inserted into forms to add a group of
design features quickly. Graphics, text, and other design objects
added to a form are copied into every document created from the
form. Inserting applets in forms or subforms reduces development
time because the forms or subforms can be shared by many documents.
However, if you need an applet for just one document, inserting it
into that document is a better way to go.
Let's run through an example of using Notes
Designer to integrate our sample DevPack application into Domino.
For demonstration purposes, we'll insert the sample app into a
Domino document. Figure 6
shows the finished Domino
document with the DevPack applet.
Step 1.
Start Lotus Notes, and use the File|Database|New command to create a
database called DevPack Demo; for the database type, you can use
Document Library.
Step
2. Open the newly created
database, and click the New Document button to create a new
document.
Step
3. Double-click the document,
and choose Actions|Edit Document to put it in edit
mode.
Step
4. Choose File|Tools|User
Preferences, and verify that the Enable Java applets option is
selected in the list of Advanced options. If this option does not
appear as a preference, check with your system administrator to make
sure the Java files necessary for running applets are installed on
your workstation.
Step
5. As you edit the applet,
you might not want to incur the reloading delay caused by resizing
an applet or changing its parameters while it's running. To prevent
the applet from running, choose View|Show|Java Applets Running and
deselect the option. When an applet is not running, it is displayed
as a gray box of the specified dimension.
Step 6.
While editing the document, use the Create|Java Applet command to
insert an applet into a form or subform or a rich-text field of a
document. Note that to link to an applet on the Internet, the
current Location documents (which store control information for the
users) need a valid Web proxy value; to link to an applet on an
intranet, the current Location documents need a valid No proxy
value. To view the Web proxy value on your workstation, choose
File|Mobile|Edit Current Location. If you have questions about which
proxy server your users need to set as the Web proxy in their
Location documents, consult your system
administrator.
Step
7. In the Create Java Applet
window (Figure 7), select "Link to an applet on a web server." Then,
in the Base URL field, enter the path for the applet files. The
server and directory are the same as the URL you would use in the
CODEBASE attribute of the HTML APPLET tag in Figure 4. For example,
the following base URL links to a Web server named
ffktst04.stl.ibm.com, on which DevPack has been installed in the
eSuiteDP directory:
http://ffktst04.stl.ibm.com/eSuiteDP
Next, in the Class name field, enter the
case-sensitive applet class name. The applet class names are the
same as the possible values for the CODE attribute of the HTML
APPLET tag in Figure 4. Click OK. The applet will be displayed on
the form, subform, or document.
Step 8. The next step
is to set applet parameters in the Notes Designer design pane
(Figure 8). To load the applet, you must include the archive
parameter, whose value points to the jar files the applet uses. The
archive parameter value is the same as the value of the ARCHIVE
attribute of the HTML APPLET tag in Figure 4. If you want the applet
data to be editable, you must add the readExternalData and
writeExternalData parameters to let data be saved in the
document.
Let's take a
detailed look at the parameters in the design pane. Figure 9 lists
the parameters and their values. The parameter list in Figure 8
shows that the AppletContainer applet is used to display an
InfoCenter. It explicitly positions the Sheet above the Chart using
the AppletContainer applet's infoCenterVisible, applet0, and applet1
parameters. Note that the sum of the values for the Sheet and Chart
applets' height parameters must equal the value of the
AppletContainer applet's HEIGHT attribute. When applets appear side
by side in an AppletContainer frame, a similar constraint applies to
the values for width.
Upon
closer investigation, you can tell that most of the applet parameter
values in Figure 8 are the same as the parameter values in Figure 4.
The only special parameters necessary for Notes Designer are the
readExternalData and writeExternalData parameters, which make the
spreadsheet editable. The values of these two parameters must be the
same to allow the applet to load and save the same set of data. Also
note that you can specify a maximum of four applets in an
AppletContainer. The sheet.documentName must be put into the correct
Web directory to enable the applet to locate it and load the data.
In our example, we put file sinnSample.html-wk in the same place as
the root of the applet ffktst04.stl.ibm.com/eSuiteDP on the Domino
server (Figure 10).
Step
9. To change an applet's
height and width or to hide the applet from Web users, you first
select the applet in the form, subform, or document by clicking to
the right of the applet and using the left arrow key to select the
applet. Then select Java Applet|Java Applet Properties (Figure 11).
The applet is selected when a border appears around it and a small
filled-in rectangle appears in the lower-right corner of the applet
window. If the entire applet area is highlighted, you have selected
a text region, not the applet. Another way to bring up Java applet
properties or parameters is to right-click on a selected applet
(Figure 12).
Step
10. To test the applet,
choose View|Show Java Applets Running or double-click the gray
applet box.
Step
11. To troubleshoot any
problems, click File|Tools|Show Java Debug
Console.
Step
12. Close and save the form,
subform, or document.
Parameters readExternalData and
writeExternalData
To complete
the integration, we need to take a closer look at the
readExternalData and writeExternalData parameters. Except when
creating read-only applets, you must configure applets to enable
users to save their work. For example, when users create documents
from a form that contains the DevPack Sheet applet, you'll want to
make sure the Sheet work becomes part of their documents. The
readExternalData and writeExternalData parameters that we added
above actually force Domino to save the applet data in a hidden file
attachment within the documents and retrieve it on demand. The
parameters and their values are not case sensitive, and applets that
save data in Notes documents must be in applications served from a
Domino Web server.
Parameter
readExternalData causes Domino to load the applet with values saved
from a previous session after the applet is initialized. Without
this parameter, you can't retrieve applet values. If a document that
contains the applet has never been saved, Domino looks for the
values in the form used to create the document. In our example, the
value is "saveappcon". On the other hand, parameter
writeExternalData causes Domino to save current values for the
applet when the document that contains the applet is saved. Without
this parameter, you can't save applet values.
Domino uses the value specified in
readExternalData and writeExternalData as an identifier for
retrieving and saving the data in the document. The value can be
anything as long as it is unique within the applet or
AppletContainer and is the same for both readExternalData and
writeExternalData. As with any parameter, the value must be in
quotation marks. If you have multiple applets in one
AppletContainer, you need only one readExternalData parameter and
one writeExternalData parameter for the container. It's helpful to
use values that reflect the type of applet, such as "savesheet" for
a Sheet applet or "saveappcon" for data stored in an AppletContainer
applet. If you have multiple applets or containers on a form and its
subforms, use different names for each applet's data so they won't
conflict with each other (e.g., "savesheet1" and "savesheet2" or
"saveappcon1" and "saveappcon2").
Because applets are independent of the document that contains
them, Notes can't detect changes to applet data. Unless something
else changes in the document, Notes closes without prompting users
to save their work. Thus, we have to add some simple LotusScript
code to prompt the user to save applet data to prevent unexpected
data loss.
To do so, in the
design pane for the form, select Define: form name and Event:
QueryClose, and then enter the LotusScript code shown in Figure 13.
Figure 14 shows this step. Once you've done this, a dialog box
(Figure 15) prompts the user to save the applet data when the
document is closed in edit mode. Thus, the document must be in edit
mode for this prompt to work.
DevPack and Domino: A Powerful Pair
As you can see, building business applications
using DevPack is easy. You just select the right Java components
from DevPack and put them together. The result is flexible,
standards-based end products that you can deploy rapidly and
cost-effectively. Developing with DevPack is the software
counterpart to building a PC from parts.
If you want to leverage enterprise Internet and
intranet technology using Java, respond quickly to business
opportunities and customer needs, leverage your existing Domino
infrastructure, and build more powerful applications, I highly
recommend using Domino with Lotus eSuite DevPack. To learn more
about eSuite and DevPack, visit http://esuite.lotus.com/. For Java computing information, visit Sun's home
page, http://www.sun.com/java. For more information about Lotus Domino, see
http://www.lotus.com/.
 Richard Sinn is a
staff software engineer at IBM's Santa Teresa Laboratory in San
Jose, California. He is also a lecturer at San Jose State University
and a freelance writer for different magazines and journals. You can
reach him via e-mail at webmaster@openloop.com or at his Web site, http://www.openloop.com/.
Figure
1.
Figure 2.
Figure 3 - eSuite extensions by
applet type
Template extensions:
Template Extensions
Chart .echart
Presentation .pg, .prz
Scheduler .lps
Spreadsheet .htm, .html, .html-wk,
.html-wkt, .wk1
Word
processor .htm, .html, .html-wp, .html-wpt,
.txt
Customized
InfoCenter file extensions:
Template Extensions
Chart .ICC-ECHART
Presentation .ICC-PG,
.ICC-PRZ
Scheduler
.ICC-LPS
Spreadsheet
.ICC-HTM, .ICC-HTML, .ICC-WK, .ICC-WK1, .ICC-WKT
Word processor .ICC-HTM, .ICC-HTML,
.ICC-TXT, .ICC-WP, .ICC-WPT
Figure 4 - HTML to load the
sinnSample template
<HTML>
<HEAD>
<TITLE>Example: SpreadSheet and Chart with
InfoCenter</TITLE>
</HEAD>
<BODY>
<H2>Example: SpreadSheet and Chart with
InfoCenter<HR></H2>
<H2><CENTER>University of Minnesota - Student
Grade</CENTER></H2>
<APPLET CODEBASE="../.."
CODE="lotus.fc.AppletContainer"
ARCHIVE="jars/devpack_chart_sheet_jdbc_app.jar"
WIDTH=640 HEIGHT=480>
<PARAM NAME="cabinets"
VALUE="cabs/devpack_infobus.cab,cabs/devpack_shared.cab,cabs/devpack_ic.cab,cabs/devpack_sheet.cab,cabs\devpack_chart.cab">
[begin callout A]
<PARAM NAME="infoCenterVisible"
VALUE="true">
[end
callout A]
<PARAM
NAME="applet0" VALUE="lotus.sheet.Sheet">
[begin callout B]
<PARAM NAME="name0"
VALUE="sheet">
[end
callout B]
[begin
callout C]
<PARAM
NAME="sheet.documentName"
VALUE="sinnSample.html-wk">
[end callout C]
<PARAM NAME="sheet.height"
VALUE="250">
<PARAM
NAME="applet1" VALUE="lotus.chart.Chart">
<PARAM NAME="name1"
VALUE="chart">
[begin callout D]
<PARAM NAME = "chart.dataInputItemName" VALUE =
"grade">
[end
callout D]
<PARAM
NAME="chart.height" VALUE="230">
</APPLET>
</BODY>
</HTML>
Figure
5a.
Figure 5b.
Figure 6.
Figure 7.
Figure 8.
Figure 9 - Notes Designer design
pane applet parameters
Class name:
lotus.fc.ac.AppletContainer
Parameter Value
archive "jars/devpack_sheet.jar,
jars/devpack_chart.jar, jars/devpack_shared.jar,
jars/devpack_infobus.jar, jars/devpack_ic.jar"
cabinets "cabs/devpack_sheet.cab,
cabs/devpack_chart.cab, cabs/devpack_shared.cab,
cabs/devpack_infobus.cab, cabs/devpack_ic.cab"
infoCenterVisible "true"
applet0
"lotus.sheet.Sheet"
name0
"sheet"
sheet.documentName "http://ffktst04.stl.ibm.com/eSuiteDP/sinnSample.html-wk"
sheet.height "250"
applet1 "lotus.chart.Chart"
name1 "chart"
chart.dataInputItemName
"grade"
chart.height
"230"
readExternalData
"saveappcon"
writeExternalData "saveappcon"
Figure
10.
Figure 11.
Figure 12.
Figure 13 - LotusScript code to
prompt user to save applet data
Sub Queryclose(Source As Notesuidocument,
Continue As Variant)
Dim
answer As Integer
If
Source.EditMode Then
answer = Messagebox ("Do you want to save the "
_
+ "data in your
applet?", 4, "Applet Data Save")
If answer = 6 Then Call Source.Save
End If
End Sub
Figure
14.
Figure 15.
For more of Richard's work, check
out:
•
Archive by Author: Richard Sinn
|