The SharePoint 2010 Web Part Adder control in a Master Page
One of the common requirements when building SharePoint solutions is to control the list of available Web Parts. Find out how to do this using the new Web Part Adder control available in SharePoint 2010.

Inconvenient Web Part Gallery

Web Parts are one of the most common building blocks for SharePoint solutions. With time, as you add new functionality to your solution, the number of available Web Parts grows. And although theoretically you are providing your users with what they have been asking for, they have been really asking for something else.

Too much of something is rarely a good thing. If you look at the user interface in SharePoint 2010, you see that Microsoft put some great effort in making it easier for users to benefit of all the functionality provided with SharePoint. Menu options have been replaced with Ribbon which is contextual giving you quick access only to options which are relevant to what you are doing at that moment.

So how come the Web Part Gallery looks like this:

Web Part Gallery filled with Web Parts on a standard SharePoint 2010 Publishing Site

Controlling the list of available Web Parts

It seems to be not that easy to control which Web Parts should be available to users in a scalable and manageable way.

One approach that many people choose, is to remove all, or at least most of the, standard Web Parts and provide users only with Web Parts configured for the specific solution. Although this might give the illusion of doing the job, it really doesn’t. First of all it’s limiting: it applies to every page in your Site Collection. And since not all pages are the same you end up with providing more Web Parts than you would want. Secondly, just because you remove a Web Part from the Web Part Gallery, doesn’t mean it’s permanent. A user with sufficient permission can navigate to Web Part Gallery and add any Web Part that’s available back to the gallery or simply import a Web Part directly on the page ruining all of your hard work.

Another approach that you might have heard about is to user item level permissions on specific Web Parts making them available to specific users only. Just like the previous solution, this approach trims the list of available Web Parts. The downside is that it makes it really challenging to manage the environment: have you ever tried to get an overview of item level permissions without third party functionality? On top of that, just like the previous solution, this approach applies globally to all pages in the whole Site Collection.

In SharePoint 2007 we had some options to control which Web Parts should be available where. The problem with it was that it was fragmented and had to be configured separately for every Web Part Zone. The great news is that this situation has changed in SharePoint 2010 with the introduction of the Web Part Adder control.

What is Web Part Adder?

Web Part Adder (Microsoft.SharePoint.WebPartPages.WebPartAdder) is a new control available with SharePoint 2010 which is responsible for providing the list of Web Parts available for specific Web Part Zone. Since it’s scoped to a Page it provides you with great flexibility of choosing which Web Parts should be available where.

Web Part Adder is visible every time you choose to add a Web Part to a page. By default it’s included in the Master Page and can be configured both declaratively and imperatively. The important thing is that you can have only one instance of Web Part Adder on a page.

Controlling the list of available Web Parts using Web Part Adder

Web Part Adder gives us a number of configuration capabilities to control which Web Parts should be available for the users to add.

Importing Web Parts

One of the interesting properties of the Web Part Adder control is the AllowWebPartImport property, which, as its name says, defines whether users are allowed to import Web Parts or not. When set to false, it will hide the Upload a Web Part section in the Web Part Adder.

Web Part Adder with the option to import a Web Part removed from the UI

Inserting List View Web Parts

Another property that allows you to configure the list of available Web Parts is the ShowListsAndLibraries property. After setting this property to false users will not be able to insert List View Web Parts:

The List and Libraries category hidden from the list of available categories in the Web Part Adder

Inserting Web Parts from Web Part Catalog and Web Part Gallery

Two other properties that can help you to further restrict the list of available Web Parts are ShowServerGalleryWebParts and ShowSiteGalleryWebParts. Settings those properties to false will remove from the Web Part Adder either all Web Parts located in the inetpub folder of your Web Application or all Web Parts from the Web Part Gallery of your Site Collection.

All Web Parts except of List View Web Parts removed from the list of available Web Parts in the Web Part Adder

Inserting Closed Web Parts

Whenever you don’t want your users to be able to reinsert Web Parts that have been closed, you can use the ShowClosedWebParts property. After setting its value to false the Closed Web Parts category will not appear in the list of available categories in the Web Part Adder even though there are closed Web Parts associated with the page.

Recommended specific Web Parts for specific Site Templates

A great way of optimizing the list of available Web Parts for users is by using the RecommendSiteTemplate property. After setting this value to true the Web Part Adder will use the name of the Site Definition (unfortunately, it doesn’t support Web Templates) as a filter to select recommended Web Parts. If your solution consists of multiple Site Definitions this approach can help you help your users to find the right Web Parts.

Red arrow pointing to the Recommended Items category in the Web Part Adder

Working with the Web Part Adder imperatively

Using the Web Part Adder is a great way of controlling the list of available Web Part. As you have just seen it offers you a number of ways to control which Web Parts are available to users. Next to the capabilities that I have just showed you there are two more properties that the Web Part Adder offers you to control the list of available Web Parts. One thing that you should take into account is, that those properties cannot be used declaratively. One way of working with them is to create a Delegate Control and programmatically access their values:

public class WebPartAdderTrimmingControl : Control {
    protected override void OnLoad(EventArgs e) {
        WebPartAdder wpa = Page.Items[typeof(WebPartAdder)] as WebPartAdder;
        if (wpa != null) {
            // work with Web Part Adder here
        }
    }
}

A powerful consequence of the imperative approach is that you can use custom code to dynamically control the list of available Web Parts. As I mentioned before Web Part Adder is scoped to a page so there are a number of variables that you can use, like Page Layout, Web Template, User’s Permissions/Claims to control which Web Parts he should see.

The properties

The two additional properties that Web Part Adder offers to control the list of available Web Parts are Included and Recommended. Both properties work the same way and the only difference is that while Recommended includes specific Web Parts in the Recommended Items category, the Included property filters the list of available Web Parts including only those Web Parts that fulfill the specified criteria.

Selectors

The Included and Recommended properties work based on selectors. A selector is nothing more than a string constructed matching the following pattern:

[!]MAJOR[:MINOR]

According to MSDN the MAJOR part refers to the Site Template while the optional MINOR part points to a specific Web Part Zone. This is however merely a guidance. There is no mechanism in SharePoint that reinforces this. Additionally, even standard Web Parts available with SharePoint 2010 such as Content Query Web Part don’t comply to this schema.

The selector can be prepended with an exclamation mark (!) to state that instead of including the matching Web Parts you want to exclude them from the list of available Web Parts. It is also worth noting that neither the MAJOR nor the MINOR parts of the string can contain the following chars:

,!: (space)

How it works?

While loading the list of available Web Parts Web Part Adder starts with loading definitions of all available Web Parts: both from the server and site catalog. Then it checks if the Included property contains any filters. If so, for every Web Part definition it will execute a check to control if the Web Part matches the filter and should be included in the list of available Web Parts. To compare the selectors, Web Part Adder will use the value of the QuickAddGroups field of the Web Part definition file (.webpart/.dwp).

Putting things to practice

Imagine that on particular page you wanted to allow users to insert only your Web Parts. Let’s start off by creating a copy of the Content Editor Web Part:

Copy of the Content Editor Web Part definition highlighted in the Web Part Gallery

Next in the Ribbon click the Edit Properties button and in the Recommendation Settings field enter the following value:

MyPage

Entering Recommendation Settings for a Web Part

Next confirm the changes by clicking the Save button.

MyPage selector added to the copy of the Content Editor Web Part

Next in your Web Part Adder Trimming Delegate Control add the following code:

public class WebPartAdderTrimmingControl : Control {
    protected override void OnLoad(EventArgs e) {
        WebPartAdder wpa = Page.Items[typeof(WebPartAdder)] as WebPartAdder;
        if (wpa != null) {
            if (SPContext.Current.File.Name == "My-Page.aspx") {
                wpa.ShowListsAndLibraries = false;
                wpa.Included.Add("MyPage");
            }
        }
    }
}

If you navigate to the My Page now and try to add a Web Part you should see only the copy of the Content Editor Web Part available in the Web Part Adder:

Only one Web Part available to be added to page

Although the example above uses page name as filter, you could implement any kind of comparison that makes sense in your scenario.

Web Part-level control

Web Part Adder uses the value of the QuickAddGroups field of the Web Part Definition item to determine whether the specific Web Part should be available to users or not. For most Web Parts the value of that field is empty and some Web Parts have it filled with the name of the page. This makes it impossible for you to trim the list of available Web Parts for specific items. One thing that you could do to gain some more control would be to prefill the QuickAddGroups field with the name of the Web Part and its Category. That should give you some more control over which Web Parts should be available to users where within your site. Additionally such approach would give you the ability to control whether users should or should not be able to add standard Web Parts provided with SharePoint.

Summary

One of frequent requirements when building SharePoint solutions is controlling the list of available Web Parts. Using the new SharePoint 2010 Web Part Adder control you can control which Web Parts should be available to users on the page level. Depending on your requirements this can be done either declaratively or imperatively. Using the Web Part Adder control you can control which Web Parts are available to your users making it easier for them to work with SharePoint.