CDF Reference for Active Channels

CDF Reference for Active Channels


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.

arrowr.gifCDF Syntax

arrowr.gifCDF Elements

CDF Syntax

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>

CDF Parsing Rules and Hints

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.
Character Encoded value
< &lt;
> &gt;
' &apos;
" &quot;
& &amp;

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 &#038.
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 (-->).

CDF Elements

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

<?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.

ENCODING="char-set"
Specifies the character set used in the document. The default is "UTF-8". Additional information on character encoding and character sets is available in the CDF Parsing Rules and Hints section.
VERSION="n.n"
Specifies the major and minor version of XML the CDF file supports. If not specified, the default value is "1.0".

Number of allowed occurrences: One
Parent elements Child elements
None None

Example:

<?XML ENCODING="UTF-8" VERSION="1.0"?>

A

<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.

HREF="url"
Required. Specifies the URL associated with the parent element. The browser navigates to this location when the parent element is clicked.

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

<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.

XML-SPACE="DEFAULT" | "PRESERVE"
Specifies how white space, such as tabs, spaces, and blank lines, should be handled. The default behavior (XML-SPACE="DEFAULT") indicates that white space characters are not considered significant, and therefore some of these characters may be filtered out during file processing. Set the value of this attribute to "PRESERVE" to ensure that all white space characters are retained. This attribute can be used with any CDF element that uses significant white space. When used as an attribute of a parent element, the XML-SPACE value applies to all child elements unless specifically overridden with another XML-SPACE attribute.

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

<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.

BASE="url"
Specifies the base URL for the channel. This is used to resolve relative URLs specified in ITEM and CHANNEL elements contained within this channel. The BASE value applies to all child elements of the current channel or subchannel. This attribute supersedes the BASE value previously defined by a parent CHANNEL element, if any exist. The URL specified must end with a trailing "/", or the last word will be removed.
HREF="url"
Specifies the URL associated with the channel. The browser navigates to this location when the user activates the channel. The HREF attribute should be omitted if the CHANNEL element contains an anchor (A) as a child element.
LASTMOD="date"
Specifies the last date/time in GMT that the page indexed by the HREF attribute was modified. GMT is Greenwich Mean Time, also known as Universal Time Coordinated (UTC). Note that the LASTMOD date/time is not necessarily your local time. This attribute allows the channel client to determine whether the content has changed since the last time it was downloaded. The item is downloaded only if the date associated with the cached item is older than the LASTMOD value in the CDF file. Additional information on optimizing channels is available in the Creating Active Channels documentation. The date format used in the LASTMOD attribute is specified in the form yyyy-mm-ddThh:mm, where:
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).
LEVEL="n"
Specifies the number of levels (or links) deep the client should "site crawl" and precache the HTML content from the URL specified in the HREF attribute. The default is zero, which specifies to only precache the URL of the CHANNEL, along with any images it uses. If the URL contains frames, the client will also retrieve all content inside the frames. By default, the maximum number of levels that can be specified for site crawling is three.
PRECACHE="YES" | "NO"
Specifies whether content should be downloaded and cached on the client computer. If PRECACHE is omitted or set to "YES", content is downloaded only if the user of Internet Explorer has specified that channel content should be downloaded. If PRECACHE is set to "NO", content is not downloaded and the LEVEL attribute is ignored.

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:

  1. The HREF= attribute of the CHANNEL element.
    <CHANNEL HREF="http://...">
  2. The HREF of the anchor (A) element that is the immediate child of the CHANNEL element.
    <CHANNEL>
    	<A HREF="http://...">My Channel</A>
    
  3. The optional InfoURI=url attribute of the CHANNEL element. This attribute is available for compatibility with other CDF parsers.
    <CHANNEL INFOURI="http://...">

The end tag </CHANNEL> is required.

EARLIESTTIME

<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.

DAY="n"
Specifies the first day within the INTERVALTIME that the schedule can be updated.
HOUR="n"
Specifies the first hour within the INTERVALTIME that the schedule can be updated.
MIN="n"
Specifies the first minute within the INTERVALTIME that the schedule can be updated.

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

<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.

NAME="headerparam"
Required. Specifies the name of the HTTP header parameter sent with the log file, such as "Encoding-Type."
VALUE="text"
Required. Specifies the value of the corresponding parameter.

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

<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.

DAY="n"
Specifies the number of days over which the schedule will repeat.
HOUR="n"
Specifies the number of hours over which the schedule will repeat.
MIN="n"
Specifies the number of minutes over which the schedule will repeat.

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

<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."

HREF="url"
Required. Specifies the URL that represents the channel. The browser navigates to this location when the user activates the channel. There must be exactly one HREF attribute with the ITEM element. The HREF attribute should be omitted if the ITEM element contains an anchor (A) as a child element.
LASTMOD="date"
Specifies the last date/time in GMT that the page indexed by the HREF attribute was modified. GMT is Greenwich Mean Time, also known as Universal Time Coordinated (UTC). Note that the LASTMOD date/time is not necessarily your local time. This allows the channel client to determine whether the content has changed since the last time it was downloaded. The item is downloaded only if the date associated with the cached item is older than the LASTMOD value in the CDF file. Additional information on optimizing channels is available in the Creating Active Channels documentation. The date format used in the LASTMOD attribute is specified in the form yyyy-mm-ddThh:mm, where:
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).
LEVEL="n"
Specifies the number of levels (or links) deep the client should site crawl and precache the HTML content from the URL specified in the HREF attribute. The default is zero, which specifies to precache only the URL of the item and the images it references. If the URL contains frames, the client also retrieves all content inside the frames.
PRECACHE="YES" | "NO"
Specifies whether content should be downloaded and cached on the client computer. If PRECACHE is omitted or set to "YES", content is downloaded only if the user of Internet Explorer has specified that channel content should be downloaded. If PRECACHE is set to "NO", content is not downloaded and the LEVEL attribute is ignored.

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

<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.

DAY="n"
Specifies the latest number of days to which the schedule will be applied.
HOUR="n"
Specifies the latest number of hours to which the schedule will be applied.
MIN="n"
Specifies the latest number of minutes to which the schedule will be applied.

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

<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.

VALUE="document:view"
Required. Specifies the event to be logged. Currently, "document:view" is the only value supported by Internet Explorer.

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

<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

<LOGO
HREF="url"
STYLE="ICON" | "IMAGE" | "IMAGE-WIDE"
/>

Specifies an image that can be used to represent a channel or channel item.

HREF="url"
Required. Specifies the URL associated with the channel logo or icon image.
STYLE="ICON" | "IMAGE" | "IMAGE-WIDE"
Specifies a text string indicating the context in which a logo will be used, as follows:
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

<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.

HREF="url"
Required. Specifies the URL of where the log should be sent.
METHOD="POST"
Required. Specifies the HTTP method to be used for sending the data.
SCOPE="ALL" | "OFFLINE" | "ONLINE"
Specifies which type of page hits should be logged. Page hits can be logged for offline (read from local cache) or online (read from URL) browsing. The default for this attribute is "ALL", which logs both types of hits.

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

<PURGETIME
HOUR="n"
/>

When the log file is being uploaded, any page hits older than PURGETIME will not be reported.

HOUR="n"
Specifies the number of hours for which the logging information is considered valid.

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

<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.

ENDDATE="date"
Specifies the day on which the schedule stops updating (expires). If this attribute is omitted, the schedule will not expire. The date for this attribute is specified in the following form: yyyy-mm-dd.
yyyy Specifies the year.
mm Specifies the month (01-12).
dd Specifies the day of the month (01-31).
STARTDATE="date"
Specifies the day on which the schedule will start to apply. If this attribute is omitted, the schedule will start to apply on the current day. The date for this attribute is specified in the following form: yyyy-mm-dd.
yyyy Specifies the year.
mm Specifies the month (01-12).
dd Specifies the day of the month (01-31).
TIMEZONE="offset"
Specifies the difference between local time and Universal Time Coordinated (UTC). This allows channel publishers to specify an absolute time for an update schedule. The offset specified for this attribute adjusts the EARLIESTTIME and LATESTTIME child elements accordingly. The date for this attribute is specified in the following form: szzzz.
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

<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.

XML-SPACE="DEFAULT" | "PRESERVE"
Specifies how white space, such as tabs, spaces, and blank lines, should be handled. The default behavior (XML-SPACE="DEFAULT") indicates that white space characters are not considered significant, and therefore some of these characters may be filtered out during file processing. Set the value of this attribute to "PRESERVE" to ensure that all white space characters are retained. This attribute can be used with any CDF element that uses significant white space. When used as an attribute of a parent element, the XML-SPACE value applies to all child elements unless specifically overridden with another XML-SPACE attribute.

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

<USAGE
VALUE="Channel" | "Email" | "DesktopComponent" | "NONE" | "ScreenSaver" | "SoftwareUpdate"
>

Indicates how an ITEM element should be used.

VALUE="Channel" | "Email" | "DesktopComponent" | "NONE" | "ScreenSaver" | "SoftwareUpdate"
Required. Specifies a special usage of the parent element.
"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.