PivotViewer, Silverlight

PivotViewer – Working with Facets

PivotViewer series

  1. Building your first PivotViewer application
  2. Runtime PivotViewer collection creation
  3. PivotViewer – Working with Facets
  4. Handling PivotViewer events
  5. PivotViewer – Custom actions
  6. PivotViewer and MVVM


In this next tutorial about the Silverlight PivotViewer control I would like to give a little more depth on Facets. What are facets, and how are they used in runtime generation of collections using the PivotServerTools library.

This tutorial continues on techniques from last tutorial about runtime collection creation. If you are just getting started using the PivotViewer control, you might want to have a look at the Getting Started Tutorial first. This tutorial is centered around the methods build in the last tutorial: MakeCollection and MakeItem.



Facets are basically the properties on the PivotViewer that allow the visitor to sort and filter. Facets are also shown when viewing the details of an item.


Facets are added to the collections by calling the Collection.AddItem() method. This method takes a couple of parameters. The first is the Name of the item being added. The second is a URL. This can be used to navigate to more details about the item for example. This URL is used when clicking on the Name of the item in the details panel. Then there’s the Description of the item. This text is shown on the details panel. The fourth parameter is the image shown in the DeepZoom part of the control. The ItemImage type from the PivotServerTools. Its constructor is used, to which a URL to the image is given. All parameters after that, from the fifth on are Facets. You can add as many as you need. A call to AddItem might look something like this:

        new ItemImage(new Uri(image)),
        new Facet("String value", FacetType.Text, id),
        new Facet("Integer Value", FacetType.Number, intValue),
        new Facet("Double Value", FacetType.Number, doubleValue),
        new Facet("Date value",FacetType.DateTime,date),
        new Facet("Url Value",FacetType.Link, new FacetHyperlink("Url Value", urlValue)),
        new Facet("Names", names),
        new Facet("FormattedValue",formattedValue)





Facets are grouped in Facet Categories. Every item in the collection can contain one or more facet categories and every category can contain one or more facets. Facet categories are created when a they are used for the first time while adding items to the collection.

 FacetDetails The PivotServerTools library is used to generate the .CXML. It uses 4 types of facets categories:Text, Number, DateTime and Link. The type of facet category determines how facets are displayed in the PivotViewer control.  Each facet in the category must be of this type.


The text type is used to display anything of type string. If the type is omitted and the type can’t be determined automatically the Text type is defaulted to.

To create a facet of type text you can use its constructor with a category name, the type of facet and its tag. For example:

Facet stringFacet = new Facet("Names", FacetType.Text, name);





This might look something like this in the PivotViewer control.



This facet type is used to display numbers. It allows the end-user to make selections on ranges of this tag. This tag value can also be formatted which I’ll explain later.

Again, to create a facet of this type, use its constructor and pass in a different FacetType this time:

 Facet integerFacet = new Facet("Integer Value", FacetType.Number, intValue);
 Facet doubleFacet = new Facet("Double Value", FacetType.Number, doubleValue);



Dates are displayed like in the image below. You can select a date by era, the actual value or select a custom range.

The date facets are added the same way as numbers or text, but with a different FacetType.

Facet dateFacet = new Facet("Date value",FacetType.DateTime, date);


Hyperlinks are not shown in the filter list. Only the name given to the URL is shown in the details list.  Clicking on a link does not navigate by default. You’ll have to implement the navigate yourself. An event is fired when an item on the details panel is clicked though.

To create a facet of type link you can use its constructor again. Only the third parameter is different this time. It takes a value of type FacetHyperLink. The type uses a description and a URL together. In the code below both are passed into the constructor of FacetHyperLink. Both parameters are strings. 




Facet linkFacet = new Facet("Url Value", FacetType.Link, 
                            new FacetHyperlink("Displayed Name", urlValue));


One last thing to notices about adding items to the collection. As I mentioned earlier, every facet category can be used zero or more times. The constructor of Facets takes one or more values for a value for each tag. You could, for example, add an array of strings to a category at once just by passing that array to the constructor. All values will be shown in that category on the details panel.

string[] myNames = {"Timmy Kokke", "Sorskoot"};
Facet namesFacet = new Facet("My Names",FacetType.Text, names );


More on categories

After the items are added to the collection you can fine-tune the categories a little further. Often it is necessary to make facet categories visible in only the details panel or enable filtering for a particular category but disable text search on them. The Collection class has a method to set these properties.

The SetFacetDisplay method takes the name of the category and 3 booleans.  The first of the three booleans indicated whether or not the category is shown in the list of filters. The second enables or disables the category showing up in de info panel. When the last is set to false the category is excluded from the text search.

Here are a few examples.

collection.SetFacetDisplay("Integer Value", true, false, false);
collection.SetFacetDisplay("Double Value", false, true, false);
collection.SetFacetDisplay("Names", true, true, false);

The Integer Value category is shown in the list of filters, but hidden from the info panel and the text search. The Double Value category is hidden from the filters and the text search, but is visible on the info panel. The Names category is visible in both filters and info panel, but isn’t used for text search.

The Collection class has one other method of interest concerning facets. The SetFacetFormat is used to set format of a category in which it is displayed. It uses standard .NET string formatting. For example, to display a double as a floating point with 3 decimals you can use the following code:

collection.SetFacetFormat("FormattedValue", "F3");





The code that goes along with this tutorial can be downloaded here. The next tutorial will be about the events of the PivotViewer control. To be the first to know when it is released you can subscribe to the RSS-feed or follow me on twitter.

Technorati Tags: ,



kick it on DotNetKicks.com


Shout it


  1. Tim I have created serveral collections from database stored procedures, using your example.
    I have 2 questions
    Is it possible to create jit collections that are more graphical say using a template of some kind, similiar to what can be done with the none jit collections you create?

    Also what is the best way to pass paremters down to the collection factory?

  2. There are a few ways to generate images, but I wouldn’t advice to do that at runtime. It takes time to generate images.

    However, you can use this tool (http://pauthor.codeplex.com/wikipage?title=PauthorLib%20Overview&referringTitle=Documentation) to generate images for your collection.This would be the easy way. Building an app that does the same but uses Xaml isn’t that hard.

    A more complex route to take when you absolutely need to generate images at runtime is to create DeepZoom pyramids and cache the images. Only update the images when they are changed. The downside is that you’ll have to build everything yourself, all handlers and stuff. The .cxml file uses an index for the images, so you’ll have to find a way to manage that. I’ve been experimenting with this technique, but haven’t managed to build it into a working demo yet.

    About the parameters. In the JIT sample provided with the PivotViewer parameters are passed through the URL. The MakeCollection method takes an CollectionRequestContext as a parameter. This context contains a dictionary with the querystring parameters.
    For example: string odataUrl = context.Query[“src”];
    You should have a look at the ODataCollectionSource class in the JIT sample (http://www.silverlight.net/learn/pivotviewer/download-just-in-time-tools/).

    Good Luck!

Leave a Reply

Seo wordpress plugin by www.seowizard.org.
%d bloggers like this: