The DataDOMEvent Object

< Day Day Up >

The `DataDOMEvent` Object

The DataDOMEvent object is used in association with the three InfoPath validation events ” OnBeforeChange , OnValidate , and OnAfterChange . The DataDOMEvent object is passed as the argument to an event handler for any of those validation events.

The DataDOMEvent object is used to gather information about the node in the DOM, which is subject to the validation event(s).

THE `OnValidate` EVENT

Typically, the form validation events occur in association with the editing of the values associated with form controls. However, it is possible for the OnValidate event to occur separately from the editing of form control values.

`DataDOMEvent` Object Methods

The DataDOMEvent object has only one method, ReportError() ; it's security level 2.

The ReportError() method creates an Error object and adds it to the Errors collection.

ReportError() takes six arguments:

The DOM node with which the error is associated
A string that is the short message to be used in the error message associated with the Error object
A Boolean value that indicates, when false , that the error is associated with a single DOM node (so-called site-dependent error ) or, when true , that the error applies to all nodes of the type of the node on which the error occurred (so-called site-independent error )
An optional string to be used as the full error message
An optional long integer that contains the error number
An optional string that can take the value of modal (meaning the user must explicitly cancel an error message dialog box) or modeless (meaning the user is not presented with an error message that he must cancel)

Taken together, the arguments to the ReportError() method provide a full description of the error and the characteristics of the message to be displayed.

`DataDOMEvent` Object Properties

The DataDOMEvent object has 11 properties:

IsUndoRedo ” A Boolean value that indicates whether the event occurs during an undo or redo operation. Security level 2.
MatchExpression ” Read-only. The XPath 1.0 expression that would select the node on which the event occurred. Security level 0.
NewValue ” Read-only. The new value that is to be inserted in a node during the validation event. Security level 2.
OldValue ” Read-only. The value that is to be replaced during a validation event. Security level 2.
Operation ” Read-only. The type of operation that is being performed on the DOM node. Permitted string values are Delete , Insert , and Update . Security level 0.
Parent ” Read-only. A reference to the parent node of the DOM node to which the validation event applies. Security level 2.
ReturnMessage ” Sets or retrieves a string value to be displayed if the validation event does not succeed. Security level 2.
ReturnStatus ” Sets or retrieves a Boolean value indicating whether the form validation event succeeded or failed. The value true indicates successful validation, and that the DOM node was updated. The value false indicates that validation failed, and that the value of the DOM node was not updated. Security level 2.
Site ” A reference to the DOM node that was the subject of the form validation event. This enables full access to script that node in any appropriate way. Security level 2.
Source ” A reference to the DOM, where the form validation event is occurring. Security level 2.
XDocument ” A reference to the XDocument object associated with the form validation event. Security level 2.

The IsUndoRedo property is useful for checking whether the DOM is read-only at the time an event occurs. Using code like the following at the start of a function prevents attempts at writing to a read-only DOM:

 if (eventObj.IsUndoRedo) { // An undo or redo operation has occurred and the DOM is read-only. return; }

The sample form template OldAndNew.xsn in the download uses the OldValue and NewValue properties of the DataDOMEvent object to display the relevant values in a message box:

 function msoxd_my_field1::OnValidate(eventObj) {  XDocument.UI.Alert("The old value in the text box was: " + eventObj.OldValue + ".\n"  + "The new value in the text box is: " + eventObj.NewValue + "."); }

The ReturnMessage property and the ReturnStatus property are often used together. For example, if you wanted to impose a non-empty string value for a text box form control, you would use code like the following:

 if (eventObj.NewValue = "")  eventObj.ReturnMessage("This text box cannot be blank.");  eventObj.ReturnStatus = false;  return;

Using an if statement in such a way prevents processing that is appropriate only when the text box form control contains a non-empty value.

< Day Day Up >