Using Zen Components
Zen Controls
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Zen controls are the user input elements that you place on a Zen form. All controls are Zen components, but Zen controls also have unique characteristics derived from their parent class %ZEN.Component.control.

Most importantly, each control has a value associated with it. value is a property that contains the current logical value of the control. Each control has the ability to display this value or keep it internally. Zen validates and submits all the control values for a form together, as a unit, according to the rules described in the chapter Zen Forms.”
This chapter:
Control Attributes
All Zen controls have the following attributes in common.
Control Component Attributes
Attribute Description
Zen component attributes
A control has the same general-purpose attributes as any Zen component. For descriptions, see these sections:
Of these attributes, name has special significance for a control. When the form is submitted, your code must use this name (and not the id) to retrieve the value of the control. If the control does not have a name, its value cannot be retrieved.
To avoid clashing with name values reserved by Caché Server Pages, do not use any name for a Zen control that begins with the string Cache. Also avoid using punctuation characters in name values, particularly the _ underscore character.
For more information that applies to all control components, see Data Drag and Drop and Control Methods in this chapter.
clientType
Indicates the client-side (JavaScript) data type to expect for this control’s value. By default, a controls treats its value as a string with no client-side normalization. However, a control can set a value for clientType to indicate that it has a non-string value on the client side. Possible values are:
controlClass Name of a CSS style class. When Zen lays out this control, it assigns this value to the primary HTML element displayed for this control.
controlStyle String containing a CSS style definition. Zen applies this style to the primary HTML element displayed for this control.
dataBinding If this control is associated with a data controller, this attribute identifies the specific property within the <dataController> modelClass that provides the value for this control. See the chapter Model View Controller.”
disabled
If true, this control is disabled; its appearance is unchanged, but it does not respond to user actions. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
invalid
Set to true when the value of this control is known to be invalid. Zen form validation logic does this so that Zen can display this control in a way that indicates its value is invalid. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
invalidMessage
Message text to provide when invalid is true. The default is:
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
The next several attributes in this table (names beginning with “on...”) identify event handlers for user actions relating to a control. Zen invokes the handler when the related event occurs. See Zen Component Event Handlers.”
onblur Fired when the control loses focus.
onchange Fired when the value of the control changes. Note that controls fire this event indirectly; the actual onchange event is sent to a built-in handler that notifies the form that owns this control of the modification.
onclick Fired when the mouse is clicked on the control.
ondblclick Fired when the mouse is double-clicked on the control.
onfocus Fired when the control is given focus.
onkeydown Fired when the user presses down on a key while this control has focus. There is a corresponding onkeyup for when the user releases the key.
onkeypress Fired after the user has pressed a key (that is, the user has pushed down and then released the key) while this control has focus.
onkeyup Fired when a key is released while this control has focus.
onmousedown Fired when a mouse button is released while within the area of the control.
onmouseout Fired when the mouse pointer leaves the area of the control.
onmouseover Fired when the mouse pointer enters the area of the control.
onmouseup Fired when a mouse button is pressed while within the area of the control.
onsubmit Fired when the form this control belongs to is submitted. This gives controls a chance to supply or modify the value they submit.
onvalidate Fired when this control’s value is validated by its parent form.
(End of the list of attributes that identify event handlers.)
originalValue
Original value for this control before any user modification. It is used to detect which controls have been modified. This is a special value in that it is automatically initialized when a form is displayed.
On the client side, do not access this property directly; instead use the getProperty and setProperty client-side methods. Note that setting the originalValue property on the client (via setProperty) resets it to the current value of this control.
readOnly
If true, this control is read-only. The user cannot change the value of this control, but the control still appears on the form and still submits its value when the form that contains it is submitted. Setting readOnly to true effectively disables the component; this is the standard HTML behavior for select controls. The default readOnly value is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
required
If true, this control is required. That is, a user must supply a value for this control or the default form validation logic fails.
This attribute has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
requiredMessage
Message text that the form validate method displays in an alert box when this control is required and does not have a value. The default requiredMessage text is:
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
tabIndex Integer used to provide a value for the HTML tabIndex attribute. The browser uses this attribute to control the tab order of controls within a form.
value
Default value displayed within this control. This is a special value in that it is automatically initialized when a form is displayed. The value can be a literal string, or it can contain a Zen #()# runtime expression.
On the client side, do not access this property directly; instead use the getValue and setValue client-side methods.
Data Drag and Drop
All Zen controls support data drag and drop functionality as follows:
For more information about how to configure data drag and drop for Zen controls, consult the following sections:
Control Methods
Each control has internal methods, which you can study in more detail by viewing the online class documentation for %ZEN.Component.control and its subclasses.
The most important of these methods are those used to manipulate the value of the control. You can get and set the value property using the client-side getProperty and setProperty methods. In fact, getProperty and setProperty are available for you to work programmatically with any of the properties listed in the Control Attributes section, not just value. Calling the setProperty method ensures that all actions relating to setting the property also occur, including rendering the content within the control on the page.
Zen controls also define the convenient client-side methods getValue and setValue, which work only on the value property, and so do not require you to specify which property you wish to change.
Buttons
Zen offers the following button-style controls:
<button>
The <button> component is a simple wrapper for the HTML <input type="button"> element. A Zen <button> looks like this:
<button> has the following attributes:
Attribute Description
Control component attributes <button> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” Control attributes include onclick, which determines what happens when a user clicks the button. If you want a user click to cause the form to be submitted, use the <submit> control instead of <button>.
caption
Text displayed on this button. The above example uses:
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
The caption value can be a literal string, or it can contain a Zen #()# runtime expression.
<image>
The <image> control displays a static image. <image> can be used simply to display an image, or it can serve as a button if you specify an onclick event for it. The <image> component offers several different properties whose values can specify the image to display:
Images that are binary stream objects are served via the CSP stream server. The OID value is encrypted (using the current session key) when it is sent to the client. If this value is returned to the server, it is automatically decrypted. This makes it possible to place sensitive data on the client for future processing on the server without letting a user view this data.
The <image> element has the following attributes:
Attribute Description
Control component attributes <image> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” For the <image> element, value plays a special role, as described in this section. Also, controlClass does not apply to <image>, but controlStyle does apply.
alt
A string of text to display in place of the image if it is unavailable. This becomes the alt attribute value for the HTML <img> element on the displayed page.
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
srcDisabled If provided, srcDisabled is the URI of an image to display when the disabled attribute for this <image> is set to true.
srcMissing
If provided, srcMissing is the URI of an image to display when a value for this image is missing. srcMissing is used when this image is bound to a property of a data controller and there is no value for the bound property. There is a default for srcMissing if you do not provide it. The default is a small blank space image:
src
If provided, src is the URI of an image to display. If src is the relative pathname of a file, it is understood to be relative to the Caché installation directory. Typically this path identifies the images subdirectory for your Zen application, for example:
text
If defined, this string provides a text value to associate with this image. text is used as both the logical value and the display value when this image is the source of a drag and drop operation.
To enable drag and drop features to work, the <page> that contains the <image> must have its dragAndDrop attribute set to true. For details, see the Data Drag and Drop section in this chapter.
value
The value attribute works differently for <image> than for other control components. First of all, <image> does not submit its value when the user submits the form. Secondly, the value plays an important role in serving the image.
value is used when the image is bound to a property within a data controller that contains binary stream data. In this case, value specifies an encrypted stream OID value for a binary stream object containing the image.
The %ZEN.SVGComponent.image class offers a streamId property. If it has a value, the streamId is the OID value for a binary stream object containing the image.
There is no way to assign a streamId directly in the XData block, because you must first acquire an OID for the object you are referencing. You can only assign a value to the streamId property by working with the image component programmatically, in %OnAfterCreatePage.
To specify an image using a streamId, use this technique:
  1. Provide the <image> element in XData, that is:
    <image id="img"/>
    
  2. In the %OnAfterCreatePage method for the Zen page class that displays the image, provide code that references the <image> element and provides a value for its streamId, for example:
    Set img = ..%GetComponentById("img")
    Set stream=##class(%FileBinaryStream).%New()
    Set filename=$system.CSP.GetFileName("/csp/samples/ClassLogo.jpg")
    Do stream.LinkToFile(filename)
    Set oid=stream.%Oid()
    Set img.streamId = oid
    
Note:
If both streamId and src values are provided for an image, streamId overrides src.
<submit>
<submit> is a special type of button that submits a form. For details, see the section Processing a Form Submit in this chapter.
<submit> has the following attributes:
Attribute Description
Control component attributes <submit> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” You do not supply an onclick attribute for a <submit> control, because the purpose of clicking an <submit> control is to submit the form on which it appears.
caption
Text displayed on this button.
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.
action String giving the action code associated with this <submit> button. This value is passed along to the server-side %OnSubmit method of the page that contains the <submit>. If not provided, the default string is "submit".
nextPage URI of the page to display after this form is successfully submitted. If a <submit> button defines a nextPage value, it overrides the nextPage value for the form that contains the <submit>.
Text
Zen offers the following text-style controls:
<label>
The <label> control passively displays a static text value. Zen submits the <label> along with other controls on the <form>. <label> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.”
<text>
The Zen <text> control is a wrapper around the HTML <input type="text"> element. Zen <text> displays a text input box like this:
<text> has the following attributes:
Attribute Description
Control component attributes <text> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” The <text> value is a string of text.
autocomplete Indicates whether the value of this text control can be automatically completed by default by the browser.
maxlength Maximum number of characters that the user may enter within this text control.
placeholder A placeholder that specifies a short hint describing the expected value of an input field, for example, a sample value or a short description of the expected format. The hint is displayed in the input field when it is empty.
size Integer indicating the HTML width of the input area for this text control. The default size is 20.
spellcheck If true, spellcheck is enabled. This is an HTML5 attribute. It works correctly only on HTML5 compliant browsers. Supported only by IE10 and higher. The default value is true.
spellcheck has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
<textarea>
The Zen <textarea> control is a wrapper around the HTML <textarea> element. Zen <textarea> displays a multi-line text input box, like this:
<textarea> has the following attributes:
Attribute Description
Control component attributes <textarea> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” The <textarea> value is a string of text that may or may not include line break characters, depending on what the user types. Keep in mind that many browsers do not cope well with long lines of unbroken text; that is, greater than 4K characters with no white space.
cols Number of columns in the <textarea> control. The default is 19.
rows Number of rows in the <textarea> control. The default is 2.
spellcheck If true, spellcheck is enabled. This is an HTML5 attribute. It works correctly only on HTML5 compliant browsers. Supported only by IE10 and higher. The default value is true.
spellcheck has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
<password>
The Zen <password> control is a wrapper around the HTML <input type="password"> element. Zen <password> displays a text input box for passwords. Any text that the user enters into the <password> control is echoed as a dot instead of being displayed on the screen. For example:
Note:
For an example of a user login page that use the <password> element to control access to a Zen application, see the section Controlling Access to Applications in the “Zen Security” chapter of Developing Zen Applications.
<password> has the following attributes:
Attribute Description
Control component attributes <password> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” The <password> value is a string of text.
maxlength Maximum number of characters that the user may enter within this control.
size Integer indicating the HTML width of the input area for this control. The default size is 20.
Selections
Zen offers the following selection controls:
The difference between <radioButton> and <radioSet> is that <radioSet> is simpler to lay out. Use <radioSet> for a concise list of choices. Use <radioButton> when you want a more complex page layout that provides intervening information or images in between the radio button choices, or when you want to place radio buttons in a vertical group.
<checkbox>
The Zen <checkbox> control is a wrapper around the HTML <input type="check"> element. The Zen <checkbox> control displays a caption next to the check box and detects user mouse clicks on the caption text as well as on the check box. Unlike an HTML check box, the Zen <checkbox> control always submits a value. Zen <checkbox> looks like this:
<checkbox> has the following attributes:
Attribute Description
Control component attributes <checkbox> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” <checkbox> always has its clientType set to "boolean". This means the <checkbox> value is expressed as 1 or 0 in XData Contents and server-side code, and true or false in client-side code. A value of 1 or true means the check box is currently selected; 0 or false means it is clear.
caption
Text displayed to the right of the check box. The above example uses:
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
The caption value can be a literal string, or it can contain a Zen #()# runtime expression.
captionClass
Name of a CSS style class to apply to the caption text. The default is:
<multiSelectSet>
The <multiSelectSet> control displays a column of check buttons to show a complete set of choices. The user can select one or more of the listed choices. A Zen <multiSelectSet> looks like this:
To define a <multiSelectSet>, provide a valueList for the user to choose from. If you also provide a corresponding displayList it provides the displayed captions for the user to see. For example, you could produce the sample <multiSelectSet> illustrated above by providing the following statement in XData Contents:
<multiSelectSet displayList="One,Two,Three,Four"
    valueList="1,2,3,4" />
<multiSelectSet> has the following attributes:
Attribute Description
Control component attributes
<multiSelectSet> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” The <multiSelectSet> value is a comma-separated list of the values that are currently checked. Items appear in this list in the same order as in the valueList
It is also possible to programmatically set the value of the <radioSet> to any arbitrary value using the client-side setValue method. If the value of the <multiSelectSet> does not correspond to any item in the valueList, all check boxes in the set appear clear.
captionClass Name of the CSS style class to apply to captions for check boxes within this <multiSelectSet>. The default is the built-in CSS style class multiSelectSetCaption.
choiceColumn Serves the same function as the choiceColumn attribute in dataCombo, see <dataCombo> General Attributes.”
displayList
Comma-separated list of choices to display for this <multiSelectSet>. displayList applies only if a valueList is defined. Display values may differ from the actual logical values.
If there is an empty value ("") within the items in the displayList, as in:
Then an additional check box is displayed for the empty value. The caption for this empty value is specified by the emptyCaption attribute.
The displayList attribute has its ZENLOCALIZE datatype parameter set to 1 (true). This makes it easy to localize its text into other languages, and permits use of the $$$Text macros when you assign values to this property from client-side or server-side code.
Any localized displayList string must remain a comma-separated list.
emptyCaption
The default caption to use for any check boxes in this <multiSelectSet> that have an empty value ("") assigned to them in the displayList. If you do not specify an emptyCaption, the default caption is:
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
titleList
Comma-separated list of tooltip text strings for each check box in the <multiSelectSet>.
The titleList attribute has its ZENLOCALIZE datatype parameter set to 1 (true). This makes it easy to localize its text into other languages, and permits use of the $$$Text macros when you assign values to this property from client-side or server-side code.
Any localized titleList string must remain a comma-separated list.
valueColumn Serves the same function as the valueColumn attribute in dataCombo, see <dataCombo> General Attributes.”
valueList
Comma-separated list of logical values for the <multiSelectSet>. If there is an empty value ("") in the valueList (for example, "A,,B,C"), then an additional button is displayed for the empty value. The label for the empty value is specified by the emptyCaption.
The value of the <multiSelectSet> is a comma-separated list of the values that are currently checked. Items appear in this list in the same order as in the valueList. Use the displayList to provide a corresponding list of choices to display to the user.
Zen assumes that every value within the set is distinct. If a valueList contains duplicate items, as in:
Then user selections produce unexpected behavior.
<fileUpload>
The <fileUpload> component is a simple wrapper for the HTML <input type="file"> element. A Zen <fileUpload> control looks like this:
The precise appearance and text used in the control is determined by the browser, and therefore varies with different browsers. When the user has selected a file, the text “No file chosen” is replaced with the filename, or text indicating the number of files selected in the case of multiple upload.
A user clicks the button to open a file open dialog and navigate to the file of interest, then select and open the file. The next action depends on the browser. When the user submits the form on which the <fileUpload> appears, on some browsers, the value of the <fileUpload> component is the full pathname including the filename. On many modern browsers, the value is the filename only. Browser manufacturers offer this denial of visibility into the full path as a security measure. If included in the browser design, this security measure cannot be overruled by a Zen application.
To be sure that your Zen application is independent of the user’s choice of browser, you can strip the full pathname from the returned value of the <fileUpload> component. As an example, suppose your <fileUpload> component has an id of getFile. Inside your %OnSubmit method, you can have these lines of ObjectScript code:
ClassMethod %OnSubmit(pSubmit As %ZEN.Submit) As %Status
{
 Set file = pSubmit.%GetValue("getFile")
 Set file = ##class(%Library.File).GetFilename(file) // strip out the path on IE
 // ... other lines of code here ...
 Quit $$$OK
}
<fileUpload> has the following attributes:
Attribute Description
Control component attributes <fileUpload> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” The <fileUpload> value is a string that is the full pathname of a file.
accept Comma-separated list of MIME types that can be uploaded. If provided, this value is used as the accept attribute value for the HTML <input> element.
maxlength Maximum number of characters that the user may enter in this control. This property was used in the past, when browsers allowed the user to type a filename into this control. It is retained primarily for compatibility with earlier versions of Caché
multiple If true, allow multiple files to be uploaded at once. The default value is false. This property requires an HTML5 compliant browser.
size Integer indicating the HTML width of the input area for this control. The default size is 20.
The fileSelect dialog offers a mechanism to select files on the server. See the section File Selection Dialog Window.”
Important:
If you use the <fileUpload> component, you need to be aware of an important security restriction on the file upload control that is enforced by most browsers. The following paragraphs describe this restriction.
Most modern browsers regard the value field of a file upload control to be read-only for security purposes. The rationale behind this is that, if it were possible to set the value field via a script, it would be trivial to link a form submit event to any other event generator on the page. A devious programmer could, for example, embed a hidden form, either not displayed or clipped to an area only 1 pixel square, and program it to covertly copy files off the client machine every time the mouse pointer moved. For this reason, the value of the file to be uploaded on a form submit can only be set by direct user action on most browsers. No modern browsers allow the value to be set quietly in the background.
<colorPicker>
The <colorPicker> component displays a row of color choices. The user can click on a color to select it. <colorPicker> offers a simple alternative to the complex palette in <colorPane>. A Zen <colorPicker> looks like this:
<colorPicker> has the following attributes:
Attribute Description
Control component attributes <colorPicker> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” The <colorPicker> value is a string that identifies the most recently selected CSS color value.
colorList
Comma-separated list of CSS color values to display within the control, from left to right. The default colorList value is as shown in the example above:
<radioSet>
The <radioSet> control displays a row of radio buttons to show a complete set of choices. A Zen <radioSet> looks like this:
<radioSet> General Attributes
To define a <radioSet>, provide a valueList for the user to choose from and a corresponding displayList for the user to see. For example, you could produce the sample <radioSet> illustrated above by providing the following statement in XData Contents:
<radioSet id="QuarkStatus" name="QuarkStatus"
          displayList="Up,Down,Charmed,Strange,Top,Bottom"
          valueList="U,D,C,S,T,B"/>
<radioSet> has the following general-purpose attributes.
Attribute Description
Control component attributes
<radioSet> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” The <radioSet> value is the logical value of the currently selected button in the set. This logical value comes from the corresponding valueList entry for the <radioSet>.
It is also possible to programmatically set the value of the <radioSet> to any arbitrary value using the client-side setValue method. If the value of the <radioSet> does not correspond to any item in the valueList, all buttons in the set appear clear.
Data source attributes
<radioSet> has similar attributes to <tablePane> for specifying the data source. <radioSet> supports maxRows, queryClass, queryName, and sql. See <radioSet> Query Attributes.”
captionClass Name of the CSS style class to apply to captions for radio buttons within this <radioSet>. The default is the built-in CSS style class radioSetCaption.
choiceColumn Serves the same function as the choiceColumn attribute in dataCombo, see <dataCombo> General Attributes.”
displayList
Comma-separated list of choices to display for this <radioSet>. displayList applies only if a valueList is defined. Display values may differ from the actual logical values.
If there is an empty value ("") within the items in the displayList, as in:
Then an additional button is displayed for the empty value. The caption for this empty value is specified by the emptyCaption attribute.
The displayList attribute has its ZENLOCALIZE datatype parameter set to 1 (true). This makes it easy to localize its text into other languages, and permits use of the $$$Text macros when you assign values to this property from client-side or server-side code.
Any localized displayList string must remain a comma-separated list.
emptyCaption
The default caption to use for any buttons within this <radioSet> that have an empty value ("") assigned to them in the displayList. If you do not specify an emptyCaption, the default caption is:
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
titleList
Comma-separated list of tooltip text strings for each radio button in the <radioSet>.
The titleList attribute has its ZENLOCALIZE datatype parameter set to 1 (true). This makes it easy to localize its text into other languages, and permits use of the $$$Text macros when you assign values to this property from client-side or server-side code.
Any localized titleList string must remain a comma-separated list.
valueColumn Serves the same function as the valueColumn attribute in dataCombo, see <dataCombo> General Attributes.”
valueList
Comma-separated list of logical values for the <radioSet>. One of these logical values becomes the <radioSet> value whenever the user clicks on the corresponding button. Use the displayList to provide the corresponding list of choices to display to the user.
Zen assumes that every value within the set is distinct. If a valueList contains duplicate items, as in:
Then user selections produce unexpected behavior.
<radioSet> Query Attributes
Rather than provide a valueList and a displayList, a <radioSet> can indicate a data source for its buttons via an SQL query. <radioSet> offers a number of attributes for this purpose. When you use this technique, the columns returned by the query determine what is displayed in the <radioSet> as follows:
<radioSet> provides several attributes that support using a query to generate the result set. For details and examples, see the following sections in the chapter “Zen Tables”:
<radioButton>
The Zen <radioButton> control is a wrapper around the HTML <input type="radio"> element with some enhanced capabilities. The Zen <radioButton> control has the following attributes:
Attribute Description
Control component attributes
<radioButton> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.”
name (not id) establishes the association between radio buttons. You create a set of associated radio buttons by adding <radioButton> elements to XData Contents and assigning the same name value to each <radioButton> that in the set.
At runtime, value always contains the optionValue of the button in the set that is currently selected. As soon as the user selects one of the buttons in the set, Zen resets the value of every button in this set to the optionValue of the selected button. This makes it very easy for you to determine which button in the set is currently selected, by programmatically checking the value property of any button in the set.
caption
The caption text for this <radioButton>. Each button in the set needs a caption so that the user can distinguish between the choices.
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
The caption value can be a literal string, or it can contain a Zen #()# runtime expression.
captionClass Name of the CSS style class to apply to the captions for this <radioButton>. The default is the built-in CSS style class radioButtonCaption.
optionValue
Defines a logical value to associate with this <radioButton>. The optionValue for each radio button in the set must be unique.
The optionValue can be a literal string, or it can contain a Zen #()# runtime expression.
Lists
Zen offers the following list controls:
A list box offers a simple list of options, but a combo box has two parts:
A combo box drop-down list may appear when activated by the user, for example when the user clicks the button beside the control. There are a number of ways to reveal the drop-down list. The user can click on an image or button, or the list can simply appear when the cursor has hovered over the control for some length of time. You can specify these details when you place a list control on a Zen form, or simply use the default characteristics that Zen provides.
<select>
The Zen <select> control is a wrapper around the HTML <select> element. Zen <select> produces a list from which the user can select an item.
To define a Zen <select> list, provide a valueList for the user to choose from and a corresponding displayList for the user to see. The following table describes these and other attributes for the Zen <select> component.
Attribute Description
Control component attributes <select> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” The <select> value is a string indicating the user’s current choice from the <select> list.
Data source attributes
Rather than provide a valueList and a displayList, a Zen <select> control can indicate a data source for its list via an SQL query. Zen <select> offers a number of attributes for this purpose. When you use this technique, the columns returned by the SQL query determine what is displayed within the <select> list as follows:
  • If the %ResultSet has one column, the contents of this column are used as both the logical and display values within the drop-down.
  • If the %ResultSet has two (or more) columns, the contents of the first column supply the logical value and the contents of the second column supply the display values.
<select> supports the query attributes maxRows, queryClass, queryName, and sql. For details and examples, see the following sections in the chapter “Zen Tables”:
choiceColumn Serves the same function as the choiceColumn attribute in dataCombo, see <dataCombo> General Attributes.”
displayList
Comma-separated list of values to display for this <select> list. displayList applies only if a valueList is defined. Display values may differ from the actual logical values.
The displayList attribute has its ZENLOCALIZE datatype parameter set to 1 (true). This makes it easy to localize its text into other languages, and permits use of the $$$Text macros when you assign values to this property from client-side or server-side code.
Any localized displayList string must remain a comma-separated list.
emptyText Text that is displayed in the "empty" item added if showEmpty is true. The default is "".
showEmpty
When true, the <select> outputs an extra at the top of its drop-down box. The attribute emptyText provides content for this item. The default value of emptyText is "". Typically, this is the desired behavior, so the default value of showEmpty is true. Regardless of the value of showEmpty, this blank row does not display when the <dataCombo> has its required attribute set to true.
showEmpty has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
size Number of rows to display in the <select> list.
valueColumn Serves the same function as the valueColumn attribute in dataCombo, see <dataCombo> General Attributes.”
valueList Comma-separated list of logical values for the <select> list.
<listBox>
The Zen <listBox> control displays a list box, whose options may be individually formatted.
The Zen <listBox> control is not a wrapper around HTML <select>. The Zen <listBox> is implemented using HTML primitives. This allows the <listBox> to provide functionality not available with HTML <select>, including:
<listBox> Options
The simplest way to define a Zen list box is to provide a set of <option> elements inside a <listBox> component. The following statements produce the sample list box shown previously:
<listBox id="listBox" label="listBox" listWidth="240px"
         onchange="zenPage.notifyOnChange(zenThis);"
         value="2">
  <option value="1" text="Apple" />
  <option value="2" text="Banana" style="font-size: 1.5em; "/>
  <option value="3" text="Cherry" />
  <option value="4" text="Pumpkin" />
  <option value="5" text="Eggplant" style="font-size: 2.1em; "/>
</listBox>
The <option> element is the XML projection of the %ZEN.Auxiliary.option class and supports the attributes described in the following table.
Attribute Description
style CSS style to apply to this option.
text
Display value. This is the text that the user sees in the list box.
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
value Logical value. This is the value that Zen submits for this control when it submits the form. You must always provide both text and value for each option in the list.
When you work with %ZEN.Component.listBox programmatically, you work with <option> elements as members of the options property, a list collection. Each <option> in the <listBox> becomes a member of the options collection, associated with an ordinal position: 1, 2, 3, etc.
<listBox> General Attributes
<listBox> and <dataListBox> have the following general-purpose attributes in common.
List Box Component Attributes
Attribute Description
Control component attributes A list box has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” The list box value is a string of text that represents the currently selected logical value of the control.
listHeight CSS length value. If defined, listHeight overrides the default height of the list box window, which is 250px.
listWidth CSS length value. If defined, listWidth overrides the default width of the list box window, which is 250px.
selectedIndex 0-based index of the currently selected option in the list box. The default selectedIndex is –1 (nothing is selected).
text The display text that corresponds to the currently selected item. Do not access the text value directly; use getProperty('text') instead.
<listBox> Drag and Drop
Like all controls, <listBox> supports data drag when the <listBox> dragEnabled attribute is true. This allows the application user to drag values from the list box and drop them on other controls. If dropEnabled is also true, values from other components can be dropped onto this <listBox>, where they are appended to the end of the list. This is different from the simpler replacement that drag and drop provides for other Zen controls. This special case for <listBox> enables the user to drag options from one list to another. If both drag and drop are enabled, the user can rearrange the order of list items within the same <listBox> by using the mouse to drag list items into a new position and drop them there.
To enable drag and drop features to work, the <page> that contains the <listBox> must have its dragAndDrop attribute set to true. For details, see the Data Drag and Drop section at the beginning of this chapter.
<dataListBox>
A <dataListBox> is a specialized type of <listBox> that presents the user with a list of options obtained at runtime via an SQL query. Unlike <listBox>, <dataListBox> does not allow you to specify <option> elements or to set styles for individual options in the list. This is because <dataListBox> uses a query to obtain a dynamic list of options. There are no statically defined options in a <dataListBox>, so there are no <option> elements.
A <dataListBox> with an item selected looks like this:
<dataListBox> has the following attributes:
Attribute Description
List box attributes <dataListBox> has the same general-purpose attributes as <listBox>. For descriptions, see the section <listBox> General Attributes.”
Data source attributes
The <dataListBox> provides its list by creating, executing, and fetching from a %ResultSet object on the server. You can specify how to create this %ResultSet object using the attributes that the <dataListBox> inherits from its parent class %ZEN.Component.querySource.
The columns returned by the SQL query determine what is displayed within the <dataListBox> list, as follows:
  • If the %ResultSet has one column, the contents of this column are used as both the logical and display values within the drop-down.
  • If the %ResultSet has two (or more) columns, the contents of the first column supply the logical value and the contents of the second column supply the display values.
For details and examples of using QuerySource attributes with <dataListBox>, see the following sections in the chapter “Zen Tables”:
sqlLookup <dataListBox> has an sqlLookup attribute that works in a manner similar to <dataCombo>. The primary difference in behavior is that if the value found by sqlLookup is not already visible in the list, <dataListBox> does not bring it into view. For additional information, see the section <dataCombo> Logical and Display Values.”
OnDrawItem
Name of a server-side callback method in the Zen page class. Find further information following this table.
itemCount (Read-only) Number of options within the list. This is calculated when the query for this component is run. It has no value until the list is displayed.
The OnDrawItem method returns the HTML to display within the cell for the given item. This is the place to escape special characters or make other last-minute adjustments to the HTML before displaying it.
Zen invokes this method when it first draws the list box, automatically passing it the following parameters:
The callback must return a %String that contains the resulting HTML. The following example shows a valid method signature:
Method DrawItem(pRS As %ResultSet,
                pValue As %String,
                pText As %String) As %String
{
 Set tx=pText
 Set tx=$REPLACE(tx,"&amp;eacute;",$ZCVT($CHAR(233),"O","HTML"))
 Set tx=$REPLACE(tx,"&amp;ntilde;",$ZCVT($CHAR(241),"O","HTML"))
 Quit tx
}
To use the above method as the callback, the developer would set OnDrawItem="DrawItem" for the <dataListBox>.
<combobox>
The Zen <combobox> provides a text field with a drop-down list below it:
Unlike some other controls described in this chapter, the Zen <combobox> control is not a wrapper around HTML <select>. The Zen <combobox> is implemented using HTML primitives. This allows the <combobox> to provide functionality not available with HTML <select>, including:
<combobox> Logical and Display Values
To define a <combobox>, provide a valueList for the user to choose from and a corresponding displayList for the user to see. The following table describes these <combobox> attributes.
Attribute Description
displayList
A comma-separated list of values to display for the list in this combo box. displayList applies only if a valueList is defined. Display values may differ from the actual logical values.
The displayList attribute has its ZENLOCALIZE datatype parameter set to 1 (true). This makes it easy to localize its text into other languages, and permits use of the $$$Text macros when you assign values to this property from client-side or server-side code.
Any localized displayList string must remain a comma-separated list.
valueList valueList overrides any <option> elements provided within the <combobox> (see the discussion following this table). The valueList is a comma-separated list of logical values for the drop-down list in this <combobox>. If you provide a valueList, you must also provide a displayList.
<combobox> Options
Rather than provide a valueList and a displayList, you can define a <combobox> by providing a set of <option> elements inside a <combobox> component. <option> is more flexible than a valueList and displayList because it allows you to apply a CSS style to each of the list entries individually. For example:
<combobox id="comboboxEdit" label="combobox Editable" editable="true">
  <option value="1" text="Apple" />
  <option value="2" text="Banana" style="font-size: 2.5em; "/>
</combobox>
The <listBox> control also uses <option> to add entries. See the section <listBox Options for more information.
<combobox> General Attributes
<combobox> and <dataCombo> have the following attributes in common.
Combo Box Component Attributes
Attribute Description
Control component attributes A combo box has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” The combo box value is a string of text that represents the currently selected logical value of the control.
buttonCaption
Caption used for the button when the comboType is "button".
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
buttonImage URI of the image to display for the combo button in its normal state.
buttonImageDown URI of image to display for the combo button in its down (pressed) state.
buttonTitle
Popup title used for the drop-down button when comboType is "button" or "image".
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
comboType
How the drop-down box is activated for the combobox:
  • "image" indicates that a user-clickable image should be displayed next to the combo box text box. This is the default.
  • "button" indicates that a button should be displayed next to the combo box text box.
  • "timer" indicates that the drop-down should appear shortly after the user enters a value within the combo box text box.
delay When comboType is "timer", delay specifies how many milliseconds to wait after user finishes typing before showing the drop-down. The default is 250 milliseconds.
dropdownHeight CSS length value. If defined, dropdownHeight overrides the default height of the drop-down window, which is 250px.
dropdownWidth CSS length value. If defined, dropdownWidth overrides the default width of the drop-down window, which is 250px.
editable
If true, a user can directly edit the value within the input box as if it were a text field. The default is false.
editable has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
maxlength Maximum number of characters that the user may enter within this control.
scrollIntoView
If true, Zen uses the JavaScript scrollIntoView function to try and make visible the currently selected item within the drop-down.
selectedIndex 0-based index of the currently selected option in the drop-down list. The default selectedIndex is –1 (nothing is selected).
size HTML width of the text input area for this control. The default size is 20.
unrestricted
If true, and if editable is also true, values entered by the user may be used as the value of the control. If false, the value is restricted to one of the choices within the drop-down list. The default is false.
unrestricted has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
%ZEN.Component.combobox is a subclass of the %ZEN.Component.text control. This means you can use the various methods defined by the text control to manipulate the text box portion of a <combobox> or <dataCombo>.
<dataCombo>
A <dataCombo> is a specialized type of <combobox> that presents the user with a list of options obtained at runtime via an SQL query. Unlike <combobox>, <dataCombo> does not allow you to specify <option> elements or to set styles for individual options in the list. This is because <dataCombo> uses a query to obtain a dynamic list of options. There are no statically defined options in a <dataCombo>, so there are no <option> elements.
A <dataCombo> with text entered for a search looks like this:
<dataCombo> Query Attributes
The <dataCombo> provides its drop-down list by creating, executing, and fetching from a %ResultSet object on the server. Initially, the contents of the drop-down are empty, until a user action causes the drop-down to appear. At this point a call to the server fetches the drop-down contents. You can change this behavior by setting the cached attribute of the <dataCombo>.
You can specify how the <dataCombo> creates its %ResultSet object using the attributes that the <dataCombo> inherits from its parent class %ZEN.Component.querySource. The columns returned by the SQL query determine what is displayed within the <dataCombo> list, as follows:
For details and examples, see the following sections in the chapter “Zen Tables”:
<dataCombo> Query Parameters
The query used to provide the contents of the <dataCombo> drop-down list may contain one or more runtime ? parameters, such as:
WHERE Name %STARTSWITH ?
Values for query parameters can be provided in one of the following ways:
<dataCombo> Logical and Display Values
Any list box or combo box has two current values:
These two values are usually different, but they can be the same.
The Zen controls <select>, <listBox>, and <combobox> provide a fixed list of logical and display values. When an application sets the value of one of these controls, it is simple for the control to identify which display value is associated with the new logical value.
<dataListBox> and <dataCombo> acquire their values dynamically, so additional steps are needed to match logical and display values. When an application sets the local value of a <dataCombo> control, internally the <dataCombo> tries to find the display value that best matches this logical value. This works differently on the server and client:
For example, suppose you want to define a <dataCombo> to show a set of Customer names; the display value is Name while the logical value is the ID of the Customer. To do this you define a <dataCombo> with two SQL statements, as follows:
<dataCombo id="MyCombo"
 sql="SELECT ID,Name FROM MyApp.Customer WHERE Name %STARTSWITH ? ORDER BY Name"
 sqlLookup="SELECT Name FROM MyApp.Customer WHERE ID = ?"
 editable="true"
 searchKeyLen="10"
 />
This sample <dataCombo> definition has the following effects:
  1. The SQL query provided by the sql attribute is invoked whenever the Zen page displays the drop-down list. It provides a set of logical and display values for the <dataCombo>. The <dataCombo> stores the results of the last sql query in a local cache.
  2. The SQL query provided by the sqlLookup attribute is invoked to find a specific display value for a specific logical value. The sqlLookup ? parameter gets its value from the current logical value of the <dataCombo> control.
  3. The sqlLookup query is also executed when the application tries to set the logical value of this <dataCombo> at runtime and the logical and display values are not already stored in the cache.
  4. The searchKeyLen value in the example indicates that Zen passes up to the first 10 characters from the combo input box to the SQL query that provides the contents of the drop-down list.
The sql and sqlLookup queries can use query parameters as described in the section <dataCombo> Query Parameters.”
The sqlLookup attribute has the underlying data type %ZEN.Datatype.sql. This means it cannot be accessed from the client. Its value is encrypted (using the current session key) when it is sent to the client. If this value is returned to the server, it is automatically decrypted. This makes it possible to place sensitive data on the client for future processing on the server, without letting a user view this data.
If you use the sqlLookup attribute to retrieve a list of user choices from a table, and you also set the attribute unrestricted to true so that the user can enter values that do not exist in the underlying table, the lookup that you specify in sqlLookup does not occur. unrestricted has the effect of disabling sqlLookup.
The sqlLookup attribute value must escape any XML special characters. For example, in place of the less-than symbol < you must substitute the XML entity &lt; as follows:
sqlLookup=
"select * from infonet_daten.abopos where lieferadresse=? and status&lt;9"
The following table lists XML special characters that cause problems when they appear in sqlLookup strings, and the XML entities to substitute for them.
XML Entities for Use in sqlLookup Attribute Values
Character XML Entity Description
> &gt; Right angle bracket or “greater than” symbol.
< &lt; Left angle bracket or “less than” symbol.
& &amp; Ampersand.
' &apos; Single quotation mark or apostrophe. A string enclosed in single quotes needs the &apos; entity to represent the ' character.
" &quot; Double quotation mark. A string enclosed in double quotes needs the &quot; entity to represent the " character.
<dataCombo> General Attributes
In addition to the attributes described in previous sections, <dataCombo> supports the following general-purpose attributes.
Attribute Description
Combo box attributes <dataCombo> has the same general-purpose attributes as <combobox>. For descriptions, see the section <combobox> General Attributes.” There can be no statically defined options for a <dataCombo>, so it does not support the displayList or valueList attributes.
auxColumn If there are multiple data columns displayed in the drop-down list, auxColumn is the 1-based column number of the column that provides an additional auxiliary value for this control. auxColumn provides a way to supply an additional value that is not the display or logical value. If the auxColumn value is not a valid column number, no auxiliary data is provided. The default auxColumn value is 0.
cached
If cached is true, when the page is first displayed, it executes a query to fetch the initial contents of the drop-down list, and sets the itemCount property to the number of items within the drop-down. The client uses these cached results instead of going back to the server to fetch the contents of the drop-down list. You can clear the drop-down cache at any time by modifying the search parameters for the query, or by invoking the clearCache method.
The default value for cached is false. In this case the user must take action to request the drop-down list before the query fetches its contents.
The cached attribute has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
choiceColumn If there are multiple data columns displayed within the drop-down list, choiceColumn is the 1-based column number of the column that provides the display value for this control. The default choiceColumn value is 2. If the supplied choiceColumn value is greater than the number of columns in the query, the second column is used.
clearOnLoad
If true, and this <dataCombo> is bound to a data controller, then the contents of the drop-down list are cleared whenever a new instance is loaded into the controller. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
columnHeaders
If defined, columnHeaders is a comma-separated list of column headers to display in the drop-down list.
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
Any localized columnHeaders string must remain a comma-separated list.
contentType
Indicates how display values should be rendered. Possible values are:
  • "text" — The display values are HTML-escaped before being rendered. This is the default.
  • "html" — The display values are not HTML-escaped before being rendered.
displayColumns If there are multiple data columns in the %ResultSet for the <dataCombo>, displayColumns can provide a comma-separated list of 1–based column numbers. This list identifies which columns out of the %ResultSet should be displayed.
emptyText Text that is displayed in the "empty" item added if showEmpty is true. The default is "".
itemCount
(Read-only) Number of items in the drop-down list. This value is set as a side effect of populating the drop-down list. It has no value until the list is displayed.
If cached is true, when the page is first displayed, it executes a query to fetch the initial contents of the drop-down list, and sets the itemCount property to the number of items within the drop-down immediately after the page’s %OnAfterCreatePage callback method is invoked.. The client uses these cached results instead of going back to the server to fetch the contents of the drop-down list.
You can clear the drop-down cache at any time by modifying the search parameters for the query, or by invoking the clearCache method.
The default value for cached is false. In this case the user must take action to request the drop-down list before the query fetches its contents.
loadingMessage
This message is temporarily displayed while a server-side query is running to populate the <dataCombo> list. The default is:
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
multiColumn
If true, and if the result set contains more than 2 columns, display multiple columns in the drop-down box. The default is true.
This attribute has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
onshowDropdown
The onshowDropdown event handler for the <dataCombo>. Zen invokes this handler just before the drop-down list is displayed. See Zen Component Event Handlers.” If the expression returns a value, this value is used as the filter value for the drop-down query instead of the value typed into the input box.
searchKeyLen
If non-zero, searchKeyLen is the maximum number of search characters for Zen to take from the combo input box and pass as the first parameter to the SQL query that provides the contents of the drop-down list.
If zero, the contents of the input box are not used as a query parameter. The default is 0.
If searchKeyLen is non-zero, and editable is true, then the first searchKeyLen characters in the current contents of the input box are used as the value for the first query parameter (that is, parms(1)). The first member of the parameters list becomes the value of parms(2), the second member of the parameter list becomes the value of parms(3), and so on.
If any parameter value is equal to "?" the current search key value (the value used for the first parameter) is used for this query parameter as well.
showEmpty
When true, the <dataCombo> outputs an extra at the top of its drop-down box. The attribute emptyText provides content for this item. The default value of emptyText is "". Typically, this is the desired behavior, so the default value of showEmpty is true. Regardless of the value of showEmpty, this blank row does not display when the <dataCombo> has its required attribute set to true.
showEmpty has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
valueColumn If there are multiple data columns in the %ResultSet for the <dataCombo>, valueColumn identifies the 1-based column number of the column that provides the logical value for this control. The default valueColumn is 1. If the supplied valueColumn value is greater than the number of columns in the query, the first column is used.
<dataCombo> Display Sequence
If you are interested in details of how Zen displays the <dataCombo>, 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.
<dataCombo> Display Sequence
  User Viewpoint In the Browser On the Server
1 Select the drop-down    
2   Drop-down is activated  
3   Send hyperevent to the server to execute SQL  
4     Receive hyperevent to execute SQL
5     Send hyperevent response (consisting of JavaScript code) to populate the drop-down unit
6   Server fills the drop-down list  
7 List fills with items    
8 User selects an item    
9   Drop-down item is selected  
10   Call client-side select event handler  
11   Send hyperevent to the server to start a ZenMethod  
12     Receive hyperevent to start ZenMethod
13     Update server-side DOM
14     Send hyperevent response (consisting of JavaScript code) to synchronize client DOM with server DOM
15   Update client-side DOM to reflect changes made on the server during the ZenMethod  
16   Update visual presentation of DOM-bound components to match new client-side DOM  
17 Form fields get filled in based on the selection    
<lookup>
A <lookup> control is a specialized type of control that provides a way to select a value from a list of options. This is an HTML5 component. It works correctly only on HTML5 compliant browsers. This control supports the following attributes:
Attribute Description
context A context string used to determine the selection list for this component. The context string should take the form: ?parm1=value.
displayBinding If this control is used in a form that is associated with a <dataController>, this attribute specifies the name of the property in the <dataController> that provides the display value for this control.
idProperty The name of the property in data element that supplies the value of the control after the user has made a selection.
imageProperty The name of the property in the data element that supplies a path to an image file. If this attribute is defined, and the specified property exists, the control shows the image in the popup instead of the text value. The image path is resolved relative to CSP/broker in the Caché installation directory. When the user makes a selection, the data element specified by textProperty supplies the value.
lookupIcon The path to an image file that supplies the image used to invoke the lookup popup. The image path is resolved relative to CSP/broker in the Caché installation directory.
noResultsMessage
A message to show in the lookup popup when no selections are available. The default value is “Nothing to show!”
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
ongetdata The ongetdata event handler, which returns a JavaScript array of data to display in the lookup popup. This event handler can return any array of object or literal values.
onshowPopup The onshowPopup event handler, which is fired just before the popup is displayed.
popupLabel
The title to display in the popup.
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
propertyList A comma-separated list of property names used to create the display text in the popup list.
showFilter Specify if there should be a filter text box in the pop up.
size Size of the base (non popup) portion of this control. The number provided is multiplied by 10 to get the width.
styleList A comma-separated list of CSS styles to apply to all the cells in the popup list.
text Display value for this control. The value attribute contains the logical value.
textProperty The name of the property in the data element that supplies the text value.
The following image shows the <lookup> control and identifies its main components.
This image shows the selection popup and identifies its main components. This example uses the styleList property to apply blue color to the selections. The property showFilter controls the presence of the text filter box. If the ongetdata event handler does not return any selections, the text provided by noResultsMessage replaces the list of selections .
The following code examples generate the <lookup> control illustrated in the previous images.
<page xmlns="http://www.intersystems.com/zen" title="">
 <lookup 
  popupLabel="City Selector"
  label="Choose a City:"
  lookupIcon="MyApp/eye_16.png"
  ongetdata="return zenPage.myData();"
  styleList="color:blue,"
  idProperty="id"
  textProperty="text"
  value="Seattle"
 />
</page>
ClientMethod myData() [ Language = javascript ]
{
 var data = [
  {id:1, text:'Boston',},
  {id:2, text:'New York'},
  {id:3, text:'Atlanta'},
  {id:4, text:'Chicago'},
  {id:5, text:'Tucson'},
  {id:6, text:'Seattle'},
  {id:7, text:'San Francisco'},
  {id:8, text:'Los Angeles'},
  {id:9, text:'San Diego'}
 ];
 return data;
}
The attribute imageProperty lets you use images in the selection popup. For example, the following <lookup> control and ongetdata callback:
<page xmlns="http://www.intersystems.com/zen" title="">
 <lookup 
  label="Choose a Direction:"
  ongetdata="return zenPage.myData();"
  imageProperty="image"
  textProperty="text"
  />
</page>
ClientMethod myData() [ Language = javascript ]
{
 var data = [
  {id:1, text:'Down', image:'images/arrowBD.png'},
  {id:2, text:'Left', image:'images/arrowBL.png'},
  {id:3, text:'Right', image:'images/arrowBR.png'},
  {id:4, text:'Up', image:'images/arrowBU.png'} ];
 return data;
}
Result in a popup that uses images, as shown in the following illustration:
You can use the attribute propertyList to construct the display text in the popup from more than one data element. This attribute supplies a comma-separated list of property names. The <lookup> control uses values associated with those names to populate the lookup list.
<page xmlns="http://www.intersystems.com/zen" title="">
 <lookup 
  ongetdata="return zenPage.myData();"
  idProperty="lname"
  propertyList="fname,lname,dob"
  />
</page>
Results in a popup where each line contains the values from the fields fname, lname, and dob in the data. Only the field specified by idProperty becomes the value of the control after the user has made a selection.
You can also use CSS to control the appearance of items in the popup. The CSS class for lookup items is lookupItem. For example, the following CSS sets the background of each item in the popup to yellow.
.lookupItem {
  background-color:yellow;
}
Dates
Zen offers the following date selection controls:
The components described in this topic are simple date selection controls that enable users to enter dates as values in forms. Zen offers another component, called <schedulePane>, which is not a date selection control. <schedulePane> displays a daily, weekly, or monthly calendar with time slots for each date. Users can define appointments and place them in the appropriate time slots. For details, see the Schedule Calendar section in the chapter “Other Zen Components.”
<calendar>
The <calendar> component displays a navigable calendar, one month at a time. The user can view and select dates from this calendar. A <calendar> initially displays with the current date highlighted in bold (7 in the example below) and the currently selected date in bold with a yellow background color (14 in the example below). A Zen <calendar> looks like this:
<calendar> has the following attributes:
Attribute Description
Control component attributes <calendar> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” On the client, the <calendar> value is a string in the format YYYY-MM-DD. On the server, the <calendar> value has the %Timestamp datatype.
dayList
Comma-separated list of day abbreviations to show at the top of the calendar. If you do not provide a dayList value, the default is:
The dayList attribute has its ZENLOCALIZE datatype parameter set to 1 (true). This makes it easy to localize its text into other languages, and permits use of the $$$Text macros when you assign values to this property from client-side or server-side code.
Any localized dayList string must remain a comma-separated list.
defaultTime 
Provides a default value for the time portion of the <calendar> value. The defaultTime is used as the initial time displayed in the popup calendar if the following conditions are met:
  • The property showTime is true.
  • The value supplied does not include a time portion.
  • defaultTime is a valid time string.
The calendar itself defaults to a time value of "01:00:00" when a time is not specified or when the date value passed is invalid.
endYear Four-digit end year number for the year selector in the calendar. If not defined, the default is the year portion of maxDate, if defined. Otherwise, the default endYear is 30 years from now.
firstDayOfWeek Number (Sunday=0, Saturday=6) that specifies which day of the week is displayed as the starting day of the week. The default is 0 (Sunday).
fixedMonth
If true, this calendar displays a single month and provides no way for the user to change month and year. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
gapWidth HTML length value giving the size of the gap between the month and year indicators at the top of the calendar. Setting this provides a way to adjust the width of the calendar. The above example uses the default of 40px.
maxDate
String in the format YYYY-MM-DD (datatype %Timestamp on the server). If specified, this is the latest date the <calendar> accepts as its value. The maxDate value does not affect which years are displayed by the calendar unless endYear is omitted.
The value supplied for maxDate can be a literal string, or it can contain a Zen #()# runtime expression.
minDate
String in the format YYYY-MM-DD (datatype %Timestamp on the server). If specified, this is the earliest date the <calendar> accepts as its value. The minDate value does not affect which years are displayed by the calendar unless startYear is omitted.
The value supplied for minDate can be a literal string, or it can contain a Zen #()# runtime expression.
month Number (January=1, December=12) that specifies which month of the year is currently displayed by the calendar. This is not the same as the current <calendar> value, which includes a day and year, which can include time, and whose month may be different.
monthList
Comma-separated list of month names to display in the list of months that the user can choose from the calendar. If you do not provide a monthList value, the default is:
monthList has its ZENLOCALIZE datatype parameter set to 1 (true). This makes it easy to localize its text into other languages, and permits use of the $$$Text macros when you assign values to this property from client-side or server-side code.
Any localized monthList string must remain a comma-separated list.
showTime
If true, this component displays a text entry field below the main calendar. In the example above, showTime is true. The default is false.
The user can enter a time of day in the showTime field using the 24–hour time format HH:MM:SS. When the form is submitted, the <calendar> value accepts both date and time values in the following ODBC/JDBC timestamp format: YYYY-MM-DD HH:MM:SS
showTime has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
startYear Four-digit start year number for the year selector in the calendar. If not defined, the default is the year portion of minDate, if defined. Otherwise, the default startYear is 10 years ago.
timeCaption
Caption text for the showTime field. If you do not provide a timeCaption value, the default is:
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
year Four-digit number that specifies which year is currently displayed by the calendar. This is not the same as the current <calendar> value, which includes a day and month, which can include time, and whose year may be different.
<dateSelect>
The <dateSelect> control displays three drop-down lists. From left to right, the lists allow the user to select a month, a day of the month, and a year. If the user types a character in any of these fields, Zen displays the closest matching value for that list, if one exists, such as “March” or “May” for M. <dateSelect> is useful for cases like birth dates or expiration dates when a popup calendar like <dateText> can be cumbersome.
A Zen <dateSelect> component looks like this. In the example, the user is selecting from the month drop-down list.
<dateSelect> has the following attributes:
Attribute Description
Control component attributes
<dateSelect> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.”
On the client, the <dateSelect> value is a string in the format YYYY-MM-DD. On the server, the <dateText> value has the %Timestamp datatype.
Any HTML events defined for <dateSelect> (onfocus, onclick, etc.) apply to each of the three drop-down lists independently.
format
String that specifies the order in which to display the drop-down lists, from left to right. The default is "MDY". Possible values are:
The value supplied for format can be a literal string, or it can contain a Zen #()# runtime expression.
maxYear
Integer specifying the last year allowed in the year drop-down list. The default is the current year plus 20.
The value supplied for maxYear can be a literal string, or it can contain a Zen #()# runtime expression.
minYear
Integer specifying the earliest year allowed in the year drop-down list. The default is 1900.
The value supplied for minYear can be a literal string, or it can contain a Zen #()# runtime expression.
monthList
Comma-separated list of month names to display in the list of months that the user can choose from the calendar. If you do not provide a monthList value, the default is:
monthList has its ZENLOCALIZE datatype parameter set to 1 (true). This makes it easy to localize its text into other languages, and permits use of the $$$Text macros when you assign values to this property from client-side or server-side code.
Any localized monthList string must remain a comma-separated list.
shortMonth
If true, this component shows the first 3 characters of the month names in the month drop-down list. In the example above, shortMonth is false. The default is false.
shortMonth has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
shortMonth has its ZENLOCALIZE datatype parameter set to 1 (true). This makes it easy to localize the 3–character version of the month name into other languages.
showMonthNumber
If true, this component shows the ordinal month number along with month names in the month drop-down list. In the example above, showMonthNumber is false. The default is false.
showMonthNumber has its ZENLOCALIZE datatype parameter set to 1 (true). This makes it easy to localize the longer text for the month selection into other languages.
<dateText>
The <dateText> control is essentially a combo box. It displays a text box as well as a button that, when pressed, displays a popup calendar. When the user enters a value into the text area of this control, Zen either converts this value into the closest matching date value, or it displays an invalid date message. As a comparison, see the <dateSelect> component.
A Zen <dateText> component looks like this:
<dateText> has the following attributes:
Attribute Description
Control component attributes <dateText> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.” On the client, the <dateText> value is a string in the format YYYY-MM-DD. On the server, the <dateText> value has the %Timestamp datatype. However, you can change what the user sees in the <dateText> display; see the format and separator attributes.
dayList
Comma-separated list of day abbreviations to show at the top of the calendar. If you do not provide a dayList value, the default is:
The dayList attribute has its ZENLOCALIZE datatype parameter set to 1 (true). This makes it easy to localize its text into other languages, and permits use of the $$$Text macros when you assign values to this property from client-side or server-side code.
Any localized dayList string must remain a comma-separated list.
defaultTime 
Provides a default value for the time portion of the <dateText> control value. The defaultTime is used as the initial time displayed in the popup calendar if the following conditions are met:
The calendar itself defaults to a time value of "01:00:00" when a time is not specified or when the date value passed is invalid.
firstDayOfWeek Number (Sunday=0, Saturday=6) that specifies which day of the week is displayed as the starting day of the week. The default is 0 (Sunday).
format
String that specifies the display format for this component. The internal value of this control is always YYYY-MM-DD, but you can change what the user sees. The default is "YMD". Possible values are:
  • "YDM" — Year, Day, Month
  • "MDY" — Month, Day, Year
  • "DMY" — Day, Month, Year
The value supplied for format can be a literal string, or it can contain a Zen #()# runtime expression.
invalidDateMessage
Message displayed by control when the date entered by the user fails validation. The default is:
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
maxDate
String in the format YYYY-MM-DD (datatype %Timestamp on the server). If specified, this is the latest date the <dateText> accepts as its value. The maxDate value does not affect which years are displayed by the calendar unless endYear is omitted.
The value supplied for maxDate can be a literal string, or it can contain a Zen #()# runtime expression.
minDate
String in the format YYYY-MM-DD (datatype %Timestamp on the server). If specified, this is the earliest date the <dateText> accepts as its value. The minDate value does not affect which years are displayed by the calendar unless startYear is omitted.
The value supplied for minDate can be a literal string, or it can contain a Zen #()# runtime expression.
monthList
Comma-separated list of month names to display in the list of months that the user can choose from the calendar. If you do not provide a monthList value, the default is:
monthList has its ZENLOCALIZE datatype parameter set to 1 (true). This makes it easy to localize its text into other languages, and permits use of the $$$Text macros when you assign values to this property from client-side or server-side code.
Any localized monthList string must remain a comma-separated list.
separator
Separator character to use between date segments. The default is the hyphen character (-). if the user enters the forward slash (/) instead of a hyphen, the <dateText> component accepts it, but the hyphen is the expected format.
As an alternative to the default hyphen, you can use the separator attribute to specify some other character as the date separator.
If time is also displayed, the time portion of the date is always separated from the data portion using the colon (:).
showTime
If true, this component displays a text entry field below the main calendar. In the example above, showTime is true. The default is false.
The user can enter a time of day in the showTime field using the 24–hour time format HH:MM:SS. When the form is submitted, the <calendar> value accepts both date and time values in the following ODBC/JDBC timestamp format: YYYY-MM-DD HH:MM:SS
showTime has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
size HTML width of the text input area for this control. The default is 15.
timeCaption
Caption text for the showTime field. If you do not provide a timeCaption value, the default is:
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
value
You can access the value property of a dateText control programmatically. When you do this, it bypasses the date matching function that Zen provides when the user sets the date by typing text in the input field.
Grid
<dynaGrid>
The <dynaGrid> control displays a two-dimensional, editable grid, similar to a spreadsheet. When the user clicks in a cell, an edit control appears in the cell and the user can edit the cell contents. The user presses Enter to save changes. A <dynaGrid> with a newly edited cell looks like this:
You can create a <dynaGrid> in one of the following ways:
<dynaGrid> Data Set
The data displayed within the <dynaGrid> is supplied by a %ZEN.Auxiliary.dataSet object. dataSet is a special data container object that is used to define one-, two-, or three-dimensional data in a form that can be easily transported between the server and client.
When a <dynaGrid> object is first created, it automatically creates a two–dimensional dataSet object with the number of rows (dimension 1) and columns (dimension 2) specified by the number of <gridRow> and <gridColumn> entries within the <dynaGrid> definition in XData Contents. The following example specifies four rows and four columns for the initial dataSet object:
<dynaGrid id="myGrid" OnCreateDataSet="CreateDS">
    <gridColumn width="100"/>
    <gridColumn width="100"/>
    <gridColumn width="100"/>
    <gridColumn width="100"/>
    <gridRow />
    <gridRow />
    <gridRow />
    <gridRow readOnly="true" />
</dynaGrid>
An application can change the size and contents of the initial dataSet object by defining a server-side callback method. You can specify the name of this callback method using the <dynaGrid> OnCreateDataSet attribute, as in the example above. The OnCreateDataSet value must be the name of a server-side callback method defined within the page class that contains the <dynaGrid> control. In the above example, this method name is CreateDS. The OnCreateDataSet callback method is called once, when the <dynaGrid> object is first created on the server and before the <dynaGrid> is first displayed.
The signature of the OnCreateDataSet callback method must look like this:
Method CreateDS(
  pGrid As %ZEN.Component.dynaGrid,
  pDataSet As %ZEN.Auxiliary.dataSet) As %Status
{ }
Where:
Typically a OnCreateDataSet callback method looks like this:
Method CreateDS(
  pGrid As %ZEN.Component.dynaGrid,
  pDataSet As %ZEN.Auxiliary.dataSet) As %Status
{
  // make sure dataSet is cleared out
  Do pDataSet.%Clear()

  // fill in contents of dataSet
  // This is a 2-D data structure

  // row labels (dimension 1)
  Do pDataSet.%SetLabel("Boston",1,1)
  Do pDataSet.%SetLabel("New York",2,1)
  Do pDataSet.%SetLabel("Chicago",3,1)
  Do pDataSet.%SetLabel("Miami",4,1)

  // column labels  (dimension 2)
  Do pDataSet.%SetLabel("Cars",1,2)
  Do pDataSet.%SetLabel("Trucks",2,2)
  Do pDataSet.%SetLabel("Trains",3,2)
  Do pDataSet.%SetLabel("Planes",4,2)

  // get size of dataSet
  Set rows = pDataSet.%GetDimSize(1)
  Set cols = pDataSet.%GetDimSize(2)

  // fill in initial data values
  For r=1:1:rows {
    For c=1:1:cols {
      Set value = 0
      Do pDataSet.%SetValue(value,r,c)
    }
  }

  Quit $$$OK
}
The above example defines a two–dimensional dataSet object with four rows and four columns. It supplies labels for the rows and columns and then loops over the cells to provide initial values for the cells.
If the OnCreateDataSet callback changes the dataSet object to contain three dimensions, this gives the <dynaGrid> the ability to move among “pages” of data. Each page is displayed as a two-dimensional grid that represents the currently visible page. The following figure illustrates this data model. For details regarding the label attributes shown in the figure, see the <gridRow>,” <gridColumn>,” and <dynaGrid> Attributes sections in this chapter.
Data Model for the Dynamic Grid Control
If there are pages in the <dynaGrid>, the gridLabel cell provides navigation information as follows. Click on the << symbol for the previous page or the >> symbol for the next page. The number indicates which page you are currently viewing:
<dynaGrid> Methods
Since the dataSet object is designed to work on either the server or the client, it provides local APIs for both environments. The following table lists the server-side (ObjectScript) methods. For further details, and to see the list of client-side (JavaScript) methods, see the class documentation for %ZEN.Auxiliary.dataSet.
Note:
When you work with %ZEN.Component.dynaGrid programmatically, on the server side you can access the dataSet object via the dataSet property of the dynaGrid object. On the client, you cannot access the dataSet directly; you must the dynaGrid object’s getDataSet method to get the dataSet object.
Server Method Description
%Clear Clear the contents of the dataSet (set every cell to "") without changing its size or number of dimensions.
%GetArray Gets the contents of the dataSet as a multidimensional array, subscripted by the 1–based dimensional addresses of the cells (row, column, page). This array is passed to %GetArray by reference.
%GetDimensions Returns the number of dimensions within the dataSet.
%GetDimSize Receives a 1–based number identifying a dimension (row, column, page) and returns the number of cells in that dimension.
%GetLabel
Receives two numbers:
  • 1–based number identifying a cell position within a dimension
  • 1–based number identifying the dimension (row, column, page)
%GetLabel returns the value of the label at the specified position.
%GetValue Receives up to three 1–based numbers identifying a specific cell in the grid (row, column, page). Gets the value of the cell at that position.
%SetArray
Receives up to four arguments:
  • A multidimensional array, passed by reference, and subscripted by the 1–based dimensional addresses of the cells (row, column, page). The local array must have the same dimensionality as the dataSet and must have the correct number and type of subscripts.
  • Up to three 1–based numbers identifying the number of cells in each dimension of the grid (row, column, page).
%SetArray copies the contents of the array into the dataSet.
%SetDimensions Sets the number of dimensions within the dataSet to 1, 2, or 3.
%SetLabel
Receives three arguments:
  • String that specifies a label.
  • 1–based number identifying a cell position within a dimension
  • 1–based number identifying the dimension (row, column, page)
%SetLabel copies the string to the label at the specified position.
%SetValue
Receives up to four arguments:
  • String that specifies a value.
  • Up to three 1–based numbers identifying a specific cell in the grid (row, column, page).
%SetValue sets the value of the cell at the indicated position. %SetValue also updates the dimension size, if needed.
<gridRow>
A <dynaGrid> with dimensions greater than zero must contain one or more <gridRow> and <gridColumn> elements to define the initial dimensions of the grid. <gridRow> defines dimension 1 of a one-, two-, or three-dimensional <dynaGrid>.
The <gridRow> element is the XML projection of the %ZEN.Auxiliary.gridRow class. <gridRow> supports the attributes described in the following table.
Attribute Description
height
HTML height value to apply to this row, such as 0.3in or 3%.
hidden
If true, this row is not displayed. The default is false.
hidden has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
label
Default text label for the row.
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
readOnly
If true, cells in this row are read-only; the user cannot edit them. The default is false.
readOnly has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.
rowName Logical name of the row.
style
CSS style to apply to cells in this row, for example:
If there is a column style and a row style active for a given cell, the row style is applied before the column style. This means the column style might override the row style.
title
Help text displayed when mouse hovers over this row. If there is a row title and a column title active for a given cell, the column title overrides the row title.
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
When you work with %ZEN.Component.dynaGrid programmatically, you work with <gridRow> elements as members of the dynaGrid property called rows. This is a list collection of %ZEN.Auxiliary.gridRow objects. Each <gridRow> provided in the original <dynaGrid> definition in XData Contents becomes a member of the rows collection, associated with its ordinal position in the <dynaGrid>: 1, 2, 3, etc.
<gridColumn>
A <dynaGrid> with dimensions greater than zero must contain one or more <gridRow> and <gridColumn> elements to define the initial dimensions of the grid. <gridColumn> defines dimension 2 of a two- or three-dimensional <dynaGrid>.
The <gridColumn> element is the XML projection of the %ZEN.Auxiliary.gridColumn class. <gridColumn> supports the attributes described in the following table.
Attribute Description
columnName Logical name of the column.
hidden
If true, this column is not displayed. The default is false.
hidden has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
label
Default text label for the column.
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
readOnly
If true, cells in this column are read-only; the user cannot edit them. The default is false.
readOnly has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
style
CSS style to apply to cells in this column, for example:
If there is a row style and a column style active for a given cell, the row style is applied before the column style. This means the column style might override the row style.
title
Help text displayed when mouse hovers over this column. If there is a row title and a column title active for a given cell, the column title overrides the row title.
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
width
HTML width value to apply to this column, such as 0.3in or 3%.
When you work with %ZEN.Component.dynaGrid programmatically, you work with <gridColumn> elements as members of the dynaGrid property called columns. This is a list collection of %ZEN.Auxiliary.gridColumn objects. Each <gridColumn> provided in the original <dynaGrid> definition in XData Contents becomes a member of the columns collection, associated with its ordinal position in the <dynaGrid>: 1, 2, 3, etc.
<dynaGrid> Attributes
When you place a <dynaGrid> element within an XData Contents block, you can assign it the following attributes. When working with the <dynaGrid> programmatically, these attributes are available as properties of the dynaGrid object.
Attribute Description
Control component attributes
<dynaGrid> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.”
Unlike most other controls, <dynaGrid> does not have a single value. Also, the <dynaGrid> width plays a special role in laying out the grid. For details, see the <dynaGrid> Layout section following this table.
columnWidth
Default width for columns that do not supply a width. You must specify columnWidth in pixels, for example 75px. The default is 100px.
If no columnWidth is set and a <gridColumn> does not supply a width, the width of the column is calculated by dividing the remaining width of the grid amongst the columns with unspecified widths.
For further details, see the <dynaGrid> Layout section following this table.
controllerId If this <dynaGrid> is associated with a data controller, the controllerId attribute identifies the controller that provides the data for this <dynaGrid>. The controllerId value must match the id value provided for that <dataController>. See the chapter Model View Controller.”
currColumn The 1–based column number of the currently selected cell in the grid. The default (until the user makes selections) is 1.
currPage The 1–based page number of the data currently displayed in the grid. If the data set associated with this grid contains three–dimensional data, currPage indicates which page (along the third dimension) is currently displayed. The default is 1.
currRow The 1–based row number of the currently selected cell in the grid. The default (until the user makes selections) is 1.
gridClass CSS class to apply to the HTML table that displays the grid.
gridLabel
Caption to display in the upper-left corner cell.
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. See Zen Attribute Data Types.”
nowrap
If true, the contents of cells within the grid do not word wrap. If false, they do. The default is true.
nowrap has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
onchangecell
The onchangecell event handler for the <dynaGrid>. Zen invokes this handler whenever the user changes the contents of a cell. See Zen Component Event Handlers.”
If you omit the onchangecell attribute, the default behavior is to assign the user-entered value to the cell.
onclickcolumn Client-side JavaScript expression that is executed whenever the user clicks on a column header cell (at the top of a column).
onclickrow Client-side JavaScript expression that is executed whenever the user clicks on a row header cell (at the left of a row).
OnCreateDataSet The OnCreateDataSet value is the name of a server-side callback method that provides the data set associated with this <dynaGrid>. For details, see the section <dynaGrid> Data Set.”
ondblclick Client-side JavaScript expression that is executed whenever the user double-clicks on the <dynaGrid>.
ondrawcell Client-side JavaScript expression that is executed when the <dynaGrid> is about to draw a cell. If this event handler returns a value, this value is used as DHTML to render the cell contents. This convention provides a way to display custom cell formatting within a <dynaGrid>.
oneditcell Client-side JavaScript expression that is executed when the <dynaGrid> is ready to accept user input in one of its cells. If the oneditcell event handler returns a value, this value is used as DHTML to render the editor used for the cell. oneditcell provides a way to display a custom cell editor within a <dynaGrid>. The default behavior is to place an HTML input control over that region of the grid to permit the user to enter data. There is no need to override this default, but you may.
onnotifyView
The onnotifyView event handler for the <dynaGrid>. See Zen Component Event Handlers.” This attribute applies if the <dynaGrid> is associated with a data controller. Zen invokes this handler each time the data controller connected to this <dynaGrid> raises an event. See the chapter Model View Controller.”
onselectcell Client-side JavaScript expression that is executed whenever the user navigates to a new cell. The current cell row and column numbers are updated before the onselectcell call is made. The event handler is passed two variables, row and col, which contain the 1-based row and column number of the current cell.
rowLabelWidth
rowLabelWidth applies to the column of row labels. You must specify rowLabelWidth in pixels, for example 75px. The default is 100px.
For further details, see the <dynaGrid> Layout section following this table.
scrollIntoView
If true, Zen uses the JavaScript scrollIntoView function to try and make visible the currently selected item within the grid.
showColumnLabels
If true, column labels are displayed in a row along the top of the grid. The default is true.
showRowLabels
If true, row labels are displayed in a column along the left side of the grid. The default is true.
showRowLabels has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
<dynaGrid> Layout
If the default layout of the <dynaGrid> does not suit your needs, you can adjust it. Laying out a <dynaGrid> involves many factors. These factors interact in ways that can counterbalance each other and produce surprising results. This section explains the underlying layout scheme for <dynaGrid> and the factors that you can control to produce the desired layout on the page.
The dimensions that you specify for the <dynaGrid> reserve space on the page in which to view the contents of the grid. The contents of the grid consist of the <dynaGrid> rows and columns. In practice, the contents may be larger, smaller, or the same size as the viewing space that you have allowed. If they are larger or smaller, the viewing space may resize itself to fit them. Alternatively, the viewing space may remain static and therefore “crop” or “mat” the grid contents. These options are under your control.
The primary interaction in <dynaGrid> layout is between the following two factors:
Space Reserved to Display the <dynaGrid>
The dimensions that you specify using <dynaGrid> attributes specify the size of the enclosing HTML <div> that Zen generates from your <dynaGrid> specification. The size of this <div> is the size of the viewing space for the <dynaGrid>. You can specify this size by providing a width attribute for the <dynaGrid>, specifying a width attribute in the related CSS section, or providing a width value in an enclosingStyle attribute for the <dynaGrid>.
The resulting <dynaGrid> layout depends on whether the width is set to "auto" or to some fixed width. There is one behavior for "auto" and several behaviors for fixed widths depending on how the widths are set. If you do not set a width for the <dynaGrid>, the width defaults to "auto".
The layout variations for <dynaGrid> width settings are as follows:
Width of <dynaGrid> Data Columns
You can control the layout of <dynaGrid> contents by specifying column widths using the <dynaGrid> attributes rowLabelWidth and columnWidth and the <gridColumn> attribute width. The following sections explain how the values you choose for these attributes affect the layout results.
<dynaGrid> rowLabelWidth
rowLabelWidth applies to the column of row labels that appears as the leftmost column in the grid. The column of row labels acts as a vertical header for the grid, and so it is not treated like <gridColumn> elements, which contain grid data.
Unlike the <gridColumn> width attribute, the <dynaGrid> rowLabelWidth does not support percentage values. You must specify rowLabelWidth in pixels, for example 75px. The default is 100px.
<dynaGrid> columnWidth
columnWidth gives a default width for columns that do not supply a width. The <dynaGrid> columnWidth does not support percentage values. You must specify columnWidth in pixels, for example 75px. The default is 100px.
columnWidth is essential to the default calculation when a <dynaGrid> uses the default width ("auto") and specifies all of its <gridColumn> width values as percentages. In this case, Zen computes a display width for the data columns using columnWidth as described in the <gridColumn> width section.
The total width of a <dynaGrid> is the total width of all data columns plus whatever number of pixels was specified for rowLabelWidth, plus the space needed to render any specified margins, borders or cell padding. The <dynaGrid> viewing space sizes itself to display the entire grid.
<gridColumn> width
The <gridColumn> width attribute determines the width of individual data columns and may be specified in pixels (px) or percentages (%). Pixels and percentages may be freely mixed among the <gridColumn> elements in a given <dynaGrid> specification, with the following results:
If all the column widths are given as percentages and the <dynaGrid> has "auto" size or no size specified at all, the narrowest column is assigned the width of the <dynaGrid> columnWidth, and all other columns are sized with respect to the size of this column, as follows:
  1. Find the <gridColumn> with the smallest percentage value. This is the narrowest column.
  2. Consult the <dynaGrid> columnWidth value, assign this number of pixels as the width of the narrowest column, then use this result to calculate the number of pixels that corresponds to 1%.
    For example, if the smallest <gridColumn> width is 5% and the <dynaGrid> columnWidth is 75px, Zen calculates that there are 15 pixels in every 1%, for a total width of 150 pixels across all data columns in this grid.
  3. Convert the percentage values for all other data columns into numbers of pixels.
<dataGrid>
<dataGrid> implements a component for viewing and editing tabular data. This is an HTML5 component. It works correctly only on HTML5 compliant browsers.
<dataGrid> has the following attributes:
Attribute Description
Control component attributes
<dataGrid> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.”
canResizeColumns
If true, the user can use the cursor to resize columns. The default value is true.
Has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
cellHoverColor
Specifies the background color of cells when the cursor hovers over them. The default value is #EEEEEE. See Data Grid Layout.”
checkedRows
A string containing comma separated values. Each value in the string specifies the 1-based row number of a row in which the row-selector check box is selected. If all rows are checked, the value is set to "all".
The property showRowSelector must be “true” for the user to be able to see and use the check boxes.
columnHeaderStyle
Additional CSS style to apply to column headers in this grid. The property showColumnLabels controls visibility of column headers. You can use columnHeaderStyle to set a height for column headers that is independent of the row height set using rowHeight or rowHeaderStyle.
columnLabelSpan
Specifies how parent column labels with multiple child labels are displayed. If true, then one parent label is displayed for each set of children. If false, then the parent row label is repeated for each child. The default value is false.
Has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
columnWidth
Default width, in pixels, for columns that do not supply a width.
If no columnWidth is set and a column does not supply a width, the width of the column is calculated by dividing the remaining width of the grid amongst the columns with unspecified widths.
currCellBackground The background color to apply to the currently selected cell. The default value is #D0D0FF. See Data Grid Layout.”
currCellColor The foreground color to apply to the currently selected cell. The default value is #000000. See Data Grid Layout.”
currColumn The 1–based column number of the currently selected cell in the grid. The default, until the user makes selections, is 1.
currPage The 1–based page number of the data page currently displayed in the grid. If the grid displays data on multiple pages, currPage indicates which page is currently displayed. The default value is 1. Use the getCurrPage method to view the value of currPage. The attribute pageSize specifies the number of rows on each page. See the section on Paging.”.
currRow The 1–based row number of the currently selected cell in the grid. The default, until the user makes selections, is 1.
evenRowBackground
The background color to apply to even rows when the attribute showZebra is true. The default value is "#F8F8F8". See Data Grid Layout.”
evenRowColor
The foreground color to apply to even rows when the attribute showZebra is true. The default value is #000000. See Data Grid Layout.”
filterKey
If supplied, this is a key used to filter results that are already on the client. See Filtering.”
format
The default format to apply to cells in this grid. This is a DeepSee format string: e.g., "###.##". Row and column-level formatting overrides this format.
gridStatusStyle
An optional CSS style to apply to the grid status area. See Data Grid Layout.”
gridTitle
An optional title to display along top of grid.
gridTitleStyle
An optional CSS style to apply to grid title. See Data Grid Layout.”
multiSelect
If true, users can select a range of cells in the grid. The default value is false.
Has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
oddRowBackground
The background color to apply to odd rows when the attribute showZebra is true. The default value is #FFFFFF. See Data Grid Layout.”
oddRowColor
The foreground color to apply to odd rows when the attribute showZebra is true. The default value is #000000. See Data Grid Layout.”
pageSize
The number or rows displayed on each page when the grid displays data on multiple pages. Use the getPageSize method to view the value of pageSize. The default value is 0, which displays all rows on a single page. See the section on Paging.”
pagingMode
Specifies whether data paging should occur on the server or on the client. The default value is "client".
rowHeaderStyle
An additional CSS style to apply to row headers in this grid. The property showRowLabels controls visibility of row headers. If this property is used to set height, and rowHeight is also set, the grid uses the larger of the two values.
rowHeight
The default height, in pixels, used for rows that do not supply a height. If not defined, then the height is calculated. If height is also set with rowHeaderStyle, the grid uses the larger of the two values.
rowLabelSpan
Specifies how parent row labels with multiple child labels are displayed. If true, then one parent label is displayed for each set of children. If false, then the parent row label is repeated for each child. The default value is true.
Has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
rowLabelWidth
Specifies the width of the column of row labels. The number you provide is interpreted as a number of pixels. If you do not provide a value, the width is calculated.
selectedRange
This specifies the current selected range of cells as a comma-separated list of integers. The list is of the form: startRow, startCol, endRow, endCol. All cells numbers are 1-based. If the range is equal to "", then no cells are selected. This property is used only if the attribute multiSelect is true.
selectMode
Specifies how selection works within the grid. If the value is "rows", then the user selects entire rows at a time. If the value is "cells", then the user can select and move between individual cells. The default value is "rows".
showColumnLabels
If true, column labels are displayed in a row along the top of the grid. The default is true. See Data Grid Layout.”
The default column labels are the column names as provided by the data source. You can use the caption property of <columnDescriptor> to specify column labels.
Has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
showRowLabels
If true, row labels are displayed in a column along the left side of the grid. The default is true. See Data Grid Layout.”
The default row labels are 1–based row numbers assigned to the rows. You can use the caption property of <rowDescriptor> to specify row labels.
Has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
showRowSelector
If true, display a check box in each row to allow selection of the row. If showColumnLabels is also true, a check box in the left-most column of the grid lets the user select or de-select all rows at once. The default value is false. See Data Grid Layout.”
Has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
showZebra
If true, display the grid with “zebra striping”, alternating colors applied to rows. The default value is true. See Data Grid Layout.”
The attributes oddRowBackground and evenRowBackground specify the background colors used, and oddRowColor and evenRowColor specify the foreground colors used.
Has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.”
sortColumn
For sortable tables, this attribute specifies the 1-based column number of the column used for sorting results. The direction of the sort is specified by sortOrder. The default value is 0, which means no column is sorted. See Sorting.”
sortMode
Indicates where columns are sorted. Possible values are "client" or "server". The default value is “client”. As of this release, server-side sorting is not implemented.
sortOrder
For sortable tables, this attribute specifies the sort order for values in the column specified by sortColumn. Possible values are: "" (unsorted), "asc" (ascending), or "desc" (descending). The default value is unsorted. See Sorting.”
style
An additional style to apply to cells in this grid. This is applied before any row and column-level styles.
summaryRow
Optional descriptor for the summary row.
valueColumn
The 1-based column number of the column that supplies the value for a row in the table. The default value is 1.
The following figure shows the major components of a <dataGrid>. In addition to the labeled items, the figure illustrates odd and even color and background color.
Data Grid Layout
The following attributes specify event handlers. See Zen Component Event Handlers.”
Attribute Description
onaction
A client-side JavaScript expression that is executed when the user executes an action within a cell, such as clicking on a column-defined checkbox, button, or link. Generally this expression invokes a client-side JavaScript method defined in the page class. This method becomes the “onaction event handler” for the grid. The current cell row and column number are updated before this call is made. The event handler is passed 3 variables, row, name, and value, which contain the row number of the current cell (1-based), the logical name of the column, and the current value of the action control, if applicable.
onchangecell
The onchangecell event handler for the grid. Zen invokes this handler whenever the user finishes editing a cell value. See Zen Component Event Handlers.” The current cell row and column number is updated before this call is made. The event handler is passed the new cell value. It should return the value to be placed into the cell or null to cancel the edit.
ondrawcell
The ondrawcell event handler for the grid. Zen invokes this handler whenever a cell is about to be drawn. See Zen Component Event Handlers.” The event handler is passed value, row, and col (1-based). If this event handler returns a value, then it is used to render the cell contents. The return value of this event handler is either null, in which case the default rendering is used for the cell, or an object with any of the following properties:
  • content - HTML to display within the cell.
  • align - horizontal alignment for the cell.
  • style - CSS style for the cell.
  • format - format string for the cell (ignored if content is supplied).
  • image - image for the cell (ignored if content is supplied).
  • type - type for the cell (ignored if content is supplied).
  • value - value for the cell (ignored if content is supplied).
onfiltercell
The onfiltercell event handler for the grid. Zen invokes this handler when the user enters a new filterKey. The event handler is passed an object, info, with the properties row, col, value, and key. The event handler should return true if the row containing the cell matches the filter, or false otherwise.
ongetlookupdata
The ongetlookupdata event handler for the grid. It returns a JavaScript array of data to display within the popup for a lookup column. The returned value can be any array of object or literal values.
ongetstatus
The ongetstatus event handler for the grid. If defined, this event handler returns the HTML that is displayed in the status area of this grid. The status area is located at the bottom of grid.
ongettitle
The ongettitle event handler for the grid. If defined, this event handler returns the HTML that is displayed in the title area of this grid. The title area is located at the top of grid. This supercedes the gridTitle property if defined.
onheaderclick
The onheaderclick event handler for the grid. If defined, this event is fired when the user clicks on a row or column header. The variable which indicates which header is clicked: "row" or "column". The variable index indicates the ordinal number of the header (1-based).
onselectcell The client-side JavaScript expression that is executed whenever the user navigates to a new cell. The current cell row and column numbers are updated before the onselectcell call is made. The event handler is passed two variables, row and col, which contain the 1-based row and column number of the current cell. See Selecting Rows and Cells.”
onselectrow The onselectrow event handler for the grid. If defined, this event is fired when the user toggles any of the visible row selector check boxes in the grid. A single variable, range, is passed to the event handler. The range is a string enumerating the currently checked rows. This variable has two special values: "" indicating that no rows are currently checked, and the reserved value "all" indicating that all rows are checked. For values between these extremes, the range parameter is a CSV string listing the (1-based) indices of the currently checked rows. Because this event is linked to the toggling of the row selectors, it only fires if showRowSelector is true. See Selecting Rows and Cells.”
Creating a Data Grid
You can create an empty <dataGrid> control by simply adding the component to the Zen page:
<dataGrid id="grid"/>
You can control the size of the <dataGrid> by putting CSS styles in the XData Style section of the page. For example, if the grid id is 'grid':
#grid
 {
   width: 600px;
   height: 600px;
 }
You can also control the size of the grid using JavaScript by setting the width and height of the grid's enclosing div and then invoking the grid's adjustSizes method to lay out the internal parts of the grid:
zen('grid').adjustSizes();
Connecting the Grid to Data
The <dataGrid> is a data view component and can be connected to an <altJSONProvider>. See the section Zen JSON Components in the book Developing Zen Applications. For example, if you have an <altJSONProvider> that supplies an array of objects:
<altJSONProvider id="json" OnGetArray="GetData" />
You can connect the <dataGrid> to this <altJSONProvider> by setting the controllerId:
<dataGrid id="grid" controllerId="json" />
The grid now displays the data served by the <altJSONProvider>. In this case, all the properties provided by the <altJSONProvider> are displayed as columns and there is one row for every object (data series) supplied by the provider.
Filtering
<dataGrid> supports client-side filtering of the grid contents. Filtering limits the data actually displayed by applying a filtering function to the client-side data before displaying it in the grid. You can override the default filtering behavior by overriding the onfiltercell event handler.
Searching
<dataGrid> supports server-side searching. The search is performed by changing the parameters used to fetch the data displayed in the grid. Typically this is done by reloading the contents of an <altJSONProvider>.
Sorting
A <dataGrid> supports column-wise sorting on the client. The attribute sortColumn specifies the column used for sorting. The attribute sortOrder determines the order in which the column should be sorted. If showColumnLabels is true, the column label for the sorted column displays an arrow that indicates the direction of the sort, as illustrated in the following figures.
Ascending and Descending Sort Order
The attribute sortMode can have a value of either “client” or “server,” indicating client-side or server-side sorting. The default value is “client.” As of this release, server-side sorting is not implemented.
Paging
The <dataGrid> component supports paging. Each page of the grid displays a fixed set of rows. Paging can be done on either the client or the server. If paging is done on the client, the grid loads all the rows and the user pages through them on the client. If paging is done on the server, the grid loads one page at a time from the server.
To use client-side paging:
If the number of rows displayed by the grid is greater than the number specified by pageSize, a set of paging buttons is displayed on the bottom of the grid. See Data Grid Layout.”
To use server-side paging:
Selecting Rows and Cells
The properties onselectcell and onselectrow let you define an event handlers that run when the end user selects a row or cell in the <dataGrid>. For example, a Zen page containing an <altJSONProvider> and <dataGrid> as follows:
<page xmlns="http://www.intersystems.com/zen">
  <altJSONProvider id="json" OnGetArray="GetData" />
  <dataGrid id="grid"
    controllerId="json" 
    showRowSelector="true"
    onselectrow="zenPage.rowSelected(range);" />
</page>
And a rowSelected callback defined as follows:
ClientMethod rowSelected(range) [ Language = javascript ] 
{ 
  alert("Selected rows are: "+range);
}
Pops up an alert message showing the currently selected rows. Similarly, the following page:
<page xmlns="http://www.intersystems.com/zen">
  <altJSONProvider id="json" OnGetArray="GetData" />
  <dataGrid id="grid"
    controllerId="json" 
    multiSelect="true"
    selectMode="cells"
    onselectcell="zenPage.cellSelected(row, col);" />
</page>
And a cellSelected callback defined as follows:
ClientMethod cellSelected(row, col) [ Language = javascript ]
{
  alert("Selected cell is: "+ row + ", " + col);
  var rng = zen('grid').selectedRange
  alert("Selected range is: " + rng);
}
Column Descriptors
You can exercise more direct control over the contents of the grid by defining one or more <columnDescriptor> objects. If the grid contains <columnDescriptor> objects, it no longer automatically displays all of the data supplied by its data controller. You must provide a <columnDescriptor> for each column you want in the grid. The value property specifies the data shown in each column.
<dataGrid id="grid" controllerId="json">
 <columnDescriptor value="100"/>
 <columnDescriptor value="=[@Name]"/>
 <columnDescriptor value="=[@City]"/>
</dataGrid>
The grid in this example shows 3 columns. The first column displays the value "100" in each cell. The second column displays the value of the Name property supplied by the altJSONProvider. The "=" character at the start indicates that this is an expression (or formula). The [ ] brackets enclose an identifier. The identifier "@Name" specifies the Name property supplied by the data controller.
<columnDescriptor> has the following attributes:
Attribute Description
align Optional horizontal alignment to apply to this column. Use this to control alignment rather than the style property.
caption Optional caption to apply to this element. It appears in the grid as the column label text.
columns Optional child descriptors for this column.
format Optional format to apply to this element.
headerAlign Optional horizontal alignment to apply to the header for this column. If not defined, then the value specified in align is used. Use this to control alignment rather than the style property.
headerStyle Style string to apply to the header for this column.
hidden Do not show this column.
image For image columns, this is the name of the image to display.
ongetlookupspec This event is used to compute the lookup (popup) information for this column.
priority Optional priority to apply to this element.
readOnly Optional readOnly attribute to apply to this element. If true, the contents of this column cannot be edited. The default value is false.
style Style string for this column.
type
If the <dataGrid> selectMode property is set to "cells", then you can use the type property of the column descriptor to specify the type of edit control that is displayed in the cell when it is selected. Possible values for the type property are:
  • "string" — display a string value and edit as a string.
  • "image" — display an image (using the url in the image property).
  • "button" — display a button. You must implement an onaction handler to supply behavior for the button.
  • "checkbox" — display a checkbox.
  • "link" — display an HTML link. You must implement an onaction handler to supply behavior for the link.
  • "lookup" — display a lookup control. You must implement an ongetlookupdata handler to supply behavior for the lookup.
  • "user" — display arbitrary HTML as defined by the ondrawcell callback
value Optional default value for this column. This can be a literal value or an expression such as this one: "=[@Name]"
The "=" character at the start indicates that this is an expression (or formula). The [ ] brackets enclose an identifier. The identifier "@Name" specifies the Name property supplied by the data controller.
If you do not specify the value attribute, the grid displays values from the data controller in the order in which they are supplied.
width Optional default minimum width, in pixels, used for this column on initial rendering. The actual width may be adjusted higher as needed depending on the actual widths of data in the cells themselves. This setting does not preclude the end user from manually resizing the column width to a smaller value.
You can use CSS to modify non-essential display properties of editable cells in a <dataGrid>. The CSS class for editable cells is dgCellEditor. For example, the following CSS sets the cell background to yellow during editing:
.dgCellEditor {
  background-color:yellow;
}
You can also modify display properties of lookup cells, specifically the image on the button the user clicks to open the lookup list. The CSS class is dgAction. The URL specified for an image file is resolved with respect to the csp/broker directory under the Caché install directory. For example, the following CSS sets the lookup button image:
.dgAction {
  background-image:url("lookupicon.png");
}
Row Descriptors
You can exercise more direct control over the contents of the grid by defining one or more <rowDescriptor> objects. If the grid contains <rowDescriptor> objects, it no longer automatically displays what is served by its data controller. You must provide a <rowDescriptor> for each row you want in the grid.
<dataGrid id="grid" controllerId="json">
  <rowDescriptor caption="ROW 1"/> 
  <rowDescriptor caption="ROW 2"/> 
  <rowDescriptor caption="ROW 3"/>
</dataGrid>
<rowDescriptor> has the following attributes:
Attribute Description
caption Optional caption to apply to this element. It appears in the grid as the row label text.
format Optional format to apply to this element.
priority Optional priority to apply to this element.
readOnly Optional readOnly attribute to apply to this element. If true, the contents of this row cannot be edited. The default value is false.
rows Optional child descriptors for this row.
style Style string for this column.
Hidden
The Zen <hidden> control is a wrapper around the HTML <input type="hidden"> element. The <hidden> control is present in the form, and has a value associated with it, but is never visible to the user. The value can be changed programmatically on the client or server side. When the form is submitted, the values of any <hidden> controls are submitted along with all the others.
<hidden> has the same general-purpose attributes as any Zen control. For descriptions, see the section Control Attributes.”