Adding a Silverlight PivotViewer control to your website is as simple as adding any other Silverlight control to your website. Your implementation of PivotViewer can be as simple as an application that loads a collection and handles links clicked in the Info Pane, or complex as an application that responds to the user’s facet selection and implements on-item buttons. This document provides an overview of the release package and information important to anyone intending to implement a custom PivotViewer control. For detailed information, see the PivotViewer API.

Release Package

The release package contains the following items:

• A bin directory with Pivot DLLs
• A sample XAP and HTML demonstrating implementation of PivotViewer API functionality
• A ZIP file containing source code to build the sample XAP in Visual Studio 2010
• A redist.txt file
• The End User License Agreement

Prerequisites

• Visual Studio 2010
• Silverlight 4 Tools for Visual Studio 2010
• Silverlight 4 Toolkit (released April 2010)

Note: The Pivot DLLs and sample XAP were tested with the April 2010 version of the Silverlight toolkit. To develop with the PivotViewer DLLs, or build the sample code included in the installation package you need to install the April 2010 toolkit. You do not need the toolkit installed to use the pre-built XAP.

Deploying Your PivotViewer Application on a Web Server

A web server which hosts PivotViewer applications must map the following MIME type:

• XAP - application/x-silverlight-app

A web server which hosts PivotViewer collections must map the following MIME types:

• CXML - text/xml
• DZC - text/xml
• DZI - text/xml

You will need to add a clientaccesspolicy.xml file to the root directory of the servers hosting DZC and CXML content. For more information on clientaccesspolicy.xml files please refer to the following link: http://msdn.microsoft.com/en-us/library/cc197955%28VS.95%29.aspx.

Using the Sample XAP

The sample XAP and HTML included in the release package will not work correctly when the HTML is opened locally from the file system. Specifically, collections will load, but Deep Zoom imagery will not.

In order to use the sample XAP and HTML, it must be deployed on a web server (and MIME types must be mapped as described above).

Alternatively, the source code for the sample XAP may be unzipped and built in Visual Studio 2010. When running the web project from Visual Studio 2010, a development web server will be started to host the project (the Visual Studio 2010 development web server automatically maps the required MIME types).

Localization and Globalization

The PivotViewer control is globalization aware. Dates and numbers display in a format determined by the client OS culture. PivotViewer custom date formats, such as those shown in Graph View when drilling into DateTime categories, are defined in the resources file.

We highly recommend using the same CurrentCulture and CurrentUICulture.

How to Localize the Control

You have the option of providing localized strings for all string resources in the PivotViewer.

To provide resources externally:

1. Create a resources file (e.g. SampleResources.resx) in your XAP project and add the string resources you would like to localize.
2. Use the PivotViewer.SetResourceManager() API method to set the external ResourceManager.

PivotViewer.SetResourceManager(SampleResources.SampleResources.ResourceManager);

For each string resource required by PivotViewer, the control will query to determine if there is a developer-defined resource in the ResourceManager. If the resource is not in the ResourceManager, the control will use the default string resource.

Once the string resources are externalized, you can localize your application in the same manner as any other Silverlight application. Instructions for creating satellite assemblies can be found here: http://msdn.microsoft.com/en-us/library/dd941931(v=VS.95).aspx

After your resources are localized, you may have multiple resources in your XAP application e.g.SampleResource.fr-Fr.resx (for fr-FR), SampleResource.es-ES (for es-ES) etc.

Please ensure that all cultures for which you have resources have a tag in the .csproj file.

<SupportedCultures>en-US;fr;fr-FR;es-ES;</SupportedCultures>

Finally, in the aspx or html file where you reference your XAP, specify the culture you would like to use.

<param name="culture" value="fr-FR" />
<param name="uiculture" value="fr-FR" />

Please see the sample XAP included in the release package for more information.

Control Considerations

Here are items you should consider when building a PivotViewer-based Silverlight control.

Setting Width and Height

The width and height of the control must be constrained by a finite amount. If you put your PivotViewer control in a Grid and you just want the control to fill the available space, set the Width and Height of any RowDefinitions or ColumnDefinitions corresponding to rows and columns containing a PivotViewer to “*”. Setting Width or Height of such rows and/or columns to “Auto” will cause items not to render.

Containers with infinite dimensions (such as StackPanels) will not work without other dimensional constraints.

ViewerState

When you call LoadCollection with a collection Uri and a ViewerState, you should always use a fully formed ViewerState including both the desired view, and the desired sort.

• If you omit setting a value for facet0, the entire ViewerState is ignored, and the collection will return to Grid view with the default sort value
• If you omit setting a value for view, there behavior is dependent upon whether you are also changing the collection Uri. If so, the new collection will be loaded in Grid view and the sort value you specified will be applied. Otherwise, nothing will happen at all. (You will not be returned to Grid view)
• If you specify both values, but one or the other is invalid (ie, not applicable to the current collection, such as $view$=3 or $facet0$=foo, the invalid value is ignored and the valid value is used. So for example, if you want to switch the user to histogram view programmatically, you need to include a "$facet0$=foo" in the ViewerState. The facet value you provide doesn’t matter as the control will detect that the facet value you provided is invalid and set it to the first valid facet category.

Control Bar Applied Filters

If you load one collection, apply filters, and then load another collection, the filters will continue to appear in the control bar unless you clear the ViewerState before loading the new collection.

Popups

Every Popup containing a PivotViewer needs to be parented by some other element in the visual tree. If a popup containing a PivotViewer is not parented, there will be input problems when the browser zoom level is not 100%.

Full Screen

For security reasons alpha-numeric keys are disabled in full screen mode in Silverlight. For more information please refer to this article: http://msdn.microsoft.com/en-us/library/cc189023(VS.95).aspx#Entering_Full-screen_Mode

Exceptions

An exception can occur when the custom date range control in the Filter Pane appears on screen. You check for this exception (in the handler for the Application.UnhandledException event) and ignore it with no known side effects.

Item Imagery

DeepZoom is used for imagery in Pivot. A good understanding of the technology will help with building and refining collections.

Multiple DZCs

The PivotViewer control only supports displaying images from one DZC per collection. If you provide multiple DZCs in a collection only some images will display.

Unspecified Images

If images are not specified in the DZC file, the PivotViewer control will show blank space where the image should be. It is highly recommended that you build collections with an image for every item.

Repeated Images

The DZC for the collection should have an entry for every CXML item. If imagery is repeated, multiple entries in the DZC can point to the same DZI.

In histogram view each CXML item may be part of more than one histogram bucket. If items are repeated in this way, the duplicate item will display with a slight delay.

Blank Images

There are a number of reasons images may appear blank in the PivotViewer:

• Images are improperly specified in the DZC file
• The server hosting the DZC file does not have a clientaccesspolicy.xml file

Performance

The Silverlight Pivot Control was created to perform well with collections of up to 3,000 items on a variety of machines.

Larger collections will load in the PivotViewer, but they will not be as performant.

Caching

All content requested by the control (example: CXML and DZC files) may be cached by your browser. Based on your server’s caching configuration if your collection content changes, you may need to clear your cache to see updates immediately.

Security

When developing for the Silverlight Pivot control it is important to keep security in mind, the following four areas of Silverlight Pivot that may require in-depth analysis before deploying to your service.

HTTPS

If you decide to host your control on an HTTPS site, the CXML and DZC need to be hosted on HTTPS servers as well. Mixing secure and unsecure content is not supported in the PivotViewer control as it can create vulnerabilities that put the secure page at risk.

User input via the search box

Users can enter free-form text into the search box in the filter pane. This text should not be trusted, though it is exposed to your Silverlight runtime through the applied filters and ViewerState in the public API.

Untrusted CXML

Use caution when implementing the ability for end-users to request CXML from untrusted sources.

Stress

It is important to understand the performance characteristics of your system and stress implications of the collections your system is hosting. This is especially true if you are using the API to listen to events happening on the client or have large collections that require significant computation or throughput.

Encryption

Similar to any open HTTP request, CXML files are transmitted and loaded into the control without encryption.

Using the Pivot Client

If you use the Pivot client in conjunction with the Silverlight PivotViewer, please be aware of the following issue: if you load a collection in PivotViewer and then load the same collection in the Pivot client (or vice versa), the collection imagery will not display. To recover, clear your cache and restart the Pivot client.

Help Dialog