The XDocument Object

The XDocument Object

The XDocument object represents the underlying XML document of an InfoPath form.

XDocument Object Methods

The XDocument object has nine methods:

• GetDataVariable() ” Retrieves the value of a variable held as a pseudo-attribute in an XML processing instruction. The method's single argument is a long integer that is the number of the variable. Security level 2.

• GetDOM() ” Returns a reference to the DOM of a DataObject object. The method's single argument is a string that is the name of the secondary data source. Security level 2.

• ImportFile() ” Imports another InfoPath form into the current form. The method's single argument is a URL that indicates the location of the file to be imported. Security level 2.

• PrintOut() ” Prints out the currently active view. Security level 3.

• Query() ” Retrieves data from the form's data adapter and stores the data in the DOM for the form. The method has no arguments. Security level 2.

• Save() ” Saves the (partly completed or completed) form back to a URL that it is already associated with. The method has no arguments. Security level 3.

• SaveAs() ” Saves a form to a different location. The method's single argument is a URL. Security level 3.

• SetDataVariable() ” Partner of the GetDataVariable() method. The SetDataVariable() method sets the value of a pseudo-attribute in an XML processing instruction. The method has two arguments: a long integer that specifies the number of the variable, and a string holding the value of the variable. Security level 2.

• Submit() ” Causes the form to be submitted according to predefined rules for submission of that form. The method has no arguments. Security level 2.

XDocument Object Properties

The XDocument object has 16 properties:

• DataObjects ” A reference to the DataObjects collection associated with the InfoPath form, therefore allowing programmatic access to the form's secondary data sources. Security level 2.

• DOM ” A reference to the XML DOM associated with the form, therefore allowing programmatic access to the XML underlying the form. Security level 2.

• Errors ” Read-only. A reference to the Errors collection associated with the form. Security level 2.

• Extension ” A reference to a form's global scripting object, therefore allowing access to the form's primary scripting file ( script.js or script.vbs ). Security level 2.

• IsDirty ” Read-only. A Boolean value indicating whether the form's data has been modified since the form was opened. Security level 2.

• IsDOMReadOnly ” Read-only. A Boolean value indicating whether the DOM is in a read-only state. Security level 2.

• IsNew ” Read-only. Indicates whether a newly created form has been saved since it was created. Security level 2.

• IsReadOnly ” Read-only. Indicates whether the form is in a read-only state. If so, the form cannot be saved using the Save() method; the SaveAs() method must be used instead. Security level 2.

• IsSigned ” Read-only. A Boolean value indicating whether a form has been digitally signed. Security level 2.

• Language ” Sets or retrieves the default language code of the form. Security level 2.

• QueryAdapter ” A reference to the data adapter of a form, which is represented by an ADOAdapter object, a WebServiceAdapter object, or an XMLFileAdapter object. Security level 2.

• Solution ” A reference to the Solution object associated with the form's form template. Security level 2.

• UI ” A reference to the UI object. Security level 2.

• URI ” A string value that is the location where the form is stored. Security level 2.

• View ” A reference to the currently active View object. Security level 2.

• ViewInfos ” A reference to the ViewInfos collection of the form. Security level 2.

The IsDirty Property

It is often useful to know if data has been entered into a form by a user . The XDocument.IsDirty property checks whether any change has been made to the DOM that underlies the data source.

The sample form template IsDirtyTest.xsn uses the XDocument.IsDirty property to test whether any change has been made to a text box in the form template.

IsDirty CHECKS WHETHER CHANGES HAVE BEEN MADE

The IsDirty property checks whether any change has been made since a form was opened. It doesn't check whether any data is currently present. For example, adding some text to a text box form control and deleting it again leaves the IsDirty property with the value of true . So, a blank form can have IsDirty with a value of true .

The ViewInfos Property

The ViewInfos property of the XDocument object allows you to programmatically discover a form's default view. The SimpleHR2.xsn example template in the download includes a button that cycles through the members of the ViewInfos collection to find which view is the default and then displays the name of that view in a message box.