Home > Class Reference > %SYS namespace > %ZEN.Component.control

%ZEN.Component.control

abstract class %ZEN.Component.control extends %ZEN.Component.component

Base class for controls.
A control is a specialized type of component that can be placed within a form. Typically controls are used to allow the user to display and edit values (such as text controls) or to let the user take actions (such as button controls).
Most controls define a value (via the value) that is the data value associated with the control. This value can be submitted to the server as part of a form submit operation.
Controls define a set of common event handler properties, such as onclick that let you define a JavaScript expression that is executed when a given event occurs within the control.
Using the ZEN Model-View-Controller mechanism, you can bind data values to controls within a form. This provides a way to automatically set the value of a control to a property within a DataModel object.
Controls work together with a form to provide support for data validation and change tracking. Each control can define whether its current value is valid or not.
By default controls support drag-and-drop in the following way:
A drag from a control will drag the current value of the control.
A drop onto a control will set the current value of the control to the value of the drag data object. The text value is used if different than the logical value.

Property Inventory (Including Private)

Method Inventory (Including Private)

Parameters

parameter DEFAULTCLIENTTYPE;
The default value for the clientType property.
parameter DEFAULTCONTROLCLASS;
The default css class used for the main element within this control. This is overridden by subclasses.
parameter SYSMODULE = form;
Inherited description: If set, this indicates that this system component should be placed in the given "module". A module is a grouping of components within the same class package that share common include (js or css) files. Note that certain root classes are implicitly placed within the "core" module.
Classes outside of the Zen library should not set this, they should use the MODULE instead.

Properties (Including Private)

property clientType as %ZEN.Datatype.string (VALUELIST = ",string,boolean,integer,float") [ InitialExpression = ..#DEFAULTCLIENTTYPE ];
Indicates the client-side (JavaScript) type that should be used for this control's value.
By default controls treat their values as strings with no client-side normalization.
A control, or a page containing the control, can override this to indicate that this control displays a non-string value. The client-side logic will then try to convert the value to the appropriate client-side type whenever the value of the control is set.
Possible values are:
  • 'string' - the control will trim leading and trailing spaces from its value.
  • 'boolean' - the control will convert its value to true or false.
  • 'integer' - the control will convert its value to an integer or '' for an invalid integer.
  • 'float' - the control will convert its value to an float or '' for an invalid float.
Property methods: clientTypeDisplayToLogical(), clientTypeGet(), clientTypeIsValid(), clientTypeLogicalToDisplay(), clientTypeLogicalToOdbc(), clientTypeNormalize(), clientTypeSet()
property controlClass as %ZEN.Datatype.cssClass [ InitialExpression = ..#DEFAULTCONTROLCLASS ];
Optional CSS class used for the primary HTML element displayed for this control.
Property methods: controlClassDisplayToLogical(), controlClassGet(), controlClassIsValid(), controlClassLogicalToDisplay(), controlClassLogicalToOdbc(), controlClassNormalize(), controlClassSet()
property controlStyle as %ZEN.Datatype.style;
Optional CSS style applied to the primary HTML element displayed for this control.
How, and whether, this CSS style is used is up to the actual control implementation.
This property is provided as a convenience. It is more typical to provide style information via a style sheet.
Property methods: controlStyleDisplayToLogical(), controlStyleGet(), controlStyleIsValid(), controlStyleLogicalToDisplay(), controlStyleLogicalToOdbc(), controlStyleNormalize(), controlStyleSet()
property dataBinding as %ZEN.Datatype.string;
Optional. If this control belongs to a form that is associated with a dataController, this specifies the name of the property within the dataController that will provide the value for this control.
Property methods: dataBindingDisplayToLogical(), dataBindingGet(), dataBindingIsValid(), dataBindingLogicalToDisplay(), dataBindingLogicalToOdbc(), dataBindingNormalize(), dataBindingSet()
property disabled as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If true, this control is disabled.
Property methods: disabledDisplayToLogical(), disabledGet(), disabledIsValid(), disabledLogicalToDisplay(), disabledLogicalToOdbc(), disabledLogicalToXSD(), disabledNormalize(), disabledSet(), disabledXSDToLogical()
property invalid as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
Set this true when the value of this control is known to be invalid. Typically this is done by the form validation logic to to display this in a way that indicates it contains an invalid value.
Property methods: invalidDisplayToLogical(), invalidGet(), invalidIsValid(), invalidLogicalToDisplay(), invalidLogicalToOdbc(), invalidLogicalToXSD(), invalidMessageDisplayToLogical(), invalidMessageGet(), invalidMessageIsValid(), invalidMessageLogicalToDisplay(), invalidMessageLogicalToOdbc(), invalidMessageNormalize(), invalidMessageSet(), invalidNormalize(), invalidSet(), invalidXSDToLogical()
property invalidMessage as %ZEN.Datatype.caption [ InitialExpression = "out-of-range or invalid value." ];
Value displayed in alert box by the form validate() method when the contents of this control are invalid.
This is a localized value.
Property methods: invalidMessageDisplayToLogical(), invalidMessageGet(), invalidMessageIsValid(), invalidMessageLogicalToDisplay(), invalidMessageLogicalToOdbc(), invalidMessageNormalize(), invalidMessageSet()
property onblur as %ZEN.Datatype.eventHandler;
onblur event handler: This event is fired when the control loses focus.
Property methods: onblurDisplayToLogical(), onblurGet(), onblurIsValid(), onblurLogicalToDisplay(), onblurLogicalToOdbc(), onblurNormalize(), onblurSet()
property onchange as %ZEN.Datatype.eventHandler (HANDLER = """_..%Self()_"".onchangeHandler();");
onchange event handler: This event is fired when the value of the control changes. Note that controls fire this event indirectly; the actual onchange event is sent to a built-in handler that notifies the form that owns this control of the modification.
Property methods: onchangeDisplayToLogical(), onchangeGet(), onchangeHandler(), onchangeIsValid(), onchangeLogicalToDisplay(), onchangeLogicalToOdbc(), onchangeNormalize(), onchangeSet()
property onclick as %ZEN.Datatype.eventHandler;
onclick event handler: This event is fired when the mouse is clicked on the control.
Property methods: onclickDisplayToLogical(), onclickGet(), onclickIsValid(), onclickLogicalToDisplay(), onclickLogicalToOdbc(), onclickNormalize(), onclickSet()
property ondblclick as %ZEN.Datatype.eventHandler;
ondblclick event handler: This event is fired when the mouse is double-clicked on the control.
Property methods: ondblclickDisplayToLogical(), ondblclickGet(), ondblclickIsValid(), ondblclickLogicalToDisplay(), ondblclickLogicalToOdbc(), ondblclickNormalize(), ondblclickSet()
property onfocus as %ZEN.Datatype.eventHandler;
onfocus event handler: This event is fired when the control is given focus.
Property methods: onfocusDisplayToLogical(), onfocusGet(), onfocusIsValid(), onfocusLogicalToDisplay(), onfocusLogicalToOdbc(), onfocusNormalize(), onfocusSet()
property onkeydown as %ZEN.Datatype.eventHandler;
onkeydown event handler: This event is fired when a key is pressed when this control has focus.
Property methods: onkeydownDisplayToLogical(), onkeydownGet(), onkeydownIsValid(), onkeydownLogicalToDisplay(), onkeydownLogicalToOdbc(), onkeydownNormalize(), onkeydownSet()
property onkeypress as %ZEN.Datatype.eventHandler;
onkeypress event handler: This event is fired when a key is pressed when this control has focus.
Property methods: onkeypressDisplayToLogical(), onkeypressGet(), onkeypressIsValid(), onkeypressLogicalToDisplay(), onkeypressLogicalToOdbc(), onkeypressNormalize(), onkeypressSet()
property onkeyup as %ZEN.Datatype.eventHandler;
onkeyup event handler: This event is fired when a key is released when this control has focus.
Property methods: onkeyupDisplayToLogical(), onkeyupGet(), onkeyupIsValid(), onkeyupLogicalToDisplay(), onkeyupLogicalToOdbc(), onkeyupNormalize(), onkeyupSet()
property onmousedown as %ZEN.Datatype.eventHandler;
onmousedown event handler: This event is fired when a mouse button is released while within the area of the control.
Property methods: onmousedownDisplayToLogical(), onmousedownGet(), onmousedownIsValid(), onmousedownLogicalToDisplay(), onmousedownLogicalToOdbc(), onmousedownNormalize(), onmousedownSet()
property onmouseout as %ZEN.Datatype.eventHandler;
onmouseout event handler: This event is fired when the mouse pointer leaves the area of the control.
Property methods: onmouseoutDisplayToLogical(), onmouseoutGet(), onmouseoutIsValid(), onmouseoutLogicalToDisplay(), onmouseoutLogicalToOdbc(), onmouseoutNormalize(), onmouseoutSet()
property onmouseover as %ZEN.Datatype.eventHandler;
onmouseover event handler: This event is fired when the mouse pointer enters the area of the control.
Property methods: onmouseoverDisplayToLogical(), onmouseoverGet(), onmouseoverIsValid(), onmouseoverLogicalToDisplay(), onmouseoverLogicalToOdbc(), onmouseoverNormalize(), onmouseoverSet()
property onmouseup as %ZEN.Datatype.eventHandler;
onmouseup event handler: This event is fired when a mouse button is pressed while within the area of the control.
Property methods: onmouseupDisplayToLogical(), onmouseupGet(), onmouseupIsValid(), onmouseupLogicalToDisplay(), onmouseupLogicalToOdbc(), onmouseupNormalize(), onmouseupSet()
property onsubmit as %ZEN.Datatype.eventHandler);
onsubmit event handler: This event is fired when the form this control belongs to is submitted. This gives controls a chance to supply or modify the value they submit.
Property methods: onsubmitDisplayToLogical(), onsubmitGet(), onsubmitIsValid(), onsubmitLogicalToDisplay(), onsubmitLogicalToOdbc(), onsubmitNormalize(), onsubmitSet()
property ontouchend as %ZEN.Datatype.eventHandler;
ontouchend event handler: This event is fired on a touch screen device when the last figure or stylus breaks contact the screen at the end of a gesture.
Property methods: ontouchendDisplayToLogical(), ontouchendGet(), ontouchendIsValid(), ontouchendLogicalToDisplay(), ontouchendLogicalToOdbc(), ontouchendNormalize(), ontouchendSet()
property ontouchmove as %ZEN.Datatype.eventHandler;
ontouchmove event handler: This event is fired on a touch screen device when the one or more of the active contact points changes position as part of a gesture input.
Property methods: ontouchmoveDisplayToLogical(), ontouchmoveGet(), ontouchmoveIsValid(), ontouchmoveLogicalToDisplay(), ontouchmoveLogicalToOdbc(), ontouchmoveNormalize(), ontouchmoveSet()
property ontouchstart as %ZEN.Datatype.eventHandler;
ontouchstart event handler: This event is fired on a touch screen device when a figure or stylus initially contacts the screen within the area of the control.
Property methods: ontouchstartDisplayToLogical(), ontouchstartGet(), ontouchstartIsValid(), ontouchstartLogicalToDisplay(), ontouchstartLogicalToOdbc(), ontouchstartNormalize(), ontouchstartSet()
property onvalidate as %ZEN.Datatype.eventHandler);
onvalidate event handler: This event is fired when this control's value is validated by its parent form. Return false if the value of this control is invalid.
Property methods: onvalidateDisplayToLogical(), onvalidateGet(), onvalidateIsValid(), onvalidateLogicalToDisplay(), onvalidateLogicalToOdbc(), onvalidateNormalize(), onvalidateSet()
property originalValue as %ZEN.Datatype.value;
Original value for this control before any user modification. It is used to detect which controls have been modified.
This is a special value in that it is automatically intialized when a form is displayed.
Do not use this property directly on the client; instead used the getProperty() method.
Note that setting this on the client (via setProperty()) will reset it to the current value of this control.
Property methods: originalValueDisplayToLogical(), originalValueGet(), originalValueIsValid(), originalValueLogicalToDisplay(), originalValueLogicalToOdbc(), originalValueNormalize(), originalValueSet()
property readOnly as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If true, this control is readOnly.
Property methods: readOnlyDisplayToLogical(), readOnlyGet(), readOnlyIsValid(), readOnlyLogicalToDisplay(), readOnlyLogicalToOdbc(), readOnlyLogicalToXSD(), readOnlyNormalize(), readOnlySet(), readOnlyXSDToLogical()
property required as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If true, this control is required. That is, a user must supply a value for this control or the default form validation logic will fail.
Property methods: requiredDisplayToLogical(), requiredGet(), requiredIsValid(), requiredLogicalToDisplay(), requiredLogicalToOdbc(), requiredLogicalToXSD(), requiredMessageDisplayToLogical(), requiredMessageGet(), requiredMessageIsValid(), requiredMessageLogicalToDisplay(), requiredMessageLogicalToOdbc(), requiredMessageNormalize(), requiredMessageSet(), requiredNormalize(), requiredSet(), requiredXSDToLogical()
property requiredMessage as %ZEN.Datatype.caption [ InitialExpression = "required." ];
Value displayed in alert box by the form validate() method when this control is required and does not have a value.
This is a localized value.
Property methods: requiredMessageDisplayToLogical(), requiredMessageGet(), requiredMessageIsValid(), requiredMessageLogicalToDisplay(), requiredMessageLogicalToOdbc(), requiredMessageNormalize(), requiredMessageSet()
property tabIndex as %ZEN.Datatype.integer;
If defined, this is used to provide a value for the HTML tabIndex attribute. This is used by the browser to control the tab order of controls within a form.
Property methods: tabIndexDisplayToLogical(), tabIndexGet(), tabIndexIsValid(), tabIndexLogicalToDisplay(), tabIndexLogicalToOdbc(), tabIndexNormalize(), tabIndexSet()
property value as %ZEN.Datatype.value (ZENEXPRESSION = 1);
Default value displayed within this control. This is a special value in that it is automatically intialized when a form is displayed.
Do not use this property directly on the client; instead used the getValue() method to get the current value of a control.
Property methods: valueDisplayToLogical(), valueGet(), valueIsValid(), valueLogicalToDisplay(), valueLogicalToOdbc(), valueNormalize(), valueSet()

Methods (Including Private)

method %GetForm() as %ZEN.Component.form [ Language = objectscript ]
Server-side method. Find the form object that this control belongs to. Return "" if there is no form.
method %Name() as %String [ Language = objectscript ]
Utility method used by subclasses to write out the nameattribute for the primary HTML element of this control.
Names are of the form: $V_id
If name starts with "IRIS" or "Cache" then it is assumed to be a built-in variable and is not escaped.
method %SetDefaultValues() [ Language = objectscript ]
This method fills in reasonable default values for this control. Used by tools (such as the Control Tester) to dynamically create controls.
clientmethod dragStartHandler(dragData) [ Language = javascript ]
Default drag handler for controls.
clientmethod dropStartHandler(dragData) [ Language = javascript ]
Default drop handler for controls.
clientmethod focus() [ Language = javascript ]
Client-side method to give input focus to this control.
abstract clientmethod formatValue(val) [ Language = javascript ]
If defined, convert the internal value of this control into a display value.
final clientmethod getDisabled() as %Boolean [ Language = javascript ]
Client-side method to get the disabled state of this control.
clientmethod getDragData(dragData) [ Language = javascript ]
Fill in the zenDragData object for this control. This is called when a drag operation starts on this control. Subclasses can override this to provide customized behavior.
clientmethod getForm() [ Language = javascript ]
Find the form object that this control belongs to. Return null if there is no form.
clientmethod getInvalidReason() [ Language = javascript ]
This method is called by the form validation mechanism in order to get an invalid message to display for this control.
This is called by the form's validate() method after it has determined that this control has an invalid value.
clientmethod getProperty(property, key) as %String [ Language = javascript ]
Override to get current value of control.
final clientmethod getReadOnly() as %Boolean [ Language = javascript ]
Client-side method to get the disabled state of this control.
final clientmethod getValue() as %String [ Language = javascript ]
Client-side method to return the value associated with this control.
clientmethod isModified() [ Language = javascript ]
Return true if the current value of this control is different than its orginal value.
clientmethod isValid() [ Language = javascript ]
This method is called by the form validation mechanism to test if the current contents of this control are valid.
Returns true if the control value is valid; false otherwise. Subclasses can override this to provide specific behavior.
The default behavior is to return true.
clientmethod normalizeValue(val) as %String [ Language = javascript ]
Normalize the type of val based on the clientType of this control.
clientmethod onSerialize() [ Language = javascript ]
This is called when the client serializes this object.
This gives us a chance to make sure that the value property is updated to have the current value displayed within the control. This version will take care of this for native controls. Custom controls must either ensure that the value property matches the current value of the control or override this method.
clientmethod onchangeHandler() [ Language = javascript ]
This built-in event handler is called by the HTML control associated with the control to raise notification that the control's value has changed.
clientmethod select() [ Language = javascript ]
Client-side method to select the contents of this control.
final clientmethod setDisabled(flag) [ Language = javascript ]
Client-side method to set disabled state of this control.
clientmethod setProperty(property, value, value2) [ Language = javascript ]
Set the value of a named property.
Assume that subclasses that simply wrap HTML controls have named the control 'control' or else have overridden this method.
final clientmethod setReadOnly(flag) [ Language = javascript ]
Client-side method to set disabled state of this control.
final clientmethod setValue(value, value2) [ Language = javascript ]
Client-side method to set the value associated with this control. value2 is an optional, second parameter used by some controls (such as dataCombo).
clientmethod sysName() [ Language = javascript ]
Client-side version of the %Name() method. Use this to contruct control names when creating controls via DHTML that may be submitted by a Zen form.
abstract clientmethod unformatValue(val) [ Language = javascript ]
If defined, convert display value of this control to its internal value.
clientmethod validationHandler() [ Language = javascript ]
This client-side method is called by the form object's validate() to test if the contents of this control are valid.
This method does the following:
  • If this control is required, it tests that a value has been supplied.
  • If this control has an onvalidate callback defined, it calls it.
  • Otherwise, it invokes the isValid() method for this control to perform control-specific validation logic.
Readonly and disabled controls are always considered to be valid. A subclass can override this method to provide additional behavior, but the overridden method should perform the above actions.
Returns true if the control value is valid; false otherwise.

Inherited Members

Inherited Properties (Including Private)

Inherited Methods (Including Private)

Subclasses