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.