A Guide to Field Pre-population for IBM Lotus Notes Domino Web Apps

06/16/2010 01:20 AM by Chris Toohey

Pre-populating Fields via Query String Parameters is really the first step to developing custom APIs for your IBM Lotus Notes Domino applications. Once you understand the possible relationship between URL and the available View layer (for MVC enthusiasts), you can combine NotesData management with functional Domino URL Commands to create some pretty slick features for your apps.

This article will show you how you can pre-populate UI Fields on both Traditional Form Design Elements and XPages via URL Query String Parameters.

By the end of this article, you will be able to use this technique in your IBM Lotus Notes Domino Web Applications regardless of version or release of the Domino Server.

Build Synopsis
Traditional Form Design Elements
XPage Design Elements
Conclusion

Build Synopsis

We will be creating 2 HTML Forms: the first via a Traditional Form Design Element, and the second via an XPage Design Element.

Each HTML Form will allow for the pre-population of 3 fields via the submitted URL Query String: firstname, lastname, and emailaddress.

Back to Top

Traditional Form Design Elements

I start by creating a simple Form Design Element named document, and add my 3 Fields (firstname, lastname, and emailaddress):

When previewed in a Web Browser Client, we see a very basic Domino RAD-rendered HTML Form:

So far, we have no Query String Parameters defined, nor any handler for those Query String Parameters. Let's add our firstname, lastname, and emailaddress Query String Parameters, which will change our URL syntax to the following:

document?OpenForm&firstname=Chris&lastname=Toohey
&emailaddress=ctoohey@dominoguru.com

Simply adding the Query String Parameters -- even if they match our UI Fields (which in this case they do) -- does not automatically pre-populate a Domino-rendered HTML Form... and with good reason.

Imagine in a workflow-based application if I was able to change the URL Query String and have it populate an application logic-controlled UI Field. Bad stuff there...

But this won't work for a very basic reason: there is no native handler in Domino for random Query String Parameters. There are several examples of functional handlers for Query String Parameters -- such as ?openview&count=10 -- but those are part of the standard Domino HTTP stack.

For our firstname, lastname, and emailaddress Query String Parameters, we'll need to build our own handler... which is thankfully quite simple with Traditional Form Design Elements.

Each editable Field in a Form Design Element allows for a Default Value. Simply add the following @Formula to each Field's Default Value:

1. @URLQueryString(@ThisName)

This relies on a 1:1 match of Query String Parameter and your UI Form Field names... but you could just as easily replace @ThisName with the Query String Parameter name.

Once we've added the Query String Parameters and our Default Value @Formula handlers, we'll have a URL-driven pre-populated HTML Form:

For those of you interested in the document Form Design Element DXL:

1. <richtext>
2.     <pardef id='1' />
3.     <par def='1' />
4.     <par def='1'>
5.         First Name:
6.         <field type='text' kind='editable' name='firstname'>
7.             <code event='defaultvalue'>
8.                 <formula>@UrlQueryString(@ThisName)</formula>
9.             </code>
10.         </field>
11.     </par>
12.     <par def='1'>
13.         Last Name:
14.         <field type='text' kind='editable' name='lastname'>
15.             <code event='defaultvalue'>
16.                 <formula>@UrlQueryString(@ThisName)</formula>
17.             </code>
18.         </field>
19.     </par>
20.     <par def='1'>
21.         Email Address:
22.         <field type='text' kind='editable' name='emailaddress'>
23.             <code event='defaultvalue'>
24.                 <formula>@UrlQueryString(@ThisName)</formula>
25.             </code>
26.         </field>
27.     </par>
28. </richtext>

Back to Top

XPage Design Element

Like the Traditional Form Design Element, an XPage does not have a native handler for custom Query String Parameters. The good news is that building the handler in SSJS is just as simple!

I start by creating a simple XPage named document. I create a Data Source for this XPage, pointing it to the document Form Design Element. I drag-and-drop my UI Fields onto my XPage (firstname, lastname, and emailaddress):

When previewed in a Web Browser Client, we see a very basic Domino XPage RAD-rendered HTML Form:

As with the Form Design Element, the XPage does not have native custom Query String Parameter handlers. Thus, as we did with the Form Design Element, we will need to create a handler for our UI Field pre-population.

It's worth noting that unlike Traditional Design Elements, the XPage URL Syntax does not require a Domino URL Command as the first Query String Parameter. In the past, savvy developers would use the ?open&... syntax to simplify the URL Query String. With XPages, you can immediately begin with your custom Query String Parameters!

The URL syntax for our XPage UI Field pre-population:

document?firstname=Chris&lastname=Toohey
&emailaddress=ctoohey@dominoguru.com

Every Input Text Control in XPages has a Default Value, and we'll mirror our Form Design Element technique in our document XPage with the following SSJS:

1. defaultValue="#{javascript:context.getUrlParameter(this.id) ;}"

Adding the above SSJS to the firstname, lastname, and emailaddress Input Text Controls allow us to create the 1:1 Query String Parameter to UI Field handler, which allows us to easily pre-populate an XPage via URL!

For those of you interested in the DXL:

1. <xp:table>
2.     <xp:tr>
3.         <xp:td>
4.             <xp:label value="Firstname:" id="firstname_Label"
5.                 for="firstname">
6.             </xp:label>
7.         </xp:td>
8.         <xp:td>
9.             <xp:inputText value="#{thisDoc.firstname}"
10.                 id="firstname"
11.                 defaultValue="#{javascript:context.getUrlParameter(this.id) ;}">
12.             </xp:inputText>
13.         </xp:td>
14.     </xp:tr>
15.     <xp:tr>
16.         <xp:td>
17.             <xp:label value="Lastname:" id="lastname_Label"
18.                 for="lastname">
19.             </xp:label>
20.         </xp:td>
21.         <xp:td>
22.             <xp:inputText value="#{thisDoc.lastname}"
23.                 id="lastname"
24.                 defaultValue="#{javascript:context.getUrlParameter(this.id) ;}">
25.             </xp:inputText>
26.         </xp:td>
27.     </xp:tr>
28.     <xp:tr>
29.         <xp:td>
30.             <xp:label value="Emailaddress:" id="emailaddress_Label"
31.                 for="emailaddress">
32.             </xp:label>
33.         </xp:td>
34.         <xp:td>
35.             <xp:inputText value="#{thisDoc.emailaddress}"
36.                 id="emailaddress"
37.                 defaultValue="#{javascript:context.getUrlParameter(this.id) ;}">
38.             </xp:inputText>
39.         </xp:td>
40.     </xp:tr>
41. </xp:table>

Back to Top

Conclusion

As I mentioned at the top of this article, pre-populating Fields via Query String Parameters is really the first step to developing custom APIs for your IBM Lotus Notes Domino applications.

While not appropriate for all applications, the ease of implementation and simple extension of the techniques discussed in this article make pre-populating NotesData via URL Query String Parameters a no-brainer. Also, depending on the given application, this technique can be employed to create an integration point for other technology investments in your organization.

Hopefully you find this article helpful, and find a use for these simple yet highly extendable techniques.

A few notes:

@URLQueryString() and @ThisName were introduced in Release 6.0. Thus this code is only compatible with the platform from 2002 forward.

I have not yet tested the XPages Custom Query String Parameters technique in the Lotus Notes 8.5.1 Client. I have tested it in a Web Browser Client and was able to create a simple Lotus Notes Client Sidebar Widget which worked perfectly. I presume that as long as you are calling the XPage and passing it Query String Parameters when called, it should work fine.

Back to Top