The DataObject Object

The DataObject Object

The DataObject object represents an association with a data adapter for a secondary data source. The DataObject objects in a document are contained in the DataObjects collection.

To learn more about creating a secondary data source for a drop-down list form control, see "The Drop-Down List Box Control," p. 62 (Chapter 4).

InfoPath 2003 supports three types of data adapter:

• The ActiveX Data Objects (ADO) data adapter, represented in InfoPath by the ADOAdapter object

• The XML Web services data adapter, represented in InfoPath by the WebServiceAdapter object

• The XML file data adapter, represented in InfoPath by the XMLFileAdapter object

DataObject Object Methods

The DataObject object has a single method, Query() , which is security level 2. The Query() method retrieves data from the data adapter that is associated with the DataObject object and populates the DOM associated with the DataObject object (see the DOM property of the DataObject object in the next section).

The DataObject.Query() method is accessed from the DataObjects collection. To refresh data from a secondary data source named Categories in JScript, you would use code like this:

 XDocument.DataObjects("Categories").Query(); 

Remember, when you create a secondary data source for a drop-down list form control, for example, you have to give the data source a name ”in this case, Categories .

After you have refreshed the DOM, you will typically also want to display the refreshed DOM in the current view. You can do this by using the ForceUpdate() method of the View object:

 XDocument.View.ForceUpdate(); 

DataObject Object Properties

The DataObject object has three properties:

• DOM ” A reference to the DOM associated with the DataObject object.

• Name ” The name of the secondary data source associated with the DataObject object.

• QueryAdapter ” Read-only. A reference to the data adapter associated with the DataObject object.

The SecondarySource.xsn form template in the download illustrates how you can display the name of a secondary data source. The JScript code is here:

 function DisplayDO::OnClick(eventObj) { var x; var count = XDocument.DataObjects.Count; var displayString = "Here are the names of secondary data sources.\n "; for (x=0; x < count; x++) {  displayString += "Data Object " + x + " is called " + XDocument. DataObjects.Item(x).Name + ".\n";  } // end for loop XDocument.UI.Alert(displayString); } 

In this sample form template, there is only a single secondary data source named Categories . The displayString variable contains an initial string to be displayed, and the for loop adds to the displayString variable for each secondary data source in the form template. We use the Name property of the Categories data source, using the Item property of the DataObjects collection to select each DataObject object in the code shown here, and then using the Name property of each DataObject object to contribute to the value of the displayString variable.

Figure 18.1 shows the message box displaying the name of the only secondary data source for SecondarySource.xsn .

Figure 18.1. Using the DataObject object to display the name of a secondary data source.

The second button in the sample form template displays the location of the secondary data source, in this case an XML file:

 function DisplayLocation::OnClick(eventObj) { var objFileAdapter; objFileAdapter = XDocument.DataObjects("Categories").QueryAdapter; XDocument.UI.Alert("The Secondary Data Source is located at: " + objFileAdapter.FileURL); } 

In this case, we use the FileURL property of the data adapter, having assigned the variable objFileAdapter to the data adapter for the named DataObject object, and using the DataObjects collection to provide the reference to the named DataObject object.