Web Templates are the way to go

Back in SharePoint 2007 we had two options for templating sites: we could either save sites as templates which resulted in unmaintainable STP files or create Site Definitions and deploy them using Solution Packages. In both scenario we were locked and unable to change the template. Even though Site Definitions were deployed using solutions, changing them after sites have been created off them was not allowed and creating another Site Definition was the only option. Unfortunately, since Site Templates didn’t support Publishing Sites, creating Site Definitions was the only option in SharePoint 2007 if you had to offer the publishing capabilities in your template.

With the release of SharePoint 2010 Microsoft introduced Web Templates – a new, highly flexible concept for templating sites. Because there is no reference between the created site and the Web Template itself modifying Web Templates is not a problem. There is no restriction to the capabilities supported by Web Templates so you can use them with any kind of sites that you want. Additionally Web Templates can be deployed on both Farm and Site Collection level using a Farm or Sandboxed Solutions and that allows you to use Web Templates with SharePoint Online. And although Web Templates have some limitations, they are the recommended way of templating sites in SharePoint 2010.

Sandboxed Web Templates

Web Templates can be deployed on specific Site Collections only as opposite to the whole Farm and with that they can be deployed using Sandboxed Solutions. This offers great flexibility to IT-Pros, developers and power users. Sandboxed Solutions require virtually no maintenance from IT-Pros. Site Templates created by power users are saved as Sandboxed Solutions and with some effort they can be extended by developers with new functionality. Distributing Web Templates using Sandboxed Solutions allows you to truly benefit of the customization capabilities of the SharePoint 2010 platform and create business solutions that are usable both on-premise and on-line.

Although there is no difference in building Web Templates for the Sandbox and Farm Solutions, there are some differences in how SharePoint provisions contents of Sandboxed Solutions. One of those difference impacts using Web Templates for templating sites.

Inconvenient Sandboxed Web Templates and Navigation

Imagine we had a Web Template distributed with a Sandboxed Solution. The Web Template is a template for a Publishing Site used for creating subsites on a Publishing Site Collection with anonymous access. As soon as you create a subsite off the Web Template what you will see is that the link to that particular site is automatically added to the navigation.

This works as expected given we are authenticated and have access to pages that haven’t been published yet. Unfortunately if you access the same site as an anonymous user you will still be able to see the link to the newly created subsite that hasn’t been published yet!

It’s not that hard to imagine that as soon as you click this link you will see a 404 error: after all the Welcome Page of that subsite hasn’t been published yet and therefore is not available for anonymous users.

If you now go back to the newly created subsite and check in the Welcome Page as draft, the link to that subsite will disappear from the navigation for anonymous users – just as you would expect it to in the first place.

This odd behavior has partly to do with the fact how Sandboxed Solutions provision files by default. Whenever you provision a file using a Module in a Sandboxed Solution that file will remain checked out and there is no version checked in at all. What’s surprising is how SharePoint Navigation Providers deal with that scenario. Instead of hiding the link to the website, the link is displayed in the navigation and if the content author isn’t careful enough, such “broken” links will appear to anonymous users.

Sandboxed Web Templates and Navigation – better together

Provisioning files as checked out without any version checked in is how Sandboxed Solution handle Modules by default. Unfortunately there is now way to change this behavior declaratively and with that there are two solutions that you can choose from.

Teach, teach, teach

One approach that you could choose for is to stick with the standard SharePoint 2010 behavior and educate content authors to always check in the Welcome Page after creating a subsite. This is useful not only to prevent broken links to be displayed in the navigation but also to allow other members of the content authoring team to edit the contents of the Welcome Page. The great benefit of this approach is that you stick with the standard approach and instead of altering it or introducing custom solutions you educate users about the issue and potential consequences.

Check it in… automatically

Another choice that you have is to add a Feature Receiver to the Feature responsible for provisioning the Welcome Page and have it automatically check in the Welcome Page as a draft. With that the Welcome Page remains invisible to anonymous/unprivileged users and no additional effort is required from the content authors. The only downside is that custom code is required and is something that cannot be created by power users themselves and would need to be maintained and tested in the future.

As you can imagine both approaches have their pro’s and cons. It’s important to know that neither of them is better than the other and which one you choose depends a lot on your team and requirements.

Summary

Web Templates are the new recommended way for templating sites in SharePoint 2010. Unfortunately when used with Sandboxed Solutions, when you create a subsite off a Web Template, a broken link is added to the navigation for all users. This inconvenience can be solved by either manually checking in the Welcome Page of the subsite or using custom code and the choice for either approach should be made based on the requirements of the particular scenario.

Templated Controls are the way to go

When building public-facing websites the HTML is the center of the universe. At the end of the day it’s the HTML that has a big influence on the success of your website. By crafting proper HTML you can ensure that your website is accessible for all users and devices, you can optimize its contents for search engines and in many cases you can even improve the perceived performance of your web pages. You can achieve all of this if you construct HTML optimized for the specific needs of your website and its content.

Assuming that you’re following this pattern, of starting from HTML and implementing it into SharePoint, it’s only the matter of time until you find that some of the standard available controls and Web Parts won’t support your HTML. In such cases developers often choose either to build their own controls that produce just the right HTML or to change the HTML to match the output of the standard SharePoint 2010 controls. It’s not that hard to imagine that neither of those choices are great in long term and preferably you would like to have another possibility.

When it comes to building public-facing websites, where the HTML is the foundation of the user experience, Templated Controls are probably the best approach to choose. Because they separate the functionality from the UI you can use one and the same control to build virtually any kind of HTML imaginable. Previously on my blog I’ve showed you how you can leverage the concept of Templated Controls for building menus and breadcrumbs.

Many faces of building websites in SharePoint 2010

When building public-facing websites, or any other solution for that matter, on the SharePoint 2010 platform there are two ways in how you can approach the process: you can choose for a more structured and repeatable process based on automation, Solution Packages and Features or you can leverage the customization capabilities of the SharePoint and move away from the custom development path.

A structured and repeatable approach offers you great control and lowers possible risks. The consequence of using it is however that you will end up spending more time to automate your deployment and test your solution in all the different environments. Customization-based approach on the other hand is great for working in dynamic teams where adjustments or changes have to be done immediately and where they are related to content management rather than business logic.

It’s important to understand that there is no “best practice” and that you should always make educated choice about which approach you choose based on your situation and requirements. You should however be always able to choose out of those two approaches and not be limited to a certain choice.

Inconvenient Templated Controls and customized Master Pages and Page Layouts

Templated Controls allow you to separate the business logic from the UI and with that create truly reusable components: while the business logic is often the same within the whole organization, different teams or brands have very likely their own way of presenting things to the end users.

When working with Templated Controls you can define the presentation layer using Templates. The exact number of those templates depends of course on the control that you are using, but the mechanics is the same for all them. The following code snippet shows an implementation of a breadcrumb using the Mavention Templated SiteMapPath control that I have built recently:

<Mavention:TemplatedSiteMapPath runat="server">
    <HeaderTemplate><div id="breadcrumbs"></HeaderTemplate>
    <RootNodeTemplate><a href='<%# Eval("Url") %>'>home</a></RootNodeTemplate>
    <NodeTemplate><a href='<%# Eval("Url") %>'><%# Eval("Title") %></a></NodeTemplate>
    <CurrentNodeTemplate><%# Eval("Title") %></CurrentNodeTemplate>
    <SeparatorTemplate> / </SeparatorTemplate>
    <FooterTemplate></div></FooterTemplate>
</Mavention:TemplatedSiteMapPath>

Here is another control that I have used recently to render meta description:

<Mavention:FieldValue FieldName="MetaDescription" runat="server"><ContentTemplate><meta name="description" content='<%# Eval("FieldValue") %>' /></ContentTemplate></Mavention:FieldValue>

While both controls work great, as soon as you customize the Master Page you will see the following error message:

Plan for customization

There is a difference between how SharePoint handles customized and uncustomized Master Pages and Page Layouts. One of those differences is that by default no inline code is allowed on customized pages. As I have just showed you, although some code might work just perfectly on uncustomized pages, it can break as soon as you customize them.

Although you could suppress this security feature by registering a Page Parser Path, it introduces a security risk. As soon as you define a Page Parser Path everyone with write access to the files in that path will be able to include server-side code that could potentially break your entire farm! With that you should be really careful with designing your solutions with dependencies on Page Parser Paths.

The customization capabilities of SharePoint 2010 are very powerful and just because you might not use them at first doesn’t mean you won’t be using them later on. It is therefore important that you take the customization scenarios into account and check if the code that you are using works properly with customized pages. Without this it is only the matter of time until you find yourself facing a choice: not using customization capabilities, even though it might make just perfect sense for that particular scenario, or refactoring all the code that doesn’t work with customized pages. As you can imagine neither of those choices is a great option and if you will eventually refactor the code why not do it in the first place?

Templated Controls and customized Master Pages and Page Layouts – better together

Templated Controls do support customized pages. There are however a few things that you have to take care for to ensure that your code snippets won’t break pages once they are customized.

Using the out-of-the-box

In both examples that I have showed you before I have used content templates based on static HTML calling the Eval method to get the underlying data. It’s the combination of static HTML and Eval that causes the error that we have seen after customizing the Master Page. Because the Eval method is called directly from the content template it’s being considered in-line code which is not allowed on customized pages. In order to solve this issue all you need to do is to ensure that all calls to the Eval method happen from within a server-side control.

If we look at the code samples I have showed you previously, we could refactor the breadcrumb to look as follow:

<Mavention:TemplatedSiteMapPath runat="server">
    <HeaderTemplate><div id="breadcrumbs"></HeaderTemplate>
    <RootNodeTemplate><asp:Hyperlink NavigateUrl='<%# Eval("Url") %>' Text="home" ID="Link" runat="server" /></RootNodeTemplate>
    <NodeTemplate><asp:Hyperlink NavigateUrl='<%# Eval("Url") %>' Text='<%# Eval("Title") %>' ID="Link" runat="server" /></NodeTemplate>
    <CurrentNodeTemplate><asp:Literal Text='<%# Eval("Title") %>' ID="Node" runat="server" /></CurrentNodeTemplate>
    <SeparatorTemplate> / </SeparatorTemplate>
    <FooterTemplate></div></FooterTemplate>
</Mavention:TemplatedSiteMapPath>

By replacing static HTML with ASP.NET controls we can work around the security feature and have our breadcrumbs work both with uncustomized and customized pages:

As for refactoring the second control – the meta description tag you could use the HtmlMeta control that is a part of the ASP.NET framework:

<Mavention:FieldValue runat="server" FieldName="MetaDescription"><ContentTemplate><asp:HtmlMeta Name="description" Content='<%# Eval("FieldValue") %>' ID="MetaDescription" runat="server" /></ContentTemplate></Mavention:FieldValue>

The only downside of this approach is that because we have to specify the ID for the HtmlMeta control the ID will be added to the output HTML and we will end up with HTML similar to following:

<meta id="ctl00_ctl01_ctl00_MetaDescription" name="description" content="Meta description 123" />

Although it’s still valid (X)HTML the id attribute is somewhat pointless yet necessary from the ASP.NET perspective.

Another approach that you might consider is somewhat more complex to come up with and to manage but it gives you some more control of the output HTML:

<Mavention:FieldValue runat="server" FieldName="MetaDescription"><ContentTemplate><meta name="description" content="<asp:Literal Text='<%# Eval(&quot;FieldValue&quot;) %>' runat='server' ID='FieldValue' />" /></ContentTemplate></Mavention:FieldValue>

As you can see we still use static HTML here but in the content attribute we inject the ASP.NET Literal control to have the binding executed in the context of a server control. The biggest challenge in this approach is trying to follow the code and having all the quotes, especially when they are nested, in the right place.

Building custom controls

Although ASP.NET provides you with many controls that should be sufficient for most scenarios, there are situations when you might want that extra bit of control of the output HTML: after all this is exactly the reason why we chose for Templated Controls in the first place. In such cases you have two options: you can build your own custom controls or using an alternative templating mechanism.

Building your own set of custom controls is not that complex and requires no new skills other than what you already can, assuming you are a SharePoint developer. Unfortunately it undermines the whole concept of using Templated Controls since custom control have to have at least partial knowledge about the HTML that they are supposed to render and with that it’s very likely that you won’t be able to reuse them with other solutions.

Another thing that you could do, and that would give you full control of the output HTML is to use a templating mechanism other than the default binding, for example:

<Mavention:FieldValue runat="server" FieldName="MetaDescription" UseStringTemplateRendering="true"><ContentTemplate><meta name="description" content="$FieldValue$" /></ContentTemplate></Mavention:FieldValue>

Notice how the call to the Eval method has been replaced with a custom $FieldValue$ token. Also to notify our control that we want to use the alternative templating method we have set the UseStringTemplateRendering property to true. During the rendering stage of the process the control will check if it should use the standard or the string-based rendering process and if the later is the case, it will basically do a string replace on all registered parameters which in this case is $FieldValue$.

protected override void Render(HtmlTextWriter writer) {
    if (UseStringTemplateRendering) {
        if (FieldValue != null) {
            StringBuilder sb = new StringBuilder();
            using (StringWriter sw = new StringWriter(sb)) {
                using (HtmlTextWriter htw = new HtmlTextWriter(sw)) {
                    base.Render(htw);
                }
            }

            writer.Write(sb.ToString().Replace("$FieldValue$", FieldValue as string));
        }
    }
    else {
        base.Render(writer);
    }
}

Because no ASP.NET bindings are used we can now support both uncustomized and customized pages and have full control of the output HTML which is essential if you want to build public facing websites on the SharePoint 2010 platform and to have HTML to be leading in the process.

Summary

Templated Controls are a great way for separating the UI from the code and creating reusable components that support every kind of HTML markup. Unfortunately because there is a difference in how SharePoint treats uncustomized and customized pages, it’s challenging to work with Templated Controls and support both types of pages. In such cases using an alternative templating approach is often the best choice that offers the most flexibility and control over the output HTML.

Inconvenient switching Page Layouts

When the Ribbon has been introduced with SharePoint 2010 almost all of the UI has been redesigned to make it more intuitive and easier to use. As a result most of the options have been put in a different place than where they used to be in SharePoint 2007.

In SharePoint 2010 almost all of the tasks related to working with Publishing Pages are available from the page itself. This is very convenient for content authors and content managers since they have easy access to all functionality that they need to do their work.

The only problem is that if the page is broken, you don’t have the access to most of the options that you could use to fix that page! Because the associated Page Layout is not a field it is not accessible via the Edit Properties page and the only way to change is to navigate to the page and use the Ribbon. But if the page is broken, all you will see instead is an error message.

In such case you can either recreate the page with all the data, losing the version history and perhaps some other information or you can try to fix the Page Layout which might not always be a viable option for the given moment. So is there anything else that we could do?

SharePoint gem

Back in SharePoint 2007 you could change the Page Layout of a Publishing Page by navigating to the Page Settings page. Unfortunately in SharePoint 2010 this page is no longer accessible via the UI. The great news is though, that this page is still available and that we can still use it to change the associated Page Layout for a broken Publishing Page.

You can access the Page Settings page by appending to the URL of the site _layouts/PageSettings?Page=id and replacing the id with the ID of the Publishing Page, for example:

http://mavention/PressReleases/_layouts/pagesettings.aspx?Page=1

While this works, it is pretty inconvenient to get the ID of the Publishing Page that is broken. There is however a better way to access the Page Settings page.

Opening the Page Settings page with Mavention Publishing Page Settings

Mavention Publishing Page Settings is a Sandboxed Solution that upon installation adds a new button to the Ribbon in all Pages Libraries. Using that button you can open the Page Settings page for the selected Publishing Page.

When you first navigate to a Pages Library the Page Settings button is disabled.

Once you select a Publishing Page it becomes enabled.

After you click the Page Settings button, the Page Settings page will be opened in a modal dialog window – which is exactly how you want it to be in SharePoint 2010.

Using the Page Settings page you can now change the Page Layout of your broken page.

Summary

When working with Publishing Pages there are situations when the Page Layout is broken and you cannot change it, because the only option to change the Page Layout of a Publishing Page is located on that page itself. Using the Mavention Publishing Page Settings solution you can easily change the Page Layout of a Publishing Page from within the Pages Library.

Download: Mavention Publishing Page Settings (1,29KB, Sandboxed WSP)

What is Mavention Solution Store Builder

Mavention Solution Store Builder is a SharePoint 2010 Solution that allows you to easily build an Enterprise Solution Store for your own organization. It uses a Document Library to store Solutions and you can have multiple Document Libraries spread across multiple Site Collections that will make up your Enterprise Solution Store.

Building an Enterprise Solution Store with Mavention Solution Store Builder

After deploying the Mavention Solution Store Builder Solution your Enterprise Store will be installed. You can confirm that if you see the Enterprise Store tab added to the Gallery.

Since no configuration for the Enterprise Store has been provided yet, you will see an error message when you open it.

In order to build an Enterprise Store you have to do two things: you have to create at least one Store Catalog Library where you will upload your Solutions and you have to deploy a configuration file that will point to all the locations of all your Store Catalog Libraries.

Creating a Store Catalog Library

The Mavention Solution Store Builder Solution contains the Store Catalog List that can be used to create catalog libraries for storing Solutions. In order to install this List Definition you have to activate the Mavention Solution Store Builder Store Library Site Collection Feature.

After activating the Site Collection Feature you can continue with creating Store Catalog libraries. You need at least one Store Catalog library and you can have as many of them as you want. There is no limitations as to where those libraries are located as long as their contents can be requested by the current user.

Configuring Enterprise Store

After you have created Store Catalog libraries the last thing that you need to do is to let the Mavention Solution Store Builder know where your Store Catalogs are located. You can do this by using a configuration file that must be called Mavention.SharePoint.SolutionStore.dll.config and must be located in the 14\TEMPLATE\LAYOUTS\AddGalleryProviders folder. The following code snippet shows the sample structure of the configuration file:

<configuration>
  <Provider>
    <Sources>
      <SharePointLocal SiteUrl="http://mavention" ListName="SolutionCatalog"/>
    </Sources>
  </Provider>
</configuration>

For every Store Catalog you have to create a SharePointLocal element and have its SiteUrl and ListName attributes point to respectively the site where the Store Catalog library is located and the name of the Store Catalog library.

After you have created the configuration file you have to deploy it to the right location. You could do this manually but it’s definitely a better idea to follow the pattern I have described in my previous article and to have the configuration file deployed using a SharePoint Package.

If you have done everything correctly, if you would navigate to the Enterprise Store now all you should see would be an empty page. Although the Store Catalog is in place there are no Solutions in it yet, so this is what we will do next: upload some Solutions to the Store Catalog.

Uploading Solutions to the Store Catalog

In this release of Mavention Solution Store Builder the Store Catalog is simplified version of what’s possible to achieve using the Gallery capability. At this moment using a Store Catalog you can upload a Sandboxed Solution, provide its title, description, comma-separated list of categories, image, and URL to the image and EULA. One more thing, that probably has the most influence on how the Solution will be installed is the Solution Code Type property that I explained in my previous article.

Important: If you set the Solution Code Type property to Full Tust code your Solution will not appear in the Gallery since this Solution Code Type is not supported by the Gallery at this moment.

To support the review process of uploaded Solutions, the Store Catalog List Definition has the Approval Workflow enabled and allows to view draft versions only by users who have Approval Permissions by default. Those settings will be applied by default to every Store Catalog Library that you create. With this you can control when Solutions become available to users but you can configure the settings for your organization by altering the list configuration.

Once you’ve uploaded and approved your Solutions they will appear in the Enterprise Store ready to be downloaded and installed by your users.

Summary

Mavention Solution Store Builder is a solution that allows you to easily create a simple company-wide Solution Store for your organization without any custom development. Although it doesn’t offer full capabilities of the Gallery component of SharePoint 2010 it gives you a quick start in providing you with a mechanism to deliver your custom Solutions to your users.

Download: Mavention Solution Store Builder (151KB, WSP)

Extending the SharePoint platform

Probably the greatest strength of the SharePoint 2010 platform is its extensibility capabilities. While SharePoint 2010 contains some standard functionality, it’s the ability of configuring it, customizing it and building on top of it that allows you to get the very most out of SharePoint for your organization.

When building SharePoint solutions there are a number of options you can choose from. One approach is to use nothing more than standard functionality provided with SharePoint and use nothing more than configuration capabilities of those standard components. Another approach is to use the Client Object Model (Silverlight or ECMA script) to interact with SharePoint data. Finally you can use the server API to get the richest integration with the SharePoint platform. No matter your choice, once done, you would very likely package your solution to make it easy to install and reuse for your end users. An Enterprise Solution Catalog seems like a great way to deliver such solutions to end user so that they can install them on their sites.

Enterprise Solution Catalog – the requirements

An Enterprise Solution Catalog is a platform for showcasing and distributing SharePoint solutions within your organization. As opposite to a public marketplace, an Enterprise Solution Catalog is internal only meaning that you can ensure that your intellectual  property will not leave the organization and yet have all the different departments and teams benefit of each others work.

From the publishers perspective an Enterprise Solution Catalog should at least support a way to upload solutions alongside with some information about them such as title, description, purpose, etc. Organization might want to have some process in place that would allow them to review the uploaded solutions and control how they appear in the Solution Catalog. Finally end users should be given the ability to easily discover available solution and install them without too much work.

Catalog? It’s already there!

Given those requirements we could build a custom solution that would become an Enterprise Solution Catalog. Did you know however, that SharePoint 2010 provides you with an extensible mechanism for building your own Enterprise Solution Store?

Although it’s not that well known or documented you might have noticed it whenever you create a new List or Site – the Office.com link in the Create dialog window.

Although clicking the Office.com doesn’t do much at the moment, it is a good example that shows how you can extend the Create dialog and add your own Enterprise Solution Store to it.

Anatomy of a solution provider

The Create dialog in SharePoint 2010 is built around a provider model: every link is an implementation of a Gallery Provider that is responsible for returning Gallery Items (solutions).

How it works: retrieving available providers

Every time the Create dialog window opens the Gallery is loaded. The Gallery is driven by the 14\TEMPLATE\LAYOUTS\AddGallery.aspx Application Page and the Gallery Silverlight application is located in the 14\TEMPLATE\LAYOUTS\AddGallery.xap file. The Application Page contains the AddGalleryWebPart Web Part which is the backbone of the Gallery mechanism and facilitates communication between the UI and Gallery Providers.

One of the first calls made after opening the Create dialog window is retrieving available Gallery Providers which in this case is nothing more than an assembly located in the 14\TEMPLATE\LAYOUTS\AddGalleryProviders folder. Out of the box you can find there the AddGallery.OfficeOnlineProvider.dll assembly which contains the implementation of the Office.com Gallery Provider and is a great resource to see how a Gallery Provider works.

Important: Gallery Providers are Farm-wide so you cannot install them for specific Web Applications/Site Collections only.

After available Gallery Providers are enumerated, their assemblies are streamed to the Gallery application and loaded.

How it work: loading a Gallery Provider

After the assembly with Gallery Provider has been loaded in the Gallery application the available Gallery Providers are instantiated. Each Gallery Provider is a class that inherits from the Microsoft.SharePoint.Solutions.AddGallery.Provider.ClientFilteredProvider<T> base class. That class can be found in the AddGallery.Provider assembly located inside the AddGallery.xap file.

After the Gallery application has discovered Gallery Providers’ classes it instantiates them and adds them to the UI of the Gallery application.

How it works: configuration

Right after a Gallery Provider has been initialized, the Gallery application checks if configuration for that provider is available. A configuration in this case is a text file which must match the name of the Gallery Provider assembly plus .config for example: given we had a Gallery Provider assembly Mavention.SharePoint.EnterpriseSolutionStore.dll then a valid configuration file would have to be called Mavention.SharePoint.EnterpriseSolutionStore.dll.config in order to be loaded by the Gallery engine.

You are free in how you define the configuration file. Its contents, if available, are streamed together with the assembly and are made available in your Gallery Provider via the ClientFilteredProvider<T>.Configuration property. It’s worth noting that the configuration is available after the Gallery Provider has been registered with the Gallery application UI so you cannot for example configure its Title that is displayed in the Gallery application.

How it works: providing Gallery Items

The last thing that a Gallery Provider is responsible for is providing the Gallery application with the list of available Gallery Items (solutions). When building a Gallery Provider you have to provide the name of the class that will be used for defining Gallery Items for your Gallery Provider. When implementing a Gallery Item class you have to at minimum inherit from the Microsoft.SharePoint.Solutions.AddGallery.Provider.GalleryItem abstract class which you can then optionally enrich with your own properties.

Building a minimal Enterprise Solution Catalog

To get better understanding of how everything works, let’s take a look at building a minimal Gallery Provider.

Preparing the solution

Important: As you might have noticed, the Gallery is a Silverlight application so in order to ensure that your Gallery Provider will be able to run in context of a Silverlight application you should choose the Silverlight Class Library Project Template as a starting point to ensure that your assembly will have valid assemblies references.

To build a Gallery Provider we will need two projects: one – a Silverlight Class Library project, to implement the Gallery Provider and one – a SharePoint Project, to deploy the Gallery Provider to SharePoint. Optionally, if you would like to use configuration with you Gallery Provider, you should add another SharePoint Project that would deploy the .config file to the 14\TEMPLATE\LAYOUTS\AddGalleryProviders folder. Keeping the configuration separate from the Gallery Provider allows you to have different configuration files for different environments such as development, UAT and production.

The following screenshot presents the project structure used for building a minimal Gallery Provider that uses configuration:

Tip: Because neither the Installer nor the Configuration projects contain any code you can set their Include Assembly In Package properties to False not to include unnecessary assemblies in the WSP.

Configuring Gallery Provider deployment

Before we start building the Gallery Provider, let’s configure the deployment options so that both the Gallery Provider and its configuration will get deployed to the right location in the SharePoint Root Folder.

To the Installer project add an Empty Element called GalleryProvider. Remove the Elements.xml file and in the SPI’s Properties click the ellipsis next to the Project Output References property. Add a new Project Output Reference. Set Project Name to the Mavention.SharePoint.MinimalGalleryProvider project (Silverlight Class Library project), Deployment Type to TemplateFile and finally Deployment Path to LAYOUTS\AddGalleryProviders. The following screenshot shows the complete configuration.

After configuring the Project Output References add the GalleryProvider SPI to the Package. To verify that everything has been configured correctly Package the Installer project. By browsing through the contents of the hidden pkg folder you can verify that the Gallery Provider assembly will end up in the right location.

Configuring Gallery Provider Configuration deployment

The next step is to ensure that the configuration file for our Gallery Provider will be deployed to the right location. For that add a new SharePoint Mapped Folder to the Configuration project and in the tree view select the TEMPLATE\LAYOUTS\AddGalleryProviders folder.

Next add to it the configuration file which should be called Mavention.
SharePoint.MinimalGalleryProvider.dll.config.

Getting prerequisites for building a Gallery Provider

The last thing that we need to configure before we can start building our minimal Gallery Provider is to get a reference to the AddGallery.Provider base assembly. For that go the 14\TEMPLATE\LAYOUTS folder and copy the AddGallery.xap file. Change the extension to .zip and extract the contents. From there copy the AddGallery.Provider.dll file and paste is somewhere in your solution structure. Next, in the Gallery Provider project (Silverlight Class Library project) add a new Assembly Reference and lookup the AddGallery.Provider assembly. After it has been added as a reference set the Copy Local property to False.

Tip: To simplify deploying the Gallery Provider you can set the Post-Build event of the Silverlight Class Library project to
copy "$(TargetPath)" "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS\AddGalleryProviders" /Y

Tip: The Gallery Provider is Silverlight code so if you want to debug it you have to attach the debugger to the iexplore.exe process rather than the w3wp.exe process that runs SharePoint code.

This concludes the preparations and allows us to start building the minimal Gallery Provider.

Building the minimal Gallery Provider

At minimal a Gallery Provider consists of two classes: a Gallery Item that inherits from the Microsoft.SharePoint.Solutions.AddGallery.Provider.GalleryItem class and the Gallery Provider itself which inherits from the Microsoft.SharePoint.Solutions.AddGallery.Provider.ClientFilteredProvider<T> class.

Whenever you define the Gallery Item class you can simply inherit from the base class. No extra properties have to be defined and no methods have to be defined. The following code snippet presents the minimal code for a Gallery Item.

using Microsoft.SharePoint.Solutions.AddGallery.Provider;

namespace Mavention.SharePoint.MinimalGalleryProvider {
    public class MinimalGalleryProviderGalleryItem : GalleryItem {
    }
}

Next we can continue with building the minimal Gallery Provider. Whenever you inherit from the ClientFilteredProvider<T> generic class you have to pass the type of the Gallery Item class that the Gallery Provider will use. In our case this is the MinimalGalleryProviderGalleryItem class. Additionally you have to define two methods: BeginGetDistinctFilterValues and BeginGetItems. The BeginGetDistinctFilterValues method can be used if you want to define additional filters for your provider. We will skip it for now and will use the default implementation. The BeginGetItems method is the core of every Gallery Provider and contains the logic responsible for retrieving Gallery Items (solutions).

The following code snippet presents the base code for our minimal Gallery Provider.

using System.Collections.Generic;
using System.Globalization;
using Microsoft.SharePoint.Solutions.AddGallery.Provider;

namespace Mavention.SharePoint.MinimalGalleryProvider {
    public class MinimalGalleryProvider : ClientFilteredProvider<MinimalGalleryProviderGalleryItem> {
        IList<MinimalGalleryProviderGalleryItem> items;

        public MinimalGalleryProvider() {
            Title = "Mavention Solution Store";
        }

        public override void BeginGetDistinctFilterValues(CultureInfo language, ItemAttribute itemAttribute, object asyncState) {
            IList<FilterValue> filterValues = ProcessFilterValues(items, itemAttribute);
            OnGetDistinctFilterValuesCompleted(new GetDistinctFilterValuesCompletedEventArgs {
                AsyncState = null,
                Error = null,
                ItemAttribute = itemAttribute,
                DistinctFilterValues = filterValues
            });
        }

        public override void BeginGetItems(CultureInfo language, string searchText, FilterCollection filters, SortOrderCollection sortOrders, int firstItemIndex, int lastItemIndex, object asyncState) {
        }
    }
}

Next to defining the required methods in the constructor of the Gallery Provider on line 10 we have defined the title of our Gallery Provider. As discussed previously the title is being used immediately after instantiating the Gallery Provider so it’s important to define it in the Gallery Provider constructor.

If we deployed the Installer solution now this is what you should see after opening the Create dialog window:

Although our Gallery Provider doesn’t display any items at this moment, it proves that so far we have done everything correctly.

Loading Gallery Items

From the Gallery perspective there is no restrictions with regard to what you want to use as the store for your solutions. You could for example use something as simple as a SharePoint List but you could as well use a cloud-based solution that is running on Azure. This is why the exact implementation logic for the BeginGetItems method will differ based on where you store the solutions. So instead of getting a complete backend implementation, let’s focus on what the capabilities of the Gallery are and how you can present your solutions.

Let’s start with defining a few items in our Gallery Provider by changing the code of the BeginGetItems method as shown in the following snippet:

public override void BeginGetItems(CultureInfo language, string searchText, FilterCollection filters, SortOrderCollection sortOrders, int firstItemIndex, int lastItemIndex, object asyncState) {
    items = new List<MinimalGalleryProviderGalleryItem> {
        new MinimalGalleryProviderGalleryItem {
            DisplayName = "Mavention Solution 1",
            Description = "This is Mavention Solution #1",
            ImageUrl = "/_layouts/images/ltpp.png",
            Categories = new List<string> { "Category 1", "Category 2" }
        },
        new MinimalGalleryProviderGalleryItem {
            DisplayName = "Mavention Solution 2",
            Description = "This is Mavention Solution #2",
            ImageUrl = "http://mavention/_layouts/images/ltworksp.png",
            Categories = new List<string> { "Category 1", "Category 3" }
        }
    };

    GalleryItemCollection galleryItems = ProcessItems(items, searchText, filters, sortOrders, firstItemIndex, lastItemIndex);

    OnGetItemsCompleted(new GetItemsCompletedEventArgs {
        AsyncState = asyncState,
        Error = null,
        Items = galleryItems
    });
}

If you reload the Gallery you will see our two items displayed on the screen:

For every item the display name (1), a description (2), an image (3) and the categories (4) will be displayed. All properties except the display name are optional. Additionally, based on all unique categories the categories refiner will be filled (5).

Although our Gallery Items are now displayed there is no link to the underlying solutions yet and if you click the Create button you will simply get redirected to the welcome page of your site.

Linking Gallery Items to solutions

The underlying GalleryItem class, that is the base for every Gallery Item, contains a number of properties that allow you to define what the particular Gallery Item exactly is and how it should be used. You can define the type of the Gallery Item by using the GalleryItem.Type property. In this scenario we will focus on using the Solution type only but you should definitely explore other item types.

items = new List<MinimalGalleryProviderGalleryItem> {
    new MinimalGalleryProviderGalleryItem {
        DisplayName = "Mavention Solution 1",
        Description = "This is Mavention Solution #1",
        ImageUrl = "/_layouts/images/ltpp.png",
        Categories = new List<string> { "Category 1", "Category 2" },
        Type = ItemType.Solution
    },
    new MinimalGalleryProviderGalleryItem {
        DisplayName = "Mavention Solution 2",
        Description = "This is Mavention Solution #2",
        ImageUrl = "http://mavention/_layouts/images/ltworksp.png",
        Categories = new List<string> { "Category 1", "Category 3" },
        Type = ItemType.Solution
    }
};

When working with solutions one of the most important properties that you should define for every Gallery Item is the GalleryItem.CodeType property which defines what type of solution the particular Gallery Item is. Depending on the value of this property different requirements have to be fulfilled by the user for him to be able to install the solution. The CodeType property has three values: NoCode, PTC and FT. Although there is no documentation on the exact meaning of those values you can think of them in the following terms:

• NoCode: the solution package contains no code and in order to see the solution the user has to have the following SharePoint permissions: ManageSubWebs, ManageWeb and AddAndCustomizePages
• PTC (Partially Trusted Code): in order to see the solution in the gallery the user must be a Site Admin (SPUser.IsSiteAdmin equals true)
• FT (Full Trust Solutions): not supported at this moment and never displayed in the Gallery

items = new List<MinimalGalleryProviderGalleryItem> {
    new MinimalGalleryProviderGalleryItem {
        DisplayName = "Mavention Solution 1",
        Description = "This is Mavention Solution #1",
        ImageUrl = "/_layouts/images/ltpp.png",
        Categories = new List<string> { "Category 1", "Category 2" },
        Type = ItemType.Solution,
        CodeType = SolutionCodeType.NoCode
    },
    new MinimalGalleryProviderGalleryItem {
        DisplayName = "Mavention Solution 2",
        Description = "This is Mavention Solution #2",
        ImageUrl = "http://mavention/_layouts/images/ltworksp.png",
        Categories = new List<string> { "Category 1", "Category 3" },
        Type = ItemType.Solution,
        CodeType = SolutionCodeType.PTC
    }
};

The CodeType property works in combination with the GalleryItem.ShowOnlyIfUserHasPermissions property which is set to true by default. If you would like a particular Gallery Item to be always visible you could set its ShowOnlyIfUserHasPermissions property to false.

After setting the type of solution the next step is to make the Gallery Item point to the physical WSP file. By default the Action for each Gallery Item is set to ActionType.Link which means that after clicking the Create button the Gallery will navigate to the URL specified using the GalleryItem.Link property. If you want your solutions to be downloaded and installed instead you have to set the GalleryItem.Action property to ActionType.ForDownload and provide the URL of the WSP using the GalleryItem.URL property. There is no restriction as to where this file is located as long as it can be accessed by the specified URL.

items = new List<MinimalGalleryProviderGalleryItem> {
    new MinimalGalleryProviderGalleryItem {
        DisplayName = "Mavention Solution 1",
        Description = "This is Mavention Solution #1",
        ImageUrl = "/_layouts/images/ltpp.png",
        Categories = new List<string> { "Category 1", "Category 2" },
        Type = ItemType.Solution,
        CodeType = SolutionCodeType.NoCode,
        Action = ActionType.ForDownload,
        Url = "/SolutionCatalog/MaventionSolution1.wsp"
    },
    new MinimalGalleryProviderGalleryItem {
        DisplayName = "Mavention Solution 2",
        Description = "This is Mavention Solution #2",
        ImageUrl = "http://mavention/_layouts/images/ltworksp.png",
        Categories = new List<string> { "Category 1", "Category 3" },
        Type = ItemType.Solution,
        CodeType = SolutionCodeType.PTC,
        Action = ActionType.ForDownload,
        Url = "http://mavention/SolutionCatalog/MaventionSolution2.wsp"
    }
};

Notice that the Create button automatically changed to Download and if you click it the solution should be automatically downloaded and installed, given you have sufficient permissions on the current site.

Configuring additional settings

The Gallery has a few more options that can be configured that allow you to control how you Gallery Items are displayed.

Dealing with solution requirements

Often when building solutions we depend on some other resources: this can be either a specific SharePoint version, license, patch level, but it can also be a specific Feature that must be installed activated. For every Gallery Item we can define which dependencies it has on other resources.

You can define requirements for a Gallery Item using the GalleryItem.RequiredResources property. Defining requirements is quite complex. First you have to create an instance of the SharePointRequirementCollection class. Using its Requirements property you have to then define an array of SharePointRequirement objects – one for every dependency of your solution. When defining a requirement you can choose its type (which is an enumeration of fixed values) but it’s the CompatibleResources property that it’s challenging to define. For every requirement there is at least one compatible resource which fulfills that requirement. Requirements are compared using their names (the SharePointRequirement.Name property) and for requirements of type Feature and ProductPatch also the version number (the SharePointRequirement.ResourceVersion property) is taken into account.

Probably the easiest way of configuring required resources for your solution and ensuring that you have the right values is to get the current configuration that the Gallery uses for comparisons. The best way to do this is to use Fiddler to explore requests that are being executed after opening the Gallery. One of those requests (1) will have the request body set to Task=GetAdditionalConfig&CurrentWeb=%2F (2). If you zoom in on the response HTML and look for the <AddGalleryResponse> string you will find the XML containing all of the configuration for the current site (3).

Configuring requirements

With that information you could for example define that your solution can be installed only when the Publishing Feature is activated on the current Web:

new MinimalGalleryProviderGalleryItem {
    DisplayName = "Mavention Solution 1",
    Description = "This is Mavention Solution #1",
    ImageUrl = "/_layouts/images/ltpp.png",
    Categories = new List<string> { "Category 1", "Category 2" },
    Type = ItemType.Solution,
    CodeType = SolutionCodeType.NoCode,
    Action = ActionType.ForDownload,
    Url = "/SolutionCatalog/MaventionSolution1.wsp",
    RequiredResources = new SharePointRequirementCollection {
        Requirements = new SharePointRequirement[] {
            new SharePointRequirement {
                CompatibleResources = new SharePointResource[] {
                    new SharePointResource {
                        ResourceType = SharePointResourceType.Feature,
                        Name = "94C94CA6-B32F-4DA9-A9E3-1F3D343D7ECB",
                        DisplayName = "SharePoint Server Publishing",
                        MissingMessage = "SharePoint Server Publishing Site Feature",
                        ResourceVersion = new System.Version("14.0.0.0")
                    }
                }
            }
        }
    }
}

If you would then browse to the Gallery on a Web that doesn’t have the Publishing Feature activated you would see an error message:

and after clicking on that error message you would get an overview of all missing requirements:

Requesting a requirements check

When working with requirements there is one thing you should take into account. By default the Gallery doesn’t run the requirements check and you have to do it yourself. The good news is that the Gallery provides you with a method to run the check which is stored in the CheckItemRequirementsMethod property of your Gallery Provider. The downside is that it accepts the collection of Gallery Items as a parameter of IList<GalleryItem> type. Because you cannot directly cast IList<YourGalleryItem> to the type required by the check method you have two options. You can either create another variable, copy all items there, run the check and then add all Missing Requirements to the GalleryItem.RequiredResources.MissingRequirements property or when implementing the Gallery Provider you could inherit from the ClientFilteredProvider<GalleryItem> class and specify the GalleryItem class as the class for Gallery Item. With that you can still use your own Gallery Item class to define your items but this allows you to make use of the standard check method. Here is the sample code that shows this scenario:

using System.Collections.Generic;
using System.Globalization;
using Microsoft.SharePoint.Solutions.AddGallery.Provider;

namespace Mavention.SharePoint.MinimalGalleryProvider {
    public class MinimalGalleryProvider : ClientFilteredProvider<GalleryItem> {
        IList<GalleryItem> items;

        public MinimalGalleryProvider() {
            Title = "Mavention Solution Store";
        }

        public override void BeginGetDistinctFilterValues(CultureInfo language, ItemAttribute itemAttribute, object asyncState) {
            IList<FilterValue> filterValues = ProcessFilterValues(items, itemAttribute);
            OnGetDistinctFilterValuesCompleted(new GetDistinctFilterValuesCompletedEventArgs {
                AsyncState = null,
                Error = null,
                ItemAttribute = itemAttribute,
                DistinctFilterValues = filterValues
            });
        }

        public override void BeginGetItems(CultureInfo language, string searchText, FilterCollection filters, SortOrderCollection sortOrders, int firstItemIndex, int lastItemIndex, object asyncState) {
            items = new List<GalleryItem> {
                new MinimalGalleryProviderGalleryItem {
                    DisplayName = "Mavention Solution 1",
                    Description = "This is Mavention Solution #1",
                    ImageUrl = "/_layouts/images/ltpp.png",
                    Categories = new List<string> { "Category 1", "Category 2" },
                    Type = ItemType.Solution,
                    CodeType = SolutionCodeType.NoCode,
                    Action = ActionType.ForDownload,
                    Url = "/SolutionCatalog/MaventionSolution1.wsp",
                    RequiredResources = new SharePointRequirementCollection {
                        Requirements = new SharePointRequirement[] {
                            new SharePointRequirement {
                                CompatibleResources = new SharePointResource[] {
                                    new SharePointResource {
                                        ResourceType = SharePointResourceType.Feature,
                                        Name = "94C94CA6-B32F-4DA9-A9E3-1F3D343D7ECB",
                                        DisplayName = "SharePoint Server Publishing",
                                        MissingMessage = "SharePoint Server Publishing Site Feature",
                                        ResourceVersion = new System.Version("14.0.0.0")
                                    }
                                }
                            }
                        }
                    }
                },
                new MinimalGalleryProviderGalleryItem {
                    DisplayName = "Mavention Solution 2",
                    Description = "This is Mavention Solution #2",
                    ImageUrl = "http://mavention/_layouts/images/ltworksp.png",
                    Categories = new List<string> { "Category 1", "Category 3" },
                    Type = ItemType.Solution,
                    CodeType = SolutionCodeType.PTC,
                    Action = ActionType.ForDownload,
                    Url = "http://mavention/SolutionCatalog/MaventionSolution2.wsp",
                }
            };

            CheckItemRequirementsMethod(items);
            GalleryItemCollection galleryItems = ProcessItems(items, searchText, filters, sortOrders, firstItemIndex, lastItemIndex);

            OnGetItemsCompleted(new GetItemsCompletedEventArgs {
                AsyncState = asyncState,
                Error = null,
                Items = galleryItems
            });
        }
    }
}

Defining ratings

One more thing that the Gallery allows you to do to improve the discovery of solutions is to specify star rating for every item. You can do this using the GalleryItem.FiveStarRating property. When setting it you also have to set the GalleryItem.HasFiveStartRating property to true and the GalleryItem.TotalRatingVotes property to the number of votes, eg.

new MinimalGalleryProviderGalleryItem {
    DisplayName = "Mavention Solution 2",
    Description = "This is Mavention Solution #2",
    ImageUrl = "http://mavention/_layouts/images/ltworksp.png",
    Categories = new List<string> { "Category 1", "Category 3" },
    Type = ItemType.Solution,
    CodeType = SolutionCodeType.PTC,
    Action = ActionType.ForDownload,
    Url = "http://mavention/SolutionCatalog/MaventionSolution2.wsp",
    FiveStarRating = 4.5,
    HasFiveStarRating = true,
    TotalRatingVotes = 1
}

Providing your users with a rating mechanism allows you to engage them more, get feedback on the quality of the solutions and discover high value solutions.

Important: The Gallery only displays the rating provided by the Gallery Provider. It’s up to you to allow your users to rate Gallery Items.

Summary

Creating an Enterprise Solution Store allows you to deliver your solutions to your end users in a user-friendly fashion. SharePoint 2010 has the Gallery component that allows you to build your own solution store for your organization. The Gallery capability is a powerful mechanism that allows you not only to present and deliver your solutions but also to manage dependencies on other resources that are required by your solutions.

In the next article I will share with you a simple solution that allows you to build your own Enterprise Solution Store based on a SharePoint List.

The Conference

Last year I’ve attended the European SharePoint Best Practice Conference 2011. Although in a way I knew that the International SharePoint Conference London 2012 (ISC) would be at least as good, being a speaker in the developer track exceeded all of my expectations.

Throughout the whole conference Steve and his team took care for everything and ensured that we – the speakers, could focus on the content and deliver the best we could to the attendees. I feel like we cannot thank Steve and his team enough for how they have organized everything and how they succeeded in making the ISC the great experience that it was for both speakers and attendees.

Preparing for the conference with the dev team was a unique experience by itself. Never before I had a chance to work on a project with some of the greatest people in the SharePoint community worldwide. Being a part of the discussions that we had about designing the solution and building all the different pieces of it I learned a lot: not only technically but also how different backgrounds and areas of expertise bring different reasoning to designing and building a SharePoint solution.

The Content

Never before the content of a SharePoint conference has been organized the way it has been presented on the ISC. During the three days we have taken you on a journey of building a fully functional SharePoint solution: starting with the requirements to end up in the cloud. Hopefully this unique way of presenting has given you a better understanding on how we – the speakers thought about certain challenges both with regard to designing and building the solution.

In about two months all attendees will receive the post-conference material. In the meanwhile all of our code presented in the developer track is available on CodePlex at http://spkbase.codeplex.com/. The Visual Studio 2010 SharePoint Developer Tools extensions presented by Wictor and I on the first day are available in the Visual Studio Gallery at http://visualstudiogallery.msdn.microsoft.com/site/search?query=ISC&f%5B0%5D.Value=ISC%20&f%5B0%5D.Type=SearchText&ac=8 or you can search from the Visual Studio Extension Manager for ‘ISC ’ (the space at the end will narrow the search results). As we speak Wes Hackett of the CKS:DEV team is working on merging the new SPI Templates so that you will get them as a part of the CKS:DEV Toolkit. A new release of CKS:DEV should be available within days so stay tuned for updates.

Recap

The International SharePoint Conference London 2012 was a great experience and I’m humbled to have been a part of it. I’d like once again to thank all attendees and the organization: you rocked! I’m already looking forward to seeing you all back at the Evolutions conference that has been announced for April 15-17, 2013.

DIWUG.nl: How We Did it

Did you know that the new DIWUG website has been built on the Microsoft SharePoint 2010 platform, is accessible and uses HTML5? In this presentation my fellow-Maven Octavie van Haaften and I present how we built the new DIWUG website, what choices we made and why.

Optimizing SharePoint 2010 websites for search engines

When you build an Internet-facing website you want everyone to be able to find it. Unfortunately your website won’t become discoverable all by itself and you will have to do something to make it happen. In this presentation I show you how you can optimize public-facing websites built on the Microsoft SharePoint 2010 platform for search engines.

Create SharePoint breadcrumbs with Mavention Simple SiteMapPath

One of the challenges while building Internet-facing websites is rendering breadcrumbs the way they are defined in the user experience. Out-of-the-box you can use either the ListSiteMapPath control provided with SharePoint 2010 or the SiteMapPath control which is a part of the .NET framework.

The ListSiteMapPath control uses nested unordered lists to describe the current position within the site. While it’s a good idea from the semantic point of view the rendered markup is far from ideal and unfortunately fixed, which makes using the control with custom user experiences challenging.

A good alternative to the SharePoint’s ListSiteMapPath control is the standard ASP.NET SiteMapPath control. Although standard Master Pages provided with SharePoint 2010 contain some examples of how you can use the SiteMapPath control to render breadcrumbs the real benefit can be achieved by using the templates to render breadcrumb nodes. And while, in terms of rendering, the SiteMapPath is more flexible than the ListSiteMapPath, if you take a closer look at its output, you will find some additional spans rendered which, depending on your HTML, might be problematic.

Given the limitations of the ListSiteMapPath and SiteMapPath controls a while ago I decided to create the Mavention Simple SiteMapPath control. The main idea behind the control was to have it render as clean as possible HTML – something you would expect from a webdesigner coding the user experience. Although Mavention Simple SiteMapPath didn’t offer as rich configuration capabilities as the SiteMapPath control, it did exactly what it was supposed to do and it did it good.

The flaw of Mavention Simple SiteMapPath

Taking the most common approach to rendering breadcrumbs on the web, the Mavention Simple SiteMapPath control used an unordered list as the markup base. And this is exactly why it’s flawed: although the control is simple, it does one and one thing only and it does it certain way which cannot be configured without rebuilding the code.

Building breadcrumbs the way you want it

To avoid the limitations of the Mavention Simple SiteMapPath control and to be able to support any kind of breadcrumbs possible, I have created the Mavention Templated SiteMapPath.

Mavention Templated SiteMapPath

The Mavention Templated SiteMapPath consists of the following three files:

using System;
using System;
using System.Collections.Generic;
using System.Web;
using System.Web.UI;

namespace Mavention.SharePoint.Controls {
    [ParseChildren(true), PersistChildren(false)]
    public class TemplatedSiteMapPath : Control  {
        public bool SkipRootNode { get; set; }
        public string SiteMapProvider { get; set; }

        public ITemplate HeaderTemplate { get; set; }
        public ITemplate FooterTemplate { get; set; }
        public ITemplate RootNodeTemplate { get; set; }
        public ITemplate NodeTemplate { get; set; }
        public ITemplate CurrentNodeTemplate { get; set; }
        public ITemplate SeparatorTemplate { get; set; }

        private SiteMapProvider provider;

        protected override void OnInit(EventArgs e) {
            SetSiteMapProvider();
        }

        private void SetSiteMapProvider() {
            if (String.IsNullOrEmpty(SiteMapProvider)) {
                provider = SiteMap.Provider;
            }
            else {
                provider = SiteMap.Providers[SiteMapProvider];
            }

            if (provider == null) {
                throw new ArgumentOutOfRangeException(String.Format("SiteMap Provider '{0}' not found", SiteMapProvider ?? "default"));
            }
        }

        protected override void CreateChildControls() {
            List<SiteMapPathNodeItem> breadcrumbs = new List<SiteMapPathNodeItem>();
            breadcrumbs.Add(new SiteMapPathNodeItem(Int32.MaxValue, SiteMapPathNodeItemType.Footer));

            SiteMapNode currentNode = provider.CurrentNode;
            SiteMapNode node = provider.CurrentNode;
            SiteMapNode rootNode = currentNode.RootNode;
            int i = 0;
            while (node != null) {
                if (node.Key != rootNode.Key) {
                    if (breadcrumbs.Count > 1) {
                        breadcrumbs.Add(new SiteMapPathNodeItem(i--, SiteMapPathNodeItemType.Separator));
                    }

                    breadcrumbs.Add(new SiteMapPathNodeItem(i--, node.Key == currentNode.Key ? SiteMapPathNodeItemType.CurrentNode : SiteMapPathNodeItemType.Node) { SiteMapNode = node });
                }
                else {
                    if (!SkipRootNode) {
                        if (breadcrumbs.Count > 1) {
                            breadcrumbs.Add(new SiteMapPathNodeItem(i--, SiteMapPathNodeItemType.Separator));
                        }

                        breadcrumbs.Add(new SiteMapPathNodeItem(i, SiteMapPathNodeItemType.RootNode) { SiteMapNode = node });
                    }
                }

                node = node.ParentNode;
            }

            breadcrumbs.Add(new SiteMapPathNodeItem(Int32.MinValue, SiteMapPathNodeItemType.Header));
            breadcrumbs.Reverse();

            if (breadcrumbs.Count > 2) {
                breadcrumbs[1].ItemType = SiteMapPathNodeItemType.RootNode;
            }

            foreach (SiteMapPathNodeItem breadcrumb in breadcrumbs) {
                InitializeItem(breadcrumb);
            }
        }

        public virtual void InitializeItem(SiteMapPathNodeItem item) {
            ITemplate nodeTemplate = null;
            SiteMapPathNodeItemType itemType = item.ItemType;

            switch (itemType) {
                case SiteMapPathNodeItemType.Header:
                    nodeTemplate = HeaderTemplate;
                    break;
                case SiteMapPathNodeItemType.Footer:
                    nodeTemplate = FooterTemplate;
                    break;
                case SiteMapPathNodeItemType.RootNode:
                    nodeTemplate = RootNodeTemplate ?? NodeTemplate;
                    break;
                case SiteMapPathNodeItemType.Node:
                    nodeTemplate = NodeTemplate;
                    break;
                case SiteMapPathNodeItemType.CurrentNode:
                    nodeTemplate = CurrentNodeTemplate ?? NodeTemplate;
                    break;
                case SiteMapPathNodeItemType.Separator:
                    nodeTemplate = SeparatorTemplate;
                    break;
                default:
                    break;
            }

            if (nodeTemplate != null) {
                nodeTemplate.InstantiateIn(item);
                Controls.Add(item);
                item.DataBind();
            }
        }
    }
}

namespace Mavention.SharePoint.Controls {
    public enum SiteMapPathNodeItemType {
        Header,
        Footer,
        RootNode,
        Node,
        CurrentNode,
        Separator
    }
}

using System.Web;
using System.Web.UI;

namespace Mavention.SharePoint.Controls {
    public class SiteMapPathNodeItem : Control, IDataItemContainer, INamingContainer {
        public SiteMapPathNodeItemType ItemType { get; set; }
        public SiteMapNode SiteMapNode { get; set; }
        public int ItemIndex { get; set; }

        public SiteMapPathNodeItem(int itemIndex, SiteMapPathNodeItemType itemType) {
            ItemIndex = itemIndex;
            ItemType = itemType;
        }

        public object DataItem {
            get { return SiteMapNode; }
        }

        public int DataItemIndex {
            get { return ItemIndex; }
        }

        public int DisplayIndex {
            get { return ItemIndex; }
        }
    }
}

The first file – TemplatedSiteMapPath.cs, is the Mavention Templated SiteMapPath control itself. If you compare its code to the Mavention Simple SiteMapPath you can see that the code is much simpler and the biggest part of it supports rendering using Templates.

The second file – SiteMapPathNodeItemType.cs contains the definition of the enumeration that describes the type of the breadcrumb node. The node type is being used to apply the right rendering template while rendering breadcrumbs.

Finally there is the SiteMapPathNodeItem.cs file which contains the definition of a control in which a breadcrumb node is wrapped. The important part here is that this class inherits from the Control class, and not WebControl like the standard ASP.NET SiteMapNode class, so no additional spans or other markup for that matter is rendered.

Using the Mavention Templated SiteMapPath

The following code snippet illustrates how you can use the Mavention Templated SiteMapPath control:

<Mavention:TemplatedSiteMapPath runat="server">
    <HeaderTemplate><div id="breadcrumbs"></HeaderTemplate>
    <RootNodeTemplate><asp:Hyperlink Text='home' NavigateUrl='<%# Eval("Url") %>' runat="server"/></RootNodeTemplate>
    <NodeTemplate><asp:Hyperlink Text='<%# Eval("Title") %>' NavigateUrl='<%# Eval("Url") %>' runat="server"/></NodeTemplate>
    <CurrentNodeTemplate><asp:Literal Text='<%# Eval("Title") %>' runat="server"/></CurrentNodeTemplate>
    <SeparatorTemplate> / </SeparatorTemplate>
    <FooterTemplate></div></FooterTemplate>
</Mavention:TemplatedSiteMapPath>

Using this snippet will render breadcrumbs as hyperlinks, separated with a / (slash) where the current node is rendered as plain text. As you can imagine with some slight modifications you could change the breadcrumbs to be rendered as an unordered list should you need it, without touching the code!

Dealing with Variations

One of the common challenges when building breadcrumbs for a public-facing websites is dealing with Variations. Whenever a site is using the Variations capability to deliver multilingual content the desired way of rendering breadcrumbs is to have the first node point to the home page of the current Variation. Unfortunately the standard Navigation Providers available with SharePoint 2010 render the root site as the first node, so instead of:

home > subsite > page

you get:

root > home > subsite > page

This happens no matter how your navigation settings are configured and even if you choose to break navigation inheritance for the Variation root sites.

The Mavention Templated SiteMapPath control allows you to easily work around this issue. By setting the SkipRootNode property to true, the root node is omitted and the second node in hierarchy is promoted as the root node so that it can be properly rendered as a root node (TemplatedSiteMapPath.cs lines 55-61 and 70-72). As a result breadcrumbs will be rendered as you would expect them to.

It’s all about permissions

Using the code samples above you can implement the Mavention Templated SiteMapPath in your solution. One important thing that you should keep in mind is, that the code should be included in an assembly deployed to GAC. Without it, in some scenarios depending on how your website is built, you might experience exceptions being thrown while instantiating the ExtendedSearchXmlContentMapProvider navigation provider which is one of the standard navigation providers delivered with SharePoint 2010.

Summary

Implementing custom user experiences in public-facing websites built on the SharePoint 2010 platform knows many challenges. One of those challenges is building breadcrumbs. Using the Mavention Templated SiteMapPath control you can build virtually any kind of breadcrumbs without the need to modify the control’s code.

Diwug.nl v2 – How we did it

Recently me and fellow Mavens built a new website for the Dutch Information Worker User Group. This website uses HTML5, is accessible and, what’s the most important, is built on the Microsoft SharePoint 2010 platform. In this session, that I will co-presenting with Octavie van Haaften, we are going to show you how we built the new website for DIWUG.

Optimizing SharePoint 2010 websites for search engines

Whenever you build a public-facing website you want people to find it. Although your website will eventually be indexed by search engines by itself, there are ways for you to help search engines discover the content on your website. In this session I will share with you some tips and tricks in how you can optimize your public-facing website built on the SharePoint 2010 platform for search engines.

About SharePoint Saturday Holland

Join SharePoint architects, developers, and other professionals that work with Microsoft SharePoint Server 2010 for ‘SharePoint Saturday’ event.  SharePoint Saturday is an educational, informative & lively day filled with sessions from respected SharePoint professionals & MVPs, covering a wide variety of SharePoint-orientated topics.  SharePoint Saturday is FREE, open to the public and is your local chance to immerse yourself in SharePoint!

See you on the SharePoint Saturday Holland!

Project Startup DEV202

In the Project Startup DEV202 session, that I will be co-presenting with fellow SharePoint MVP and SharePoint MCM Wictor Wilén, Wictor and I will be discussing different approaches to structure your solution and make to help you get the most of the Visual Studio 2010 SharePoint Developer Tools .

Deployment Process – Creating web templates, setup lifecycle management and deployment parts 1 (DEV206) and 2 (DEV207)

Later in the developer track I will be co-presenting two sessions (DEV206 and DEV207) with fellow SharePoint MVP and SharePoint MCM Mirjam van Olst. In our sessions Mirjam and I will be discussing the process of packaging different pieces of the solution that we will be working with so that you can support all the different requirements during the whole lifecycle of the project.

The Developer Track

This year the developer track will be organized in a different way than previously (quoted from the ISC site):

This track is for all the Developers out there who are just starting a SharePoint journey of discovery and for those developers who have been developing for a while and now need to hone their skills to a more advanced level. There is so much that you can do with SharePoint where do you start, and what is the correct way to take a design all the way through to a finished solution deployed live in your production farm. The Developer track in 2012 will be a unique track with a complete 3 day focus on taking a concept all the way through its build, test and deployment process and showing how in the real world what situations a developer can come across and how those situations are troubleshot and resolved. Unlike normal session based conferences this year we plan on expanding on the basic knowledge and going as deep as is needed, so if a topic needs 2 sessions to cover it thoroughly then 2 sessions will be scheduled so you get all the information you need when you go back to the office.

As you can see, instead of giving separate presentations we will be aiming at giving you a more complete insight into the process and hopefully share with you more knowledge that you can benefit of in your every day's work.

I’m looking forward to seeing you in London!