readonly

note

This article is about the readonly UDB event handler.

readonly

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

Event	Applies to	Occurs when
readonly	Custom UI controls (InputControl$custom)	While the control's read-only state is being computed

This event applies only to custom UI controls. They are controls with the Type property set to 'custom'. This event is triggered internally on the control's $el element, from the readonly() method of the InputControl$custom class (which extends InputControl, defined in controls/input-custom.js). A handler can override the effective read-only state by changing options.readOnly.

Purpose

You can use the readonly event to override the read-only state that the control would otherwise compute for itself, for example to make a normally editable control read-only under certain conditions, or vice versa.

How to use

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

Insert the event listener into the object for the custom UI control. 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 override the computed read-only state depending on some condition:

if ( *condition* ) {
  options.readOnly = true;
}

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.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*   ::=  {
     control:   *control*,
     readOnly:  *read-only*,
     isLookup:  *is-lookup*
}

*read-only*  ::=  { true | false }
*is-lookup*  ::=  { 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 the control object by scripting:

options.control

Control is the control instance for which the read-only state is being computed.

Read-only is the read-only state, as computed by the control before the event fired. You can override the effective read-only state by setting options.readOnly to true or false in your event handler; the value of options.readOnly after the event handlers have run is the value that is actually used.

Is-lookup is true if the control is a lookup control; otherwise false.