%ZEN.Component.form
class %ZEN.Component.form extends %ZEN.Component.group, %ZEN.Component.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.
Property Inventory
- OnLoadForm
- OnSubmitForm
- action
- autoValidate
- autocomplete
- enctype
- invalidMessage
- key
- messageTargetId
- method
- nextPage
- noModelMessage
- onchange
- ondefault
- oninvalid
- onreset
- onsubmit
- onvalidate
- propagateChanges
- readOnlyMessage
- target
Method Inventory
- %DrawHTML()
- %InjectControls()
- %OnAddToPageAfter()
- %OnDrawForm()
- ReloadForm()
- clearModified()
- getControlList()
- getFormElement()
- getValuesAsObject()
- isModified()
- notifyViewHandler()
- onloadHandler()
- reload()
- reset()
- save()
- setProperty()
- setValuesByName()
- showMessage()
- submit()
- submitHandler()
- validate()
Parameters
parameter DEFAULTGROUPCLASS = form;
Inherited description: 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;
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.
Classes outside of the Zen library should not set this, they should use the MODULE instead.
Properties
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.
This must be the name of a server-only method in the page class that contains this form component.
Property methods: OnLoadFormDisplayToLogical(), OnLoadFormGet(), OnLoadFormIsValid(), OnLoadFormLogicalToDisplay(), OnLoadFormLogicalToOdbc(), OnLoadFormNormalize(), OnLoadFormSet()
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.
This must be the name of a server-only method in the page class that contains this form component.
Property methods: OnSubmitFormDisplayToLogical(), OnSubmitFormGet(), OnSubmitFormIsValid(), OnSubmitFormLogicalToDisplay(), OnSubmitFormLogicalToOdbc(), OnSubmitFormNormalize(), OnSubmitFormSet()
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.
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 methods: actionDisplayToLogical(), actionGet(), actionIsValid(), actionLogicalToDisplay(), actionLogicalToOdbc(), actionNormalize(), actionSet()
property autoValidate as %ZEN.Datatype.boolean [ InitialExpression = 1 ];
If true (the default), automatically invoke this form's
validate() whenever this form is submitted.
Property methods: autoValidateDisplayToLogical(), autoValidateGet(), autoValidateIsValid(), autoValidateLogicalToDisplay(), autoValidateLogicalToOdbc(), autoValidateLogicalToXSD(), autoValidateNormalize(), autoValidateSet(), autoValidateXSDToLogical()
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.
This setting can be overridden by an autocomplete attribute on an element belonging to the form.
Property methods: autocompleteDisplayToLogical(), autocompleteGet(), autocompleteIsValid(), autocompleteLogicalToDisplay(), autocompleteLogicalToOdbc(), autocompleteLogicalToXSD(), autocompleteNormalize(), autocompleteSet(), autocompleteXSDToLogical()
property enctype as %ZEN.Datatype.string;
Specifies the enctype for the form.
(Refer to the HTML form element for details).
Property methods: enctypeDisplayToLogical(), enctypeGet(), enctypeIsValid(), enctypeLogicalToDisplay(), enctypeLogicalToOdbc(), enctypeNormalize(), enctypeSet()
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.
This is a localized value.
Property methods: invalidMessageDisplayToLogical(), invalidMessageGet(), invalidMessageIsValid(), invalidMessageLogicalToDisplay(), invalidMessageLogicalToOdbc(), invalidMessageNormalize(), invalidMessageSet()
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.
If this form is connected to a dataController then this value will be ignored.
Property methods: keyDisplayToLogical(), keyGet(), keyIsValid(), keyLogicalToDisplay(), keyLogicalToOdbc(), keyNormalize(), keySet()
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 methods: messageTargetIdDisplayToLogical(), messageTargetIdGet(), messageTargetIdIsValid(), messageTargetIdLogicalToDisplay(), messageTargetIdLogicalToOdbc(), messageTargetIdNormalize(), messageTargetIdSet()
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.
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 methods: methodDisplayToLogical(), methodGet(), methodIsValid(), methodLogicalToDisplay(), methodLogicalToOdbc(), methodNormalize(), methodSet()
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 methods: nextPageDisplayToLogical(), nextPageGet(), nextPageIsValid(), nextPageLogicalToDisplay(), nextPageLogicalToOdbc(), nextPageNormalize(), nextPageSet()
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 methods: noModelMessageDisplayToLogical(), noModelMessageGet(), noModelMessageIsValid(), noModelMessageLogicalToDisplay(), noModelMessageLogicalToOdbc(), noModelMessageNormalize(), noModelMessageSet()
property onchange as %ZEN.Datatype.eventHandler);
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.
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 methods: onchangeDisplayToLogical(), onchangeGet(), onchangeIsValid(), onchangeLogicalToDisplay(), onchangeLogicalToOdbc(), onchangeNormalize(), onchangeSet()
property ondefault as %ZEN.Datatype.eventHandler);
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 methods: ondefaultDisplayToLogical(), ondefaultGet(), ondefaultIsValid(), ondefaultLogicalToDisplay(), ondefaultLogicalToOdbc(), ondefaultNormalize(), ondefaultSet()
property oninvalid as %ZEN.Datatype.eventHandler);
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 methods: oninvalidDisplayToLogical(), oninvalidGet(), oninvalidIsValid(), oninvalidLogicalToDisplay(), oninvalidLogicalToOdbc(), oninvalidNormalize(), oninvalidSet()
property onreset as %ZEN.Datatype.eventHandler;
onreset event handler:
This event is fired when this form is about to be reset.
Property methods: onresetDisplayToLogical(), onresetGet(), onresetIsValid(), onresetLogicalToDisplay(), onresetLogicalToOdbc(), onresetNormalize(), onresetSet()
property onsubmit as %ZEN.Datatype.eventHandler);
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.
Note that unlike the HTML onsubmit event, this callback is always called when the form is submitted.
Property methods: onsubmitDisplayToLogical(), onsubmitGet(), onsubmitIsValid(), onsubmitLogicalToDisplay(), onsubmitLogicalToOdbc(), onsubmitNormalize(), onsubmitSet()
property onvalidate as %ZEN.Datatype.eventHandler);
onvalidate event handler:
This event is fired when this form's validate method is called.
Property methods: onvalidateDisplayToLogical(), onvalidateGet(), onvalidateIsValid(), onvalidateLogicalToDisplay(), onvalidateLogicalToOdbc(), onvalidateNormalize(), onvalidateSet()
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.
The default is false. In this case, events are only raised in response to user actions.
Property methods: propagateChangesDisplayToLogical(), propagateChangesGet(), propagateChangesIsValid(), propagateChangesLogicalToDisplay(), propagateChangesLogicalToOdbc(), propagateChangesLogicalToXSD(), propagateChangesNormalize(), propagateChangesSet(), propagateChangesXSDToLogical()
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.
This is a localized value.
Property methods: readOnlyMessageDisplayToLogical(), readOnlyMessageGet(), readOnlyMessageIsValid(), readOnlyMessageLogicalToDisplay(), readOnlyMessageLogicalToOdbc(), readOnlyMessageNormalize(), readOnlyMessageSet()
property target as %ZEN.Datatype.string;
Specifies the target for the form.
(Refer to the HTML form element for details).
Property methods: targetDisplayToLogical(), targetGet(), targetIsValid(), targetLogicalToDisplay(), targetLogicalToOdbc(), targetNormalize(), targetSet()
Methods
method %DrawHTML()
Inherited description: 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.
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.
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.
Invokes the OnLoadForm callback for this form.
method %OnDrawForm() as %Status
This callback gives form subclasses a chance to add additional
hidden fields.
Internal method.
Get values for form from user callback; Apply them to client form.
Get values for form from user callback; Apply them to client form.
clientmethod 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 '';
If reset is provided and true, then this also sets the value of every control to '';
clientmethod 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".
clientmethod 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.
clientmethod 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.
clientmethod 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.
clientmethod notifyViewHandler(reason, data1, data2, data3) [ Language = javascript ]
Notification that the dataController associated with this form
has raised an event.
clientmethod onloadHandler() [ Language = javascript ]
This client event, if present, is fired when the page is loaded.
clientmethod reload(key) [ Language = javascript ]
Reload the contents of this form given a key value .
clientmethod reset() [ Language = javascript ]
Reset the HTML form associated with this component.
clientmethod 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.
If this form is not connected to a dataController, this method does nothing.
clientmethod setProperty(property, value, value2) [ Language = javascript ]
Set the value of a named property.
clientmethod 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.
clientmethod showMessage(message) [ Language = javascript ]
Show a message by setting the value of the control identified by
messageTargetId.
Returns true if the message was displayed.
clientmethod 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.
clientmethod submitHandler() [ Language = javascript ]
Internal method.
Onsubmit event handler. This is an internal method used to trap the default action of the form.
Onsubmit event handler. This is an internal method used to trap the default action of the form.
clientmethod validate() [ Language = javascript ]
Validate the contents of this form.
This does the following:
This does the following:
- Invokes the form-specific onvalidate callback, if present.
- Calls the validationHandler() method for each control within this form.
Inherited Members
Inherited Properties
- %condition
- %controller
- %import
- %includeFiles
- %page
- %resource
- align
- aux
- cellAlign
- cellSize
- cellStyle
- cellVAlign
- children
- composite
- containerStyle
- controller
- controllerId
- disabled
- dragEnabled
- dropEnabled
- enclosingClass
- enclosingStyle
- error
- groupClass
- groupStyle
- height
- hidden
- hint
- hintClass
- hintStyle
- id
- index
- label
- labelClass
- labelDisabledClass
- labelPosition
- labelStyle
- layout
- name
- onafterdrag
- onbeforedrag
- onclick
- ondrag
- ondrop
- onhide
- onnotifyView
- onrefresh
- onshow
- onupdate
- parent
- showLabel
- slice
- title
- tuple
- valign
- visible
- width
- window
Inherited Methods
- %AddChild()
- %AddChildAfter()
- %AddChildBefore()
- %AddToSaveSet()
- %Attr()
- %BindExport()
- %ClassIsLatestVersion()
- %ClassName()
- %ConstructClone()
- %DispatchClassMethod()
- %DispatchGetModified()
- %DispatchGetProperty()
- %DispatchMethod()
- %DispatchSetModified()
- %DispatchSetMultidimProperty()
- %DispatchSetProperty()
- %DrawComponentHTML()
- %DrawJSStrings()
- %EnclosingDivId()
- %Eval()
- %EvalC()
- %Extends()
- %ForceClientRender()
- %GetChildIndex()
- %GetEventHandlers()
- %GetParameter()
- %GetXMLName()
- %IsA()
- %IsModified()
- %MakeId()
- %New()
- %NormalizeObject()
- %ObjectModified()
- %OnAddToPageBefore()
- %OnDrawEnclosingDiv()
- %OnDrawObjectProperties()
- %OnMutateChildren()
- %OnObjectSynch()
- %OnZENDeserialize()
- %OriginalNamespace()
- %PackageName()
- %QuoteValue()
- %QuoteValueL10N()
- %RemoveChild()
- %RemoveChildren()
- %RemoveFromSaveSet()
- %Self()
- %SerializeObject()
- %SetModified()
- %ValidateObject()
- XMLDTD()
- XMLExport()
- XMLExportToStream()
- XMLExportToString()
- XMLNew()
- XMLSchema()
- XMLSchemaNamespace()
- XMLSchemaType()
- addChild()
- addChildAfter()
- addChildBefore()
- childrenMutated()
- dragFinishHandler()
- dragHandler()
- dragNotifyHandler()
- dragStartHandler()
- dropHandler()
- dropStartHandler()
- exposeComponent()
- findElement()
- fireOnUpdateEvent()
- getChildIndex()
- getController()
- getEnclosingDiv()
- getHidden()
- getHintElement()
- getLabelElement()
- getProperty()
- getSettings()
- getType()
- invokeSuper()
- isOfType()
- makeId()
- onCreate()
- onDelete()
- onDisplayHandler()
- onEndModalHandler()
- onPopupAction()
- onRefreshContents()
- onSerialize()
- onStartModalHandler()
- ondisabledHandler()
- onunloadHandler()
- onupdateHandler()
- refreshContents()
- removeChild()
- render()
- renderContents()
- renderSVG()
- sendEventToController()
- setControllerId()
- setHidden()
- setOverlayMode()
- setPropertyAll()
- startProgressBar()
- stopProgressBar()