Class Reference
Cache for UNIX 2018.1.1
InterSystems: The power behind what matters   
Documentation  Search
Private  Storage  

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.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
3 30 28


Summary

Properties
%condition %import %includeFiles %page
%resource align aux clientType
composite containerStyle controlClass controlStyle
dataBinding disabled dragEnabled dropEnabled
enclosingClass enclosingStyle error height
hidden hint hintClass hintStyle
id index invalid invalidMessage
label labelClass labelDisabledClass labelStyle
name onafterdrag onbeforedrag onblur
onchange onclick ondblclick ondrag
ondrop onfocus onhide onkeydown
onkeypress onkeyup onmousedown onmouseout
onmouseover onmouseup onrefresh onshow
onsubmit ontouchend ontouchmove ontouchstart
onupdate onvalidate originalValue parent
readOnly required requiredMessage showLabel
slice tabIndex title tuple
valign value visible width
window

Methods
%AddToSaveSet %Attr %BindExport %ClassIsLatestVersion
%ClassName %ConstructClone %DispatchClassMethod %DispatchGetModified
%DispatchGetProperty %DispatchMethod %DispatchSetModified %DispatchSetMultidimProperty
%DispatchSetProperty %DrawComponentHTML %DrawHTML %DrawJSStrings
%EnclosingDivId %Eval %EvalC %Extends
%ForceClientRender %GetEventHandlers %GetForm %GetParameter
%GetXMLName %IsA %IsModified %MakeId
%Name %New %NormalizeObject %ObjectModified
%OnAddToPageAfter %OnAddToPageBefore %OnDrawEnclosingDiv %OnDrawObjectProperties
%OnObjectSynch %OnZENDeserialize %OriginalNamespace %PackageName
%QuoteValue %QuoteValueL10N %RemoveFromSaveSet %Self
%SerializeObject %SetDefaultValues %SetModified %ValidateObject
XMLDTD XMLExport XMLExportToStream XMLExportToString
XMLNew XMLSchema XMLSchemaNamespace XMLSchemaType
dragFinishHandler dragHandler dragNotifyHandler dragStartHandler
dropHandler dropStartHandler exposeComponent findElement
fireOnUpdateEvent focus formatValue getDisabled
getDragData getEnclosingDiv getForm getHidden
getHintElement getInvalidReason getLabelElement getProperty
getReadOnly getSettings getType getValue
invokeSuper isModified isOfType isValid
makeId normalizeValue onCreate onDelete
onDisplayHandler onEndModalHandler onPopupAction onRefreshContents
onSerialize onStartModalHandler onchangeHandler onloadHandler
onunloadHandler onupdateHandler refreshContents render
renderContents renderSVG select setDisabled
setHidden setOverlayMode setProperty setReadOnly
setValue startProgressBar stopProgressBar sysName
unformatValue validationHandler

Subclasses
%DeepSee.Component.styleEdit %DeepSee.Report.UI.abstractIconBar %DeepSee.Report.UI.captionEditor
%DeepSee.Report.UI.codeEditor %DeepSee.Report.UI.colorPalette %DeepSee.Report.UI.colorPip
%DeepSee.Report.UI.hSlider %DeepSee.Report.UI.pageSetupControl %DeepSee.Report.UI.pickBox
%DeepSee.Report.UI.spinner %DeepSee.Report.UI.strokeStyleBar %DeepSee.Report.UI.strokeWidthBar
%DeepSee.Report.UI.textJustifyBar %DeepSee.Report.UI.textStyleBar %DeepSee.Report.UI.toggleIcon
%ZEN.Component.abstractListBox %ZEN.Component.button %ZEN.Component.calendar
%ZEN.Component.checkbox %ZEN.Component.colorPicker %ZEN.Component.dataGrid
%ZEN.Component.dateSelect %ZEN.Component.dateText %ZEN.Component.dynaGrid
%ZEN.Component.fileUpload %ZEN.Component.hbutton %ZEN.Component.hidden
%ZEN.Component.image %ZEN.Component.label %ZEN.Component.listControl
%ZEN.Component.lookup %ZEN.Component.radioButton %ZEN.Component.text
%ZEN.Component.textarea %ZEN.ComponentEx.colorWheel %ZEN.ComponentEx.scribbleArea
%ZEN.Portal.assistedText %ZEN.Portal.selector

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";
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

• 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 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 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 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 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.

Methods

• 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.


Copyright © 1997-2019, InterSystems Corporation