abstract class %ZEN.Component.control
extends 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.
• 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";
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.
• 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 controlClass
as %ZEN.Datatype.cssClass [ InitialExpression = ..#DEFAULTCONTROLCLASS ];
Optional CSS class used for the primary HTML element displayed for this control.
• 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 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 disabled
as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If true, this control is disabled.
• 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 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 onblur
as %ZEN.Datatype.eventHandler;
onblur event handler:
This event is fired when the control loses focus.
• 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 onclick
as %ZEN.Datatype.eventHandler;
onclick event handler:
This event is fired when the mouse is clicked on the control.
• property ondblclick
as %ZEN.Datatype.eventHandler;
ondblclick event handler:
This event is fired when the mouse is double-clicked on the control.
• property onfocus
as %ZEN.Datatype.eventHandler;
onfocus event handler:
This event is fired when the control is given focus.
• property onkeydown
as %ZEN.Datatype.eventHandler;
onkeydown event handler:
This event is fired when a key is pressed when this control has focus.
• property onkeypress
as %ZEN.Datatype.eventHandler;
onkeypress event handler:
This event is fired when a key is pressed when this control has focus.
• property onkeyup
as %ZEN.Datatype.eventHandler;
onkeyup event handler:
This event is fired when a key is released when this control has focus.
• 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 onmouseout
as %ZEN.Datatype.eventHandler;
onmouseout event handler:
This event is fired when the mouse pointer leaves the area of the control.
• property onmouseover
as %ZEN.Datatype.eventHandler;
onmouseover event handler:
This event is fired when the mouse pointer enters the area of the control.
• 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 onsubmit
as %ZEN.Datatype.eventHandler(HANDLER="");
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 onvalidate
as %ZEN.Datatype.eventHandler(HANDLER="");
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 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 readOnly
as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If true, this control is readOnly.
• 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 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 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 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.
• method %GetForm()
as %ZEN.Component.form
Server-side method.
Find the form object that this control belongs to.
Return "" if there is no form.
• method %Name()
as %String
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 "Cache" then it is assumed to be a built-in
variable and is not escaped.
• method %SetDefaultValues()
This method fills in reasonable default values for
this control. Used by tools (such as the Control Tester) to
dynamically create controls.
• method dragStartHandler(dragData)
[ Language = javascript ]
Default drag handler for controls.
• method dropStartHandler(dragData)
[ Language = javascript ]
Default drop handler for controls.
• method focus()
[ Language = javascript ]
Client-side method to give input focus to this control.
• abstract method formatValue(val)
[ Language = javascript ]
If defined, convert the internal value of this control into a display value.
• final method getDisabled()
as %Boolean
[ Language = javascript ]
Client-side method to get the disabled state of this control.
• method 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.
• method getForm()
[ Language = javascript ]
Find the form object that this control belongs to.
Return null if there is no form.
• method 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.
• method getProperty(property, key)
as %String
[ Language = javascript ]
Override to get current value of control.
• final method getReadOnly()
as %Boolean
[ Language = javascript ]
Client-side method to get the disabled state of this control.
• final method getValue()
as %String
[ Language = javascript ]
Client-side method to return the value associated with this control.
• method isModified()
[ Language = javascript ]
Return true if the current value of this control is different
than its orginal value.
• method 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.
• method normalizeValue(val)
as %String
[ Language = javascript ]
Normalize the type of val based on the clientType
of this control.
• method 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.
• method 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.
• method select()
[ Language = javascript ]
Client-side method to select the contents of this control.
• final method setDisabled(flag)
[ Language = javascript ]
Client-side method to set disabled state of this control.
• method 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 method setReadOnly(flag)
[ Language = javascript ]
Client-side method to set disabled state of this control.
• final method 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).
• method 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 method unformatValue(val)
[ Language = javascript ]
If defined, convert display value of this control to its internal value.
• method 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.
