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.

The following sections describe each of these services in detail.

Part Discovery Service

The Part Discovery service allows Web Parts to detect other Web Parts on the dashboard at run time. This enables Web Parts to customize their functionality depending on whether other Web Parts are present.

While the Part Discovery service can also be used to find and manipulate other Web Parts directly through DHTML, a better way to do this is through the Notification service, which is described later in this document.

The following sections list the objects, methods, properties, and parameters used in Web Part discovery.

DDSC Object

During page construction, a single DDSC object is inserted into the page by the dashboard factory, making the services this document describes available to Web Parts on that page. In addition, the dashboard factory generates code to call the Init method to initialize the dashboard object. It may also provide the URL of the server that is used to post Web Part state changes and requests.

From the DDSC object, you can also retrieve the handle to the active Dashboard object, described later in this section.

Methods

Dashboard Init (DashboardID, DOMObject, StateServiceURL);

Dashboard Dashboard ();


Parameters

DashboardID—the ID of the dashboard, typically a URL. If StateServiceURL is not specified, all state changes will be posted to this location. If StateServiceURL is not specified, the value of this parameter will be supplied as an argument in the calls to the methods POST and GET.

DOMObject—handle to the top-level DOM node of the dashboard element on the page.

StateServiceURL—not supported in this release.

Dashboard—returns a handle to the Dashboard object.

Dashboard Object

This Dashboard object is the encapsulation of the current dashboard. It contains the collection of all Web Parts on the dashboard and allows Web Parts to modify the dashboard state. Web Parts that are in the dashboard folder but do not appear on the page can be accessed only through the Web Part retrieval service, which is described later in this document. The Dashboard object provides the following properties:

·         DashboardID

·         DOMObject

Methods

PartCol Parts ();

Parameters

Parts —returns a handle to the PartCol collection object that contains all of the Web Parts on the page.

Part Object

The Part object is the encapsulation of the services the Digital Dashboard Services Component provides for Web Parts in the current dashboard. The Part object is what is returned from the Part Discovery service and used to set and retrieve Web Part state. For more information about Web Part state, see “State Management Service” later in this document.

The Part object provides the following properties:

·         WebPartQualifier—uniquely identifies a Part object on the current dashboard page. This is automatically generated by the dashboard factory when the dashboard is rendered and is registered with the Web Part.

·         WebPartID—uniquely identifies a part in the store (typically a URL) specified when the Web Part is registered on the page. If StateServiceURL is specified during the call to the DDSC object’s Init method, this value will be supplied as an argument in the calls to the methods POST and GET.

·         DOMObject—This is the default property of the Part object and provides a handle to the HTML DOM node for the part.

Note   Often, you may want to get a handle to a Part object within the body of a Web Part. This is especially useful when using the Part State management features described later in the document. During page creation, the dashboard factory defines a set of page variables that provide access to all Part objects. You use the string ‘varPart_WPQ_’ when referencing the Web Parts themselves in script, as shown in the following example.

<SCRIPT LANGUAGE=VBSCRIPT>
     dim MyPart, Dashboard
     Set Dashboard = DDSC.Dashboard
     Set MyPart = varPart_WPQ_
     MyPart.InnerHTML = …

</SCRIPT>

When the page is constructed, the string ‘_WPQ_’ is replaced by a unique qualifier for the Web Part.

PartCollection Object

The PartCollection object allows Web Parts to be registered, unregistered, and retrieved by index or enumeration. Because the code to register Web Parts is automatically generated by the dashboard factory, Web Parts should only use the registration functions if they are designed to dynamically add or remove Web Parts from the page.

Methods

PartObj Register (WebPartQualifier, WebPartID, DOMObj,);

UnRegister (Index);

PartObj Item (Index);

Count Count ();

Parameters

WebPartQualifier—unique identifier for a Web Part on the dashboard. This is automatically generated by the dashboard factory when the dashboard page is rendered.

WebPartID—uniquely identifies a part in the store and is used by state management service to post modification back to the store module. If the Init function has not been called, WebPartID must be a fully qualified URL. If the Init function has been called, WebPartID is used as a parameter to identify the Web Part.

Index—identifies the Web Part in the Web Part collection. The value of Index can either be the WebPartQualifier or an integer that indicates the location of the Web Part in the collection.

S_OK, E_FAIL, or E_INVALIDARG—return values used for error handling.


Part Discovery Service Example

The following example illustrates the Parts method.

<SCRIPT LANGUAGE=VBSCRIPT>
     dim Part, Dashboard
     Set Dashboard = DDSC.Dashboard
For Each Part in Dashboard.Parts

Next
</SCRIPT>

Notification Service

While Web Parts can be coded to communicate with one another directly by calling functions within the content of specific Web Parts, this is not a good practice. For example, if a particular Web Part is not on the dashboard or if a different version of it is present, the intended interaction may not take place. The Digital Dashboard Services Component solves these problems by acting as an intermediary between the various Web Parts on a dashboard.

The Web Part notification service provides a standard multicast event mechanism for Web Parts and hides the complexity of the underlying event mechanisms of the Web browser (DHTML events).

Through the Notification service, Web Parts can indicate interest in an event, providing a handle to a function that will be called when the event runs. Note that system and custom events are handled in exactly the same way.

All of the notification service methods are on the DDSC object. The following sections list the methods and parameters the Web Part Notification service uses.

Methods

RegisterForEvent(NamespaceURN, EventName, Function);

RaiseEvent (NamespaceURN, EventName, [optional] EventObject);

Parameters

NamespaceURN—the unique namespace that describes the context for the event.

EventName—the name of the event for which the Web Part is registering.

Function—the function that should be called when the event occurs.

EventObject—a variant type that contains additional data passed to the functions registered for this event.

S_OK, E_FAIL, or E_INVALIDARG—return values used for error handling.


System Notifications

Web Parts can register to receive notifications for standard system events triggered in the browser. As the browser supports only a single callback function for events, parts should register for system events instead of trying to provide an event handler directly.

The following table lists the events that are provided automatically by the dashboard factory. The NamespaceURN for these events is urn:schemas.microsoft.com:dhtml.

Event Name

Description

onactivate

Runs when the window object is set as the activeElement.

onafterprint

Runs on the window object immediately after its associated document prints.

onbeforedeactivate

Runs immediately before the activeElement is changed from the current window object to another object in the parent document.

onbeforeprint

Runs on the window object before its associated document prints.

onbeforeunload

Runs before a page is unloaded.

onblur

Runs when the window object loses the input focus.

oncontrolselect

Runs when the user makes a control selection of a window object.

ondeactivate

Runs when the activeElement is changed from the current window object to another object in the parent document.

onerror

Runs if an error occurs when the window object is loading.

onfocus

Runs when the window object receives the focus.

onhelp

Runs when the user presses the F1 key while the browser is the active window.

onload

Runs immediately after the browser loads the window object.

onresize

Runs when the user changes the size of the window object.

onresizeend

Runs immediately after the user changes the dimensions of the window object.

onresizestart

Runs when the user begins to change the dimensions of the window object.

onunload

Runs immediately before the window object is unloaded.


Notification Example

The following example shows how Web Parts can interact in a dashboard through the Notification service. When a user selects a car in the Web Part on the left, the Web Part on the right displays a simple GIF of that car from CarPoint.

 

The Web Part Picture of Car registers itself for events using the RegisterForEvent function. When registering, the Web Part specifies the namespace and name of the event, and the function to call when that event occurs, which is DisplayCarInfo. DisplayCarInfo is a simple function that displays the appropriate picture depending on the selected car.

Here is the content for the Web Part Picture of Car:

<center>
<div id=car_WPQ_><IMG id=img_WPQ_ border=0 src=""></div>
</center>
<SCRIPT language="JScript">
var sCarSelected;
DDSC.RegisterForEvent("urn:myCompany:Car", "onSelect", DisplayCarInfo);
function DisplayCarInfo(sCarSelected)
{
     switch (sCarSelected) {
     case "BMW" :
          document.all.img_WPQ_.src = _ “http://carpoint.msn.com/merismus/Gallery/c436829a.jpg”;
          break;
     case "PORSCHE" :
          document.all.img_WPQ_.src = _ “http://carpoint.msn.com/merismus/Gallery/c437128a.jpg”;
          break;
     case "MERCEDES" :
          document.all.img_WPQ_.src = _ “http://carpoint.msn.com/merismus/Gallery/c436231a.jpg”;
          break;
     }  
}
</SCRIPT>

The Web Part Select Car raises an event whenever a user selects the name of a car. To do this, the Web Part uses the RaiseEvent function, specifying its namespace and the name of the event, and passing the value of the item the user selected from the list.

Here is the content of the Web Part Select Car:

<SELECT ID="CarsForSale" NAME="CarsForSale" SIZE="3" OnClick="SendNotification()" OnKeyUp = "SendNotification()">
<OPTION VALUE="BMW" SELECTED>BMW</OPTION>
<OPTION VALUE="PORSCHE">PORSCHE</OPTION>
<OPTION VALUE="MERCEDES">MERCEDES</OPTION>
</SELECT>
<SCRIPT language="JScript" id=s1>
function SendNotification()
{
            DDSC.RaiseEvent ("urn:myCompany:Car", "onSelect", CarsForSale.value);
}
</SCRIPT>

Because the Web Part Picture of Car is registered to receive notification of this event, the function DisplayCarInfo is called with the value that was passed as an argument to RaiseEvent, displaying the picture of the selected car.


Session State Management Service

Through the Session State Management service, Web Parts can share data with other parts (even if the Web Parts are located on other dashboards) through name-value pairs associated with the browser session. For simplicity and to avoid complex identification mechanisms, session state is always global and is always retrieved synchronously.

A Web Part that has information to communicate publishes state information. After the information is posted, the Web Part can use the notification service previously described to alert other parts. Any part can retrieve the values that have been previously stored.

All session state methods are provided by the DDSC object. The following sections list the methods and parameters the Session State Management service uses.

Methods

Value GetSessionState (NamespaceURN, Name,);

PutSessionState (NamespaceURN, Name, Value, [optional] LONG Flags);

ClearSessionState (NamespaceURN, Name);

Parameters

NamespaceURN—identifies the schema.

Name—identifies the schema element.

Value—the property value.

Flags—reserved for future use.

S_OK, E_FAIL, E_INVALIDARG—return values used for error handling.


Session State Example


Expanding on the earlier example, when the Web Part Picture of Car displays the selected car, it must make the name of the selected car available to the Web Part Get Sales Information. When the user navigates to the purchasing dashboard to place an order, the selected car is retrieved and displayed.

 


To accomplish this, Picture of Car uses the PutSessionState function, specifying the namespace URN, the name of the value to save, and the actual value associated with that name:

<SCRIPT language="JScript" id=s1>
function DisplayCarInfo(sCarSelected)
{
     switch (sCarSelected) {     

     }  
          DDSC.PutSessionState("urn:myCompany:Car", "SelectedCar", sCarSelected);
}
</SCRIPT>


When the purchase dashboard is initialized, the Web Part Purchase Car retrieves the stored session state using the GetSessionState function, specifying the namespace URN and the name of the value to display. It then adds the name of the selected car to the purchase form:

<TABLE border=0 cellPadding=1 cellSpacing=1 style="HEIGHT: 228px; WIDTH: 415px" width="75%">
  <TR>
    <TD>Selected Car:</TD>
    <TD><INPUT DISABLED="1" ID="CarsForSale" NAME="CarsForSale" SIZE="30"></TD></TR>

</TABLE>
<SCRIPT LANGUAGE=javascript>
CarsForSale.value = DDSC.GetSessionState ("urn:myCompany:Car", "SelectedCar");
</SCRIPT>

State Management Service

State management is a simple but essential feature of dashboard applications. The state of a Web Part or dashboard is the combination of standard Web Part and dashboard schema properties and any user- or system-defined extensions.

For example, a Web Part that displays a stock ticker must be able to save and retrieve customization information between sessions. In this case, the stock symbols the user selects are private data that, together with the values from the Web Part schema that you specify, constitute the state of the Web Part.

The Digital Dashboard Services Component allows setting and retrieving of content and individual property elements. Stored state information is location transparent; an object does not require information about the location in which its state is stored. Additionally, while the Digital Dashboard Services Component allows for maintaining personalized or global state for an object, all access to the dashboard and Web Parts through the PartCollection retrieves personalized state. For information on how to set the global state for a Web Part or dashboard, see “Item Retrieval” later in this paper.

It is important to note that state is stored with the Web Part. If you delete a Web Part, its state information is lost.

The following example shows an XML representation of the state for a Stock Ticker Web Part:

<?xml version="1.0" ?>
<Part xmlns="urn:schemas-microsoft-com:webpart">
<Title>Stock Ticker</Title>
<Description>Stock Ticker for my favorite stocks</Description>
<Content> … </Content>
<Zone>Right</Zone>
<PartOrder>0</PartOrder>
<LastModified>2000-01-27T13:55:01</LastModified>
<PartStorage>MSFT; COMP</PartStorage>
<Update xmlns=”urn:parts.utilities”>30min</Update>
</Part>

The state of the stock ticker Web Part can be manipulated by providing the Web Part URN and the name of the individual schema element. The following table lists some of the properties in the above example.

Namespace

Schema Element

Value

DAV:

CreationDate

4/2/00

urn:schemas-microsoft-com:webpart

Zone

Right

urn:schemas-microsoft-com:webpart

PartStorage

MSFT;COMP

urn:parts.utilities:StockTicker

Update

30min

The following sections list the objects, methods, properties, and parameters used by the State Management service.

Part Object

The Part object provides access to all of the properties that are defined for the Web Part. It also provides the capability to save property changes to the store.

Methods

Save (UpdateFlag);

PropCol Properties ();

Parameters

UpdateFlag—determines when the state is persisted. Deferred updates are persisted when the dashboard is unloaded. Possible values are the following:

·         IMMEDIATE (0)

·         DEFERRED (1)

PropCol—returned handle to the collection of properties defined for the Web Part.

Dashboard Object

Similar to the Part object, the Dashboard object provides access to all of the properties that are defined on the currently loaded dashboard. It also provides the capability to save property changes to the store.

Methods

Save (UpdateFlag);

PropCol Properties ();

Parameters

UpdateFlag—determines when the state is persisted. Possible values are the following:

·         IMMEDIATE (0)

·         DEFERRED (1)

PropCol—returned handle to the collection of properties defined for the dashboard.

PropertyCollection Object

The PropertyCollection object allows properties to be retrieved, set, added, or deleted. Only properties that are set for the object appear. Note that removing a property is not the same as setting the property value to NULL.

Methods

PropertyObject Add (PropertyName,);

Remove (Index);

PropertyObject Item (Index);

Count Count ();

Parameters

Index—identifies the property in the collection. The value of Index can be one of the following:

·         an integer that indicates the position of the property in the collection

·         a string, which is the combination of URN and property Name separated by the pound sign (#) or colon (:); for example, Part.Properties.Item (“urn:schemas-microsoft-com:webpart:PartStorage”).

Note   In the Add method, the value of Index must be a string.

PropertyObject—the returned property object.

S_OK, E_FAIL, E_INVALIDARG—return values used for error handling.

Property Object

The Property object provides access to an individual property value. The Digital Dashboard Services Component tracks whether a property has been changed since the dashboard was loaded. The Property object has the following properties:

·         URN

·         SchemaElement

·         Variant Value


State Management Example

In the following example, the Web Part Get More Information tracks the requester’s name and address so that it can be retrieved the next time the user accesses the dashboard. It stores these values in custom properties using the State Management service. For each property, the Web Part specifies the namespace and name in addition to the value for each property.

Later, the Web Part can retrieve this state through the Properties collection.

 

Following is the content of the Web Part Purchase Car. Note that the Web Part uses the string ‘varPart_WPQ_’ to reference itself. For more information on the string ‘varPart_WPQ_’, see the description of the Part object in the “Part Discovery Service” section of this document

<TABLE border=0 cellPadding=1 cellSpacing=1 style="HEIGHT: 228px; WIDTH: 415px" width="75%">
  <TR>
    <TD>Name:</TD>
    <TD><INPUT id=txtName_WPQ_ style="HEIGHT: 22px; WIDTH: 278px"></TD></TR>
         
</TABLE>
</P>
<INPUT id=load_WPQ_ type=button value="Remember Me" LANGUAGE=javascript onclick="load_WPQ__onclick();">
<INPUT id=save_WPQ_ type=button value="Place Order" LANGUAGE=javascript onclick="save_WPQ__onclick();">
<SCRIPT LANGUAGE=”javascript”>
function save_WPQ__onclick() {
          varPart_WPQ_.Properties.Add("urn:myCompany:Custinfo#CustName").Value =
                        txtName_WPQ_.value;
          varPart_WPQ_.Properties.Add("urn:myCompany:Custinfo#Address1").Value =
                        txtAddress1_WPQ_.value;
          varPart_WPQ_.Properties.Add("urn:myCompany:Custinfo#Address2").Value =
                        txtAddress2_WPQ_.value;
          varPart_WPQ_.Properties.Add("urn:myCompany:Custinfo#City").Value =
                        txtCity_WPQ_.value;
          varPart_WPQ_.Properties.Add("urn:myCompany:Custinfo#State").Value =
                        txtState_WPQ_.value;
          varPart_WPQ_.Properties.Add("urn:myCompany:Custinfo#Zip").Value =
                        txtZip_WPQ_.value;
          varPart_WPQ_.Save();
}
function load_WPQ__onclick() {
          txtName_WPQ_.value =
          varPart_WPQ_.Properties.Item("urn:myCompany:Custinfo#CustName").Value;
          txtAddress1_WPQ_.value =
          varPart_WPQ_.Properties.Item("urn:myCompany:Custinfo#Address1").Value;
          txtAddress2_WPQ_.value =
          varPart_WPQ_.Properties.Item("urn:myCompany:Custinfo#Address2").Value;
          txtCity_WPQ_.value =
          varPart_WPQ_.Properties.Item("urn:myCompany:Custinfo#City").Value;
          txtState_WPQ_.value =
          varPart_WPQ_.Properties.Item("urn:myCompany:Custinfo#State").Value;
          txtZip_WPQ_.value =
          varPart_WPQ_.Properties.Item("urn:myCompany:Custinfo#Zip").Value;
}
</SCRIPT>

Item Retrieval Service

The Item Retrieval service allows Web Parts to retrieve items such as Web Parts and dashboards from the store, even if they do not reside on the current dashboard. The items can then be modified the same way they can with the Part State Management service.

The following sections list the objects, methods, properties, and parameters used by the Item Retrieval service.

DDSC Object

The LoadItem method is provided on the DDSC object.

Methods

Item LoadItem (ID, LONG LoadFlag);

Parameters

ID—the identifier to the item (typically a URL) that should be loaded.

StateFlag—if personalization is supported by the store, StateFlag controls whether the Web Part properties retrieved are specific to the user or global (apply to all users). Possible values are the following:

·         USER (0)

·         GLOBAL (1)

Item—the item retrieved.

Item Object

The Item object provides the capability to retrieve or modify the content of an object in the store and the collection of Properties for the item. The Item object also provides the capability to save changes back to the store, much like the Part State Management service does. The item can also be deleted from the store by means of the Delete method. The Item object provides the following properties:

·         ID

·         Content

Methods

Save ();

Delete ();

PropCol Properties ();

ItemCol Contents ();

Parameters

PropCol—handle to the properties collection for the item.

ItemCol—handle to the contained items collection for the item.

ItemCollection Object

The ItemCollection object provides access to the items that are contained by a parent item. New items can be added to the parent collection through the Add method. Items can also be deleted from the store with the Remove method.

Methods

Item Add (Name, IsFolder);

Remove (Index);

Item Item (Index);

Long Count ();

Parameters

Name—The name of the item. Items must be uniquely named within their parent.

IsFolder—Indicates whether the item to create should be able to contain other items.

Index—The index used to identify the item in the parent item collection. It can either take the form of an integer that indicates the position of the item or the name of the item.