fetchdata

note

This article is about the fetchdata UDB event handler.

fetchdata

The fetchdata event may be called from web pages developed in Web Designer and processed by a USoft page engine service.

Event	Applies to	Occurs when
fetchdata	Lookup data source objects (UdbDataSource)	Before the framework fetches lookup values for a column, for a row set that does not yet exist locally

This event is triggered internally by the UdbRowSet class, from its syncLookups() method, on the lookup data source, just before that data source's lookup values would be fetched from the server for the current parent key.

Purpose

You can use this event to take over responsibility for supplying lookup data yourself, instead of letting the framework fetch it with its default getLookupValues() call. This is useful, for example, if you want to populate the lookup row set from data you already have available on the client.

How to use

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

Insert the event listener into the lookup 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 supply the lookup data yourself, set options.fetch to false, and then populate the lookup row set with your own data. This pattern looks like this:

if ( *condition* ) {
  options.fetch = false;
  // populate the lookup row set yourself, e.g. by creating it directly
}

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

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*   ::=  {
     pKeys:  *pKeys*,
     fetch:  *fetch*
}

*fetch*  ::=  { [true] | false }

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

This syntax means that you can access an option by scripting

options.*option*

pKeys is the parent-key string that identifies the (not-yet-existing) row set for which lookup values are about to be fetched.

Fetch indicates whether the framework will go on to call its default lookup fetch (getLookupValues()) for pKeys. It is true by default (as long as pKeys is not empty). If you set fetch to false in your handler, the framework skips its own fetch; in that case your handler is responsible for supplying the lookup row set's data itself.