This is a replicated copy of Building Java Apps with Lotus eSuite DevPack, Part II: DevPack in Action. It is provided for completeness and avoid "broken" link.

 
  DominoPro Article 

  Editorial
    Articles
    Ask Ben
    News & Notes
    Tips Corner

  Forums
    Welcome
    General
    Administration
    Adv Programmability
    Old Forum Archive

  Career
    Job Center

  Newsletters
    DominoWire
    DominoWire Tips

  Site Info
    Letters
    About Us
    Contact Us
    Masthead
    Media Kit
    Write for Us




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 1.

Figure 2
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 5a.

Figure 5b
Figure 5b.

Figure 6
Figure 6.

Figure 7
Figure 7.

Figure 8
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 10.

Figure 11
Figure 11.

Figure 12
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 14.

Figure 15
Figure 15.




For more of Richard's work, check out:
    Archive by Author: Richard Sinn








You are at dominopro.com.
Report Bugs | Submit Comments | Read Site Use Agreement | Read Privacy Policy | Contact Us
Copyright 2000 Duke Communications International.

Duke Communications DominoPro | AS400 Network | Business Finance | SQL Server Magazine | Windows 2000 Magazine