Microsoft Tabular Data Control Reference

Microsoft Tabular Data Control Reference


The Microsoft® Tabular Data Control allows an HTML page to display data from delimited text files, either as part of tables or a row at a time. The data can optionally be filtered or sorted by the browser under script control (with no server involvement). If the first line of the text file is a header line that describes the column names and data types, intelligent sorting and filtering will occur. For example, dates and numbers will sort as expected rather than in strict text order (that is, 2 will sort before 10). Extensions in Microsoft® Internet Explorer 4.0 allow you to bind data fields to controls on an HTML form as well as a single table row that will be expanded to show the data in all rows.

This reference describes the object, properties, and method of the Tabular Data Control.

Objects

Object

<OBJECT ID=object
CLASSID = "clsid:333C7BC4-460F-11D0-BC04-0080C7055A83">
[<PARAM NAME=property VALUE=setting>]
</OBJECT>
Object
String identifying the object.
Property
One of the elements in the table below.
Setting
Value for the property.

Property Description
AppendData Specifies whether new data is appended or replaces existing data.
CaseSensitive Indicates whether the TDC distinguishes characters in the data set based upon their case.
CharSet Identifies the character set of the data file.
DataURL Specifies the location of the data file.
EscapeChar Specifies the character used to escape special characters.
FieldDelim Specifies the character used to mark the end of data fields.
Filter Specifies the criteria to use for filtering the data.
Language Specifies the language of the data file, including numerical and date formats.
RowDelim Specifies the character used to mark the end of each row.
Sort Identifies the columns to be sorted, and ascending or descending sort order.
TextQualifier Specifies the optional character that surrounds a field.
UseHeader Specifies whether the first line of the data file contains header information.

Method Description
Reset Causes the control to filter or sort its data based on new settings.

Properties

This section describes the TDC properties.

AppendData

dataobj.AppendData = fValue

Specifies whether new data is appended or replaces existing data.

fValue
Boolean expression that controls how data from DataURL is treated. If FALSE, when new data is read it replaces the existing data set. If TRUE, it is added to the existing data. The default value is FALSE.

When this property is set to its default value of FALSE, whenever DataURL is changed and Reset is called, the Tabular Data Control will clear any data it has stored, fetch a new copy of the data, and display it according to the Filter and Sort properties. When AppendData is TRUE, a data fetch will add the data to the existing data. For example, this could be used with search results so that initial results aren't discarded.

It is assumed that the new data exactly matches the format of the first data fetched. The header line is ignored and the data is added to the existing columns. If values are the incorrect type, they will be stored as string values and will thus sort to the end of the column.

CaseSensitive

dataobj.CaseSensitive = fValue

Indicates whether or not comparisons with the data should ignore case.

fValue
Boolean value. TRUE (default) indicates the data file should be treated case-sensitively. FALSE indicates that upper- and lower-case characters should be treated equally.

CharSet

dataobj.CharSet = sValue

Identifies the character set of the data file.

sValue
String expression that describes the character set used for the data file. If no value is supplied, the input file is interpreted using codepage 1252 (Western Alphabet).

In normal use, the CharSet property is set in the Web page (or is left at its default value) and never referenced again. Although you can set the property when the data has been loaded, this will not change the interpretation of the data. The only exception to this is if the DataURL property is set to a new value that forces all properties to be reevaluated.

The following are the possible values for the CharSet property.
CharSet Value CodePage Description
DIN_66003 20106 IA5 (German)
NS_4551-1 20108 IA5 (Norwegian)
SEN_850200_B 20107 IA5 (Swedish)
_autodetect 50932 Japanese (Auto Select)
_autodetect_kr 50949 Korean (Auto Select)
big5 950 Chinese Traditional (Big5)
csISO2022JP 50221 Japanese (JIS-Allow 1 byte Kana)
euc-kr 51949 Korean (EUC)
gb2312 936 Chinese Simplified (GB2312)
hz-gb-2312 52936 Chinese Simplified (HZ)
ibm852 852 Central European (DOS)
ibm866 866 Cyrillic Alphabet (DOS)
irv 20105 IA5 (IRV)
iso-2022-jp 50220 Japanese (JIS)
iso-2022-jp 50222 Japanese (JIS-Allow 1 byte Kana)
iso-2022-kr 50225 Korean (ISO)
iso-8859-1 1252 Western Alphabet
iso-8859-1 28591 Western Alphabet (ISO)
iso-8859-2 28592 Central European Alphabet (ISO)
iso-8859-3 28593 Latin 3 Alphabet (ISO)
iso-8859-4 28594 Baltic Alphabet (ISO)
iso-8859-5 28595 Cyrillic Alphabet (ISO)
iso-8859-6 28596 Arabic Alphabet (ISO)
iso-8859-7 28597 Greek Alphabet (ISO)
iso-8859-8 28598 Hebrew Alphabet (ISO)
koi8-r 20866 Cyrillic Alphabet (KOI8-R)
ks_c_5601 949 Korean
shift-jis 932 Japanese (Shift-JIS)
unicode 1200 Universal Alphabet
unicodeFEFF 1201 Universal Alphabet (Big-Endian)
utf-7 65000 Universal Alphabet (UTF-7)
utf-8 65001 Universal Alphabet (UTF-8)
windows-1250 1250 Central European Alphabet (Windows)
windows-1251 1251 Cyrillic Alphabet (Windows)
windows-1253 1253 Greek Alphabet (Windows)
windows-1254 1254 Turkish Alphabet
windows-1255 1255 Hebrew Alphabet (Windows)
windows-1256 1256 Arabic Alphabet (Windows)
windows-1257 1257 Baltic Alphabet (Windows)
windows-1258 1258 Vietnamese Alphabet (Windows)
windows-874 874 Thai (Windows)
x-euc 51932 Japanese (EUC)
x-user-defined 50000 User Defined

DataURL

dataobj.DataURL = sValue

Specifies the location of the data file.

sValue
String expression that points to the data file using a standard URL format such as http:, ftp:, or file: (for example, http://www.microsoft.com/dummy/testdata.txt).

Normally the DataURL property is specified in the Web page along with the <OBJECT> tag for the Tabular Data Control. However, if you change this property after the page has been loaded, this will cause the data file to be loaded on the next Reset. The most common use for DataURL is to set AppendData to TRUE and combine multiple different data files. It could also be used to force the data to be read a second time. You could use this to force a refresh during debugging, for example.

See also AppendData, Reset

EscapeChar

dataobj.EscapeChar = cValue

Specifies the character used to escape special characters.

cValue
Single character string that is used to avoid the meaning of the other special characters specified by the FieldDelim, RowDelim, and TextQualifier properties. If set to a zero-length string "" (the default), there is no escape character.

Having an escape character is useful if you have data that contains the same type of characters that you are using to delimit fields or rows. For example, if the TextQualifier property is set to the quotation mark character to surround input fields, but some of the fields themselves contain quotation marks, you could edit the data file to prefix the embedded quotation marks with the escape character. In this scenario, if TextQualifier is set to " (double-quote) and you set the EscapeChar property to \ (backslash), the following data file will be interpreted correctly.

"This is cool"
"This is \"really\" cool"

See also FieldDelim, RowDelim, TextQualifier

FieldDelim

dataobj.FieldDelim = sValue

Specifies the character used to mark the end of data fields.

sValue
String expression that separates one data field from the next. A comma (,) is the default character, but you can set it to any other character. Only a single character can be used to delimit the fields.

Setting nonprintable characters is dependent on the browser language used. In the initial object tag declaration, you can set the FieldDelim property to a tab character as follows:

<PARAM NAME=FieldDelim VALUE="&#09;">

See also EscapeChar, RowDelim, TextQualifier

Filter

dataobj.object.Filter = sValue

Specifies how the data will be filtered.

sValue
String expression containing one or more columns and associated criteria. By default, this is set to the empty string (that is, no filtering occurs and all rows are displayed). An invalid expression will cause all rows to be returned. If there is no header line that names the columns, they are given default names of Column1, Column2, Column3, and so on. The special wildcard character, *, can be used to match any character.

Filter restricts the data displayed to the user. It can be set in the <OBJECT> tag description to cause initial filtering, or the browser script language can set it and it will take effect when the Reset method is called. The data is fetched only once, so this is an efficient way of displaying the same data many different ways.

The following <OBJECT> tag description will cause address book data to be filtered so that only entries with phone numbers will be displayed.

<PARAM NAME=Filter VALUE="PhoneNum <> ''">

You could use the wildcard character to match all phone numbers starting with 9 with:

<PARAM NAME=Filter VALUE="PhoneNum <> '9*'">

A more complex filter could be:

<PARAM NAME=Filter VALUE="(Quantity > 10 & color = 'lime') | 
    Quantity < 5"

This code would find rows with a quantity greater than 10 that are lime colored combined with all rows that have a quantity less than five.

The exact syntax support by filter is defined below. In essence, any arbitrary expression using the usual relational operators is allowed, including comparisons between fields. AND (&) and OR (|) operators have equal precedence and thus must be surrounded by parenthesis if combined.

Complex ::== Simple
 ::== Simple '&' Simple [ '&' Simple ... ]
 ::== Simple '|' Simple [ '|' Simple ... ]

Simple ::== '(' Complex ')'
 ::== Atom Relop Atom

Relop ::== '=' | '>' | '>=' | '<' | '<=' | '<>'

Atom ::== Characters up to a (, ), >, <, =, & or |

If an atom is recognizable as a field name, it is treated as a field name. Otherwise, it's treated as a value. Quotes (") are processed and force the atom to be treated as a value. Escape characters (\) are processed and allow the use of special characters within a field name. It is illegal to attempt a comparison of two columns with different types.

The definition of 'Complex' expressly forbids mixing logical ANDs and ORs (& and |) unless parentheses are used to clarify the query. The following is illegal:

field1 > 10 & field3 = "lime" | field4 < 5

But the following is allowed:

(field1 > 10 & field3 = "lime") | field4 < 5

See also Reset, Sort, UseHeader

Language

dataobj.object.Language = sValue

Specifies the language of the data file, including numerical and data formats.

Note The object property is specified to avoid a conflict with the language extender property which is exposed on all elements.

sValue
String expression that describes the language of the data file using the HTML standard codes (as defined by ISO 369). The default value is eng-us. Set this appropriately to ensure the correct handling of decimal separator characters in floating-point data and default data interpretation.

See also CharSet

RowDelim

dataobj.RowDelim = sValue

Specifies the character used to mark the end of each row.

sValue
String expression that separates one data field from the next. The default value is "newline", but it can be set to any other character. Only a single character may be used to delimit a row.

Special interpretation is done for end-of-line or newline characters, which should provide correct parsing in most circumstances.

See also EscapeChar, FieldDelim, TextQualifier

Sort

dataobj.Sort = sValue

Identifies the columns to be sorted, and ascending or descending sort order.

sValue
String expression that is the name of one or more comma-separated names of columns in the text file. Each name can be optionally prefixed with a minus sign (-) to indicate a descending sort. By default this property is set to the empty string. If there is no header line that names the columns, they are given default names of Column1, Column2, Column3, and so on. If Sort is set to an empty string (""), no data will be sorted.
Data types are sorted as follows:
Data type Ascending Descending
Text "a", "b", "c" ... "z" "z", "y", "x" ... "a"
Numeric ... -1, 0, 1, ... ...1, 0, -1...
Date 1/1/1950, 1/1/1990, 1/1/2000 1/1/2000, 1/1/1990, 1/1/1950
Logical False, False, ... , True, True True, True, ..., False, False

Sort sorts the data displayed to the users. It can be set in the initial <OBJECT> tag description to cause initial sorting, or the browser script language can set it and sorting will take effect when the Reset method is called.

Text data is sorted case-insensitively.

The following example shows how you could sort a food list into ascending order by name and decreasing price.

dataobj.Sort = "FoodItem; -Price"

All invalid data always sorts higher than valid data. For example, a string in an ascending numeric column will display at the end. Multiple invalid data rows are grouped together but not sorted into a defined order within the group.

See also Filter, Reset

TextQualifier

dataobj.TextQualifier = cValue

Specifies the optional character that surrounds a field.

cValue
Single character string used to surround fields that can include special characters such as newlines, tabs, or commas. These characters can also be active as field or row delimiters. The default value is the double quote character (").

Comma-delimited text files and similar text data files usually surround text fields in those files with quotes. For example, a simple phone book text file could be arranged like the following:

Fred Nurks, "42 Worldwide Way, Woy Woy", 555-1212
Brianne Hardy, "Apt 3, 14 Hopalong Crescent, Wogga", 555-2121

Normally the commas in the address text would cause the fields to be read incorrectly, but the surrounding double-quote characters avoid that.

Another common use for TextQualifier is when one of the data fields contains HTML text with lots of separate paragraphs (also known as newline characters).

See also EscapeChar, FieldDelim, RowDelim

UseHeader

dataobj.UseHeader = fValue

Specifies whether the first line of the data file contains header information.

fValue
Boolean expression that indicates that the data file contains an initial line that names each column and optionally specifies its data type.

If fValue is TRUE, the first line of the data file should match the following layout:

fieldname:type, fieldname:type, ...

Note that the above assumes the default field and row delimiters (comma and newline, respectively).

Fieldname can be an arbitrary text string, although it is best to avoid spaces and other punctuation characters.

Type can be one of the following types of values:
String Textual data (default)
Date Calendar dates (see below for formatting)
Boolean Logical data (Yes/No, True/False, 0/not 0)
Int Integral numbers (-3, 1, 5)
Float Floating point numbers (3.141, 2.77, 0)

Date can be optionally followed by a space and then the letters D, M, and Y in any order. These correspond to Day, Month, and Year and control the interpretation of the dates in the data file. The date data is treated as three numbers separated by characters, so the actual separation character is not important.

Boolean will interpret the following data:
True values: Yes, True, 1, -1, any nonzero number
False values: No, False, 0 (zero)

The decimal separator used by float data is determined by the Language property.

The following sample data file shows how the various data types can be declared when UseHeader is set to TRUE and the default settings for FieldDelim, RowDelim, and Language are used.

FoodItem,Price:Float,Purchased:Date YMD,OnOrder:Boolean,Quantity:Int
Bread,1.57,97/5/12,Yes,30
Cheese,3.52,96/2/2,No,5
Old Wine,183.99,1905-1-1,No,1

See also DataURL, Language, Reset

Methods

This section describes the Reset method.

Reset

dataobj.Reset

Causes the control to filter or sort its data based on new settings.

When Reset is called, all the data is filtered and sorted according to the settings of the filter and sort properties. A typical use of the Reset method would be to specify a new Sort or Filter in script in response to a user action.

Data will only be fetched again if either DataURL has been changed or if the data has changed since the last Reset. Note that setting DataURL to itself is viewed as a change, so you can force a refetch of the data from script with the following:

dataobj.DataURL = Dataobj.DataURL
dataobj.Reset

After the Reset method is invoked, the browser will redisplay the data if necessary.

See also Filter, Sort

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.