Skip to main content

By clicking Submit, you agree to the developerWorks terms of use.

The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

  • Close [x]

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

By clicking Submit, you agree to the developerWorks terms of use.

All information submitted is secure.

  • Close [x]

developerWorks Community:

  • Close [x]

XPages, Themes, and Mashups in Domino Web Application Development

Creating the Big Brother mashup application

Summary:  XPages and Themes are two new technologies available to Lotus Domino Web application developers with the release of IBM Lotus Notes and Lotus Domino 8.5. They provide more flexibility and greater control over what is delivered to the Web browser client screen than any previous release. XPages leverages a new JavaServer Face rendering engine while Themes allows even further control to manipulate the content -- from CSS declarations to XML markup rendering -- that is displayed. In this tutorial, you will use both XPages and Themes to create an enterprise-class salesforce tracking and task assignment Lotus Domino Web application. To further showcase the advanced capabilities of the technologies available to Lotus Domino Web application developers, the example for this tutorial is a mashup application featuring functional OpenStreetMap and GeoCoder integration.

Date:  16 Dec 2008
Level:  Intermediate

Activity:  58 views
Comments:  

Creating the mashup

Now that you have looked at the elements that make up the example project, it's time to look at the step-by-step build process for the creation of the Big Brother functionality and user interface.

Getting started

To recap, the project for this tutorial will consist of the following:

  • Simple Contact Management through Lotus Domino Forms and Views
  • Simple Location Entries Management through Lotus Domino Forms and Views
  • Management Dashboard through a Custom Theme-controlled XPage

For most organizations currently using Lotus Domino to deliver their Web applications, XPages and Themes are two new technologies that will more than likely be applied to existing applications. That is, after all, the true appeal of learning and deploying these technologies: the fact that you can take existing applications that may have Web browser user interfaces but that deliver a dated user experience and update them.

For the purposes of this tutorial, the People and Locations exist from within the same NotesDatabase as the XPages and Themes rendering your OpenStreetMap user interface. Ideally, you would see this XPages and Themes infusion into an existing Lotus Domino Web application (or a Lotus Notes Client application for that matter) in a separate NotesDatabase, complete with custom Themes and XPages with defined data sources in ancillary NotesDatabases.

This will be a first-step example project and your first potential XPage and Themes usage in your world of Lotus Domino Web application development: the infusion of XPage and Theme technologies into an existing Lotus Domino Web application.


The XHTML, CSS, and JavaScript build project user interface

Because the example project is to act as an existing, established, and functional Lotus Domino Web application, you must take into consideration an existing user interface. Most users, while thinking that they honestly want something new, will often immediately dislike even an improved user interface to their day-to-day applications if the user interface changes too drastically between releases. Therefore, your XPage and Themes will incorporate your build project's fictional existing user interface. It is fictional because you will actually be building your user interface using the classic form and view design elements in combination with a stylesheet and inline JavaScript as needed.

To do this, I have created a simple XHTML file in a WYSIWYG (What-You-See-Is-What-You-Get) HTML and CSS editor, as well as an accompanying stylesheet (see figure 3). You will use the XHTML file as a template when building your form, view, and XPage design elements.


Figure 3. XHTML and CSS user interface template
XHTML and CSS user interface template

You will use the XHTML markup to structure your Lotus Domino design elements and the stylesheet to render a similar consistent user interface for all of your design elements: forms, views, and XPages alike.


Simple contact management through Lotus Domino forms and views

Now let's use form and view design elements to build a simple yet powerful contact list for the example project. Once the contact list is complete, you will be able to easily maintain Contacts from a Web browser client.

The person form

You will create a simple form design element called person, which will house the contact information for your salespeople as well as their avatar (or contact photo). The avatar will be used as the pinpoint graphic for the individual sales person on your OSM-based latest location map.

You will add the following fields to the person form (see table 1).


Table 1. Adding fields to the person form
FieldTypeValue
fullnameText Computedfullname
emailaddressText Computedemailaddress
phonenumberText Computedphonenumber
companyText Computedcompany
$$returnText Computed for Display[http://" + @GetHTTPHeader("host") + "/" + @WebDbName + "/index.xsp]
$V2AttachmentOptionsText Computed for DisplayREM {Hides the attachments from the footer};
"0"

The first four fields in table 1 (fullname, emailaddress, phonenumber, and company) will be used to store the contact information for a given sales person.

The $$return field is a special functional field used to either post response information post NotesDocument submission/update or, in your case, used for redirection to a given URL. You will redirect the user to the index.xsp XPage, which will act as the main page/dashboard for your application.

The $V2AttachmentOptions field is another special functional field that, when set to "0", hides file attachments from the Lotus Domino RAD-rendered user interface. As you plan to include a file upload control for the express purpose of allowing an avatar (or Contact photo) to be added per person entry, you will want to properly handle file attachments to the Person NotesDocuments when rendered in the Web browser client.

You will use some known Lotus Domino Web development techniques for developing more advanced Web browser applications. For the example, you will be merging your XHTML template into the person form through a combination of pass-through HTML, computed text objects, hide-when formulas, subforms, embedded views, and form design element attributes. The result can be seen in the included example application in the person form design element.

As will be discussed later, locations will be children/response NotesDocuments of their person NotesDocument. Thus, you will use an embedded single category view on your person form design element to allow a user to see all location entries per sales person directly from their rendered person NotesDocument. You will also easily create a new location NotesDocument through the ParentUniqueID Lotus Domino URL command.

The people view

As you will be using a $$ViewTemplateDefault to better structure both your people and location views, your build for the people view design element will be relatively simple. You will create five columns; the first four are hidden (see table 2).


Table 2. The people view build
ColumnValue
1 - Hiddenfullname
2 - Hiddenemailaddress
3 - Hiddenphonenumber
4 - Hiddencompany
5 - Visible _doc := "people/" + @Text(@DocumentUniqueID);
_img := @If(@AttachmentNames = ""; ""; "<img src=\"" + _doc + "/$file/"
+ @Subset(@AttachmentNames; -1) + "\" />");
_markup := "
<tr>
<td class=\"avatar\"><a href=\"" + _doc
+ "?OpenDocument\">" + _img + "</a></td>
<td class=\"contactinfo\">
<span class=\"fullname\">" + fullname + "</span>
<span class=\"emailaddress\">" + emailaddress + "</span>
<span class=\"phonenumber\">" + phonenumber + "</span>
<span class=\"company\">" + company + "</span>
</td>
</tr>";
@Trim(_markup)

You will then set the Treat View contents as an HTML attribute from the View Properties dialog box.

The generated markup will render an HTML table row with two columns containing your contact list information as well as an HTML link that will open the given NotesDocument. This markup will be used not only by your $$ViewTemplateDefault to render the user interface for your people view, but you will also be using this markup in your XPages dashboard.


The location list

Next, you will use form and view design elements to build a simple engine, allowing sales people or manager users to enter the location of a given sales person. The latest location entry will be used in combination with the sales person contact information and an individual avatar for the OpenStreetMap POI map mashup on your dashboard XPage design element.

The location form

Just like with your person form, you will create a simple location form design element, the location form, which will be a child/response NotesDocument for a given person NotesDocument. As each location entry will require the longitude and latitude data for a given address, you will be adding simple integration with the GeoCoder free address lookup public Web service (see table 3).


Table 3. Adding fields to the location form
FieldTypeValue
fullnameText Computedfullname
descriptionText Computeddescription
timestampDate/Time Computed@If(timestamp = ""; @Now; @TextToTime(@Text(timestamp)))
addressText Computedaddress
latitudeText Computedlatitude
longitudeText Computedlongitude
$$returnText Computed for Display"[http://" + @GetHTTPHeader("host") + "/" + @WebDbName + "/index.xsp]"

As with your person form, the location form design element will use a combination of design elements and Lotus Domino Web development techniques to render a simple, yet pleasing user interface that matches that of your XHTML and CSS template.

To help the user enter the latitude and longitude information, you will add a simple button and iframe object through pass-thru HTML and a simple JavaScript function to the location form design element's JS Header attribute. This will be used to allow the user to look up the location entered into the address field on the Location Form through simple IFRAME-based integration with the aforementioned GeoCoder free address lookup public Web service.

Let's look at the markup and script used to build the GeoCoder Web service integration, as shown in table 4.


Table 4. Markup and script to build the GeoCoder Web service integration
ElementPass-thru HTML
button<input type="button" name="geocode_lookup"
onclick="geocode(document.forms[0].address.value);" value="Get GeoCode!" />
iframe<div id="geocode_container" class="hidden">
<h2>GeoCode Address Information</h2>
<iframe name="geocode" id="geocode" src="blank.html"></iframe>
</div>
CSS.hidden {
display: none;
}
JavaScript function geocode(location) {
if (location!= "" ) {
var strURL = "http://rpc.geocoder.us/service/csv?address="
+ unescape(location);
document.getElementById("geocode").src = strURL;
document.getElementById("geocode_container").className = "";
} else {
alert("Please enter a valid address before you continue!");
}
}

When called, the geocode JavaScript function checks the submitted value and, when not blank, submits the location to the GeoCoder Web service by setting the source URL of the geocode IFRAME and defining a blank ("") class for geocode_container DIV. As this DIV is hidden by default in the user interface through its .hidden class assignment, the runtime blanking of the DIV's class acts to un-hide or immediately display the IFRAME contents.

NOTE: You will notice the inclusion of the blank.html designation as the default URL source for the geocode IFRAME. You can simply create a blank page design element called blank.html to serve this purpose. This provides the geocode IFRAME with a default (and thus resolves several cross-browser DOM scripting issues) when dealing with IFRAME-based mashups.

As previously mentioned, the Location NotesDocuments will be children/responses to the given parent (Person NotesDocument). The Person form design element will include simple markup that creates a button-like link that when launched will create a new Location entry that is a child/response to the given Person NotesDocument through the following Lotus Domino URL command syntax: Location?OpenForm&ParentUNID=Person_Document_UNID.

To complete the location form design element, as well as complete this parent/child relationship architecture, you will simply change the form design element type to Response (see figure 4).


Figure 4. Location form design element properties
Location form design element properties

You will then choose the second tab to open the form design elements On Create option, and check Formulas inherit values from selected document, as shown in figure 5.


Figure 5. Location form On Create option

The Locations and embLocations views

You will create two view design elements, Locations and embLocations, to display the location NotesDocuments throughout the project. These views, much like the people view design element, will be simple views because you will be using the $$ViewTemplateDefault for user interface rendering (for the locations view) or simply embedding the view (for the embLocations view) as a component of the previously built person form design element. You will review the build of both the Locations and embLocations view design elements in this section of the tutorial.

NOTE: As these views will contain NotesDocuments that are responses, you will disable the Show response documents in a hierarchy view design element option for both your Locations and embLocations views (see figure 6).


Figure 6. Disabling the Show response documents in a hierarchy view design element option
Disabling the Show response documents in a hierarchy view design element option

As mentioned, the build for both of these view design elements will be simple enough and will mirror the build of the people view. The views will contain no column header information, and most of the columns will be hidden from user interface rendering and are specifically for XPage data source usage, as shown in table 5.


Table 5. The location view design element
ColumnValue
1 - Hiddenfullname
2 - Hiddendescription
3 - Hiddentimestamp
4 - Hiddenaddress
5 - Hiddenlatitude
6 - Hiddenlongitude
7 - Visible <tr><td class=\"select\"><a href=\"locations/" +
@Text(@DocumentUniqueID) + "?EditDocument\"><img src=\"page_edit.png\"
/></a></td>" + @NewLine +
<td class=\"description\"><span>" + description +
</span></td>" + @NewLine +
<td class=\"timestamp\"><span>" + @Text(@Date(timestamp))
+ "<br />" + @Text(@Time(timestamp)) + "</span></td>" + @NewLine +
<td class=\"person\"><span>" + @Name([CN]; fullname)
+ "</span></td></tr>" + @NewLine

Just like the people view, the locations view will be used as both a data source for your dashboard XPage and for user interface rendering (see table 6).


Table 6. The embLocations view design element
ColumnValue
1 - Hidden, Categorizedfullname
2 - Hidden, Descendingtimestamp
3 - Visible <tr><td class=\"select\"><a href=\"locations/"
+ @Text(@DocumentUniqueID) + "?EditDocument\"><img src=\"page_edit.png\"
/></a></td>" + @NewLine +
<td class=\"description\"><span>" + description + "</span></td>"
+ @NewLine +
<td class=\"timestamp\"><span>" + @Text(timestamp) + "</span></td>"
+ @NewLine +
<td class=\"person\"><span>" + @Name([CN]; fullname)
+ "</span></td></tr>" + @NewLine

The embLocations view is designed specifically for use as an embedded single category view object in the person form design element. When the Single Category attribute is set to fullname, the person form design element will render all location entries for the given user, latest/active location first, as HTML Table Row objects (see figure 7).


Figure 7. Person form design element rendering all location entries for a given user

For more details on the specific builds of the design elements that will handle the person and location NotesDocument management, review the design of Big Brother because the application contains many additional known Lotus Domino Web development techniques (see Downloads).

4 of 10 | Previous | Next

Comments



static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=359309
TutorialTitle=XPages, Themes, and Mashups in Domino Web Application Development
publish-date=12162008