Home > Class Reference > ENSLIB namespace > %ZEN.Component.form
Private  Storage   


class %ZEN.Component.form extends group, dataView

Form component.
This is a specialized type of group that wraps its constituent components within an HTML form element.
Typically a form contain a set of controls. These are used to collect input from a user. This input is sent to the server for processing via an HTML submit operation.
The contents of a form can be submitted in two ways: When the user clicks a submit button placed within the form, or by calling the submit of this form object.
Note that ZEN automatically handles the details of the submit operation including invoking server callbacks and error processing. All forms are submitted using the HTTP POST submission method.


Parameters Properties Methods Queries Indices ForeignKeys Triggers
3 21 21


%condition %controller %import %includeFiles
%page %resource OnLoadForm OnSubmitForm
action align autoValidate autocomplete
aux cellAlign cellSize cellStyle
cellVAlign children composite containerStyle
controller controllerId disabled dragEnabled
dropEnabled enclosingClass enclosingStyle enctype
error groupClass groupStyle height
hidden hint hintClass hintStyle
id index invalidMessage key
label labelClass labelDisabledClass labelPosition
labelStyle layout messageTargetId method
name nextPage noModelMessage onafterdrag
onbeforedrag onchange onclick ondefault
ondrag ondrop onhide oninvalid
onnotifyView onrefresh onreset onshow
onsubmit onupdate onvalidate parent
propagateChanges readOnlyMessage showLabel slice
target title tuple valign
visible width window

%AddChild %AddChildAfter %AddChildBefore %AddToSaveSet
%Attr %BindExport %ClassIsLatestVersion %ClassName
%ConstructClone %DispatchClassMethod %DispatchGetModified %DispatchGetProperty
%DispatchMethod %DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty
%DrawComponentHTML %DrawHTML %DrawJSStrings %EnclosingDivId
%Eval %EvalC %Extends %ForceClientRender
%GetChildIndex %GetEventHandlers %GetParameter %GetXMLName
%InjectControls %IsA %IsModified %MakeId
%New %NormalizeObject %ObjectModified %OnAddToPageAfter
%OnAddToPageBefore %OnDrawEnclosingDiv %OnDrawForm %OnDrawObjectProperties
%OnMutateChildren %OnObjectSynch %OnZENDeserialize %OriginalNamespace
%PackageName %QuoteValue %QuoteValueL10N %RemoveChild
%RemoveChildren %RemoveFromSaveSet %Self %SerializeObject
%SetModified %ValidateObject ReloadForm XMLDTD
XMLExport XMLExportToStream XMLExportToString XMLNew
XMLSchema XMLSchemaNamespace XMLSchemaType addChild
addChildAfter addChildBefore childrenMutated clearModified
dragFinishHandler dragHandler dragNotifyHandler dragStartHandler
dropHandler dropStartHandler exposeComponent findElement
fireOnUpdateEvent getChildIndex getControlList getController
getEnclosingDiv getFormElement getHidden getHintElement
getLabelElement getProperty getSettings getType
getValuesAsObject invokeSuper isModified isOfType
makeId notifyViewHandler onCreate onDelete
onDisplayHandler onEndModalHandler onPopupAction onRefreshContents
onSerialize onStartModalHandler ondisabledHandler onloadHandler
onunloadHandler onupdateHandler refreshContents reload
removeChild render renderContents renderSVG
reset save sendEventToController setControllerId
setHidden setOverlayMode setProperty setPropertyAll
setValuesByName showMessage startProgressBar stopProgressBar
submit submitHandler validate



• parameter DEFAULTGROUPCLASS = "form";
Subclasses can set this to change default css class for a group.
• parameter DEFAULTGROUPSTYLE = "padding: 5px;";
Default style for cells within forms
• 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 OnLoadForm as %ZEN.Datatype.delegator(FORMALSPEC="pID:%String,*pValues:%String",RETURNTYPE="%Status");
(Optional) Name of Server-side callback method to call to get values for this form.
This must be the name of a server-only method in the page class that contains this form component.
• property OnSubmitForm as %ZEN.Datatype.delegator(FORMALSPEC="pSubmit:%ZEN.Submit",RETURNTYPE="%Status");
(Optional) Name of Server-side callback method to call when this form is submitted. If this is not specified, then the page's %OnSubmit method is called instead.
This must be the name of a server-only method in the page class that contains this form component.
• property action as %ZEN.Datatype.uri;
Specifies the action attribute for the form.
Setting this will override the default behavior of Zen forms (i.e. the normal submit logic will not be executed). This should only be used for special cases where direct control of the action attribute is required.
• property autoValidate as %ZEN.Datatype.boolean [ InitialExpression = 1 ];
If true (the default), automatically invoke this form's validate whenever this form is submitted.
• property autocomplete as %ZEN.Datatype.boolean [ InitialExpression = 1 ];
(Optional) Indicates whether controls in this form can by default have their values automatically completed by the browser.
This setting can be overridden by an autocomplete attribute on an element belonging to the form.
• property enctype as %ZEN.Datatype.string;
Specifies the enctype for the form. (Refer to the HTML form element for details).
• property invalidMessage as %ZEN.Datatype.caption [ InitialExpression = "This form contains invalid values. Please correct the following field(s) and try again." ];
Value displayed in alert box by the validate method when the contents of this form are invalid.
This is a localized value.
• property key as %ZEN.Datatype.string(ZENEXPRESSION=1);
(Optional) ID value used by the OnLoadForm method to load data for this form.
If this form is connected to a dataController then this value will be ignored.
• property messageTargetId as %ZEN.Datatype.id;
If defined, this is the id of a control (which could be anywhere on the page) that will display messages, such as the noModelMessage. The message is displayed by setting the value property of the identified control.
• property method as %ZEN.Datatype.string(VALUELIST=",post,get");
Specifies the method attribute for the form.
Setting this will override the default behavior of Zen forms. This should only be used for special cases where direct control of the method attribute is required.
• property nextPage as %ZEN.Datatype.uri;
URL to go to after this form is submitted successfully. This value may be overwritten by a specific submit button.
• property noModelMessage as %ZEN.Datatype.caption;
Value displayed in the component with id messageTargetId when this form is not connected to a data model; the form is connected to a controller but the controller does not have a data model. This is a localized value.
• property onchange as %ZEN.Datatype.eventHandler(HANDLER="");
onchange event handler: This event is fired when the value of a control on this form is changed by the user or when the modified flags are cleared.
When fired for a control, the event handler can use an argument called 'control' to get a reference to the modified control. When fired in the case of a call to clearModified, this argument will be null.
• property ondefault as %ZEN.Datatype.eventHandler(HANDLER="");
ondefault event handler: This is a special event that is fired when the user performs an action that triggers the default action for a form. Typically this is when the user presses the Enter key within a control within the form.
• property oninvalid as %ZEN.Datatype.eventHandler(HANDLER="");
oninvalid event handler: This event is fired when this form's validate method determines that the contents of this form are invalid. This provides the application with a chance to display a custom message.
• property onreset as %ZEN.Datatype.eventHandler;
onreset event handler: This event is fired when this form is about to be reset.
• property onsubmit as %ZEN.Datatype.eventHandler(HANDLER="");
onsubmit event handler: This event is fired when this form is about to be submitted. It provides a chance to perform client-side validation of values within the form. If this event handler returns false, then the submit operation will not occur.
Note that unlike the HTML onsubmit event, this callback is always called when the form is submitted.
• property onvalidate as %ZEN.Datatype.eventHandler(HANDLER="");
onvalidate event handler: This event is fired when this form's validate method is called.
• property propagateChanges as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If true, then programmatic changes, via the control's setValue method, to controls in this form will trigger onchange events and notify a dataController if present.
The default is false. In this case, events are only raised in response to user actions.
• property readOnlyMessage as %ZEN.Datatype.caption [ InitialExpression = "This data is read only." ];
Value displayed in alert box by the save method when an attempt is made to save a form bound to readonly data model
This is a localized value.
• property target as %ZEN.Datatype.string;
Specifies the target for the form. (Refer to the HTML form element for details).


• method %DrawHTML()
Static HTML display method: draw the BODY of this component as HTML.
Subclasses implement this in order to render the static HTML contents of a component.
• method %InjectControls() as %Status
Internal method.
Inject additional controls into this when it is added to the page. This is implmented by subclasses.
• method %OnAddToPageAfter() as %Status
Called just after this form is added to the page.
Invokes the OnLoadForm callback for this form.
• method %OnDrawForm() as %Status
This callback gives form subclasses a chance to add additional hidden fields.
• method ReloadForm(pFormIndex As %Integer, pKey As %String) [ ZenMethod ]
Internal method.
Get values for form from user callback; Apply them to client form.
• method clearModified(reset) [ Language = javascript ]
Clear the modified state of this form by visiting every control on the form and resetting its orginalValue property to its current value.
If reset is provided and true, then this also sets the value of every control to '';
• method getControlList(sortBy) [ Language = javascript ]
Internal method. Construct an array of references to every control that belongs to this form. If sortBy is defined, it indicates how the controlList should be ordered, "name", "id".
• method getFormElement() [ Language = javascript ]
Return the HTML form element associated with this component. This is provided in case there are addition HTML form properties or methods that an application needs access to.
• method getValuesAsObject() [ Language = javascript ]
Return the current values of all controls in this form as a zenProxy object. The names of the properties within the proxy object are based on the each control's name attribute.
• method isModified() [ Language = javascript ]
Test if the contents of the form have been modified. This is done by calling the isModified method for each control on the form.
• method notifyViewHandler(reason, data1, data2, data3) [ Language = javascript ]
Notification that the dataController associated with this form has raised an event.
• method onloadHandler() [ Language = javascript ]
This client event, if present, is fired when the page is loaded.
• method reload(key) [ Language = javascript ]
Reload the contents of this form given a key value .
• method reset() [ Language = javascript ]
Reset the HTML form associated with this component.
• method save() [ Language = javascript ]
If this form is connected to a dataController, then validate the contents of the form and then save the data to the server via the dataController. Return the id value used to save the data or "" if not saved.
If this form is not connected to a dataController, this method does nothing.
• method setProperty(property, value, value2) [ Language = javascript ]
Set the value of a named property.
• method setValuesByName(values) [ Language = javascript ]
Given an associative array of the form values[name] = value, set the value of the controls within this form by control name.
• method showMessage(message) [ Language = javascript ]
Show a message by setting the value of the control identified by messageTargetId. Returns true if the message was displayed.
• method submit(action) [ Language = javascript ]
Submit the HTML form associated with this component. action if defined, is the action value that is passed on to the server %OnSubmit callback method.
• method submitHandler() [ Language = javascript ]
Internal method.
Onsubmit event handler. This is an internal method used to trap the default action of the form.
• method validate() [ Language = javascript ]
Validate the contents of this form.
This does the following:
  • Invokes the form-specific onvalidate callback, if present.
  • Calls the validationHandler method for each control within this form.
It returns true if the form is valid.