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:  

The dashboard

In this section, you will use an XPage design element to build a functional dashboard mashup for Big Brother. To build the dashboard, you will first concentrate on the user interface of the XPage before adding the OpenStreetMap POI map integration.

The index.xsp (or dashboard) XPage

NOTE: As I write more and more XPage applications, I find myself all but ignoring the design panel and focusing more on the source pane and properties panel. This familiarity with the source pane is almost a requirement when using pass-thru XHTML markup with XPages development.

You will begin your XPage build by using your legacy XHTML template because you want to maintain the look and logical flow of the existing Lotus Domino Web application. XPages allows for the direct entry of XHTML, CSS, and JavaScript markup through the source pane. You will start by creating a new XPage named index, and through the source pane you will add the structural markup that will define the dashboard layout.

Once created, the index.xsp XPage will have the default markup shown in figure 8.


Figure 8. Default markup
default markup

By adding your structural template markup (consists of DIV, SPAN, and TABLE elements) directly into the source pane, you can see the legacy user interface-friendly XPage take shape (see figure 9).


Figure 9. Structural template markup
Structural template markup

If you were to toggle to the design pane right now, you would see the user interface rendering of the index.xsp XPage shown in figure 10.


Figure 10. User interface rendering of index.xsp XPage
User interface rendering of index.xsp XPage

After you have added all of your structural pass-thru markup, you will be ready to start using more advanced XPage controls to deliver user interface content from defined data sources from within your Lotus Domino application.

For this particular XPage, you will use two data sources: the people and locations views from the example NotesDatabase. Each of these data sources will be used to populate pass-thru DIV and TABLE elements, and they will be used to add functionality to the application's dashboard.

To define data sources for an XPage, you can choose to either use the XPage data panel in combination with the define data source dialog-based wizard or to define those data sources directly through the source pane through XPage markup. Let's review both options.

Defining a data source in the data panel

To start, select Define Data Source from the data panel drop-down list (see figure 11).


Figure 11. Select Define Data Source from the Data Panel drop-down list
Select Define Data Source from the Data Panel dropdown

Now choose the Lotus Domino View or Lotus Domino Document (Form) that will act as your data source through the Define Data Source - Data Source Selection dialog. Both data sources will come from the people and locations Lotus Domino views (see figure 12).


Figure 12. Define Data Source - Data source selection dialog
Define Data Source - Data Source Selection Dialog

Next, you need to complete the Define Data Source dialog wizard by selecting the application, view and data source name as shown in figure 13.


Figure 13. Define Data Source - Lotus Domino view dialog
Define Data Source - Lotus Domino view dialog

Defining a data source in the source pane

In this instance you define the data sources directly through the source pane through XPage markup as shown in listing 6.


Listing 6. Defining data sources directly through the source pane

    <xp:this.data>
        <xp:dominoView var="people" viewName="people"></xp:dominoView>
        <xp:dominoView var="locations" viewName="locations"></xp:dominoView>
    </xp:this.data>

After you become more familiar with XPages, direct source pane markup creation and maintenance will become the obvious choice. For those who are new to XPages development or even those who prefer a more visual RAD experience, the data panel option is available.

Now that you have your data sources, you can begin using additional XPage controls to render content from NotesDocument data. Specifically, you will use XPage repeat controls and computed field controls to pull the HTML view columns from both the people and locations Lotus Domino view data sources and use that markup to create table rows for TABLE container elements created through your pass-thru markup.

For this tutorial, you will focus on the People Data Source Repeat Control + Computed Field Controls + Pass-Thru markup TABLE element, as both the people and locations use identical builds (rendering of the HTML view column into control-driven pass-thru markup).

From the source pane, the end-result XPage markup looks like listing 7.


Listing 7. End-result XPage markup

<table>
    <tbody>
        <xp:repeat var="people_entry" indexVar="people" 
value="#{people}" id="portletPeople">
            <xp:text escape="false" id="computedField5" 
value="#{people_entry.html}">
            </xp:text>
        </xp:repeat>
    </tbody>
</table>

This simple XPage markup defines a repeat control for the people data source: value="#{people}" while defining a variable for reference per-NotesDocument in the rendered data source: var="people_entry".

This is used by the computed field control to render the contents of the HTML Notes View Column: value="#{people_entry.html}".

And because the HTML Notes view column in both the people and locations views renders XHTML table row markup per NotesDocument, this results in a very simple rendering of the markup in your index.xsp XPage.

Now that you have an understanding of how the repeat control and computed field control will work to deliver your desired user interface rendered content, let's take a look at how you got them into your XPage.

You can add a repeat control to your index.xsp XPage either through the addition of direct XPage markup through the source pane or, as most of you will, through the design pane through the controls panel. The controls panel is divided into three main sections: Core Controls, Container Controls, and User Added Controls. You will find the repeat control in the container controls section, which can easily be dragged and dropped onto the design pane once selected (see figure 14).


Figure 14. Control Panel - Container Controls - Repeat control
Control Panel - Container Controls - Repeat Control

Once added to your XPage, the repeat controls properties panel will allow you to bind the repeat control to a given data source, as well as to specify the starting index, repeat limit, and other various functional properties. Here, however, you can define the collection name that you will use in combination with your computed field to render the aforementioned table rows (see figure 15).


Figure 15. Repeat control - properties panel
Repeat Control - Properties Panel

The computed field control, grouped in the core controls section, can just as easily be dragged and dropped from the control panel to the XPage design pane.


Figure 16. Control Panel - Core Controls - Computed Field control
Control Panel - Core Controls - Computed Field Control

Once added to your XPage, the computed field control properties panel will allow you to define various properties including the rendered content type as well as bind a value to your repeat control data source through use of the repeat control's defined variable (see figure 17).


Figure 17. Computed Field Control - Properties Panel - All Properties
Computed Field Control - Properties Panel - All Properties

Thus, the computed field will not auto-escape (content type set to HTML).

As the HTML Notes view column in both the people and locations views does the markup generation, you are simply looking to the Notes view column and using those rendered contents to create your HTML TR and TD elements for usage with your pass-thru TABLE element containers.


The OpenStreetMap POI map Mashup

Now that you have your XPage repeat controls and computed field controls rendering your people and locations entries in your dashboard, you can add the OpenStreetMap Points Of Interest (POI) map integration into your XPage. The POI map example that you will use relies on each point being a combination of person data and the latest location data for that person data. In addition the data is rendered with tab-delimited values and carriage return entry separators delivered to the Web browser client as plain text.

Because the example project has each location entry act as a child/response NotesDocument per each person NotesDocument, you can easily achieve this runtime data merge and delivery through a simple Lotus Domino agent design element. And since you can control the rendered content type returned by your Lotus Domino agent, this is the ideal design element to deliver the POI data required to render the OpenStreetMap POI map on your index.xsp XPage.

Let's start your Lotus Domino agent build by creating a new agent named locations.txt. The logic behind this agent is to get all people NotesDocuments from the people NotesView, and check to see if the person NotesDocument has at least one child/response entry location. If one is found, it builds a single tab-delimited entry that merges the Person NotesDocument data with the last location NotesDocument in the .responses-based NotesDocumentCollection. As the last location, NotesDocument in the NotesDocumentCollection will act as the latest Location entry, and the merged data will display the latest location information for the POI map based on the following API schema: lat lon title description icon iconSize iconOffset.

(The listed URL shows more information on the formatted example location data for the POI map: http://wiki.openstreetmap.org/wiki/Openlayers_POI_layer_example).

Once you build your person and location data entries, you simply use print statements in your Lotus Domino agent to both control the rendered content type and rendered tab-delimited, carriage return-separated entries (see listing 8).


Listing 8. Using print statements in the Lotus Domino agent to control content type and render tab-delimited, carriage return-separated entries

Print |Content-Type: text/plain|
Print |lat| + Chr(9) + |lon| + Chr(9) + |title| + Chr(9) +
|description| + Chr(9) + |icon| + Chr(9) + |iconSize| + Chr(9) + 
iconOffset| + Chr(13)
Print content + Chr(13)

And with a completed locations.txt Lotus Domino agent, you can add the pass-thru JavaScript markup and HTML BODY element onload event trigger that will render the OpenStreetMap POI map directly in your index.xsp XPage.

First, however, you will add the OpenStreetMap and OpenLayers remote JavaScript libraries to your XPages, for which I recommend you use the source pane and the following XPage markup (see listing 9).


Listing 9. Adding OpenStreetMap and OpenLayers JavaScript libraries to your XPages

<xp:this.resources>
    <xp:script src="http://www.openlayers.org/api/OpenLayers.js"
        clientSide="true">
    </xp:script>
    <xp:script src="http://www.openstreetmap.org/openlayers/OpenStreetMap.js"
        clientSide="true">
    </xp:script>
</xp:this.resources>

NOTE: You can do this through the XPage properties panel, in the resources section, but that doesn't allow for the addition of remote JavaScript libraries, but rather limits the selection to in-NotesDatabase JavaScript Library design elements. To achieve the same results as direct XPage markup creation, you can select an in-NotesDatabase JavaScript Library design element, and modify the generated markup in the source pane, replacing the in-NotesDatabase script source attribute with the external JavaScript Library URI.

Now that you have your OpenLayers and OpenStreetMap remote JavaScript libraries, you can add the following pass-thru JavaScript directly to your index.xsp XPage through the source pane (see listing 10).


Listing 10. Adding the pass-thru JavaScript directly to your index.xsp XPage

<script type="text/javascript">
    var map;
    function init(){ map = new OpenLayers.Map('map', { maxExtent:new
        OpenLayers.Bounds(-20037508.34,-20037508.34,20037508.34,20037508.34),
        numZoomLevels: 19, maxResolution: 156543.0399, units: 'm',
        projection: new OpenLayers.Projection("EPSG:900913"),
        displayProjection: new OpenLayers.Projection("EPSG:4326") });

    var layerMapnik = new
        OpenLayers.Layer.OSM.Mapnik("Mapnik(updated weekly)");

    var layerTah = new
        OpenLayers.Layer.OSM.Osmarender("Tiles@Home");

    map.addLayers([layerTah, layerMapnik]);

    var pois = new OpenLayers.Layer.Text( "My Points", {
        location:"locations.txt", projection: new
        OpenLayers.Projection("EPSG:4326")} ); map.addLayer(pois);

    map.addControl(new OpenLayers.Control.LayerSwitcher());

    map.setCenter(new
        OpenLayers.LonLat(-73.9870,40.7561).transform(new
        OpenLayers.Projection("EPSG:4326"), new
        OpenLayers.Projection("EPSG:900913")), 2); }

    dojo.addOnLoad(init);

</script>

This pass-thru JavaScript defines the init() function, which builds your OpenStreetMap POI map in the map HTML DIV element that you've added to the index.xsp XPage referencing functions defined in the remote JavaScript Libraries just added to the XPage. As all XPages use the Dojo JavaScript libraries, you can simply call the dojo.addOnLoad function, which acts to add the init() function to your XPage HTML BODY element's onload event.

At this point, you will have a completely functional, yet completely ugly user interface for your dashboard, as you have yet to include the stylesheet resource in your index.xsp XPage. The easiest way to do this is through the resources section of the XPage properties panel (see figure 18).


Figure 18. Add Stylesheet to page dialog - XPage resources
Add Style Sheet to Page Dialog - XPage resources

By selecting your main.css stylesheet resource, you've created the following XPage markup in listing 11 and included the stylesheet in the HTTP header of your Web browser client-rendered index.xsp XPage.


Listing 11. XPage markup

<xp:this.resources>
    <xp:script src="http://www.openlayers.org/api/OpenLayers.js"
        clientSide="true">
    </xp:script>
    <xp:script src="http://www.openstreetmap.org/openlayers/OpenStreetMap.js"
        clientSide="true">
    </xp:script>
    <xp:styleSheet href="/main.css"></xp:styleSheet>
</xp:this.resources>

With that addition, you now have a completely functional XPage-based dashboard for your build project (see figure 19).


Figure 19. The index.xsp XPage - OpenStreetMap POI map and Lotus Domino data mashup
The index.xsp XPage - OpenStreetMap POI Map and Lotus Domino Data Mashup

Although it may seem as if you've completed Big Brother, there is a new technology provided to Lotus Domino Web application developers that will not only allow you to centrally control the rendered XPage RAD markup, but also allow you to bind stylesheet and script library resources to specific elements or across all Lotus Domino design elements.

5 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