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.
• 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 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.\nPlease 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, pOnLoadForm As %String, 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.
