Using a Data Source Object that Exposes Multiple Data Members

Microsoft® Internet Explorer 4.0 introduced data binding to allow content developers to access data maintained independently from the HTML markup used to display that data. In addition, data binding allows authors to uniformly access data in a variety of formats through the use of data source objects (DSOs).

Given a hypothetical DSO that provides access to a user's electronic mail, a page author might want to use a databound tree control to display the user's mail folders, a databound table to display the user's messages contained within the selected folder, and a databound text area to display the selected message. Since Internet Explorer 4.0 allows each instance of a DSO on a page to provide a single data set at a time, the page author has two options:

Forego declarative binding, and use script to populate the user interface.
Use multiple instances of the DSO (three in the example, later in this article) and use script to detect changes in the state of each DSO instance.

Neither option is appealing because it forces the page author to write complicated scripts, and, in the second case, it incurs unnecessary memory usage. To remedy this situation, Internet Explorer 5 adds support for data source objects that expose multiple, named data members. This article details how to use a DSO that supports multiple data members in a Web page.

Understanding Named Data Members

A named data member is a set of data provided by a DSO. The set can reflect the physical organization of the data. In addition, the data member can represent a logical view of the data. In both cases the data set can be referred to by a well-defined name as defined by the author of the DSO. In the electronic mail example later in this article, the DSO might expose the following data members:

folders: Represents the set of electronic mail folders created by the user, such as the user Inbox, Outbox, and Deleted Items. Each folder in the set can expose data such as the folder name, the number of items in the folder, and a description of the folder's purpose.
headers: Represents the set of headers corresponding to each message. The headers might only include information about who sent the message, to whom the message was sent, and the subject of the message.
messages: Represents the set of electronic mail messages and includes the body text of each message.

A spreadsheet DSO might expose a named data member corresponding to any valid range on a spreadsheet. The following examples use the syntax of a Microsoft® Excel range:

A1:A7: Represents the first seven cells of the first column of a spreadsheet.
B1:B1: Represents the first cell in the second column of a spreadsheet.
A1:D7: Represents the first seven cells of the first four columns of a spreadsheet.

Refer to the documentation of a DSO to determine the names of the data members exposed by the DSO.

Binding to a Named Data Member

Internet Explorer 5 extends the syntax of the DATASRC attribute to allow a page author to bind declaratively to a named data set. For example, given an electronic mail DSO that has been assigned the ID "dsoEmail" and that exposes the named data member headers, the following example demonstrates how to bind a TABLE to that data member.

<TABLE DATASRC="#dsoEmail.headers">
<TR>
   <TD><SPAN DATAFLD="from"></SPAN></TD>
   <TD><SPAN DATAFLD="to"></SPAN></TD>
   <TD><SPAN DATAFLD="subject"></SPAN></TD>
</TR>
</TABLE>

The example assumes that the headers data member exposes fields with the names "from", "to", and "subject".

Programatically Retrieving a Named Data Member

Internet Explorer 5 allows a script author to access the named data members of a DSO by exposing the namedRecordset method on the DSO. As the name of the method indicates, namedRecordset returns a reference to an ActiveX Data Object (ADO) recordset corresponding to the named data member. The recordset can be navigated using the ADO object model as demonstrated in the following example:

function WalkHeaders(oDSOEmail, oList)
{
   // retrieve a recordset corresponding to the e-mail headers
   var oRSHeaders = oDSOEmail.namedRecordset("headers");
   oRSHeaders.MoveFirst();
   // traverse the recordset
   for (var iHeader = 0; iHeader < oRSHeaders.RecordCount; iHeader++)
   {
      // filter the headers
      var sFrom = oRSHeaders.Fields("from").value;
      if (sFrom == "jsmith")
      {
        // populate a list with the subjects of qualifying headers
        sSubject = oRSHeaders.Fields("subject").value;
        sMsgID = oRSHeaders.Fields("messageId").value;
        var oOption = new Option(sSubject, sMsgID);
        oList.options[oList.options.length] = oOption;
      }
      oRSHeaders.MoveNext();
   }
}

The example traverses the set of headers and populates a SELECT element with the subjects of those messages that were sent by the user "jsmith". A more generic routine might pass the field name and value to be used as the filter. Ideally the DSO would provide properties to allow the author to filter the data set so that only the necessary data was transmitted to the user's computer.

Handling Events from Named Data Members

A DSO that supports multiple data members will fire the data binding events for each named data member that is bound to elements on the page. The script author can detect the named data member that fired the event by examining the qualifier property of the event object.

The following example handles the ondatasetcomplete event. If the qualifier property is equivalent to "headers", all of the mail headers are available, and the code calls the WalkHeaders method.

<SCRIPT FOR="ondatasetcomplete" FOR="dsoEmail">
var oEvent = window.event;
if (oEvent.qualifier == "headers")
{
   WalkHeaders(oEvent.srcElement, cboHeaders);
}
</SCRIPT>

For a complete list of events that apply to a DSO, see the DHTML Event Model Support for Data Binding article.