Figure 1: WEB FORM DESIGN WITH MULTIPLE BUTTONS--Both the hotspot button and the action bar button will be rendered in HTML.

Figure 2: FORM PREVIEWED IN WEB BROWSER--Domino R4.6 can depict more than one button.

Figure 3: JAVASCRIPT ADDED BY DOMINO--Domino adds JavaScript to track which button the user clicks.

66ce0207b3b26ec0852565ba005a4597/$Body/0.10

In Figure 3, notice that the UNID of the subform-based Register button from Figure 1 is different than the UNID of the Save and Continue Later button, which is stored on the form.

Some other interesting things to know about this new database property are

_ Domino only saves the document to disk during an HTTP submit if the clicked button formula contains @Command([FileSave]).
_ Domino handles the click tracking a little differently for documents in read mode, but it does not affect the techniques here.
_ The form UNID does not have to be the same form Domino is rendering. It can be any form, subform, view, or navigator in the database.
_ The item identifier in the Notes formula address is always "0.10" for the first object in the body of a form.

These last two observations will prove useful in Example 1, below.


Combining JavaScript with Notes actions

This article includes several techniques for combining JavaScript with Formula language, LotusScript, and Java. The techniques you will want to consider for your applications will depend on whether you want to execute the JavaScript first, or the Notes action first. Therefore, these example techniques are organized by JavaScript execution sequence.

Some of these examples use the new database property Web pages: use JavaScript. Some examples do not use this feature, although they are included here because they solve the same class of development problem: combining JavaScript and Notes actions into a single button.


Example 1. JavaScript followed by a Notes formula

Suppose you want your user to click a Save button, which first checks to see if the user has entered data into a particular field. If the field is blank, JavaScript pops up a message reminding them to fill-in that field.

This was fairly straightforward in the simple button behavior of Domino 4.5. However, if you want to render multiple buttons using the Web access: use JavaScript property, you’ll find that a regular HTML submit action does not actually save the document. This is due to the fact that, when this database property is enabled, Domino R4.6 will only save the document to disk when the user has clicked on an active element that includes an @Command([FileSave]). Therefore, you have to leverage your knowledge of how this new R4.6 database property works to trick Domino into executing your formula.

To cause your button formulas to execute, this technique first runs a custom JavaScript routine, then submits the page by passing to the _doClick() function the Notes address for the formula that Domino should execute. Finally Domino executes that formula and returns the user to the resulting document.

Here are the step by step instructions for implementing this technique.

1. Create a new form called ButtonSave. This form will be used only to store the button created in Step 2.
2. Create a button in the upper left corner containing the code that you want to execute. For example,

@Command([FileSave]);
@Command([FileCloseWindow])

Figure 4: BUTTONSAVE FORM--Each button formula is stored on a dedicated form.
This keeps the Notes formula address predictable and consistent, regardless of where we place the button.

<A HREF="javascript:_doClick('66ce0207b3b26ec0852565ba005a4597/$Body/0.10')

and buttons will start with the format

<INPUT TYPE=button onClick="_doClick('66ce0207b3b26ec0852565ba005a4597/$Body/0.10')

Copy to the clipboard the Notes formula address. This is the portion of the _doClick function call that lies between the single quotes.

6. Paste the Notes formula address (copied from Step 4) in between the single quotes of your JavaScript _doClick function call in Step 3, in place of the [--PUT FORMULA ADDRESS HERE--].

7. Re-mark the entire JavaScript and HTML areas as Pass-thru HTML, since text pasted from outside Notes is, by default, not marked as pass-thru HTML.

Figure 5: FRONT-END FIELD VALIDATION IN JAVASCRIPT--
The Input button named Register triggers the custom JavaScript validation routine.
The HTML button can be moved anywhere on the form without
affecting the Notes formula address of the button in Figure 4.

8. Preview the web form in your web browser.

Figure 6: WEB OUTPUT--JavaScript validation is possible, even with the database property
'Web access: use JavaScript when generating pages' enabled.

Notice that JavaScript first validates your entry in the EmailAddress field, then calls the Notes formula in the ButtonSave form to perform the save to disk. This example is very simple, but you could add any other JavaScript in the Save() function. You could also make the ButtonSave Notes formula much more complex.

One important point to understand is why you should place the button on its own form. This allows you to change where the HTML button occurs on your web form without changing the critical Notes formula address of the button in Figure 4. If the Notes button were stored on your web form, its formula address would change whenever you change the position of that button on the web form. By giving each button its own form, you can move the HTML button tag all you like without worrying that the formula address will change. In fact, to further modularize the button implementation, you may wish to use a shared field in your JavaScript, instead of hardcoding the Notes formula address. Then you only have to update that shared field once, while you use the same button on several forms.

This technique can be used for many other powerful features, such as refreshing fields automatically when the value of an HTML Select drop down keyword field changes.

Caveats
In this technique, forms that are manually copied from one database to another get their UNID reassigned, and therefore your Notes formula addresses for buttons on such forms must be manually changed in any JavaScript calls. Forms that are deployed using an OS-level file copy, database-level copy, replication, and design refresh/replace do not change their UNID and therefore do not need updating.

It is possible to dynamically determine the UNID of a form from the form name as a page is being served, but it requires a LotusScript call to a Notes API function and may significantly reduce performance.

Example 2. Notes formula followed by JavaScript

Suppose you want your user to click a button which immediately executes a @DbLookup formula and displays some output in a JavaScript pop-up alert window. In this technique, Notes writes the output of a multi-line formula to a place on the form which, when returned to the browser, constitutes some data or instruction in a JavaScript routine. This technique requires R4.6 and the database property..."Web access: use JavaScript when generating pages" enabled.

1. On your form, place the following

<SCRIPT language="JavaScript">
message = [--NOTESFIELD--] ;
if (message != "") {
alert(message);
}
</SCRIPT>

2. In place of the [--NOTESFIELD--], put a Notes computed field named PopUpMessage, with a formula

PopUpMessage

3. Create a Notes button containing your code. At the end of your formula, include a statement that writes your message to the PopUpMessage field, such as

FIELD PopUpMessage := PopUpMessage;

Exists := !@IsError(@DbLookup("":"NoCache"; "":""; "Entries"; EmailAddress; 1));

@If(Exists;
@SetField("PopUpMessage"; "The email address " + EmailAddress + " has already been registered! You can only register each email address one time.");
@Do(@Command([FileSave]);
@Command([FileCloseWindow]))
)
Note that the formula in step 3 assumes that you have a view named Entries with first column sorted on EmailAddress.

Figure 7: NOTES FORMULA FOLLOWED BY JAVASCRIPT--The Register button writes output to the PopUpMessage field, which feeds a JavaScript pop up alert routine when the form is served back to the user.

Figure 8: WEB OUTPUT--Robust data validation against existing records, combined with friendly pop up alerts.

Suppose you want to create a button that executes a LotusScript agent on the current page, but only after getting a confirmation from the user. In this technique JavaScript handles the confirmation, then executes a back-end Notes Agent via URL. In the URL, JavaScript passes to the agent the Universal ID (UNID) of the document to be processed. The agent uses this UNID to get and process the document, and then redirects the user back to the document to see the result. This technique requires R4.5+, and does not require the database property "Web Access: Use JavaScript when generating pages".

1. Create an HTML button by adding this pass-thru HTML code to your form

<form><INPUT type="button" value="Run Agent" onClick="javascript:runAgent();"></form>

<SCRIPT language="JavaScript">
function runAgent() {
// Here, place any JavaScript you'd like to run before executing the agent
if (confirm('Click OK to process this document.')) {
self.location.href='/[--NOTESFIELD_1--]/myAgent?OpenAgent&[--NOTESFIELD_2--]';
}
}
</SCRIPT>

2. Place on the form a Notes computed for display field named Message, with a formula

Message

3. In place of the [--NOTESFIELD_1--], put a Notes computed for display field named dbName, with a formula

@Subset(@DbName; -1)

4. In place of the [--NOTESFIELD_2--], put a Notes computed for display text field named ThisDocUNID, with a formula

@Text(@DocumentUniqueID)

Figure 9: JAVASCRIPT FOLLOWED BY LOTUSSCRIPT--
The Run Agent HTML button executes JavaScript first, then triggers a Notes agent via URL.

5. Create an agent named myAgent

6. Set Which document(s) should it act on to 'Run once (@Commands may be used)'

7. Enter the following LotusScript code:

Sub Initialize
Dim s As New NotesSession
Dim thisDB As NotesDatabase
Dim thisDoc As NotesDocument
Set thisDb = s.currentDatabase

'...From the URL, get the UNID of the current document and use it to get a handle to the doc
thisDocId = Right$(s.DocumentContext.QUERY_STRING(0), 32)
Set thisDoc = thisDB.GetDocumentByUNID( thisDocId )

'...process the document
thisDoc.Message = "LotusScript wrote this"
'...
'...update the document and return the user to it in edit mode
Call thisDoc.save(True, True)
redirect$ = "[" & thisDB.FileName & "/$defaultView/" & thisDoc.UniversalID & "?editDocument]"
Print redirect$ '...redirect the user
End Sub

7. Save the agent. Then preview the web form in your web browser and test it out. I added an editable field and a Save button to easily allow me to save the new document to disk, a necessary step before LotusScript can act on the document.

Figure 10: WEB OUTPUT--JavaScript can trigger a Notes agent,
which can write output to the current document and represent the document back to the user.

In this example, imagine you want a web button that pops up an alert window displaying the size of the current database. First, this button will call a LotusScript agent via URL. The agent will do some processing and return a stream of HTML to the browser. This HTML will include JavaScript code to alert the user with the output from the LotusScript agent. This technique requires R4.5+, and does not require the database property "Web Access: Use JavaScript when generating pages".

1. Create an HTML button by adding this pass-thru HTML code to your form:

<form><INPUT type="button" value="Check Size of this database" onClick="location.href='/[--NOTESFIELD--]/CheckSize?OpenAgent'"></form>

2. In place of the [--NOTESFIELD--], put a Notes computed for display field named dbName, with a formula:

@Subset(@DbName; -1)

3. Create an agent named CheckSize

4. Set Which document(s) should it act on to 'Run once (@Commands may be used)'

5. Enter the following LotusScript code

Sub Initialize
Dim s As New NotesSession
Dim thisDB As NotesDatabase
Set thisDb = s.currentDatabase

messageText$ = "This database is " & thisDb.Size & " bytes."
PopUpMessage$ = |<SCRIPT language="JavaScript">| &_
| alert("| & messageText$ & |"); | &_
| location.href="./" | &_
| </SCRIPT> |

Print PopUpMessage$ '...send the javascript to the user
End Sub

6. Save the agent, then Preview the web form in your web browser and test it out.

Figure 11: WEB OUTPUT--LotusScript can write data back to a JavaScript routine,
bringing back end Notes integration functionality to the front-end form.