Event descriptions

Simple action, Formula, LotusScript, JavaScript, and Java code executes in response to the occurrence of events in the following objects: actions, action hotspots, agents, hotspot buttons, databases, fields, folders, forms, formula pop-ups, outlines, pages, script libraries, subforms, and views.

You code the same event twice; once for the Notes client platform and once for the Web platform.

Note: The separate handling of Notes client and Web browser events is new for Release 6. See "Compatibility issues". The one exception to the 'coding same event twice' rule is with actions and shared actions. If you are designing in Release 6 and running in Release 5, you must code two separate actions, one for each platform. Use the hide-when formulas to hide an action from Notes or Web platforms.

Web events can be coded only in JavaScript. You can specify the same JavaScript code for both a Web event and its corresponding Notes client event.

The following table lists the events that can be handled using the formula language, LotusScript, JavaScript and Java code in the Notes client and Web browser environments. Non-programming handlers such as simple actions are also listed. For information on sequencing of events, see the table "Event sequencing." For information on the user interface, see "Exploring the Programmer's pane" and "Using the Objects tab."


Event	Run	Language	Object	Trigger
Action	Client	Formula Java LotusScript Imported Java Simple action(s)	Agent	Object is loaded
Click	Client	Formula LotusScript Simple action(s)	Action Action Hotspot Button Navigator object Picture Hotspot	Object is selected
Click	Client	Formula	Formula Popup	Object is selected
Column Value	Client Web	Field Formula Simple Function	Folder column View column	Object is loaded
Declarations	Client	LotusScript	Action Action Hotspot Agent Button Database Script Field Folder Form Globals Navigator object Page Picture Hotspot LotusScript Script Library Subform View	Object is loaded
Default Value	Client Web	Formula	Field	Document is created
Document Selection	Client	Simple Search	Agent	Object is loaded
Entering Note: Preferred is onFocus	Client	LotusScript	Field	Object is selected
Exiting Note: Preferred is onBlur	Client	LotusScript	Field	Object is deselected
Form Formula	Client Web	Formula	Folder View	Object is loaded
Frame - Client	Client Web	Formula	Outline Entry	Object is loaded
HelpRequest	Client	Formula	Folder View	Help is selected
Hide When	Client Web	Formula	Outline Entry	Object is loaded
HTML Attributes	Web	Formula	Field	Form is loaded
HTML Body Attributes	Web	Formula	Form Page	Form is loaded
HTML Head Content	Web	Formula	Form Page	Form is loaded
Image	Client	Formula	Outline Entry	Object is loaded
Initialize	Client	LotusScript	Action Action Hotspot Agent Button Database Script Field Folder Form Globals Navigator object Page Picture Hotspot LotusScript Script Library Subform View	Object is loaded
Input Enabled	Client	Formula	Field	Form is loaded
Input Translation	Client Web	Formula	Field	Document is saved
Input Validation	Client Web	Formula	Field	After Input Translation
InViewEdit Note: New with Release 6	Client	LotusScript	Folder View	View entry is edited: at query, validation, and save
JavaAgent	Client	Java	Agent	Object is loaded
Javascript Library	ClientWeb	JavaScript	Script Library	Object is loaded
Java class name	Client	Java	Script Library	Object is loaded
JS Header	Client Web	JavaScript	Form Page Subform	Object is loaded
Label	Client	Formula	Outline Entry	Object is loaded
ObjectExecute	Client	LotusScript	Action Action Hotspot Button	Object is activated by an OLE2 server that is FX/NotesFlow enabled
onBlur Note: New for LotusScript with Release 6	Client	JavaScript LotusScript	Field	Object is deselected
onBlur - Web	Web	JavaScript	Action Action Hotspot Button Field	Object is deselected
onChange Note: New with Release 6	Client	JavaScript LotusScript	Field	Contents of object change
onChange	Web	JavaScript	Field	Contents of object change
onClick	Web	JavaScript	Action Action Hotspot Button Field Form Page Picture	Object is selected
onDblClick	Web	JavaScript	Action Action Hotspot Button Field Form Page Picture	Double-click occurs on object
onFocus Note: New for LotusScript with Release 6	Client	LotusScript JavaScript	Field	Object is selected
onFocus	Web	JavaScript	Action Action Hotspot Button Field	Object is selected
onHelp	Client	Formula LotusScript JavaScript	Form Page	Help is selected
onHelp	Web	JavaScript	Action Action Hotspot Button Form Page Picture	Help is selected
onKeyDown	Web	JavaScript	Action Action Hotspot Button Field Form Page Picture	Any key is pressed
onKeyPress	Web	JavaScript	Action Action Hotspot Button Field Form Page Picture	An alphanumeric key is pressed
onKeyUp	Web	JavaScript	Action Action Hotspot Button Field Form Page Picture	Any key is released
onLoad Note: New for Formula and LotusScript with Release 6	Client	JavaScript Formula LotusScript	Form Page	Object is loaded
onLoad	Web	JavaScript	Form Page	Object is loaded
onMouseDown	Web	JavaScript	Action Action Hotspot Button Field Form Page Picture	Object is selected with either the right or left mouse button
onMouseMove	Web	JavaScript	Action Action Hotspot Button Field Form Page Picture	Mouse is moved over object
onMouseOut	Web	JavaScript	Action Action Hotspot Button Field Form Page Picture	Mouse is moved out of object
onMouseOver	Web	JavaScript	Action Action Hotspot Button Field Form Page Picture	Mouse is moved into object
onMouseUp	Web	JavaScript	Action Action Hotspot Button Field Form Page Picture	Mouse button is released over object
onReset	Web	JavaScript	Form	Object is reset
onSelect	Web	JavaScript	Field	Contents of object are selected
OnSubmit Note: New for Formula and LotusScript with Release 6	Client	Formula JavaScript LotusScript	Form Page	Before object is saved
onSubmit	Web	JavaScript	Form	Before object is saved
OnUnload Note: New for Formula and LotusScript with Release 6	Client	Formula LotusScript JavaScript	Form Page	Before object is unloaded
onUnload	Web	JavaScript	Form Page	Before object is unloaded
Options	Client	LotusScript	Action Action Hotspot Agent Button Database Script Field Folder Form Globals Navigator object Page Picture Hotspot LotusScript Script Library Subform View	Object is loaded
PostDocumentDelete	Client	Formula LotusScript	Database Script	After a document is deleted (the document is still available)
PostDragDrop	Client	Formula LotusScript	Database Script Folder View	After a drag and drop operation in object
PostEntryResize Note: New with Release 6	Client	Formula LotusScript	Folder View	After a resize operation in a calendar folder or view
PostModeChange	Client	Formula LotusScript JavaScript	Form Subform	After object is changed to Read or Edit mode
PostOpen Note: Preferred is onLoad for Form and Page	Client	Formula LotusScript	Database Script Folder Form Page Subform View	After object is opened
PostPaste	Client	Formula LotusScript	Folder View	After a paste operation
PostRecalc	Client	Formula JavaScript LotusScript	Form Page Subform	After object is refreshed (and values are recalculated)
PostSave	Client	Formula JavaScript LotusScript	Form Subform	After object is saved
PostSend Note: New with Release 6	Client	Formula JavaScript LotusScript	Form Subform	After object is sent
QueryAddToFolder	Client	Formula LotusScript	Folder View	Before a document is added to a folder
QueryClose Note: Preferred is onUnload for Form and Page	Client	Formula LotusScript	Database Script Folder Form Page Subform View	Object is being closed
QueryDocumentDelete	Client	Formula LotusScript	Database Script	Before a document is marked for deletion
QueryDocumentUndelete	Client	Formula LotusScript	Database Script	Before a document is unmarked for deletion
QueryDragDrop	Client	Formula LotusScript	Database Script Folder View	Before a drag and drop operation
QueryEntryResize Note: New with Release 6	Client	Formula LotusScript	Folder View	Before a resize operation in a calendar folder or view
QueryModeChange	Client	Formula JavaScript LotusScript	Form Subform	Before a document is changed to Read or Edit mode
QueryOpen	Client	Formula JavaScript LotusScript	Form Page Subform	Before object is opened
QueryOpen	Client	Formula LotusScript	Folder View	Before object is opened
QueryOpenDocument	Client	Formula LotusScript	Folder View	Before a document is loaded
QueryPaste	Client	Formula LotusScript	Folder View	Before a paste operation
QueryRecalc Note: New with Release 6	Client	Formula JavaScript LotusScript	Form Page Subform	Before object is refreshed (and values are recalculated)
QueryRecalc	Client	Formula LotusScript	Folder View	Before object is refreshed (and values are recalculated)
QuerySave Note: Preferred is onSubmit for Form	Client	Formula LotusScript	Form Subform	Before object is saved
QuerySend Note: New with Release 6	Client	Formula JavaScript LotusScript	Form Subform	Before object is sent
RegionDoubleClick	Client	Formula LotusScript	Folder View	Region in a calendar view or folder is double-clicked
Source	Client	Formula	Outline Entry	Object is loaded
Target Frame	Client Web	Formula	Form Page	Object is loaded
Target Frame (single click)	Client Web	Formula	Folder View	Object is loaded
Target Frame (double click)	Client Web	Formula	Folder View	Object is loaded
Terminate	Client	LotusScript	Action Action Hotspot Agent Button Database Script Field Folder Form Globals Navigator object Page Picture Hotspot LotusScript Script Library Subform View	Object is unloaded
Value	Client Web	Formula	Field	Computed field is calculated
View Selection	Client	Formula Simple Search	Folder View	Object is loaded
WebQueryOpen	Web	Formula	Form	Before object displays**
WebQuerySave	Web	Formula	Form	Before object is saved**
Window Title	Client Web	Formula	Form Page	Object is loaded

@Command([RunAgent];"agentname")
@Command([ToolsRunMacro];"agentname")

LotusScript subroutines and functions

You can add LotusScript subroutines and functions to an object. Your scripts are added to, and can be selected from, the list of events belonging to the object.

LotusScript Declarations and Options areas

Each object has a Declarations area where you can write non-executable LotusScript statements that apply to all LotusScript events in the object, and an Options area for statements such as Option, Use, UseLSX, and Const. Each form, folder, page, subform, and view has a Globals area where you can write non-executable LotusScript statements that apply to all LotusScript events in the object.

Current document in onLoad and PostOpen

Changes made to the current document in an onLoad or PostOpen event are treated as default values. The document is not marked as changed. If the user closes the document at this point, the onLoad or PostOpen changes are lost. You must explicitly save the changes, for example, with the Save method of NotesUIDocument, if you want to be sure they are applied.

Compatibility issues

In Notes Release 5 certain JavaScript events occur on the Notes client as well as the Web browser. In addition, Formula/LotusScript events that respond to the same user actions also occur on the Notes client. For example, both the onBlur and Exiting events occur when the Notes client user exits a field.

Release 6 distinguishes between the application of events to the Notes client and Web browser. You code one JavaScript or LotusScript event for the Notes client and a separate JavaScript event for the Web browser. Those JavaScript events that occur on the Notes client in Release 5 allow LotusScript and in some cases Formula in Release 6. The corresponding LotusScript-only events still occur, but their continued use in Release 6 applications is discouraged.

The following table lists the affected events:


User action	Event	Release	Occurs on	Language
Action, Action Hotspot, Button
Select object	onClick	R5 & Release 6	Web only	JavaScript
	Click	R5 & Release 6	Client only	LotusScript
Field
Enter object	Entering	R5 & Release 6	Client only	LotusScript
	onFocus	R5 & Release 6	Client & Web	JavaScript
		Release 6	Client only	LotusScript
Exit object	Exiting	R5 & Release 6	Client only	LotusScript
	onBlur	R5 & Release 6	Client & Web	JavaScript
		Release 6	Client only	LotusScript
Form, page
Open object	onLoad	R5 & Release 6	Client & Web	JavaScript
		Release 6	Client only	Formula LotusScript
	PostOpen	R5 & Release 6	Client only	Formula LotusScript
Close object	onUnload	R5 & Release 6	Client & Web	JavaScript
		Release 6	Client only	Formula LotusScript
	QueryClose	R5 & Release 6	Client only	Formula LotusScript
Save object	onSubmit	R5 & Release 6	Client & Web	JavaScript
		Release 6	Client only	Formula LotusScript
	QuerySave	R5 & Release 6	Client only	Formula LotusScript

In Notes Release 5, for example, if you code the onBlur event for FieldOne as follows:

with (window.document.forms[0]) {
  if (FieldOne.value == "foo") {
    FieldTwo.value = "bar"
  }
}

FieldTwo is set to "bar" if FieldOne is "foo" when the user exits the field in either a Web browser or the Notes client.

To duplicate this functionality in Release 6, you specify the code twice, once for the onBlur - Web event and again for the onBlur - Client event, or specify the code under "Common JavaScript."

If, in addition to coding onBlur, you code the Exiting event for FieldOne as follows:

Sub Exiting(Source As Field)
  Dim w As New NotesUIWorkspace
  Dim uidoc As NotesUIDocument
  Set uidoc = w.CurrentDocument
  If uidoc.FieldGetText("FieldOne") = "foo" Then
    Call uidoc.FieldSetText("FieldThree", "bar")
  End If
End Sub

FieldThree is also set to "bar" if FieldOne is "foo" when the user exits the field in the Notes client, but not in a Web browser.

In Release 6, if backwards compatibility is not an issue, you should combine the code in the onFocus - Client event and remove the Exiting event. You can code in JavaScript:

with (window.document.forms[0]) {
  if (FieldOne.value == "foo") {
    FieldTwo.value = "bar"
    FieldThree.value = "bar"
 }
}

Or LotusScript:

Sub Onblur(Source As Field)
  Dim w As New NotesUIWorkspace
  Dim uidoc As NotesUIDocument
  Set uidoc = w.CurrentDocument
  If uidoc.FieldGetText("FieldOne") = "foo" Then
    Call uidoc.FieldSetText("FieldTwo", "bar")
    Call uidoc.FieldSetText("FieldThree", "bar")
 End If
End Sub

Forward compatibility

Notes Release 5 applications running in the Release 6 Notes client behave the same. Those JavaScript events that worked in the Notes client continue to work on both the Web and the client. The LotusScript PostOpen, QueryClose, QuerySave, Entering, Exiting, and Click events continue to work.

When a Release 5 application is saved in Release 6 Domino Designer, JavaScript events are moved into their corresponding Web and (where applicable) Client events. The LotusScript events remain. For example, the onBlur event is moved into the onBlur - Web and onBlur - Client events, and the Exiting event remains.

However, if backwards compatibility is not an issue, you are urged to revise the code in the following cases:

For the JavaScript events that run on both the Notes client and the Web, where you use conditional code to modify the behavior for one environment or the other: instead use two routines, one for the client and one for the Web.
For the LotusScript events: move the code to the corresponding "on" client event.

Backwards compatibility

Release 6 applications running in the Release 5 Notes client behave the same as in the Release 6 client except that events new to Release 6 do not work in R5. For example, onLoad - Client for LotusScript does not work in Release 5.

If you recompile an Release 6 application in Release 5, JavaScript client events are lost and JavaScript Web events are reinstated for both client and Web. For example, onLoad - Client for JavaScript disappears if compiled in Release 5. JavaScript - Web does not disappear if compiled in Release 5 but now works for both client and Web.

Therefore a caveat exists to the guidelines for forward compatibility. If you continue to design in both Release 5 and Release 6, you should keep the LotusScript PostOpen, QueryClose, QuerySave, Entering, and Exiting events, not use the LotusScript "on" events, and code the JavaScript events for both client and Web (use "Common JavaScript").

onHelp and HelpRequest

In Release 5 the HelpRequest event (Formula) performs your action and suppresses standard help when the user presses F1 in the Notes client. The onHelp event (JavaScript) performs your action and (in addition) calls standard help when the user presses F1 in a Web browser.

In Release 6 the onHelp - Web event is the same as the Release 5 onHelp event. The onHelp - Client event, which supports Formula, LotusScript, and JavaScript, has the behavior of HelpRequest in Release 5. HelpRequest is gone from form design.