colpreupdate

note

This article is about the colpreupdate UDB event handler.

colpreupdate

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

Event	Applies to	Occurs when
colpreupdate	Data source objects (UdbDataSource)	Before a value in a column is updated *

* Whether the value is updated manually, by looking up a (new) value from a dropdown list, or by typing into a query/filter field.

This event is triggered internally by the UdbDataSource class, either from its own constructor watch on a query/filter value, or (for an actual record value) from a watch set up by the UdbRecord object that owns the value.

Purpose

You can use the colpreupdate event to manipulate programmatically a value that a user supplied manually for update.

How to use

Find or create an Event Listener object with Event Type = colpreupdate. 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. A typical pattern is to specify the condition under which you want to manipulate the user input, and then to specify how you want to alter the input if the condition applies. This pattern looks like this:

if ( *user-value-test* ) {
  options.value = *manipulated-value*;
}

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().

Examples

Example 1

This example tacitly sets a new age value to 18 if the value that the user attempts to update this column to is lower than 18:

if (options.col.name() === 'AGE' && options.value < 18)
  options.value = 18;

Example 2

This example replaces any empty values by the value 'Unknown':

if (options.value === '')
  options.value = 'Unknown';

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*   ::=  {
     value:    *value*,
     oldValue: *old-value*,
     col:      *col*,
     ref:      *ref*,
     mode:     *mode*,
     hostvars: *hostvars*
}

*mode*   ::=  { 'S' | 'E' }

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

This syntax means that you can access a caller option by scripting

options.*caller-option*

Value is the new value that the column is being updated to. Mutating options.value in your handler changes the value that is actually applied.

Old-value is the value that the column had before the update.

Col is the UdbColumn object of the column being updated (not its name).

Ref is the underlying reactive reference that holds the column's value.

Mode is 'E' if a record value is being updated, or 'S' if a query/filter value is being updated.

Hostvars is an object with the host variables that are passed along with the update. It is only present when mode is 'E'.