rowpreupdate

note

This article is about the rowpreupdate UDB event handler.

rowpreupdate

The rowpreupdate event may be called from web pages developed in Web Designer and processed by a USoft Page Engine service.

Event	Applies to	Occurs when
rowpreupdate	Data source objects (UdbDataSource)	Before a record is updated *

* Whether the value is updated manually or by looking up a (new) value from a dropdown list.

This event is triggered internally by the UdbDataSource class, from the updateMultiple() method of the UdbRecord object that represents the record being updated.

Purpose

You can use this event to inspect or react to the values a record is about to be updated with. Unlike most other *pre* events, rowpreupdate cannot cancel the update: setting options.success = false has no effect, because the update code does not check it.

How to use

Find or create an Event Listener object with Event Type = rowpreupdate. Event Listeners are in the Web Designer Controls catalog:

Insert the event listener into the data source object. Insert a callClientScript action into the event listener. Use this action's Script property to code the behaviour that you want to see when the event occurs.

You are implicitly associating the event with an event handler function. This function has an options parameter. For available options, see the Options section at the end of this help topic:

function(*event*, *options*){ ... }

Or you can create the event handler more explicitly by calling $.udb('data-source').on().

Example

console.log('Record about to be updated with', options.values);

Options

When the event occurs, the following event handler function is called. You can use this function's options parameter in your event scripting.

function( *event*, *options* )

*event*     ::=  jQuery.Event
*options*   ::=  *event-options*

*event-options*   ::=  {
     values:   *values*,
     record:   *record*,
     hostvars: *hostvars*
}

Event contains the run-time details of the triggered event, of the event type stated above.

This syntax means that you can access the options by scripting:

options.values
options.record
options.hostvars

Values is a Map of the new column values that the record is about to be updated with, keyed by column reference.

Record is the UdbRecord object being updated.

Hostvars is an object with the host variables that are passed along with the update.