About Microsoft Tabular Data Control

The Tabular Data Control (TDC) is a Microsoft ActiveX control that can be hosted by Microsoft Internet Explorer 4.0 and later to display data stored in a delimited text file. Using the TDC, a Web author can display data either within tables or within controls found in a form. (Extensions in Internet Explorer 4.0 and later allow you to bind data to HTML elements on the page as well as to repeat the content of an HTML table element for each record of a data set. The latter can be thought of as using the table as a template for the data, where the template is repeated once for each record.)

One of the primary features of the TDC is that it brings filtering and sorting operations to the client side (there are no server-side operations).

The TDC exposes the OLE-DB simple provider interfaces. For more information about these interfaces, see OLE-DB Simple Provider: A Data Binding API for MSHTML.

• Source Availability
• Licensing and Distribution
• Dependencies
• Understanding the Tabular Data Control Object Model
  • File Properties
  • Filtering Properties
  • Sorting Properties
• Using the Tabular Data Control
  • A Simple Before-and-After Example
  • Adding data to your Web page
  • Declaring the TDC object
  • Relaxing TDC Security
  • A More Advanced Example: Sorting and Filtering
• Summary

Source Availability

To aid developers in creating their own data source objects, the Tabular Data Control is provided as a sample that ships with the Internet Client SDK. The source code can be found in \inetsdk\samples\tdc.

Licensing and Distribution

The Microsoft Tabular Data Control is automatically installed as part of the base installation of Internet Explorer 4.0 and later.

Dependencies

The TDC is found in the file Tdc.ocx, which is automatically installed and registered with all versions of Internet Explorer 4.0 and later.

Understanding the Tabular Data Control Object Model

The TDC supports properties and methods that can be divided into these categories:

• Elements that describe the data file.
• Elements that support data filtering.
• Elements that support data sorting.

File Properties

Most of the properties supported by the TDC are data-file properties. These properties specify the location of the data file, the language used to create the data file, the character used to delimit fields, and so on. The following list describes each property:

Filtering Properties

One TDC property and one method apply to data filtering.

Set the Filter property to an expression that includes the name of the column to be filtered, the criteria for filtering, and the value that will be compared against the specified column using the given value. The default value is an empty string ("").

Call the Reset method to apply the filter and refresh the contents of the HTML elements bound to the data supplied by the TDC.

Sorting Properties

One TDC property and a single TDC method apply to data sorting.

Set the Sort property to a semicolon-delimited list of column names by which the bound HTML elements should be sorted. Prefixing a column name with a plus (+) symbol indicates ascending order. The minus (-) symbol indicates descending order. The default sort order is ascending.

Call the Reset method to apply the new sort order and to refresh the contents of the HTML elements bound to the data supplied by the TDC.

Using the Tabular Data Control

This section demonstrates how you can incorporate the TDC into your Web pages.

Note  The TDC examples in this section require Internet Explorer 4.0 and later.

A Simple Before-and-After Example

This section contains a very simple example demonstrating how you can replace a static table in your HTML page with a dynamic table that is generated using the TDC. When this replacement occurs, you'll no longer need to modify your HTML source file each time your data changes; instead, you can simply modify the data file or regenerate it from a database.

Adding data to your Web page

The Tabular Data Control (TDC) has many uses, but perhaps the easiest way to get a feel for its capabilities is to see a short example. If you have a data file containing some of the elements of the periodic table, it might look like this:

Element,Symbol
Hydrogen,H
Helium,He
Lithium,Li
Beryllium,Be
Boron,B
Carbon,C
Nitrogen,N
Oxygen,O
Fluorine,F
Neon,Ne

Each line contains the name of the element followed by a comma, and then its scientific abbreviation. If you wanted to display this table in a Web page without using the TDC, you would add the table tags around each word, as shown in the following example:

<TABLE>
<THEAD><TR><TD>Element</TD><TD>Symbol</TD></TR></THEAD>
<TBODY>
<TR><TD>Hydrogen</TD> <TD>H</TD></TR>
<TR><TD>Helium</TD> <TD>He</TD></TR>
<TR><TD>Lithium</TD> <TD>Li</TD></TR>
<TR><TD>Beryllium</TD> <TD>Be</TD></TR>
<TR><TD>Boron</TD> <TD>B</TD></TR>
<TR><TD>Carbon</TD> <TD>C</TD></TR>
<TR><TD>Nitrogen</TD> <TD>N</TD></TR>
<TR><TD>Oxygen</TD> <TD>O</TD></TR>
<TR><TD>Fluorine</TD> <TD>F</TD></TR>
<TR><TD>Neon</TD> <TD>Ne</TD></TR>
</TBODY>
</TABLE>

Click the Show Me button to see how the previous table appears when viewed in your browser.

Code example: http://samples.msdn.microsoft.com/workshop/samples/author/databind/eltstat.htm

A static table is not only tedious to create, but it also makes it inconvenient to edit or update the data. This especially applies if you want to use the raw data file in other applications. Using the TDC, you can instead tell the Web page where to find the text file, and it will read the data directly from the file (plus optionally sort it, filter it, and skip columns). The previous table coding is replaced with the following coding:

<TABLE datasrc=#elements>
<THEAD><TR><TD>Element</TD><TD>Symbol</TD></TR></THEAD>
<TBODY>
<TR><TD><DIV datafld="Element"></DIV></TD><TD><DIV datafld="Symbol"></DIV></TD></TR>
</TBODY>
</TABLE>

Click the Show Me button to see how data binding can be used to replace a static table in Internet Explorer 4.0 and later.

Code example: http://samples.msdn.microsoft.com/workshop/samples/author/databind/eltdyn.htm

If you look more closely at these changes, you will note that the first line uses the dataSrc attribute to identify the TDC. (This identifier corresponds to the id attribute that was specified for the object element that loaded the control.)

<TABLE datasrc=#elements>

The prepended # symbol is always required by the dataSrc attribute.

You can include multiple linked tables and objects in each Web page; each table should specify a dataSrc attribute that can be unique to that table or shared between tables or other elements on the page, such as forms.

The second line of the table definition is unchanged. As you can see, it provides the table heading.

<THEAD><TR><TD>Element</TD><TD>Symbol</TD></TR></THEAD>

The fourth line is the most interesting. Instead of providing the actual data, you specify the name of a column in the data file using the new dataFld attribute.

<TR><TD><DIV datafld="Element"></DIV></TD><TD><DIV datafld="Symbol"></DIV></TD></TR>

Because the original data file had a header that specified the name of each column, these column names can be used. If no header is provided in your data file, you should use the default names of Column1, Column2, and so on.

As part of the header that specifies column names, a type specifier can be included indicating the data type of the column. Since the TDC reads its data from a text file, this indicates the appropriate type conversion to do upon reading the data from the file. The TDC uses this to perform accurate sorting and filtering. Consider the case where you have integers in a column and you request the column to be sorted. Without the type specification, the sort would be done using string (lexicographic) ordering, which would give the wrong result. For more information on specifying data types for columns, see TDC Reference.

With this information encoded in the table, Internet Explorer 4.0 and later will ask the TDC for data to put into the table. It will then create one new row for each row of data. Notice how all the other table encoding tags remain unchanged. In fact, you can treat the incoming data exactly as if it were text that you hard-coded into your Web page. For example, if you wanted the symbols in the table to be bold and centered in their column, you could change the table entry to the following:

<TD><CENTER><DIV datafld="Symbol"></DIV></CENTER></TD>

You could also choose to completely leave out the symbol information from the table just by removing the <DIV> entry where it is specified. Although this might not necessarily be appropriate for this example, it's often convenient to omit some fields because that allows you to reuse the same data file in many different Web pages rather than maintaining multiple copies of almost identical data.

Declaring the TDC object

The only other new entry in your Web page is the TDC object declaration. The above examples use the following:

<OBJECT id=elements CLASSID="clsid:333C7BC4-460F-11D0-BC04-0080C7055A83">
    <PARAM NAME="DataURL" VALUE="minielts.txt">
    <PARAM NAME="UseHeader" VALUE="True">
</OBJECT>

The id attribute identifies the TDC and its associated data for later use by elements such as tables, forms, and scripting. The id attribute can be any arbitrary name, but it's best to start with a letter and avoid spaces and punctuation characters.

The DataURL property tells the TDC where to find the data file. You can provide any valid URL, or, as in this example, use a relative URL that will cause the TDC to look in the same place your Web page was found. Other valid DataURL settings include the following:

<PARAM NAME="DataURL" VALUE="data/elements.txt">
<PARAM NAME="DataURL" VALUE="http://www.mycoolsite.com.au/elements.txt">
<PARAM NAME="DataURL" VALUE="file://\\intranet\server\buried\down\a\long\path\elements.txt">

DataURL is the only property required by the TDC to access data. To delay the binding, omit the specification of the DataURL property in the object declaration, and set it later in script code.

The UseHeader property indicates whether the first line of the data file identified by DataURL lists the names of the fields. In the example text file above, the first line was:

Element,Symbol

This isn't part of the data. Instead, it identifies the names of the columns in the data set. Because the default value of this property is FALSE, the UseHeader property must be set to TRUE.

The Tabular Data Control (TDC) determines the codepage for the source data file incorrectly in certain scenarios. The problem can occur if the ambient codepage is Unicode, in which case the TDC assumes that the bound data is also Unicode, which is not necessarily true. When the TDC attempts to identify the Unicode signature in the byte-reversed case, it compares the value incorrectly. If the TDC reads a variable that is uninitialized, it waits for an excessive period of time in an attempt to identify the ambient codepage. If the TDC changes its codepage because it sees a Unicode signature, it fails to update its CharSet property. Therefore, to avoid potential problems associated with incorrect codepage identification, the CharSet property can be set explicitly when declaring the TDC, as shown in the following example.

<OBJECT classid=CLSID:333C7BC4-460F-11D0-BC04-0080C7055A83>
<PARAM NAME="CharSet" VALUE="iso-8859-1" / >
</OBJECT>

Relaxing TDC Security

By default, if the DataURL property specifies a URL on a different domain than that of the Web page, the TDC will silently fail to load the data. This feature prevents unauthorized pages or untrusted scripts from using the TDC to access private data. To allow content providers to create pages that access data on a different domain, providers can insert a domain string in the data. The string begins with "@!allow_domains" and is followed by a semicolon-delimited list of domain names and/or IP addresses. The string must appear exclusively at the beginning of the first line in the data set with no preceding white-space. The exact specification for the format string is as follows:

domain_string: header_string "=" domain_list
   header_string: "@!allow_domains"
   domain_list: domain_spec [; domain_list ]
   domain_spec: * | [*.] domain | ipaddr

Observe that while wildcards may be used in domain names (*.microsoft.com), they are not supported in IP addresses.

The following is an example of a domain string that could be embedded in a data set to enable a page hosted on all microsoft.com and investor.msn.com servers to access the data.

   @!allow_domains=*.microsoft.com; investor.msn.com

A More Advanced Example: Sorting and Filtering

The example behind the following Show Me button demonstrates how you can automate the sorting and filtering of data in a table. Using the chemistry theme, the example displays a table that contains the first five periods of the periodic table. You can sort the data by clicking any of the three table headings (Position, Element, or Symbol); you can filter the data by choosing a specific period and group from the Period or Group list box.

Code example: http://samples.msdn.microsoft.com/workshop/samples/author/databind/eltadv.htm

Sorting data

Dynamic sorting is enabled using the Sort property and the Reset method on the TDC. In the previous example, a VBScript function supports the onclick event for each column heading in the table. When the user clicks a given heading, the corresponding function is called and the Sort property is assigned a value prior to calling the Reset method. The following example shows the function that handles sorting for the Symbol column.

function symbol_onclick()
    elem_list.Sort = "+Symbol"
    elem_list.Reset()
end function

In this example, the Sort property is assigned the name of the third column (Symbol), and then the Reset method is called. The "+" indicates an ascending sort. A "-" prefix indicates a descending sort.

The following excerpt from the HTML source file for this example demonstrates how the column headings were set up using the HTML div element.

<THEAD><TR>
     <TD><DIV ID=position><U><FONT COLOR=BLUE>Position</FONT></U></DIV></TD>
     <TD><DIV ID=element><U><FONT COLOR=BLUE>Element</FONT></U></DIV></TD>
     <TD><DIV ID=symbol><U><FONT COLOR=BLUE>Symbol</FONT></U></DIV></TD>
</TR></THEAD>

Filtering data

Dynamic filtering is enabled using the Filter property and the Reset method of the TDC. In the example, a VBScript function supports the onchange event for each drop-down list box that appears above the table. When this function is invoked, a filter expression is constructed from the selected values in the Period and Group combo boxes, the expression is assigned to the Filter property, and the Reset method is called to synchronize the table displaying the data.

The following excerpt from the HTML source file shows the definition of the Period drop-down list box.

<SELECT ID=cboPeriod>
  <OPTION SELECTED VALUE=0>ALL
  <OPTION VALUE=1>1
  <OPTION VALUE=2>2
  <OPTION VALUE=3>3
  <OPTION VALUE=4>4
  <OPTION VALUE=5>5
</SELECT>

When a user selects a different value from either the Period drop-down or the Group drop-down, the following VBScript function handles the resulting onchange event.

function FilterGroupAndPeriod()
   cFilterExpr = Empty
   if cboPeriod.selectedIndex > 0 then
      cFilterExpr = "Period=" & cboPeriod.selectedIndex
   end if
   if cboGroup.selectedIndex > 0 then
      if Not IsEmpty(cFilterExpr) then
         cFilterExpr = cFilterExpr & " & "
      end if
      cFilterExpr = cFilterExpr & "Group=" & cboGroup.selectedIndex
      elem_list.object.Filter = cFilterExpr
   end if
   elem_list.object.Filter = cFilterExpr
   elem_list.Reset
end function

The code builds a single expression representing a filter on both the Period and the Group columns in the data set. Notice that if the first value (ALL) is selected in either drop-down, the respective code will not contribute to the filter expression. Also, note that if the user has selected both an explicit period and group, the subexpressions are separated by " & ", indicating to the TDC that the records to be displayed must meet both filter criteria. When the user selects "ALL" in both drop-downs, neither of the conditional statements is executed, the filter expression remains empty, and all the data is displayed in the bound table.

The final line in this function invokes the Reset method, which evaluates the filter expression, applies it to the data set, and forces MSHTML to re-render the table in which the data is displayed.

Summary

This article has described the features of the Tabular Data Control, a simple read-only data source object provided with Internet Explorer 4.0 and later. For more detailed information on the methods and properties supported by this object, see the TDC Reference.