PROGRAMMING OVERVIEW AND USER INTERFACE


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" below. 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."

EventRunLanguageObjectTrigger
ActionClientFormula
Java
LotusScript
Imported Java
Simple action(s)
AgentObject is loaded
ClickClientFormula
LotusScript
Simple action(s)
Action
Action Hotspot
Button
Navigator object
Picture Hotspot
Object is selected
ClickClientFormulaFormula PopupObject is selected
Column ValueClient
Web
Field
Formula
Simple Function
Folder column
View column
Object is loaded
DeclarationsClientLotusScriptAction
Action Hotspot
Agent
Button
Database Script
Field
Folder
Form
Globals
Navigator object
Page

Picture Hotspot
LotusScript Script Library
Subform
View

Object is loaded
Default ValueClient
Web
FormulaFieldDocument is created
Document SelectionClientSimple SearchAgentObject is loaded
Entering

Note Preferred is onFocus

ClientLotusScriptFieldObject is selected
Exiting

Note Preferred is onBlur

ClientLotusScriptFieldObject is deselected
Form FormulaClient
Web
FormulaFolder
View
Object is loaded
Frame - ClientClient
Web
FormulaOutline EntryObject is loaded
HelpRequestClientFormulaFolder
View
Help is selected
Hide WhenClient
Web
FormulaOutline EntryObject is loaded
HTML AttributesWebFormulaFieldForm is loaded
HTML Body AttributesWebFormulaForm
Page
Form is loaded
HTML Head ContentWebFormulaForm
Page
Form is loaded
ImageClientFormulaOutline EntryObject is loaded
InitializeClientLotusScriptAction
Action Hotspot
Agent
Button
Database Script
Field
Folder
Form
Globals
Navigator object
Page
Picture Hotspot LotusScript Script Library
Subform
View
Object is loaded
Input EnabledClientFormulaFieldForm is loaded
Input TranslationClient
Web
FormulaFieldDocument is saved
Input ValidationClient
Web
FormulaFieldAfter Input Translation
InViewEdit

Note New with Release 6

ClientLotusScriptFolder
View
View entry is edited: at query, validation, and save
JavaAgentClientJavaAgentObject is loaded
Javascript LibraryClientWebJavaScriptScript LibraryObject is loaded
Java class nameClientJavaScript LibraryObject is loaded
JS HeaderClient
Web
JavaScriptForm
Page
Subform
Object is loaded
LabelClientFormulaOutline EntryObject is loaded
ObjectExecuteClientLotusScriptAction
Action Hotspot
Button
Object is activated by an OLE2 server that is FX/NotesFlowâ„¢ enabled
onBlur

Note New for LotusScript with Release 6

ClientJavaScript
LotusScript
FieldObject is deselected
onBlur - WebWebJavaScriptAction
Action Hotspot
Button
Field
Object is deselected
onChange

Note New with Release 6

ClientJavaScript
LotusScript
FieldContents of object change
onChangeWebJavaScriptFieldContents of object change
onClickWebJavaScriptAction
Action Hotspot
Button
Field
Form
Page
Picture
Object is selected
onDblClickWebJavaScriptAction
Action Hotspot
Button
Field
Form
Page
Picture
Double-click occurs on object
onFocus

Note New for LotusScript with Release 6

ClientLotusScript
JavaScript
FieldObject is selected
onFocusWebJavaScriptAction
Action Hotspot
Button
Field
Object is selected
onHelpClientFormula
LotusScript
JavaScript
Form
Page
Help is selected
onHelpWebJavaScriptAction
Action Hotspot
Button
Form
Page
Picture
Help is selected
onKeyDownWebJavaScriptAction
Action Hotspot
Button
Field
Form
Page
Picture
Any key is pressed
onKeyPressWebJavaScriptAction
Action Hotspot
Button
Field
Form
Page
Picture
An alphanumeric key is pressed
onKeyUpWebJavaScriptAction
Action Hotspot
Button
Field
Form
Page
Picture
Any key is released
onLoad

Note New for Formula and LotusScript with Release 6

ClientJavaScript
Formula
LotusScript
Form
Page
Object is loaded
onLoadWebJavaScriptForm
Page
Object is loaded
onMouseDownWebJavaScriptAction
Action Hotspot
Button
Field
Form
Page
Picture
Object is selected with either the right or left mouse button
onMouseMoveWebJavaScriptAction
Action Hotspot
Button
Field
Form
Page
Picture
Mouse is moved over object
onMouseOutWebJavaScriptAction
Action Hotspot
Button
Field
Form
Page
Picture
Mouse is moved out of object
onMouseOverWebJavaScriptAction
Action Hotspot
Button
Field
Form
Page
Picture
Mouse is moved into object
onMouseUpWebJavaScriptAction
Action Hotspot
Button
Field
Form
Page
Picture
Mouse button is released over object
onResetWebJavaScriptFormObject is reset
onSelectWebJavaScriptFieldContents of object are selected
OnSubmit

Note New for Formula and LotusScript with Release 6

ClientFormula
JavaScript
LotusScript
Form
Page
Before object is saved
onSubmitWebJavaScriptFormBefore object is saved
OnUnload

Note New for Formula and LotusScript with Release 6

ClientFormula
LotusScript
JavaScript
Form
Page
Before object is unloaded
onUnloadWebJavaScriptForm
Page
Before object is unloaded
OptionsClientLotusScriptAction
Action Hotspot
Agent
Button
Database Script
Field
Folder
Form
Globals
Navigator object
Page
Picture Hotspot
LotusScript Script Library
Subform
View
Object is loaded
PostDocumentDeleteClientFormula
LotusScript
Database ScriptAfter a document is deleted (the document is still available)
PostDragDropClientFormula
LotusScript
Database Script
Folder
View
After a drag and drop operation in object
PostEntryResize

Note New with Release 6

ClientFormula
LotusScript
Folder
View
After a resize operation in a calendar folder or view
PostModeChangeClientFormula
LotusScript
JavaScript
Form
Subform
After object is changed to Read or Edit mode
PostOpen

Note Preferred is onLoad for Form and Page

ClientFormula
LotusScript
Database Script
Folder
Form
Page
Subform
View
After object is opened
PostPasteClientFormula
LotusScript
Folder
View
After a paste operation
PostRecalcClientFormula
JavaScript
LotusScript
Form
Page
Subform
After object is refreshed (and values are recalculated)
PostSaveClientFormula
JavaScript
LotusScript
Form
Subform
After object is saved
PostSend

Note New with Release 6

ClientFormula
JavaScript
LotusScript
Form
Subform
After object is sent
QueryAddToFolderClientFormula
LotusScript
Folder
View
Before a document is added to a folder
QueryClose

Note Preferred is onUnload for Form and Page

ClientFormula
LotusScript
Database Script
Folder
Form
Page
Subform
View
Object is being closed
QueryDocumentDeleteClientFormula
LotusScript
Database ScriptBefore a document is marked for deletion
QueryDocumentUndeleteClientFormula
LotusScript
Database ScriptBefore a document is unmarked for deletion
QueryDragDropClientFormula
LotusScript
Database Script
Folder
View
Before a drag and drop operation
QueryEntryResize

Note New with Release 6

ClientFormula
LotusScript
Folder
View
Before a resize operation in a calendar folder or view
QueryModeChangeClientFormula
JavaScript
LotusScript
Form
Subform
Before a document is changed to Read or Edit mode
QueryOpenClientFormula
JavaScript
LotusScript
Form
Page
Subform
Before object is opened
QueryOpenClientFormula
LotusScript
Folder
View
Before object is opened
QueryOpenDocumentClientFormula
LotusScript
Folder
View
Before a document is loaded
QueryPasteClientFormula
LotusScript
Folder
View
Before a paste operation
QueryRecalc

Note New with Release 6

ClientFormula
JavaScript
LotusScript
Form
Page
Subform
Before object is refreshed (and values are recalculated)
QueryRecalcClientFormula
LotusScript
Folder
View
Before object is refreshed (and values are recalculated)
QuerySave

Note Preferred is onSubmit for Form

ClientFormula
LotusScript
Form
Subform
Before object is saved
QuerySend

Note New with Release 6

ClientFormula
JavaScript
LotusScript
Form
Subform
Before object is sent
RegionDoubleClickClientFormula
LotusScript
Folder
View
Region in a calendar view or folder is double-clicked
SourceClientFormulaOutline EntryObject is loaded
Target FrameClient
Web
FormulaForm
Page
Object is loaded
Target Frame (single click)Client
Web
FormulaFolder
View
Object is loaded
Target Frame (double click)Client
Web
FormulaFolder
View
Object is loaded
TerminateClientLotusScriptAction
Action Hotspot
Agent
Button
Database Script
Field
Folder
Form
Globals
Navigator object
Page
Picture Hotspot
LotusScript Script Library
Subform
View
Object is unloaded
ValueClient
Web
FormulaFieldComputed field is calculated
View SelectionClientFormula
Simple Search
Folder
View
Object is loaded
WebQueryOpenWebFormulaFormBefore object displays**
WebQuerySaveWebFormulaFormBefore object is saved**
Window TitleClient
Web
FormulaForm
Page
Object is loaded
**WebQueryOpen and WebQuerySave must be a formula with either of the following @commands:
@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 actionEventReleaseOccurs onLanguage
Action, Action Hotspot, Button
Select objectonClickR5 & Release 6Web onlyJavaScript
ClickR5 & Release 6Client onlyLotusScript
Field
Enter objectEnteringR5 & Release 6Client onlyLotusScript
onFocusR5 & Release 6Client & WebJavaScript
Release 6Client onlyLotusScript
Exit objectExitingR5 & Release 6Client onlyLotusScript
onBlurR5 & Release 6Client & WebJavaScript
Release 6Client onlyLotusScript
Form, page
Open objectonLoadR5 & Release 6Client & WebJavaScript
Release 6Client onlyFormula
LotusScript
PostOpenR5 & Release 6Client onlyFormula
LotusScript
Close objectonUnloadR5 & Release 6Client & WebJavaScript
Release 6Client onlyFormula
LotusScript
QueryCloseR5 & Release 6Client onlyFormula
LotusScript
Save objectonSubmitR5 & Release 6Client & WebJavaScript
Release 6Client onlyFormula
LotusScript
QuerySaveR5 & Release 6Client onlyFormula
LotusScript

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


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:


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:


Or LotusScript:
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:


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.

See Also