Introduction

A digital dashboard is a customized portal for knowledge workers that consolidates personal, team, corporate, and external information and provides single-click access to collaborative tools. With the introduction of the Digital Dashboard Resource Kit 2.0, Microsoft is enabling customers and partners to develop a new generation of customizable digital dashboards based on Internet standards.

Across an enterprise, different groups of users need access to distinctly different types of information. The executives in a company may need a high-level view of up-to-date sales statistics in addition to industry news and competitive intelligence, while the sales team in the same company may need detailed customer, product, and sales information. With its flexible, modular architecture, a digital dashboard makes it easy for you to create personalized applications that meet the needs of users throughout your organization.

Introducing Web Parts

At the heart of the customization capabilities of the digital dashboard are Web Parts. Web Parts are reusable components that wrap Web-based content such as XML, HTML, and scripts with a standard property schema that controls how the Web Parts are rendered in a digital dashboard. The Web Part schema offers you multiple ways of supplying content to your Web Parts. You can embed content in the Web Part itself, add a pointer to a location on the Internet or your local intranet, stream content from your Internet server, or add pointers to XML documents and XSL files. Because all Web Parts adhere to a common standard, you can create Web Part libraries that you can draw from to assemble all digital dashboards in your organization, and system administrators can manage and distribute Web Parts using these libraries.

You do not need to learn new skills to create Web Parts. You can easily create simple Web Parts using tools included in the Digital Dashboard Resource Kit 2.0 and more complex Web Parts using a Visual InterDev® add-in provided with the Digital Dashboard Resource Kit.

Digital Dashboard Services Component

The Digital Dashboard Services Component is a client-side component that is included in every dashboard page as a hidden object. This component makes Web Parts truly reusable and easier to build by providing a standard infrastructure for the following services:

· Part discovery—allows Web Parts to discover other Web Parts on a dashboard.

· Notification—allows Web Parts to respond to external events that occur at the dashboard or Web Part level.

· Session state management—allows Web Parts to interchange information and objects within a browser session.

· State management—allows dashboards and Web Parts to maintain global state and to persist this state between activations.

· Item retrieval—allows Web Parts to retrieve and maintain the state of items in the store module.

For more information about the Digital Dashboard Services Component, see the Digital Dashboard Services Component reference document, which is included in the Digital Dashboard Resource Kit.

Digital Dashboard Terminology

This section lists terms that are used throughout the documentation in the Digital Dashboard Resource Kit 2.0. To use the resource kit fully, you should read this section before continuing.

Digital dashboard: The rendering of a set of Web Parts in an HTML page. For more information about the Dashboard schema, see the Dashboard Schema Reference in the Digital Dashboard Resource Kit.

Web Part: reusable components that wrap Web-based content such as XML, HTML, and scripts with a standard property schema that controls how the Web Parts are rendered in a digital dashboard.

Dashboard factory: A code engine (an ASP) that assembles Web Parts into a view layout suitable for rendering in a dashboard.

Digital dashboard application: A digital dashboard plus all support pieces, customization pages, and custom Web Part forms.

Web Part Schema

The Digital Dashboard Resource Kit features a comprehensive, easy-to-use schema for Web Parts that dashboard factories interpret in a consistent fashion. Web Parts that you define using this schema belong to the content class, " urn:schemas-microsoft-com:office:Webpart:". The schema works with Exchange 2000 Server, SQL Server™, and the Windows 2000 file system. You can attach additional property values to a given Web Part, but the default dashboard factory engine will not reference these properties and they are not part of the base content class.

Schema Properties

Schema properties specify how a Web Part looks, the location from which it obtains content, how it runs, whether the user can customize its properties, and so on. For additional information about schema properties, see the Web Part Schema Reference.

The following tables list the properties that the Web Part schema defines and describe the purpose of each property. Unless otherwise noted, all property names belong to the namespace " urn:schemas-microsoft-com:office:Webpart:". The User Specific column in each table indicates whether a given property is user specific. Properties that are not user specific are metadata properties stored on the server. Dashboards can store user-specific property values for each user, so different users can have different values for these properties. For more information about how dashboards store user-specific property values, see “Customizable Web Parts” later in this paper.

Basic Properties

The properties in the following table define basic metadata for a Web Part.

Property Name	User Specific	Description
Description	No	Description of the Web Part
LastModified	Yes	Date and time the Web Part was last modified (in Greenwich mean time)
Title	Yes	Title of the Web Part
Namespace	No	Namespace for the Web Part

Appearance Properties

The properties in the following table control how a Web Part appears on a dashboard.

Property Name	User Specific	Description
AllowMinimize	No	Indicates whether the user can minimize the Web Part
AllowRemove	No	Indicates whether a user can remove the Web Part from the dashboard
DetailLink	No	URL to a detail page for the Web Part, which is often a full-page user interface for the Web Part.
FrameState	Yes	Indicates the frame state of a Web Part (normal or minimized).
HasFrame	No	Set this property to TRUE if you want the Web Part to include a frame with title and buttons.
Height	Yes	Fixed height for the Web Part in the dashboard.
IsIncluded	Yes	Indicates whether the Web Part should be included in the dashboard.
IsVisible	Yes	Makes a Web Part visible or invisible in the view.
PartOrder	Yes	The order of the Web Part relative to other Web Parts in the same zone.
Width	Yes	Fixed width for the Web Part in the dashboard.
Zone	Yes	The area of the dashboard in which the Web Part is located. For more information, see the Web Part Schema Reference.

Content Properties

The properties in the following table specify the location from which the Web Part gets its content, the portion of a Web page that the Web Part displays, and the type of content the Web Part renders.

Property Name	User Specific	Description
Content	No	Embedded content (the body of the Web Part).
ContentLink	No	URL to use instead of the embedded content.
ContentType	No	Indicates the type of embedded content the Web Part contains (HTML, VBScript, JavaScript, XML, and so on)

Execution Properties

The properties in the following table specify how the Web Part runs on the dashboard.

Property Name	User Specific	Description
CacheBehavior	No	Controls whether and how a dashboard factory should cache content. Settings are None, All Users, or Each User.
CacheTimeout	No	How long a dashboard factory should keep cached results
CustomizationLink	No	URL to a page that allows the end user to customize the operation of the Web Part
MasterPartLink	No	URL to a master version of the Web Part
PartStorage	Yes	Element for storing Web Part state and customization information
RequiresIsolation	No	Indicates whether to isolate the Web Part from other Web Parts
XSL	No	Embedded XSL to use on the Web Part’s content before rendering the content to a dashboard
XSLLink	No	URL to an XSL to use on the Web Part’s content before rendering the content to a dashboard

Before You Begin Building Web Parts

Before building your first Web Part, you need to set up the Microsoft® Windows® 2000 file system sample digital dashboard and install the Web Part Builder, an add-in to Visual InterDev included in the Digital Dashboard Resource Kit. The Windows 2000 file system digital dashboard is designed as a platform that developers can use to build and test Web Parts.

Setting up the Windows 2000 File System Dashboard

You must install the Windows 2000 file system sample dashboard on a computer running Windows 2000 and Internet Information Services (IIS) 5.0. The computer and drive on which you install the sample dashboard must be formatted with NTFS.

To install the Windows 2000 file system sample dashboard, choose Install the File System Sample Digital Dashboard from the Building Digital Dashboards page of the Digital Dashboard Resource Kit. You can also run DDRK_FS.msi from the CD-ROM. An installation wizard guides you through the installation process.

During installation, the wizard will prompt you for the following information:

· The name of the folder or virtual root that will hold your users’ digital dashboards. The default virtual root is Dashboards.

· The name of the virtual Web root that contains the Dashboard factory. The default virtual Web root is Factory.

Installing the Web Part Builder

The Web Part Builder requires Microsoft Visual InterDev 98 running on Windows 2000. Before you install the Web Part Builder, make sure you have closed Visual InterDev.

To install the Web Part Builder, run Setup.exe, which is located in the Builder directory on the Digital Dashboard Resource Kit CD-ROM. An installation wizard guides you through the process.

After you install the Web Part Builder, you must connect to the dashboard site:

1. In Visual InterDev, select File, and then select New Project.

2. Select Digital Dashboard as the project type.

3. In the dialog box, type the name of the server on which you loaded the digital dashboard.

You are now ready to begin building Web Parts.

Building a Basic Web Part

This section walks you through the process of building Web Parts. You can build Web Parts in two ways—inline in the dashboard or using the Web Part Builder add-in for Visual InterDev. Even end users can build simple Web Parts from the dashboard; for example, an end user can create a Web Part that displays a favorite Web site.

Web Parts can contain embedded content, which includes HTML, scripts, ActiveX controls, or XML, or they can contain links pointing to any type of Web-based content in any location. When you build a Web Part, you use only the properties in the schema that are appropriate for that Web Part. Properties that you do not define use default settings.

The type of Web Part you build depends on the Web Part’s purpose and the location and amount of content the Web Part will display; for example, if you are creating a Web Part that displays static content such as a greeting, you can embed the content in the Web Part itself. If you are creating a Web Part that pulls content from another source such as your Web server, a database, or the Internet, you can add a link that points to the source of the content.

Building a Web Part from the Dashboard

Creating a simple Web Part from the dashboard is easy.

To build a Web Part inline in the dashboard:

1. On the dashboard, click Content, which is located in the upper right corner of the dashboard’s title bar.

2. On the Content page, click Create a new Web Part.

3. On Properties for “New Part”, define the properties for the new Web Part.

4. Click OK to save your new Web Part.

Building a Web Part Using the Web Part Builder

You can use the Web Part Builder to create Web Parts that are more complex. Using the add-in, you can preview your Web Part to make sure it functions the way you want it to.

To build a Web Part using the Web Part Builder:

1. In the project view, right-click the Dashboards folder, and then select Add a Dashboard Folder.

2. Type a name and a title for the new dashboard folder.

3. Right-click your new dashboard folder, and then select Add Web Part.

4. In the Create Web Part dialog box, type a name and description for the Web Part, and then for the content type, select HTML.

5. Type in some HTML content into the Web page.

6. From the File menu, select Save.

To see how the Web Part looks in the dashboard, right-click the dashboard folder you just created, and then select View Dashboard.

Creating a Web Part with Embedded Content

To create a Web Part that contains embedded content, you use the Content property in the Web Part schema. All content that the Web Part displays is contained within this property. The Content property can contain HTML, XML, VBScript, or JavaScript.

Here is the code for Web Part with embedded content that shows the contents of a user’s Inbox. Notice that several properties, such as ContentLink and DetailLink, are not defined. These properties use the default values the Web Part schema specifies.

<?xml version="1.0" ?>

<Part>

<Title>Inbox</Title>

<Description>The Outlook Inbox</Description>

<![CDATA[

<OBJECT classid=clsid:0006F063-0000-0000-C000-000000000046 id=OVCtl1><PARAM NAME="View" VALUE=""><PARAM NAME="Folder" VALUE=""><PARAM NAME="Namespace" VALUE="MAPI"><PARAM NAME="Restriction" VALUE=""><PARAM NAME="DeferUpdate" VALUE="0"></OBJECT>

]]>

</Content>

</WebPart>

The following illustration shows how the completed Web Part looks on a dashboard.

If you are using a content type other than HTML, you should use the ContentType property in conjunction with the Content property. This enables the dashboard factory to interpret the content correctly. The following table lists the possible values for the ContentType property.

Value	Meaning
0	Content is HTML.
1	Content is VBScript that runs on the server.
2	Content is JavaScript that runs on the server.
3	Content is XML and should be transformed using the XSL or XSLLink property.

Dashboard factories interpret values outside this range as unknown; however, if you are creating a specialized Web Part, it is possible to modify the dashboard factory to extend this list. If you do not specify a value for this property, the default is 0, or HTML.

If the Content property contains VBScript or JavaScript, the dashboard factory must be able to allow the script to generate content back to the dashboard factory. To enable this, make sure you include a function in the script called getContent.

The getContent function takes a single input parameter, an MSXML.DomDocument object that contains the property information of the Web Part in the Web Part XML format. This allows the script content to access properties such as PartStorage to determine any initialization settings that are present. Script can also access the standard ASP Session, Application, Request, and Response objects to get cookies, post and query string parameters, or any stored session or application state information.

When processing Web Parts with VBScript or JavaScript content, the dashboard factory adds the script necessary to call the getContent function and receive generated content.

Following are examples of the getContent function in JavaScript and VBScript:

JavaScript

function getContent(xmldomPart)
{
var sContent = new String();
//code to generate content into sContent
return sContent;
}

VBScript

Function getContent(xmldomPart)
Dim sContent
'code to generate content into sContent
getContent = sContent
End Function

Creating a Web Part with Linked Content

When you create a Web Part with linked content, you use the ContentLink property to add a link that points to any type of Web content. Types of content include HTML, which is the default; VBScript; JavaScript; or XML. To enable the dashboard factory to interpret linked content correctly, you should use the ContentType property in conjunction with ContentLink. For more information about using the ContentType property, see the previous section, “Creating a Web Part with Embedded Content.”

Here is an example of a Web Part containing a link that points to content located on the Internet:

<WebPart>
<Title>Linked Content Web Part</Title>
<Description>A Web Part that contains linked content.</Description>
<ContentType>0</ContentType>
<ContentLink>http://www.msn.com</ContentLink>
<RequiresIsolation>1</RequiresIsolation>
</WebPart>

The following illustration shows how the Web Part looks in a browser.

By default, content from ContentLink is read directly into the page and included in the dashboard’s document object model. In most cases, however, you may want the Web Part to simply provide a window around the Web page you are linking to. If so, set the RequiresIsolation property to TRUE to place the Web Part in an IFrame. For additional information about RequiresIsolation, see “Building Good Web Parts” later in this paper.

Creating a Web Part with XML Content

To create a Web Part that contains XML content, you can use one of the four combinations shown in the following table.

Properties	Description
ContentLink and XSL	The ContentLink property contains a URL that points to an XML document. The XSL property contains the style sheet the dashboard factory uses to transform the XML into HTML.
ContentLink and XSLLink	The ContentLink property contains a URL that points to XSL content. The XSLLink property contains a URL that points to a style sheet that the dashboard factory uses to transform the XML content into HTML.
Content and XSL	The Content property contains embedded XML content. The XSL property contains the style sheet the dashboard factory uses to transform the XML to HTML.
Content and XSLLink	The Content property contains XML content. The XSLLink property contains a URL pointing to a style sheet that the dashboard factory uses to transform the XML to HTML.

Note When you build a Web Part containing embedded or linked XML content, set the value of the ContentType property to 3, or XML. This enables the dashboard factory to recognize the contents of the Content or ContentLink property as XML and interpret the content correctly.

Here is an example of what a Web Part that contains linked XML content and a link to a site containing an XSL that the dashboard factory uses to transform the XML:

<WebPart>
<Title>XML Web Part</Title>
<Description>A Web Part that contains embedded XML and a link to a site containing XSL.</Description>
<ContentType>3</ContentType>
<ContentLink>http://www.msn.com/news.xml</ContentLink</ContentLink>
<XSLLink>http://www.msn.com/news.xsl</XSLLink>
</WebPart>

Using XML with the Sample Digital Dashboards

A few XML and XSL encoding limitations exist for the digital dashboard samples included in the Digital Dashboard Resource Kit 2.0.

· With the Windows 2000 file system sample dashboard, Web Parts that store XML in the Content property or return XML from VBScript or JavaScript that runs on the server must use UTF-16 encoding. With the SQL Server sample dashboard, Web Parts that store XML in the Content property or return XML from VBScript or JavaScript that runs on the server must use UTF-8 encoding. When a Web Part stores XML in Content or returns it from script that runs on the server, the dashboard factory temporarily stores the XML in a string variable on the server and then initializes an XMLDOM object from that variable. This means that if you using one of these methods to return XML, you cannot specify an encoding type in the XML.

· Be sure to set the value of the ContentType property to 3, or XML, if your Web Part retrieves XML content through a URL in the ContentLink property. Otherwise, the dashboard factory will not render the XML correctly. If you use the ContentLink property but do not define the ContentType property correctly, the dashboard will temporarily convert that content into a string, causing an XSL error when transforming XML that does not use UTF-16 encoding (or UTF-8 with the SQL Server sample dashboard).

· You cannot specify an encoding type for Web Parts that store an XSL in the XSL property because the dashboard factory passes the XSL through a string.

Building Good Web Parts

This section provides key guidelines for building good Web Parts and discusses ways that you can implement these guidelines in the Web Parts you design and build. The best Web Parts:

· Are informative and customizable. Good Web Parts deliver targeted information tailored to specific users in a manner that is appropriate for a digital dashboard. To ensure that the Web Parts you build truly serve their purpose, make it possible for users to customize them.

· Have a consistent look and feel. The look and feel of your Web Parts should be appealing to users and appropriate for a digital dashboard. Allow your Web Parts to inherit styles from the dashboard’s style sheet to give your Web Parts a look and feel that is consistent with other Web Parts on the dashboard.

· Are isolated from other Web Parts on the dashboard. The functionality of a Web Part should not interfere with other Web Parts on a dashboard. Isolating your Web Parts and using token replacement for all scripts and variables ensures that your Web Parts will run on a dashboard without causing naming and script collisions.

· Are portable. To make your Web Parts truly reusable, you should design them to be as self-contained as possible. They should not rely on network connectivity or other Web Parts on the dashboard, and above all, their properties should adhere to the Web Part schema.

· Are able to be used offline. Web Parts must function appropriately when viewed offline. Embed text in the Content property of your Web Part that displays when linked content is unavailable.

Building Web Parts that Are Informative and Customizable

The purpose of a digital dashboard is to help reduce information overload by delivering tailored information to users in a manner they can easily assimilate. While it may be tempting to create complex Web Parts that deliver large amounts of constantly changing information, Web Parts like these may not serve their purpose. Above all, a good Web Part must display information in a manner appropriate to a digital dashboard.

Before you begin building Web Parts, think about the needs of your users. Often, the best Web Parts are ones that users can customize; for example, a Web Part that shows the contents of an Outlook® folder must display a view that each user can customize using the Outlook View Control, or a Web Part that displays a stock ticker must be customizable so that it shows only the stocks each user selects.

Customizable Web Parts have three requirements: a way for the user to provide customization information, a location for storing that information, and a method of retrieving it. To provide an interface that allows users to customize a Web Part, you use the CustomizationLink property in the Web Part schema. You can store customization information on the client, on the server, or in the Web Part itself using the PartStorage property.

Using the CustomizationLink Property

When specified, the CustomizationLink property contains a URL for a page that allows users to customize the content of the Web Part. You can do this inline in the Web Part's content or you can supply a URL in CustomizationLink—the dashboard user interface provides a way for the user to navigate to it. For example, the dashboard might place a small Edit button on the right side of the Web Part's title bar. When the user clicks the button, the view navigates to this URL, allowing the user to customize the content of the Web Part. Note that this is likely a per-user customization of content and does not affect the properties of the Web Part item in the Exchange Web store. In your customization pages, you will often want to provide a Submit button that applies the user’s changes and takes the user back to the dashboard. You can offer this by using Java or VBScript to back up one page (window.history.back method).

This URL can point to anywhere, but it typically points to the site that is supplying the content for the Web Part. It can also point to another Web Part or even the same Web Part, passing a parameter indicating customization.

Using the PartStorage Property

The best place to store customization information related to a Web Part is in the PartStorage property, which you can access through the Digital Dashboard Services Component. For more information about the Digital Dashboard Services Component, see the Digital Dashboard Services Component reference documentation.

In the following example, the Web Part Purchase Car tracks the user’s name and address so that it can be retrieved the next time the users accesses the Purchase dashboard. Purchase Car stores these values in custom properties using the State Management service of the Digital Dashboard Services Component. The Web Part specifies the namespace and name for each property in addition to the value for each property. Later, the Web Part can retrieve this state information through the Properties collection.

Following is the content of the Web Part Purchase Car. Note that the Web Part uses the string ‘This_WPQ_Part’ to reference itself. For more information on the string ‘_WPQ_Part’, see the “Part Discovery Service” section of the Digital Dashboard Services Component reference documentation.

<TABLE border=0 cellPadding=1 cellSpacing=1 style="HEIGHT: 228px; WIDTH: 415px" width="75%">
<TR>
    <TD>Name:</TD>
    <TD><INPUT id=txtName name=text1 style="HEIGHT: 22px; WIDTH: 278px"></TD></TR>
            …
</TABLE>
</P>
<INPUT id=load type=button value="Remember Me" LANGUAGE=javascript onclick="load_onclick();">
<INPUT id=save type=button value="Place Order" LANGUAGE=javascript onclick="save_onclick();">
<SCRIPT LANGUAGE=javascript>
function save_onclick() {
this_WPQ_Part.Properties ("urn:Custinfo#CustName", txtName.value, 0);
this_WPQ_Part.Properties ("urn:Custinfo#CustName ", txtAddress1.value, 0);
this_WPQ_Part.Properties ("urn:Custinfo#Address2", txtAddress2.value, 0);
this_WPQ_Part.Properties ("urn:Custinfo#City", txtCity.value, 0);
this_WPQ_Part.Properties ("urn:Custinfo#State", txtState.value, 0);
this_WPQ_Part.Properties ("urn:Custinfo#Zip", txtZip.value, 0);this_WPQ_Part.Save()
}
function load_onclick() {
txtName.value = this_WPQ_Part.Properties("CustName");
txtAddress1.value = this_WPQ_Part.Properties ("urn:Custinfo#Address1");
txtAddress2.value = this_WPQ_Part.Properties ("urn:Custinfo#Address2");
txtCity.value = this_WPQ_Part.Properties ("urn:Custinfo#City");
txtState.value = this_WPQ_Part.Properties ("urn:Custinfo#State");
txtZip.value = this_WPQ_Part.Properties ("urn:Custinfo#Zip");
}
</SCRIPT>

Cookies

When you create a customizable Web Part, the customization generally takes place inline in the dashboard, but you must also make sure that other pages are supported.

For example, a Web Part that shows the contents of an Outlook folder using the Outlook View control must be capable of showing the contents of any folder that the user chooses at run time. To do this, the Web Part must have information about which folder to display and possibly the name of a stored view to use. You can provide this type of functionality using client-side cookies.

The Web Part displays a user interface that allows a user to change the current folder or view. Once the user changes the view, the Web Part uses client-side script to write a cookie containing the configuration information. When the user refreshes the dashboard or returns to it in another session, the Web Part uses the client-side script to read the cookie value and re-apply the configuration information.

You can access cookies through the document object model (DOM). The code for this is document.cookie.

Although writing client-side cookies is the easiest way store and retrieve user settings, these setting are confined to the client computer. A user cannot log on to another computer in the network and view the customized Web Part. If your Web Part includes embedded script that runs on the server, that embedded script can access cookies passed by Internet Explorer through the Request.Cookies collection in ASP.

Cookies and Non-Isolated Content

Typical Web sites use cookies to identify the client between page requests. When a client accesses a page, the page drops a cookie associated with the site's domain that indicates the user has been validated. When the user requests another page from that domain, Internet Explorer passes the cookie value in the HTTP headers and the server can then determine which user is making the request.

A digital dashboard presents a new twist on this, because if a Web Part is not isolated, the request for content comes from the dashboard server and not the client computer.

For example, say you create a Web Part that displays the MSN home page. Users must be able to customize the page and Internet Explorer must be able to determine the identity of the client. To accomplish this, the following process occurs:

1. The process begins when the client requests a dashboard for the first time. Internet Explorer sends a URL Get request to the server hosting the dashboard ASP. The dashboard ASP receives no cookies from Internet Explorer because no cookies have been dropped that are associated with the domain of the dashboard ASP.

2. The dashboard factory renders Web Parts, one of which contains a ContentLink URL pointing to the MSN home page. The dashboard factory requests this URL, but because there are no cookies to forward, it does not send any cookies with the request.

3. Because the dashboard factory has not passed any cookies in the request, the MSN site returns a generic version of the home page to the dashboard factory.

4. To customize the Web Part, the user clicks the Customize button in the title bar of the Web Part. The hyperlink associated with this button points to the URL specified in the CustomizationLink property, but the dashboard factory also adds two query string parameters: ReturnURL and PartNamespace. ReturnURL is set to the dashboard.asp (the URL of the dashboard) and PartNamespace is set to the value in the Namespace property of the Web Part. The dashboard factory appends these to any existing query string parameters defined in CustomizationLink or adds a query string if no other query string parameters are defined.

Note If the results of the ContentLink is a login screen, that page will not have the correct information for the ReturnURL and PartNamespace parameters. To correct this, the dashboard factory uses a simple case insensitive string replace operation to search for two tokens, _OfficeDashReturnURL_ and _OfficeDashPartNamespace_, and replace them with the appropriate values. For example, an Web site that supplies a login screen might return the following HTML:

5. After the user customizes the MSN home page, the site performs an HTTP redirect (Response.Redirect in ASP) back to the return URL. The site also includes three query string parameters in the redirection response: Partnamespace, UserTicket and Expires.

· Partnamespace can contain the same value passed to the site, or the site may modify it. This will be used to qualify the cookie name that the dashboard will eventually drop on the client computer, and will be used to determine when to forward the cookie back to the site in future content requests.

· UserTicket is an opaque string value, which contain any value the site adds. The dashboard factory does not use it. This value will be passed back to the site as the cookie value in future content requests, enabling the site to determine the identity of the client.

· Expires is a string specifying the cookie expiration date, and this is in the same format you use when specifying a cookie expiration date in ASP or client-side script; for example "December 31, 2001". If this parameter is not included, the dashboard factory does not give the cookie an expiration value, which means the cookie will be deleted when the user closes the browser.

6. When the client browser receives the redirect, it requests the redirect URL, which contains the query string parameters mentioned previously. The dashboard factory now receives these parameters.

What happens next will depend on whether the factory page itself is the return URL, or if the factory delegates this to another specialized page. If it is the former, the factory will first go through its rendering processing, but will make sure to forward the UserTicket cookie back to any ContentLink that has the same Namespace value as the PartNamespace return parameter. It will also include a new cookie in the returned page. The cookie's name will be "<PartNamespace>:UserTicket" and its value will be the value returned in the UserTicket parameter.

If the factory uses a specialized page to handle the ReturnURL, that page first returns the cookie described previously and then redirects back to the main dashboard ASP.

7. Because the Web site has returned the UserTicket cookie value, the dashboard can forwards this cookie value when requesting the URL in ContentLink. The algorithm for this is as follows:

1. When requesting a ContentLink URL

2. If any cookies exist whose name starts with Currentwebpart.Namespace

3. Forward the cookie in the HTTP_COOKIE header under the name "UserTicket"

Note that the cookie name the site receives is just "UserTicket" without the namespace. This makes it easier to locate.

8. The MSN site retrieves the UserTicket cookie and any other cookies that the Web Part's client-side script may have dropped under the same namespace. The MSN site uses this ticket value to look up the user's personal settings and information and generate specific content for that user.

Internet Explorer receives the cookie and stores it for future requests.

Maintaining a Consistent Look and Feel

A good Web Part must have a look and feel that is consistent with other Web Parts on the dashboard. The dashboard defines a set of style classes that Web Parts inherit to ensure that they render with a similar look and feel. The dashboard itself also uses these styles. Do not use linked or embedded style sheets that contain these styles because they can overwrite the style of the entire dashboard. The following table describes the style classes that the dashboard defines.

Style Class	Description
BODY	Specifies default text formatting and any other global styles
P	Default text formatting
H1, H2, H3, H4, H5, H6	Headings within a Web Part
TH	Table header cells
TH.Filled	Table header cells filled with a background color
TD	Table cells within a Web Part
TD.Filled	Table cells filled with a background color
a:link	Hyperlink
a:hover	Hyperlink when mouse is over it
a:active	Hyperlink when it has been activated
a:visited	Visited hyperlink
LI	List items
INPUT	Input controls
TEXTAREA	Text areas
SELECT	Select (drop-down list) controls
OPTION	Options within a select
B, STRONG	Bold text
I, EM	Italic text
U	Underline text

Isolating Your Web Parts

Because the Web Parts you build are included in the Document Object Model of the digital dashboard along with other Web Parts, there is a high possibility of script collisions. Any time you create a Web Part that contains client-side script, you need to isolate that Web Part from the other Web Parts on the page. Any of the following cause an error in the dashboard:

· Functions that have the same name in multiple Web Parts

· Objects that have the same names in multiple Web Parts

· Variables that have the same name in multiple Web Parts

When you isolate a Web Part, script functions and event sinks in that Web Part run as though they are the only scripts on the page, function names do not conflict with function names in other Web Parts, and event sinks do not conflict with other event sinks on the page. In addition, HTML IDs in the isolated Web Part do not conflict with HTML IDs in other Web Parts on the dashboard, and any ID referenced in a script uniquely identifies an element in the content of that Web Part.

If you are building a Web Part that will not be isolated, that Web Part’s module-level variables and procedures will be part of the same page as the dashboard’s variables and procedures. The variables and procedures the dashboard uses have a ddv_ prefix to reduce the likelihood of duplicate variable or procedure names, but it is a good idea to also prefix your variables and procedures with the replacement token “_WPQ_” to avoid name collisions with other non-isolated Web Parts. Do not include <HTML>, <HEAD>, or <BODY> tags in your source code because your code will be inserted into a page that already contains these tags. It is good practice to wrap your code inside procedures whenever possible and limit variable declarations to the procedural level. This eliminates unnecessary variables and reduces the potential for namespace collisions.

Using Frames

To fully isolate a Web Part from the other Web Parts on a dashboard, use the RequiresIsolation property. This places the Web Part in an IFrame. When you use RequiresIsolation, the request for the content comes from the client computer (instead of the server), so the Web Part can pass cookies and prompt for basic authentication. The request for content for an isolated Web Part occurs asynchronously from the rest of the Web Parts on the page. This can be useful for Web Parts with linked content that loads slowly. The downside of using RequiresIsolation is that it makes the Digital Dashboard Services Component inaccessible because of security considerations.

Using String Replacements

If you do not want to isolate a particular Web Part but are concerned about name collisions with HTML elements or scripting functions on the dashboard, you can use the digital dashboard Globally Unique Identifier (GUID) service to ensure that the function names and HTML IDs in your Web Part are unique.

To use the service, add the prefix “_WPQ_” to the HTML IDs and function names in your Web Part. The dashboard then performs a string search-and-replace function, converting the string to the ID of the Web Part, which makes the HTML IDs and function names for your Web Part unique within the assembled page.

Using Token Replacements

To make it easier for Web Parts to function in a variety of environments, dashboard factories perform token replacements. Tokens are case-insensitive—you can use any combination of upper- and lower-case characters. The following table lists the tokens you can use and the properties with which you can use them.

Token	Properties	Replacement
_WPID_	Content, ContentLink, CustomizationLink, DetailLink	Unique ID of this Web Part instance. Format may vary between data stores.
_WPQ_	Content	Unique ID of this Web Part instance with respect to other Web Parts in the same dashboard. This can be used to qualify HTML IDs and script function names to avoid name collision. Does not vary between data stores.
_DashboardID_	Content, ContentLink, CustomizationLink, DetailLink	Unique ID of this dashboard.
_LogonUser_	Content, ContentLink, MasterPartLink	Value retrieved from ASP function Request.ServerVariables("LOGON_USER"). This value typically contains the client's Windows 2000 user name (for example,. "adventureworks\kimy") and can be used for user identification within an intranet. This allows a URL in ContentLink that points to an intranet site to identify the client without having to be set up to delegate Windows 2000 credentials.

Building Portable Web Parts

To be truly reusable, a Web Part must be able to be used in any digital dashboard. This means that Web Parts should not be dependent on other Web Parts, network connectivity, or computer configurations. To guarantee portability, follow these rules:

· Don’t create Web Parts that use the DOM of a specific dashboard. Dashboard implementations can vary, and if you tie a Web Part to the DOM of a particular digital dashboard, that Web Part may not function properly when used in a different dashboard.

· Don’t create dependencies between Web Parts. Because users can customize their dashboards by adding and removing Web Parts, creating a Web Part whose functionality is tied to another Web Part on the dashboard is not a good practice. Your Web Part will not function properly if a user removes the Web Part on which it depends. Use the Digital Dashboard Services Component for communication between Web Parts. By using the discovery and notification functionality of the Digital Dashboard Services Component, Web Parts can interact without being dependent on one another. In addition, the Digital Dashboard Services Component allows you to capture Internet Explorer events without causing collisions.

· Use common schemas for communication between Web Parts. The most powerful element of the digital dashboard is that any Web Part can communicate with any other Web Part provided they use a common language to share collaborative data. For example, a Contacts Web Part can share information with a Phone Book Web Part—but if Contacts sends out the name Smith, John and the corresponding entry in Phone Book is John Smith, the user will not get the right phone number. You can solve this problem by using common schemas. Exchange 2000 Server defines a number of common schemas for collaborative data such as contacts, tasks, mail, and calendar items that are excellent for sharing these types of data.

Building Web Parts that Users Can Take Offline

Web Parts must function appropriately when users take their computers offline. If the data underlying a Web Part is exceedingly complex, the Web Part may render only a small portion of the data. Additionally, if the data is not appropriate for offline use, the Web Part may simply notify the user that it is not available offline.

Failing Gracefully When Offline

Embed text in the Content property of your Web Part that displays when the linked content in your Web Part is unavailable. When processing Web Parts, the dashboard factory first checks the ContentLink property for a value. If the dashboard factory cannot retrieve content from ContentLink, the factory then checks the Content property for a value and renders embedded content if available. By placing the text, “This Web Part does not function when offline,” in the Content property, you can provide an appropriate backup experience for the user. If you choose, you can use the Content property to provide a richer backup experience than a text message. For more information about using the Content property, see “Creating a Web Part with Embedded Content” earlier in this paper.

Taking Collaborative Data Offline

With Microsoft Outlook 2000, you can take a wide variety of collaborative information offline, such as discussions and public folder content. The best way to integrate this information into a digital dashboard is with the Outlook View Control. For example, The Outlook View Control and Exchange Server Public Folders provide an easy way to create document libraries.

The Outlook View Control is an ActiveX control that can be hosted inside any Web page. When that page is hosted inside Outlook, you can use HTML scripting to manipulate the full Outlook object model through the Outlook View Control. The control itself is a wrapper around the full Outlook EXE file. For this reason, Outlook 2000 is required on any computer running a Web page that contains the Outlook View Control.

The Outlook View Control provides the same rich user experience as Outlook when it is running in a digital dashboard. For example, users can open items and use familiar right-click commands. In addition, the Outlook View Control features category functionality. Users can sort or filter items in categories to make it easier to find information.

While the Outlook View Control has a full set of methods and properties, you will find that the three parameters in the following table are enough to get started and are quite powerful. You can also manipulate these parameters easily through HTML scripting.

Selected Outlook View Control Parameters
Parameter	Function
Folder	Takes a path to a folder. Example: “\\Public Folders\Favorites\Dashboard”
View	Applies a preset view to the control. Example: “By Conversation Topic”
Restriction	Allows for the application of a filter to the control. Example: "[Subject] = 'Cable'"

Note Full documentation for the Outlook View Control is available as part of the Microsoft Outlook 2000 Team Folders Kit.

Taking Business Intelligence Data Offline

You can integrate Office Web Components into your Web Parts so that users can take business intelligence data offline. Office Web Components are a collection of COM controls for publishing spreadsheets, charts, and databases to the Web, fully using the rich interactivity that Internet Explorer version 4.01 and later supports. Office Web Components are fully programmable, enabling you to build sophisticated, interactive Web-based solutions. These controls cache data on the client in XML files to allow for a rich offline experience.

Office 2000 includes four main Web Components:

· The DataSource Control. The DataSource Control is never actually displayed on a Web page, but it provides the connections to data sources that feed all other controls. When looking at the code generated by Excel and other tools, you will always see this control if you have connected to a database or OLAP cube.

· The Spreadsheet Component. The Spreadsheet Component provides interactivity in much the same way that a spreadsheet does. It is extremely useful for performing complex calculations because it supports most of the same formulas as the full version of Excel.

· The Microsoft PivotTable® Component. You can use the PivotTable Component to connect to OLAP data sources (such as Microsoft OLAP Services) to provide workers with the ability to perform dynamic data modeling within a digital dashboard. The following illustration shows the PivotTable Component dynamically connected to a SQL Server 7.0 OLAP Cube. Note the depth of the levels that are accessible.

· The Chart Component. The Chart Component presents information in charts that can be bound to a variety of data sources, allowing users to visualize data quickly. It also can deliver very concise alerts and warnings in digital dashboard solutions.

For more information on using these controls in advanced solutions, please refer to the Microsoft Press® book Programming Microsoft® Office 2000 Web Components, by Dave Stearns.

How a Digital Dashboard Factory Interprets Web Parts

This section describes how the dashboard factory initializes Web Parts, gets content, and, finally, displays the content on the dashboard.

The initialization process begins when a user requests a dashboard.

1. The dashboard factory first checks the AutoUpdate property (from the Dashboard schema) for a value.

2. If AutoUpdate contains a value of 1, or always, the dashboard factory checks for a value in the MasterPartLink property. If that property contains a value, the dashboard factory uses that value to get the master Web Part.

Note If this operation fails, the dashboard factory uses the last found version of the master Web Part.

If MasterPartLink does not contain a value, the dashboard factory just uses the current instance of the Web Part.

3. Next, the dashboard factory checks to determine whether the non-user–specific properties of the Web Part differ from those of the master Web Part. If the properties differ, the dashboard factory updates the non-user–specific properties to match those of the master Web Part.

The following diagram illustrates this process.

After the initialization process is complete, the dashboard factory gets the content for the Web Part and renders it to the dashboard.

1. The dashboard factory checks to determine whether the RequiresIsolation property contains a value of TRUE. If so, the dashboard factory renders the isolated Web Part.

2. If the value in RequiresIsolation is FALSE, the dashboard factory checks for a value in the ContentLink property. If this property is defined, the dashboard factory gets content from the link. If ContentLink is not defined, the dashboard factory gets embedded content from the Content property.

3. Next, the dashboard factory checks the value in the ContentType property to determine whether the content runs on the server. If it does, the dashboard factory executes the content as script.

Note If this operation fails, the Web Part displays a standard error message.

4. After checking for a value in ContentType, the dashboard factory checks for a value in the XSLLink property. If XSLLink contains a value, the dashboard factory gets the XSL from the link. If that property does not contain a value (or if the operation fails), the dashboard factory checks for a value in the XSL property.

5. The dashboard factory transforms XML content to HTML.

6. The dashboard factory performs the necessary token string replacements and displays the content of the Web Part in the dashboard.

The following diagram illustrates this process.

Digital Dashboard Architecture

The digital dashboard samples in the Digital Dashboard Resource Kit 2.0 are three-tier Web applications based on Distributed Authoring and Versioning (WebDAV) and XML. The architecture of digital dashboards includes a data tier that consists of a WebDAV-enabled Web Part store, which can be SQL Server, the Windows 2000 file system, or Exchange 2000 Server; a middle tier that consists of a store module and the dashboard factory running on Microsoft Internet Information Services (IIS); and a presentation tier, or dashboard, that renders on the user’s computer. Communication between the store module and the dashboard factory takes place through the WebDAV protocol and communication between the client and the dashboard factory takes place through HTTP.

The following sections describe each tier in detail.

Store Module

The store module provides the core input and output APIs for dashboards and Web Parts, handling all logic and storing user customization information. The store module is actually a script file called Store.vbs in the samples in the Digital Dashboard Resource Kit. You can build your own store modules, but you should make sure they interpret Web Parts in the standardized way.

Because Web Parts and dashboards are wrapped in an XML schema, they are storage-neutral and can reside in your Windows® file system, Microsoft SQL Server™, or the Exchange 2000 Web Store, allowing you to choose the type of store module that best meets the needs of your organization. Following are some of the benefits of each type of store module:

· The Windows file system is readily available, easy to use, and provides native WebDAV support.

· SQL Server is a scalable application server that offers relational user and Web Part management. The Digital Dashboard Resource Kit includes extensions to IIS that allow the dashboard to use SQL Server as a Web Part Storage Service. These are installed when the SQL Server digital dashboard is installed.

· The Exchange Web Store is integrated with Microsoft Office, supports offline use, and provides native support for WebDAV and XML.

Dashboard Factory

The dashboard factory calls the store module to get all of the Web Part and dashboard properties and then assembles the dashboard for rendering on the client. When a user requests a dashboard, the dashboard factory receives combined XML streams from the Web Parts and the dashboard, applies an XSL transformation to transform the streams into HTML and DHTML, and then uses IIS to stream the transformed content to the dashboard. For additional information on how this process works, see “How a Digital Dashboard Interprets Web Parts” earlier in this paper.

Presentation Tier

A digital dashboard is a visual representation of a WebDAV folder containing Web Parts. The presentation tier renders Web Parts and provides run-time customization.

uuuu

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.

Microsoft, ActiveX, BackOffice, MSN, Outlook, PivotChart, PivotTable PowerPoint, Visual InterDev, Visual Studio, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

Other company and product names mentioned herein may be the trademarks of their respective owners.

The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted.