
The following section describes the suggested revision to Channel Definition Format (CDF) that Microsoft and other partners are presenting to the W3C (World Wide Web Consortium). For reference purposes, this revision is CDF version 0.4. CDF is an application of the Extensible Markup Language (XML). The original submission of CDF to the W3C can be found at http://www.w3.org.
Note that the syntax might vary for different elements. The following table describes the possible formats in which the tags might appear.
| Description | Example |
| Empty element with attributes | <ELEMENT ATTR1="value" ATTR2="value"/> |
| Element with content and end tag | <ELEMENT>Element Content Here</ELEMENT> |
| Parent element with attributes and child elements | <PARENT ATTR1="value"> <CHILD1> Content </CHILD1> <CHILD2 ATTR1="value"/> </PARENT> |
To avoid some common mistakes, keep the following rules in mind when creating a CDF file.
| Special Characters | When placing text content between an element start and end tag, you must encode the following characters to prevent CDF parsing errors.
For a complete list of other named character set entities, refer to the documentation on HTML Character Sets (Charsets) and Named Entities. | ||||||||||||
| Character Encoding | The CDF file supports encoding for any ASCII character with the format &#nnn. For example, the ampersand character could also be encoded with its ASCII decimal value of 38 by using the string &. | ||||||||||||
| Attribute Syntax | All attribute values must be enclosed in quotation marks, even if the value is a number. | ||||||||||||
| Comments | Any text you want to be ignored by the CDF parser should be placed between the comment start tag (<!--) and the comment end tag (-->). |
This section describes the elements and associated attributes used to create Channel Definition Format (CDF) files for Active Channels. Some CDF files may be used for other types of Webcasting, such as Active Desktop items and Software Distribution Channels, depending on the value of the USAGE element.
| ?XML | A | ABSTRACT | CHANNEL |
| EARLIESTTIME | HTTP-EQUIV | INTERVALTIME | ITEM |
| LATESTTIME | LOG | LOGIN | LOGO |
| LOGTARGET | PURGETIME | SCHEDULE | TITLE |
| USAGE |
<?XML
ENCODING="char-set"
VERSION="n.n"
?>
Indicates an XML document and specifies the version and character set for the current document. This tag should occur only once at the beginning of the CDF file.
Number of allowed occurrences: One
| Parent elements | Child elements |
| None | None |
Example:
<?XML ENCODING="UTF-8" VERSION="1.0"?>
<A
HREF="url"
>
Defines a hypertext link for an element. The URL specified in the HREF= attribute will be displayed in the browser channel pane if the TITLE element is not present.
Number of allowed occurrences: None or one (per parent element)
| Parent elements | Child elements |
| CHANNEL | None |
| ITEM |
The HREF= attribute of the parent element must be omitted when using the A element. To a CDF client, including the A element is functionally equivalent to using the HREF= attribute with the parent element and omitting the A element.
The end tag </A> is required.
Example:
<ITEM>
<A HREF="http://www.foosports.com/page1.htm">This is a link to page 1.</A>
</ITEM>
<ABSTRACT
XML-SPACE="DEFAULT" | "PRESERVE"
>
Represents a description of the associated CHANNEL or ITEM parent element. Microsoft® Internet Explorer displays this text in a tooltip to the right of the icon in the browser channel pane when the cursor is paused over the channel or item title.
When applied to the top-level CHANNEL element, the abstract should appear near the top of the CDF file before any ITEM or nested CHANNEL elements.
Number of allowed occurrences: None or one
| Parent elements | Child elements |
| CHANNEL | None |
| ITEM | |
| SOFTPKG |
The ABSTRACT element can optionally be used as an attribute with the CHANNEL and ITEM elements to support previous implementations of CDF. Any new CDF files should use ABSTRACT as a child element.
The end tag </ABSTRACT> is required.
Example:
<ABSTRACT>This article describes how to create a CDF file.</ABSTRACT>
<CHANNEL
BASE="url"
HREF="url"
LASTMOD="date"
LEVEL="n"
PRECACHE="YES" | "NO"
>
Defines a channel or subchannel. The channel is defined by the first occurrence of the CHANNEL element and the corresponding </CHANNEL> end tag. All CHANNEL elements contained within the top-level channel represent subchannel folders that are used to create a hierarchy of channel items.
| yyyy | Specifies the year. |
| mm | Specifies the month (01-12). |
| dd | Specifies the day of the month (01-31). |
| hh | Specifies the hour of the day (00-23). |
| mm | Specifies the minutes (00-59). |
Number of allowed occurrences: Any number
| Parent elements | Child elements |
| None | ABSTRACT |
| CHANNEL | |
| ITEM | |
| LOG | |
| LOGIN | |
| LOGO | |
| LOGTARGET | |
| SCHEDULE | |
| SOFTPKG | |
| TITLE |
An optional SELF= attribute can be added in the top-level CHANNEL to indicate the location of the CDF file to use for creating a channel subscription. Note that this attribute is unnecessary and is only supported for backward compatibility.
If more than one mechanism is used to specify a URL for a channel, Internet Explorer will look for URLs in this order of precedence:
<CHANNEL HREF="http://...">
<CHANNEL> <A HREF="http://...">My Channel</A>
<CHANNEL INFOURI="http://...">
The end tag </CHANNEL> is required.
<EARLIESTTIME
DAY="n"
HOUR="n"
MIN="n"
/>
Specifies the beginning of the valid range of time that the update to the CDF can occur. By default, if this value is not specified, the earliest time is set to the beginning of the INTERVALTIME value. The days, hours, and minutes are totaled to determine the offset value from the start of the INTERVALTIME. Additional information on scheduled updates is available in the Creating Active Channels documentation.
Number of allowed occurrences: None or one
| Parent elements | Child elements |
| SCHEDULE | None |
Client applications can round the specified value to the nearest value that they consider significant.
<HTTP-EQUIV
NAME="headerparam"
VALUE="text"
/>
Supplies information that can also be provided through HTTP response headers. In the context of sending files over the HTTP protocol through the LOGTARGET element, it indicates that an HTTP header parameter based on the information in this tag should be added.
Number of allowed occurrences: Any number
| Parent elements | Child elements |
| LOGTARGET | None |
The following example shows how to send a compressed log file back to the server:
Example:
<LOGTARGET HREF="http://www.mysite.com/logging/" METHOD="POST"> <HTTP-EQUIV NAME="encoding-type" VALUE="gzip" /> </LOGTARGET>
<INTERVALTIME
DAY="n"
HOUR="n"
MIN="n"
/>
Indicates the interval of time over which the schedule should repeat. The days, hours, and minutes are totaled to determine the length of the repeating range. Additional information on scheduled updates is available in the Creating Active Channels documentation.
Number of allowed occurrences: None or one
| Parent elements | Child elements |
| SCHEDULE | None |
The time quantity specified by this element will be rounded up to a fraction of a day (fourth, third, half, and so on) or rounded to the nearest multiple of a day. For example, 1-, 2-, 3-, and 4-hour increments will be used by Internet Explorer without rounding, but 5 hours will be rounded to 6 hours (a fourth of a day). An INTERVALTIME with a value greater than a half day but less than a day will be rounded up to a day. This element is a required child element of SCHEDULE, and it must contain a nonzero value to be considered valid. The following example shows a schedule that will update the channel every day during the month of December (1997) sometime between 10 A.M. and 2 P.M..
Example:
<SCHEDULE STARTDATE="1997-12-01" ENDDATE="1997-12-31"> <INTERVALTIME DAY="1" /> <EARLIESTTIME HOUR="10" /> <LATESTTIME HOUR="14" /> </SCHEDULE>
<ITEM
HREF="url"
LASTMOD="date"
LEVEL="n"
PRECACHE="YES" | "NO"
>
Defines an item in a channel. An item is a unit of information that usually corresponds to a Web page. In an Active Channel, items will appear in the hierarchy exposed in the Channels Explorer Bar. To prevent an item from showing up in the Channels Explorer Bar, the USAGE element should be included as a child element of the ITEM with the VALUE attribute set to "None."
| yyyy | Specifies the year. |
| mm | Specifies the month (01-12). |
| dd | Specifies the day of the month (01-31). |
| hh | Specifies the hour of the day (00-23). |
| mm | Specifies the minutes (00-59). |
Number of allowed occurrences: Any number
| Parent elements | Child elements |
| CHANNEL | ABSTRACT |
| LOG | |
| LOGO | |
| TITLE | |
| USAGE |
The end tag </ITEM> is required.
Example:
<ITEM HREF="http://www.foosports.com/intro.htm" LASTMOD="1997-09-11T10:30">
<TITLE>Welcome to FooSports!</TITLE>
<ABSTRACT>FooSports articles, news, and promotional offers</ABSTRACT>
</ITEM>
<LATESTTIME
DAY="n"
HOUR="n"
MIN="n"
/>
Specifies the latest time during the INTERVALTIME that the schedule will be applied and updated. The days, hours, and minutes are totaled to determine the offset value from the INTERVALTIME that represents the latest valid time for updating a channel. If omitted, the latest time is set to the beginning of INTERVALTIME. Additional information on scheduled updates is available in the Creating Active Channels documentation.
Number of allowed occurrences: None or one
| Parent elements | Child elements |
| SCHEDULE | None |
Client applications can round the specified value to the nearest value that they consider significant.
<LOG
VALUE="document:view"
/>
Specifies that the URL of the parent ITEM element should be recorded in a page-hit log file. Additional information on page-hit logging is available in the Creating Active Channels documentation.
Number of allowed occurrences: Any number
| Parent elements | Child elements |
| ITEM | None |
An ITEM can be logged only if the path of the ITEM's HREF attribute falls under the path of the CDF file's URL or the path of the LOGTARGET's HREF. Note that this element is also valid for a CDF file being used as an Active Desktop item (<USAGE VALUE="DesktopComponent"></USAGE>).
There is no end tag associated with this element.
Example:
<ITEM HREF="http://www.foosports.com/promotion.htm">
<LOG VALUE="document:view"/>
</ITEM>
<LOGIN/>
Specifies that the channel requires authentication for updates. A CDF file containing this element will prompt the user for a name and password during the channel subscription process.
Number of allowed occurrences: None or one (top-level channel only)
| Parent elements | Child elements |
| CHANNEL | None |
There is no end tag associated with this element.
Example:
<LOGIN />
<LOGO
HREF="url"
STYLE="ICON" | "IMAGE" | "IMAGE-WIDE"
/>
Specifies an image that can be used to represent a channel or channel item.
| Value | Image Size | Display Description |
| "ICON" | 16H x 16W | This image appears in the Channels Explorer Bar hierarchy and other areas of the Microsoft® Windows® namespace, like when viewing the contents of a folder containing the CDF. |
| "IMAGE" | 32H x 80W | This logo image is placed in the desktop Channel Bar to provide a quick launching mechanism for the main channel page. |
| "IMAGE-WIDE" | 32H x 194W | Wide logos are displayed in the Channels Explorer Bar to provide a link to the main channel page. When clicked, this image will also expand or contract the channel's hierarchy (if one exists) in the Channels Explorer Bar. |
Number of allowed occurrences: None or one (per STYLE attribute)
Note GIF, JPEG, and other standard image formats supported by Internet Explorer can be used for logo images. However, animated GIF files are not supported with this element. Image formats and styles are subject to change.
| Parent elements | Child elements |
| CHANNEL | None |
| ITEM | |
| SOFTPKG |
There is no end tag associated with this element.
Example:
<LOGO HREF="http://www.foosports.com/images/logo.gif" STYLE="IMAGE"/>
<LOGTARGET
HREF="url"
METHOD="POST"
SCOPE="ALL" | "OFFLINE" | "ONLINE"
>
Specifies where to send a CDF client page-hit log file. This element must occur before any ITEM elements in the CDF file. For details about the type of information gathered, see the Page-Hit Logging section.
Number of allowed occurrences: None or one (top-level channel only)
| Parent elements | Child elements |
| CHANNEL | HTTP-EQUIV |
| PURGETIME |
The end tag </LOGTARGET> is required.
Example:
<LOGTARGET HREF="http://www.foosports.com/logging" Method="POST" SCOPE="OFFLINE">
<PURGETIME HOUR="12"/>
<HTTP-EQUIV NAME="ENCODING-TYPE" VALUE="gzip"/>
</LOGTARGET>
<PURGETIME
HOUR="n"
/>
When the log file is being uploaded, any page hits older than PURGETIME will not be reported.
Number of allowed occurrences: None or one
| Parent elements | Child elements |
| LOGTARGET | None |
There is no end tag associated with this element.
The log file (filename.log) is stored in the user's local cache in the %userprofile%\history\log folder. This file is cleared after it is successfully posted to the HTTP server during the CDF update.
<SCHEDULE
ENDDATE="date"
STARTDATE="date"
TIMEZONE="offset"
>
Defines the schedule used for channel updating. Starting at midnight on STARTDATE, channel updating occurs once within each consecutive time interval specified by the INTERVALTIME child element. The EARLIESTTIME and LATESTTIME child elements specify offsets that define the valid range of time within each interval that channel updates can occur.
The schedule must be placed directly under the top-level channel element, and it must contain a nonzero INTERVALTIME value to be considered valid. This schedule is relative to the time zone in TIMEZONE, if present; otherwise the schedule is relative to the local time of the user. This schedule only applies to the channel if the user accepts the default "publisher's recommended schedule" when subscribing to the channel. Additional information on scheduled updates is available in the Creating Active Channels documentation.
This element should appear near the top of the CDF file, after the top-level CHANNEL element and before any ITEM or nested CHANNEL elements.
| yyyy | Specifies the year. |
| mm | Specifies the month (01-12). |
| dd | Specifies the day of the month (01-31). |
| yyyy | Specifies the year. |
| mm | Specifies the month (01-12). |
| dd | Specifies the day of the month (01-31). |
| s | Specifies the relationship of the local time to UTC. A minus (-) or plus (+) sign is used to indicate whether the local time is earlier or later than UTC. |
| zzzz | Specifies the offset from UTC in hours and minutes. |
Number of allowed occurrences: None or one (top-level channel only)
| Parent elements | Child elements |
| CHANNEL | EARLIESTTIME |
| ITEM | INTERVALTIME |
| LATESTTIME |
The end tag </SCHEDULE> is required.
For example, to specify the U.S. Eastern Standard Time (EST), which is 5 hours earlier than UTC, use: TIMEZONE="-0500".
The following example shows a schedule that takes effect immediately and updates the channel once per day, sometime between noon and 6 P.M.. The channel will stop receiving updates on December 1, 1997.
Example:
<SCHEDULE ENDDATE="1997-12-01">
<INTERVALTIME DAY="1"/>
<EARLIESTTIME HOUR="12"/>
<LATESTTIME HOUR="18"/>
</SCHEDULE>
<TITLE
XML-SPACE="DEFAULT" | "PRESERVE"
>
Specifies a text string representing the title of the CHANNEL or ITEM element. Internet Explorer displays this title to the right of the item's icon in the Channels Explorer Bar. A TITLE element that is the direct child of the top-level channel element appears in place of the channel logo in the Channels Explorer Bar when another channel is selected by the user.
When applied to the top-level CHANNEL element, the title should appear near the top of the CDF file before any ITEM or nested CHANNEL elements.
Number of allowed occurrences: None or one
| Parent elements | Child elements |
| CHANNEL | None |
| ITEM | |
| SOFTPKG |
The TITLE element can optionally be used as an attribute with the CHANNEL and ITEM elements to support previous implementations of CDF. Any new CDF files should use TITLE as a child element.
The end tag </TITLE> is required.
Example:
<TITLE>CDF Reference</TITLE>
<USAGE
VALUE="Channel" | "Email" | "DesktopComponent" | "NONE" | "ScreenSaver" | "SoftwareUpdate"
>
Indicates how an ITEM element should be used.
| "Channel" | These items appear in the browser channel pane. This is the default behavior when no USAGE element appears under an ITEM. |
| "Email" | This one item is e-mailed when the channel content is updated (one per CDF). |
| "NONE" | If a "NONE" value is used as the only USAGE element in an ITEM, the item will not appear in the Channels Explorer Bar. |
| "DesktopComponent" | These items are displayed in a frame located on the Active Desktop. A CDF with this usage value can only be used in the context of an Active Desktop item. An Active Channel would require a separate CDF file. |
| "ScreenSaver" | This one item is displayed in the special Internet Explorer screen saver (one per CDF). |
| "SoftwareUpdate" | This indicates the CDF file is being used for a Software Distribution Channel to automatically update software over the Web. In addition to a CDF file with this usage value, an Open Software Description (OSD) file is also required for Software Distribution Channels. |
Number of allowed occurrences: Any number
| Parent elements | Child elements |
| ITEM | None |
| SOFTPKG |
For information on additional CDF elements supported for "DesktopComponent" usage, consult the CDF Extensions for Active Desktop Items.
For information on additional CDF elements supported for "SoftwareUpdate" usage, consult the CDF Extensions for Software Distribution Channels.
Some older implementations of CDF clients look for a SHOW attribute instead of the USAGE child element inside the ITEM element. An attribute of SHOW="string" in an ITEM element is functionally equivalent to adding a child element of <USAGE VALUE="string"></USAGE> to an ITEM element.
The end tag </USAGE> is required. The content of the element is optional and varies according to the VALUE attribute.
Example:
<ITEM HREF="http://www.foosports.com/screensaver.htm">
<USAGE VALUE="ScreenSaver"></USAGE>
</ITEM>
Note "SmartScreen," a trademark of PointCast Inc., can be used in place of "ScreenSaver".
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.