This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

%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 (Including Private)

Method Inventory (Including Private)

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.

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

private method %BindDataControls(pController As %ZEN.Auxiliary.dataController, pGroup As %ZEN.Component.group = "") as %Status
Internal method.
Copies values from a dataController object to the controls that belong to this form.
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.
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.
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 '';
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.
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.
clientmethod 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.

Inherited Members

Inherited Properties (Including Private)

Inherited Methods (Including Private)

Subclasses

Feedback