Zen Forms

Forms and Controls

The Zen library includes a number of controls for use in forms. Many of these controls are wrappers for the standard HTML controls, while others offer additional functionality. The following figure displays a form that contains a number of controls, including text fields and radio buttons. This is the sample form generated by the class ZENDemo.FormDemoOpens in a new tab in the SAMPLES namespace.

The following figure lists the form and control components that Zen provides. Most of the classes shown in the figure are controls. All of the classes shown in the diagram are in the package %ZEN.Component, for example %ZEN.Component.formOpens in a new tab and %ZEN.Component.controlOpens in a new tab. The diagram shows the inheritance relationships for these classes, and highlights the base classes most frequently discussed in this book.

For details about individual controls, see the chapter “Zen Controls.”

User Interactions

The basic interaction between a Zen application user and a Zen form is as follows:

1. A user interacts with controls on the form

2. Zen may validate the data as it is entered

3. A user action indicates that it is time to submit the form

4. Zen may validate the data prior to attempting the submit

5. Zen interacts with the user to handle any errors it finds

6. When all is well, Zen submits data from the form

7. Any of the following might happen next:

   • Data from the form may be written to the server

   • The same Zen page may redisplay

   • A different Zen page may display

   • The same Zen page may display, but with components added or changed

Defining a Form

The Zen components “<form>” and “<dynaForm>” each support the following attributes for defining the characteristics of a form.

The OnLoadForm method retrieves the values that appear on the form when it first displays. It can get values from the object whose model ID is provided by the key attribute for the form, or it can assign literal values. The method must then place these values into the input array, subscripted by the name attribute for the corresponding control on the form. It is this name (and not the id) that associates a control with a value. Zen invokes this method when it first draws the form, automatically passing it the following parameters:

• %StringOpens in a new tab — the key value for the form

• An array of %StringOpens in a new tab passed by reference

The callback must return a %StatusOpens in a new tab data type. The following example shows a valid method signature and use of parameters:

Method LoadForm(pKey As %String,
                ByRef pValues As %String) As %Status
{
  Set emp = ##class(ZENDemo.Data.Employee).%OpenId(pKey)
  If ($IsObject(emp)) {
    Set pValues("ID") = emp.%Id()
    Set pValues("Name") = emp.Name
    Set pValues("SSN") = emp.SSN
  }
  Quit $$$OK
}

To use the above method as the callback, the developer would set OnLoadForm="LoadForm" for the <form> or <dynaForm>.

Providing Values for a Form

A form can initially display with blank fields, or you can provide data for some of the fields. Providing data for a field that the user sees means setting the value property for the associated Zen control component, before you ask Zen to display the form. There are several ways to do this:

• Set the value attribute while adding each control to XData Contents.

  <text value="hello"/>

• Set the onLoadForm attribute while adding the form to XData Contents.

  <form id="MyForm" OnLoadForm="LoadForm">

• Set value properties from the page’s %OnAfterCreatePage method.

  Do ..%SetValueById("Doctor",$G(^formTest("Doctor")))

• On the client side, call the setValue method for each control.

Presumably, once the user begins editing the form, any initial values may change.

Detecting Modifications to the Form

A Zen form component tracks whether or not changes have occurred in any control on the form. %ZEN.Component.formOpens in a new tab and %ZEN.Component.controlOpens in a new tab each offers a client-side method called isModified that tests this programmatically.

A control’s isModified method returns true if the current logical value of the control (the value property) is different from its original logical value (the originalValue property). With each successive submit operation, the originalValue for each control acquires its previous value, so that this answer is always current with respect to the current state of the form.

When you call a form’s isModified method, it invokes isModified for each control on the form, and if any control returns true, isModified returns true for the form.

Validating a Form

Each Zen form has a validate method whose purpose is to validate the values of controls on the form. If the form’s autoValidate property is true, validate is called automatically each time the form is submitted. Otherwise, validate may be called explicitly by the application. validate does the following:

1. Calls a form-specific onvalidate event handler, if defined. If this event returns false, Zen declares the form invalid and no further testing occurs.

2. Resets the invalid property of all the form’s controls to false, then tests each control by calling the control’s validationHandler method. This method, in turn, does the following:

   • If the control’s readOnly or disabled properties are true, return true.

   • If the control’s required property is true and the control does not have a value (its value is ""), return false.

   • If the control defines an onvalidate event, execute it and returns its value. Otherwise, call the control’s isValid method. isValid can be overridden by subclasses that wish to provide built-in validation (such as the dateText control).

3. As the validate method tests each control, the form builds a local array of invalid controls.

4. After the validate method is finished testing the controls, it returns true if the form is valid.

5. If the form contains one or more controls with invalid values, it is invalid. validate performs one of the following additional steps to handle this case:

   • If the form defines an oninvalid event handler:

     Execute the handler. This provides the form with a chance to handle the error conditions. The value returned by the oninvalid event is then returned by the form’s validate method. The oninvalid handler has an argument named invalidList that receives a JavaScript array containing the list of invalid controls. For example:

     <form oninvalid="return zenPage.formInvalid(zenThis,invalidList);" />

     

     Where the formInvalid method looks like this:

     
     ClientMethod formInvalid(form,list) [ Language = javascript ]
     {
       return false;
     }

     

   • When the form has no oninvalid event handler:

     validate sets the invalid property to true for each invalid control (which changes their style to zenInvalid); gives focus to the first invalid control; and displays an error message within an alert box. The message displayed in the alert box is built from a combination of the form’s invalidMessage property along with the value returned from each invalid control’s getInvalidReason method.

Errors and Invalid Values

Should an error occur while a form is being submitted, or should the form fail validation, Zen redisplays the page containing the form. The user has the opportunity to re-enter any incorrect values and submit the page again. All of this is extremely easy to set up when adding the <form> or <dynaForm> component to the Zen page.

The SAMPLES namespace class ZENTest.FormTestOpens in a new tab allows you to experience error handling with Zen forms as follows:

1. Start your browser.

2. Enter this URI:

   http://localhost:57772/csp/samples/ZENTest.FormTest.clsOpens in a new tab

   Where 57772 is the web server port number that you have assigned to Caché.

3. Ensure that the Name field is empty.

4. Clear the Status check box.

5. Click Submit.

6. The form’s validate method detects the invalid fields and highlights them with pink.

7. The following alert message displays in the browser.

   

   To generate this message, the form has assembled the following snippets of text. Zen offers default values for these items, so there is no need for you to do anything for the default message to appear. However, if you wish you can customize them to any extent:

   • The message begins with the form’s invalidMessage text.

   • For each control that has its required attribute set to true, but contains no entry, the message lists the control’s label followed by the control’s requiredMessage text.

   • For each control that contains an invalid value, the message lists the control’s label followed by the control’s invalidMessage text.

8. Click OK to dismiss the alert message box.

9. The invalid controls remain highlighted until the user edits them and resubmits the form.

Processing a Form Submit

The request to submit the contents of a form can be triggered in one of two ways:

• The user clicks a “<submit>” button placed within the form.

• The application calls the submit method of the form object in response to a user event:

  %form.submit

When a form is submitted, the values of the controls in the form are sent to the server and the %OnSubmit callback method of the page containing the form is called. Note that the %OnSubmit callback method is that of the page that contains the form, not of the form itself or of any component on the form.

%OnSubmit receives an instance of a special %ZEN.SubmitOpens in a new tab object that contains all the submitted values. Note that there is no page object available during submit processing. Zen automatically handles the full details of the submit operation, including invoking server callbacks and error processing. All forms are submitted using the HTTP POST submission method.

Note that using the setting ENCODED=2 disables the <form> component, because ENCODED=2 removes all unencrypted parameters from the url.

If you are interested in details of how Zen executes a submit operation, the following table lists the internal events in sequence, organized by user viewpoint, browser-based execution, and server-side execution. Most of the communication details are handled by the CSP technology underlying Zen. For background information, see the “Zen Client and Server” chapter in Using Zen.

User Login Forms

An application login page presents a special case of a Zen form. To create application login and logout pages, see the section “Controlling Access to Applications” in the “Zen Security” chapter of Developing Zen Applications.

Dynamic Forms

A <dynaForm> is a specialized type of form that dynamically injects control components into a group (or groups) on the Zen page. Layout is determined automatically by code internal to the <dynaForm>. The list of controls may be determined by the properties of an associated data controller, or by a callback method that generates a list of controls.

<dynaForm> has the following attributes:

The callback method identified by the OnGetPropertyInfo attribute prepares additional controls to inject onto the form when it is displayed. If this method is defined in the page class, Zen invokes it when it first draws the form, automatically passing it the following parameters:

• %IntegerOpens in a new tab — the next index number to apply to a control on the generated form. As the callback method injects additional controls on the form, it must increment this index value, as shown in the example below.

• As array of %StringOpens in a new tab passed by reference.

• %StringOpens in a new tab — the current data model ID, for cases where the contents of a dynamic form vary by instance of the data model object. The method can get values from this object, or it can assign literal values.

To define additional controls, the method must place values into the input array, using two-part subscripts as follows:

1. The first subscript is the value of the name attribute that was assigned to the corresponding control on the form. It is this name (and not the id) that identifies the control and associates it with a value. For example, the following array position stores the 1–based index of the control’s ordinal position on the form:

   pInfo(name)

2. The second subscript is the name of a property on the control object. %type is a control property whose value identifies the type of the control. The names of other properties are listed in the “Zen Controls” chapter, either in the “Control Attributes” section or in topics about specific controls. For example, the following array position stores the value for the attr attribute of the name control:

   pInfo(name,attr)

The callback must return a %StatusOpens in a new tab data type. The following example shows a valid method signature and use of parameters and array subscripts:

Method GetInfo(pIndex As %Integer,
               ByRef pInfo As %String,
               pModelId As %String) As %Status
{
  Set pInfo("Field1") = pIndex
  Set pInfo("Field1","%type") = "textarea"
  Set pInfo("Field2") = pIndex + 1
  Set pInfo("Field2","label") = "Field 2"
  Quit $$$OK
}

To use the above method as the callback, the developer would set OnGetPropertyInfo="GetInfo" for the <dynaForm>.

If the last control on the generated form comes from an embedded property with n fields, your callback must increment past these generated controls by adding n to the index number at the beginning of the method, before assigning the index to any controls. This convention is not necessary when the last generated control on the form comes from a simple data type, such as %StringOpens in a new tab, %BooleanOpens in a new tab, or %NumericOpens in a new tab. The previous example shows the simple case, in which the method uses and increments the index provided.