Events

To build a program for an event, you can use:

• Formulas
• Simple actions
• LotusScript®
• JavaScript™
• Common JavaScript™ (which works on both the Web and the Notes® client)

When to use event programming

Use event programming to run tasks that users shouldn't have to activate themselves and that are very specific. Event programming is particularly useful when the timing of the program must be precise or the tasks are associated with a particular design element.

Examples of event programming

• Error checking when a user completes a field or closes a document
• Recalculating fields when a user saves a document
• Prohibiting certain actions in a document
• Prompting for user input
• Displaying information when a user clicks a button

Types of events

Every design element has events that you can program, but they vary according to the design element. In the Programmer's pane, click the Objects tab to review the events you can program.

Database Script events

Database Script events pinpoint database-wide activities such as opening and closing a database or deleting and undeleting documents. To access the Database Script events, double-click Database Scripts under Code in the Applications Navigator.

Examples:

• PostOpen -- open a specific view to direct users to action items
• QueryDocumentDelete -- prevent users from deleting a particular document when the value of a status field on an action item is "Open."
• PostDocumentDelete -- archive a deleted document.
• QueryClose -- prevent users from closing a database when there are still action items in the action item view assigned to them.

View and folder events

View events occur when users work in a specific view or folder. View events include opening or closing a view, adding documents to a calendar view, or adding documents to a folder.

Examples of view and folder events

• QueryOpen -- prevent users from opening a view in certain circumstances such as from opening a "month end" view before the twentieth day of the month.
• PostOpen -- create a new document or open an existing one.
• QueryRecalc -- inform users before a large view refreshes that it could take a while and ask them if they really want to proceed.
• QueryPaste -- prevent users from pasting documents into the database.
• PostPaste -- change the value of StartDateTime and EndDateTime in the document when you paste an appointment on a particular day and time slot.
• QueryClose -- prevent users from closing a view such as when there are still action items in the action item view assigned to them.
• QueryAddToFolder -- lets you prevent someone from dragging a document from one folder or view to another. For example, you can prevent documents from moving to the Done folder if their status is still Open. Note that the trigger for this event is in the view or folder from which the document is moved.

In addition to the events available for all views, calendar views have specific events.

Examples of calendar view events

• RegionDoubleClick -- create a new document when users click an area in a calendar view.
• QueryDragDrop -- prevent someone from dropping an appointment on an inappropriate day or time, such as a weekend day or a time that is after 5 PM.
• PostDragDrop -- change the value of StartDateTime and EndDateTime in the document after you drop an appointment on a particular day and time slot.

Form events

Form events occur at the document level when users open or close a document. They are useful for speeding up document display times because they execute only when a specific form event occurs, unlike field recalculations that occur each time a document is saved, opened, or refreshed.

Examples

• Initialize -- load an additional program before a document displays.
• QueryClose -- check for errors and validate fields before closing a document.
• QuerySave -- reset a field value when users save documents rather than using conditional formulas in the field itself. For example, to reset the status field if the document is being saved, create a script for a QuerySave event rather than include a formula that uses @If(@IsDocBeingSaved;"x";"y").

  With QuerySave, you can also execute processing logic and avoid the unnecessary recalculations inherent in computed fields. For example, you have a form with a hidden computed field called State that determines where documents are in the workflow and where they need to be sent. By replacing the field formula with a LotusScript® program that sets a field value during the QuerySave form event, set the field value in the document only when it is saved, not when it is opened or refreshed.

Field events

Field events capture users' movements into or away from a field.

Examples

• Entering -- refresh hide-when formulas
• Exiting -- guide users to a certain field
• Exiting -- verify that users supplied valid information

Click events

The Click event occurs when users click actions or hotspots, or choose tasks from the Actions menu. Other events for actions, buttons, and hotspots allow you to add programming to other events. After the object is loaded, the "initialize" event is triggered and then the click event is triggered.

Examples

• Compose a new document
• Save a form
• Make a calculation

Agent event

The Initialize event stores all the programming associated with the agent. Always add the programming to the Initialize event for an agent.