Chapter 15. Building pages and dashboards – SharePoint 2010 Web Parts in Action

Chapter 15. Building pages and dashboards

 

This chapter covers

  • Pages in SharePoint
  • Web Part Zones
  • Web Part Manager
  • Deployment and packaging of pages

 

In the previous chapter, I showed you how to build Web Parts that you can connect so that they can exchange information. Users can combine various Web Parts and connect them to build dashboards and pages. For instance, a user might build a customer relationship management (CRM) dashboard by connecting a SharePoint list of customers, Web Parts that read information from a backend system, and filter Web Parts. But not all users can or want to build their own Web Part pages with Web Parts and connections. In many cases, it’s better to build ready-to-go dashboard pages and then allow users to fine-tune them. Building deployable dashboard solutions is a good idea if you plan to reuse the pages or dashboards multiple times.

In this chapter, we’ll take an in-depth look at Web Part pages and zones. You’ll learn how to add and configure pages with Web Part zones and package them into solutions. Then we’ll look at the control that orchestrates the Web Part pages: the Web Part Manager. Finally, I’ll show you ways to package and deploy dashboards.

15.1. Working with pages

I think that Web Parts are one of the most important and interesting things in SharePoint, but Web Parts wouldn’t be useful if you had no place to put them. Web Parts are added to pages and Web Part zones. Specifically the site pages, compared to application pages, are of interest because it’s in those pages that end users can customize Web Parts. Web Part pages have one or more zones that contain the Web Parts. These zones can be configured in several ways and control how the Web Parts within them can be customized.

The glue that holds the Web Parts, pages, and zones is the Web Part Manager. This control is responsible for the connections between Web Parts and ensures that the customized values of the Web Part are persisted to the content databases. Developers can programmatically customize Web Parts using the Web Part Manager, which is useful when you’re dynamically creating Web Part pages.

15.1.1. Pages and Web Part zones

In the first chapter of this book, I introduced you to the various kinds of pages in SharePoint, such as site, publishing, and application pages. Most pages in SharePoint are site pages that contain text, images, Web Parts, and Web Part zones. These pages are normally added to a document library or similar library, and users with the appropriate permissions can add and edit them. A dashboard (which is just another name for a page that uses connected Web Parts) is a site page with one or more Web Part zones.

In many situations you need to supply your users with a preconfigured page or dashboard instead of just giving them the puzzle pieces (the Web Parts). In this section I’ll show you how to build a SharePoint project using Visual Studio and you’ll see how to deploy pages into a site page library.

Adding Pages to Sharepoint

There are many ways to add new pages to SharePoint. Your options vary, depending on the type of page you’re going to deploy. In chapter 10 you learned how to deploy application pages. In this chapter the focus is on site pages and especially Web Part pages.

Although you could use the SharePoint API to add pages using a Feature receiver, the easiest way is to use a declarative approach and deploy the pages using a Module element in a Feature. You do this by creating a new SharePoint project using Visual Studio and adding a new item of the type Module. You can use a sandboxed or a farm solution (more on this later in the chapter). You then remove the sample.txt file that’s included in the Module SPI by default. To add the site page, you need to add a new ASPX page to this module. Unfortunately, Visual Studio doesn’t offer a project item for site pages. So here are your options:

  • Export a page from SharePoint Designer 2010
  • Manually create an ASPX site page or Wiki page or copy from out-of-the-box pages in SharePoint root
  • Download extension project items, such as the CKS:DEV, which contains a Basic Site Page SPI

The first option is useful if you want to customize the page using a rich editor. Pages can be created and edited in SharePoint Designer and then exported as ASPX files. First, select the file in a site page library in SharePoint Designer. Then in the Manage group of the Pages Ribbon tab, select the Export File option, as shown in figure 15.1. Although this approach works well, the code that’s exported into the file contains a lot of SharePoint Designer code and attributes, which may clutter the code (and is useless in this case).

Figure 15.1. Use SharePoint Designer 2010 to create and edit Web Part pages and then export them to a file that can be imported to a Visual Studio project.

To import the page into the Module project item in Visual Studio, right-click the item and select Add > Existing Item; then select the ASPX file that you exported using SharePoint Designer. Visual Studio automatically modifies the elements.xml file to include the new file.

 

Note

When exporting a site page from SharePoint Designer, you’ll see two attributes in the Page directive: meta:webpartpageexpansion and meta:progid. These two tags instruct SharePoint to automatically customize the pages.

 

The second approach requires that you write all the code yourself or, better still, make a copy of the default SharePoint Team Site page. You can copy this file, called default.aspx, from {SharePoint Root}\TEMPLATE\SiteTemplates\sts\. Add the page using Add > Existing Item. (When adding pages throughout the rest of this chapter, you’ll use this method.)

To add a site page based on the Wiki page (which allows you to add Web Parts into the Wiki contents instead of in just Web Part zones), you follow the same procedure but use another source page. You’ll find the source page for Wiki pages (called wkpstd.aspx) in {SharePoint Root}\TEMPLATE\DocumentTemplates\.

The final approach is to use an extension project item such as the Basic Site Page from the CKS:DEV Visual Studio extension. I recommend that you download this extension because it’ll increase your productivity and it contains a useful set of features and project items.

The elements.xml file that defines how the pages are deployed into SharePoint automatically updates itself when you’re adding new pages to the Module project item. By default, the Module element creates a folder in the root of the SharePoint site where it’s deployed. This folder isn’t accessible from any navigation in the SharePoint user interface, and these folders can’t be configured for versioning, security, and more. A better way is to deploy the page into a new or an existing document or site pages library. Do so by adding the Url attribute to the Module element; this attribute specifies the root URL of the deployment as follows:

<Module
    Name="PageDeployment"
    Url="SitePages">
<File
    Path="PageDeployment\Page.aspx"
    Url="PageDeployment/Page.aspx" />
</Module>

The Url attribute of the Module element specifies the root where the files are deployed (SitePages). Each File element represents a file to be deployed, and its Url attribute specifies the filename and (optionally) a folder. In this case the Page.aspx page will be deployed to folder called PageDeployment. To deploy the file’s Site Pages root, remove the folder name from the Url attribute of the File element as follows:

<File
    Path="PageDeployment\Page.aspx"
    Url="Page.aspx" />

The File element contains more attributes, such as the Type, which you can set to Ghostable or GhostableInLibrary. Only use GhostableInLibrary on libraries where you store pages, files, and documents that can benefit from versioning, check-in, and check-out. The benefit of setting File to either of those values is that SharePoint will keep the files cached in memory and any updates to the original file in the file system will be reflected. Not specifying the File attribute puts the file in the database only, and you can’t benefit from caching or updates to the original file. Another important attribute is IgnoreIfAlreadyExists, which you can set to true or false. If you specify this attribute as true, SharePoint ignores any existing file during the file provisioning. The best practice when deploying content files and Web Part pages into a library is to use these attributes. The following code shows the modified elements manifest (elements.xml) with the Type and IgnoreIfAlreadyExists attributes configured:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Module
        Name="PageDeployment"
        Url="SitePages">
        <File
            Path="PageDeployment\Page.aspx"
            Url="Page.aspx"
            IgnoreIfAlreadyExists="TRUE"
            Type="GhostableInLibrary" />
    </Module>
</Elements>
Configuring Web Part Zones

The foundation of a Web Part page or dashboard is the zones that contain Web Parts. The zones allow users to add, move, and configure Web Parts, and they determine the basic layout of the page. Even though Web Parts can be added to areas outside a zone, only Web Parts within the zones, called dynamic Web Parts, can be configured and customized. Static Web Parts can only be updated by customizing the file using SharePoint Designer in Advanced Editing mode or by editing and redeploying the feature.

You add a Web Part zone to a page using the WebPartZone control, defined in the Microsoft.SharePoint.WebPartPages namespace. This control is a SharePoint-specific Web Part zone that derives from the ASP.NET Web Part zone. In SharePoint 2010 there are two types of Web Part zones: the standard Web Part zone and the new Wiki-based zone (which allows mixing of wiki content and Web Parts).

The Team Site page that you used earlier to add a new page in the Module project item uses two Web Part zones defined in a table. The first one (the left one) looks like this:

<WebPartPages:WebPartZone
    runat="server"
    FrameType="TitleBarOnly"
    ID="Left"
    Title="loc:Left" />

In addition to the runat attribute, the zone has three parameters. FrameType defines how the frame of the zone should be rendered. Normally you set this parameter to TitleBarOnly. The ID attribute is important, not only because the zone needs a unique ID, but also because it’s used to reference the zone when programmatically adding Web Parts to the zone. Also, it’s this ID that the Web Part uses to connect to the zone. The Title attribute is also important, because it’s the name of the Web Part zone and is used when adding new Web Parts to the page through the Web Part Gallery. If you remove a zone that contains Web Parts, these Web Parts will still be stored in the database and can’t be removed until you add the zone back or create a new zone with the same ID as the removed zone.

There are a few other attributes that you should know about that you can use when configuring or adding zones. One of the most important is LayoutOrientation. This attribute specifies whether the Web Parts are displayed horizontally or vertically in the zone. Table 15.1 lists some of the attributes that you can use when designing Web Part pages. The Web Part zone controls have numerous properties that can be used to format the zones. Normally you shouldn’t use these properties but should instead rely on the SharePoint standard layout and design.

Table 15.1. Web Part Zone properties

Property

Description

AllowCustomization Boolean value indicating whether users are allowed to customize the shared mode of Web Parts in the zone.
AllowLayoutChange Boolean value indicating if a user can add, close, remove, or change specific layout properties of Web Parts in the zone.
AllowPersonalization Boolean value indicating if users are allowed to personalize the Web Parts in the zone.
Title The title of the Web Part. The property accepts localization strings.
LayoutOrientation Determines the layout orientation of the Web Parts in the zone. Its value can be Horizontal or Vertical.

To build a page that has one zone that’s horizontally oriented and two zones with vertical aligned Web Parts, as shown in figure 15.2, remove all markup in the asp:Content element named PlaceHolderMain of the Web Part page.

Figure 15.2. Web Part zones are positioned in the ASPX pages and are preferably positioned using DIV elements and CSS classes.

The default markup of the Team Site Web Part page uses tables to arrange the Web Part zones, but we’ll use DIV elements instead in this implementation. Listing 15.1 shows how the PlaceHolderMain should look like after you add the DIV elements and Web Part zones.

Listing 15.1. Three Web Part zones positioned using DIV elements and CSS

To use DIV elements for the layout of the page, you need to add custom CSS styles . In this case the CSS elements are added inline in the site page, instead of using a custom CSS file (which might have been more appropriate). Then the user interface is built using a set of DIV elements with unique IDs that map to the CSS styles. In the inner DIV elements, the WebPartZone controls are added. The top one uses horizontal orientation and the other two use vertical.

 

Tip

If you want to change the HTML that the Web Part zones are omitting, you can create a custom control adapter for the WebPartZone control, just as you did for the mobile controls in an earlier chapter.

 

15.1.2. The Web Part Manager

The Web Part Manager is the control that makes the Web Part pages work. It’s responsible for everything relating to Web Parts and zones, such as loading and storing the customized state and layout of the Web Part. The Web Part Manager allows Web Parts to be connected to one another.

SPWebPartManager

In addition to handling all zones, Web Parts, connections, and events on the page, the Web Part Manager is responsible for storing and retrieving the current customized or personalized state of all Web Parts. SharePoint uses the SPWebPartManager, which derives from the ASP.NET WebPartManager control.

The SPWebPartManager control is added to the master page, and normally you don’t need to use it directly, unless you’re building custom master pages. In the v4.master master page, used by SharePoint 2010, the SPWebPartManager is added just below the form control and the ScriptManager control:

<WebPartPages:SPWebPartManager id="m" runat="Server" />

The SPWebPartManager can be accessed from code using a static method. This method requires that you have access to the HttpContext and a page. For instance, in a Web Part or control, the current manager is retrieved like this:

SPWebPartManager manager =
    SPWebPartManager.GetCurrentWebPartManager(this.Page);

You can use the SharePoint Web Part Manager to create Web Parts from a list using the CreateWebPartFromList static function or to add new Web Parts to the page. SPWebPartManager also lets you connect Web Parts or verify whether Web Parts can be connected.

The SPLimitedWebPartManager

The SPWebPartManager control is a complex control and requires that an HttpContext object exist. To make it easier to work with Web Parts programmatically, there’s an object called SPLimitedWebPartManager. This control provides you with a limited but useful set of Web Part operations without requiring an HttpContext object, as in Feature receivers or timer jobs. The SPLimitedWebPartManager also exposes a subset of its functionality through the Client Object Model, as you saw in chapter 11, but it’s not available in sandboxed solutions.

You use the SPLimitedWebPartManager when you need to modify properties of a Web Part during runtime and save its state, or when you add new or connect existing Web Parts on a page. To update and save a property of a Web Part, you can use SPLimitedWebPartManager in an application page, web service, or a dialog window.

Assume that you have a Web Part with a property called Data and that you’d like to update the property when the user clicks a button in the Web Part. To do so, add a button click event handler like this:

The button click event is defined as a lambda expression and the SPLimitedWebPartManager is retrieved by getting the current SPFile object from the SPContext object. The current file is the page where the Web Part exists. When instantiating the SPLimitedWebPartManager object, you need to specify which personalization scope to use (Shared or User); in this case the Shared scope is used. By using the ID of the Web Part, you ensure that the correct Web Part is retrieved from the collection of Web Parts in the SPLimitedWebPartManager. Finally, the Data property is set and the Web Part is saved using the SaveChanges method.

15.2. Deploying dashboards

Now that you know how Web Parts, zones, and connections work, it’s time to put them all together into a dashboard. A dashboard is essentially a Web Part page with a set of connected Web Parts. It could be a reporting page that reads information from a line-of-business system where the users can filter and slice the information dynamically. Typically a dashboard page contains one or more connection providers and a set of connection consumer Web Parts. The consumer Web Parts can be lists or graphs, or they can present other relevant information.

You can build and deploy dashboards in several ways. Which method you’ll use depends on the situation. You can create a complete dashboard by using a declarative approach where you define the page, Web Parts, and connections using XML. Or you can programmatically provision the Web Parts and connections on a page, perhaps using external dependencies. The dashboard can be a preconfigured Web Part page that your end users can extend and configure, or it can be a static dashboard that can’t be configured. You can even deploy dashboards as a part of the site-creation procedure.

15.2.1. Deploying using a Feature

The first way to deploy a Web Part page or dashboard is to use a declarative approach, without any compiled code. By using a Module in a Feature, you can create a page, including its Web Parts and connections.

I’ll show you how to deploy a Web Part page that will contain a Web Part zone and two connected Web Parts. You’ll use the Web Parts from the previous chapter, as shown in figure 15.3. First you need to create a new Empty SharePoint project. For this first sample, you can select to deploy your solution as a sandboxed solution. Also make sure that the solution from chapter 14 is deployed to SharePoint. Remember that Visual Studio, by default, retracts solutions after running and debugging solutions unless you explicitly tell it to deploy the solution.

Figure 15.3. A page can be installed prefilled with Web Parts and connections to make it easier for end users to configure their sites.

Add a new Module to the project, remove the sample file, and then add a new Web Part page (by copying the Team Site Web Part page as shown earlier). Give it the name default.aspx. Modify the PlaceHolderMain so that it contains one Web Part zone called Main; the code looks like this:

<asp:Content ContentPlaceHolderId="PlaceHolderMain" runat="server">
    <WebPartPages:WebPartZone
        runat="server"
        FrameType="TitleBarOnly"
        ID="Main"
        Title="loc:Main"
        LayoutOrientation="Vertical"/>
</asp:Content>

Make sure that the page is provisioned to a Site Pages library and configure it as described earlier in the elements manifest file. The following code copies the default.aspx page into the Dashboard1 subfolder in the Site Pages library:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Module
        Name="Dashboard1"
        Url="SitePages">
        <File
            Path="Dashboard1\default.aspx"
            Url="Dashboard1/default.aspx"
            Type="GhostableInLibrary"
            IgnoreIfAlreadyExists="TRUE"/>
    </Module>
</Elements>

To add Web Parts to the file that’s provisioned using the Module item, use an element called AllUsersWebPart. This element is added as a child to the File element, and it contains the contents of a Web Part controls description file (the .webpart file), as shown in listing 15.2. You can either copy the contents of a .webpart file from a Visual Studio project or select to export a preconfigured Web Part, save it to disk, and then copy the contents from that file. The connection between the Web Parts is done using another element called WebPartConnection.

Listing 15.2. Declarative provisioning Web Parts on a page

The File element contains two AllUsersWebPart elements: the Feed Input Web Part and the RSS Web Part . Both specify that the Web Parts are placed in the zone called Main using the WebPartZoneID attribute. The WebPartOrder element specifies the order of the Web Parts in the zone using an integer starting with 0. Both Web Parts are also given a unique ID. The inner value of the AllUsersWebPart element is a CDATA element used to specify the definition, the .webpart file contents, of the Web Parts. The first Web Part is the custom Web Part provider you built in chapter 14 and the second is the RSS Web Part from the same chapter. Both Web Parts have their Title specified in the CDATA element, and the RSS Web Part also has the ItemCount property defined.

 

Note

I use the fully qualified name of the Web Parts and its assemblies in this sample since they exist in another Visual Studio project. If the Web Parts exist in the same project as the page provisioning Module, then you should use the Visual Studio replaceable tokens instead of the fully qualified names.

 

The Web Parts are connected using the WebPartConnection element . This element connects two Web Parts using the IDs specified in the AllUsersWebPart elements with the ConsumerID and ProviderID attributes. It’s also necessary to specify the names of the connection endpoint for the consumer (using ConsumerConnectionPointID and ProviderConnectionPointID), because it has several endpoints. Finally, the connection needs an ID.

The dashboard is now ready to be deployed. This deployment works with the sandbox because the Web Parts used and connected are deployed using a farm solution. Press F5 to deploy and debug your solution. Then go to the Site Pages library and locate the dashboard under the Dashboard1 folder. Enter a URL in the Feed Input Web Part and see how the connected RSS Web Part is updated.

 

Tip

Microsoft recommends that a Web Part page not contain more than 25 Web Parts (open or closed) for performance reasons.

 

15.2.2. Deploying using a Feature receiver

Another option to deploy a dashboard with configured Web Parts is to use a Feature receiver and the SPLimitedWebPartManager. (You can’t use this option in sandboxed solutions.) The benefit of this approach is that you can debug the provisioning of the dashboard, which isn’t possible using the declarative approach. Another benefit of using a programmatic approach is that you can define the layout of the dashboard depending on the runtime state of the site.

To build this solution you can either create a new project that’s deployed as farm solution or change the previous project from a sandboxed solution to a farm solution. The easiest way to change the old project is to select the project in the Solution Explorer, press F4, and toggle the value for Sandboxed Solution to False.

I’ll show you how to create the same dashboard with the connected Web Part as in the previous section but this time using a Feature receiver. Start by adding a new Module to the project; give it the name Dashboard2 and then add a Web Part page. Modify it as you did earlier so that it has one Web Part zone called Main. Update the elements.xml file so that your page is deployed into the Site Pages library and to a subfolder called Dashboard2, and that the name of the file is default.aspx. Once you’ve completed these steps, you need nothing more to the Module project item.

 

Tip

When creating a dashboard in a solution that’s deployed as fully trusted, you can create your own Web Part page implementation by overriding the Microsoft.SharePoint.WebPartPages.WebPartPage class. This allows you to add your custom code-behind to the Web Part page.

 

You add the Feature receiver that will do all the work in this scenario to the project by right-clicking on the Feature and selecting Add Event Receiver. When Visual Studio has added the necessary files and configuration, the event receiver file will be opened in Visual Studio. Uncomment the FeatureActivated method. It’s in this method that you’ll add the code shown in listing 15.3, which will populate the Web Part page with the Web Parts and connections. Before writing the code, add a reference to the project built in chapter 14 so that the Web Part classes can be used in this project.

Listing 15.3. Programmatically provisioning Web Parts on a page

The code in the Feature receiver retrieves the current site (SPWeb) and the file using the path . The namespace alias SP is used for Microsoft.SharePoint.WebPartPages to avoid conflicting WebPart definitions. Using the file object (SPFile), the current SPLimitedWebPartManager object is retrieved . Note that the use of the SPLimitedWebPartManager is scoped in a using statement so that it’s safely disposed at the end of the call. To make sure that Web Parts aren’t added many times to the page if the Feature is repeatedly activated, all Web Parts are removed from the page, using the LINQ statement. Once that’s done, the RSS Web Part is created and initialized. The same is done for the Feed Input Web Part. When the objects are created, they’re added to the zone on the page using the SPLimitedWebPartManager method AddWebPart. This method takes the Web Part, the name of the zone, and the position as arguments. Next up is to connect the Web Parts; this is done using a SPWebPartConnection object . This object works similarly to the WebPartConnection element in the previous sample. It needs the IDs of the provider and the consumer as well as the names of the connection endpoints and an ID of the connection itself. This connection object is added to the collection of connections in the Web Part Manager. The last thing that’s needed to complete the dashboard is to save the Web Parts using the SaveChanges method of the SPLimitedWebPartManager .

When you deploy this project solution, it will look like and work exactly the same as the previous dashboard, defined using the declarative method. The benefit of this approach is that you can debug the provisioning and add Web Parts and connections dynamically. And the downsides are that you need to reference the assemblies where the Web Parts are defined and you can’t deploy the solution into the sandbox.

15.2.3. Static dashboards

The two dashboards you’ve created are built as Web Part pages that users can further customize or personalize. In some cases you might prefer to deploy a static dashboard or page with connected Web Parts. Web Parts can be connected when they’re static, but a static Web Part can’t be connected to a dynamic Web Part. To create a static dashboard you basically have two options: lock down the Web Part zones of a dashboard page or deploy all Web Parts and connections as static.

To lock down a Web Part zone for editing, you can use the Web Part zone attributes specified in table 15.1. The following Web Part zone would prohibit users from adding new Web Parts, personalizing the Web Parts, and making layout changes:

<WebPartPages:WebPartZone
    runat="server"
    FrameType="TitleBarOnly"
    ID="Main"
    Title="loc:Main"
    LayoutOrientation="Vertical"
    AllowPersonalization="False"
    AllowLayoutChange="False"/>

The AllowPersonalization and AllowLayoutChange attributes are both set to False to prohibit users from personalizing and editing the layout of the Web Part zone. In this example, the AllowCustomization property is not set to False, which would’ve been appropriate in this case. The reason this attribute isn’t used is that when SharePoint loads the page for the first time it needs to store the values of the Web Parts into the database; if AllowCustomization is set to False this can’t be done and you’ll receive an exception. If you need to set AllowCustomization to False, you can edit the page in SharePoint Designer and customize it, which will save the contents to the database.

The other way to create a static dashboard is to not use Web Part zones and add the Web Parts directly to the page. Web Parts are essentially ASP.NET web controls and can be added to any page. When Web Parts are added out of a zone, they’re called static and can’t be modified or customized by users. But users with appropriate permissions can still use SharePoint Designer to modify the page.

Instead of adding the Web Parts to the element manifest, you add the Web Parts to the page that’s provisioned through the Module. First, add the page directives to register tag prefixes for the Web Parts:

<%@ Register
    Tagprefix="RSS"
    Namespace="WebPartsInAction.Ch14.Connections.RssWebPart"
    Assembly="WebPartsInAction.Ch14.Connections, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8b0f149932984439" %>
<%@ Register
    Tagprefix="FI"
    Namespace="WebPartsInAction.Ch14.Connections.FeedInputWebPart"
    Assembly="WebPartsInAction.Ch14.Connections, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8b0f149932984439" %>

These directives register the two tag prefixes RSS and FI and the corresponding namespaces and assemblies for the two Web Parts. Using the tag prefixes, you can add the Web Parts directly to the ASPX page:

<FI:FeedInputWebPart
    runat="server"
    id="FIWP"/>
<RSS:RssWebPart
    runat="server"
    id="RSSWP"
    ItemCount="10"/>

This code will add the Feed Input Web Part and the RSS Web Part to the page and configure the RSS Web Part to retrieve 10 items from its feed. The Web Parts can’t be connected as you did before using the WebPartConnection element in the declarative dashboards using the SPLimitedWebPartManager in the event receiver. In this case the SPWebPartManager control, defined in the master page, must be used, but achieving this would require code to connect them during runtime. Fortunately there’s a proxy control, called SPProxyWebPartManager (this control can’t be used in the sandbox), that the Web Part Manager uses to handle static connections. To create the static connection between the Web Parts, use the following code:

<WebPartPages:SPProxyWebPartManager
    runat="server"
    id="ProxyWebPartManager">
    <SPWebPartConnections>
        <WebPartPages:SPWebPartConnection
            ID="connection"
            ConsumerConnectionPointID="feed"
            ConsumerID="RSSWP"
            ProviderConnectionPointID=""
            ProviderID="FIWP">
        </WebPartPages:SPWebPartConnection>
    </SPWebPartConnections>
</WebPartPages:SPProxyWebPartManager>

The SPProxyWebPartManager control contains a collection of SPWebPartConnection objects, the same kind of object used when adding connections to the SPLimitedWebPartManager. The connection consumer and provider and their endpoints are specified as before. Once the SPProxyWebPartManager code is added to the page, you can deploy it using a Module project item containing the ASPX file. When the page is used in SharePoint, users can’t edit or customize the Web Parts. The approach of employing static Web Parts and connections can also be used when you’re deploying an application page.

15.2.4. Dashboards with a sandboxed Web Part

So far you’ve learned how to build dashboards using fully trusted Web Parts, but what about a sandboxed dashboard with a sandboxed Web Part? Creating a sandboxed dashboard involves using a single sandboxed Web Part in a Web Part page. No connections are used here because sandboxed Web Parts can’t be connected using ASP.NET 2.0 connections.

 

Note

For sandboxed Web Part pages you need to use the WebPartPage class. You can’t create custom code-behind classes for pages in the sandbox.

 

Just as with previous dashboards, the solution should consist of a Module project item that contains a Web Part page. If you added the Sandboxed Web Part to the AllUsersWebPart element specifying the type and assembly, SharePoint would throw an exception like this:

Web Part Error: Cannot import this Web Part.

This exception is thrown because the dashboard tries to reference a fully trusted Web Part with that name, and the Web Part specified only exists in the sandbox. To resolve this issue, you need to make a little modification to the Web Part control description in the AllUsersWebPart element. First, go to the Web Part Gallery, select to edit the sandboxed Web Part, and then click the View XML button in the Ribbon. Finally, save the XML file. Open the file and notice that a new element called Solution has been added as a child element to the metaData element, like this:

<Solution
    SolutionId="242e1187-5478-4ccc-9358-dff4d1188d56"
    xmlns="http://schemas.microsoft.com/sharepoint/" />

This element specifies that this Web Part belongs to a solution in the Solution Gallery of the site collection—that is, a sandboxed Web Part. The value in the SolutionId attribute is the ID of the Solution Package. By adding this to the Web Part definition in the AllUsersWebPart, you can successfully deploy the dashboard. You can also find this ID from the properties of the Package Editor. The AllUsersWebPart should look like this after you add the Solution element:

The definition of the AllUsersWebPart element looks the same as for the fully trusted dashboards, with the difference that the Solution element is added to the Web Part control description. Visual Studio replaceable parameters are used for the assembly in the type element and for the solution ID in the Solution element to avoid manually entering them.

When this dashboard is deployed, it’ll show the sandboxed Web Part and users can modify it. You can mix sandboxed and already deployed fully trusted Web Parts in your sandboxed dashboards.

To create a static sandboxed dashboard, you need to use another approach. The Web Part must be wrapped in a special Web Part called SPUserCodeWebPart. The SPUserCodeWebPart is a fully trusted Web Part that acts as a proxy for a sandboxed Web Part and serializes information to and from SharePoint to the sandbox. The user code Web Part looks like this when placed directly on an ASPX page:

<WebPartPages:SPUserCodeWebPart
    ID="SandboxWP"
    runat="server"
    Title="Sandboxed WebPart"
    AssemblyFullName="$SharePoint.Project.AssemblyFullName$"
    SolutionId="$SharePoint.Package.Id$"
    TypeFullName="WebPartsInAction.Ch15.SBDashboard.SandboxedWebPart.SandboxedWebPart" />

The SPUserCodeWebPart has three properties used to locate the wrapped sandboxed Web Part. SolutionId identifies the solution, and TypeFullName and AssemblyName identify the Web Part.

15.2.5. Deploying using a site definition

If you’re building reusable portals and sites, you’ve probably been creating, or at least looked at, site definitions. Site definitions are the basis for all sites in SharePoint, and they serve as a template for the sites. They contain, for example, the default activated features and one or more modules that are provisioned when a site is built on a site definition. In SharePoint 2010 the concept of Web Templates are introduced. Web Templates are quite similar to Site Definitions but offer more flexibility and sandbox support. Web Templates should be considered before Site Definitions because they’re supported in SharePoint Online, and Site Definitions aren’t.

The topic of building site definitions could fill a few chapters on its own and there are many opinions on how and when to use them. For our purposes here, it’s important to know that you can provision dashboards directly in a site definition using one of the following options:

  • Deploy the dashboard as a module in the site definition
  • Deploy the dashboard as a feature in the site definition
  • Deploy the dashboard feature to the sites using the site definition with feature stapling
  • Use a provisioning provider as a part of a site definition

Let’s take a look at the options starting at the top. The first option is to use a Module in the onet.xml file of the site definition. This is exactly the same procedure I’ve shown you a few times in this chapter. For the File elements in the Module elements, you add AllUsersWebPart elements that contain the Web Parts you want to provision. An easy and fast solution! The downside relates to the nature of site definitions; once the site definition is deployed and in use, modifying the site definition is no longer supported. So this approach doesn’t fit very well into an agile development methodology. For Web Templates, this option is not available.

The second alternative is slightly better. Instead of adding the Web Parts directly to the site definition onet.xml file, you create a Feature containing a dashboard and reference that Feature from the onet.xml file. For a web-scoped Feature the code could look like this:

<WebFeatures>
    <Feature ID="2c2fd31b-d7c1-4e19-8981-8595f4da781d"/>
</WebFeatures>

When a site based on this site definition is provisioned, it’ll automatically activate the feature with the ID specified in the Feature element. Using this approach allows you to update the dashboard Feature in a supported way. This option is also valid for Web Templates. But what if you want to add your dashboard to an already existing site definition, perhaps one of the out-of-the-box site definitions? I’ve already told you that you aren’t allowed to modify existing site definitions. But then, you can take advantage of something called feature stapling.

Feature stapling is a way to add Features to an already existing site definition or Web Template. This is done by creating a specific stapler Feature that contains information about which Feature to staple onto which site definition. To create a stapler Feature, you need to create a new Feature that’s scoped at the farm level and then add an element manifest containing FeatureSiteTemplateAssociation elements:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <FeatureSiteTemplateAssociation
        Id="2c2fd31b-d7c1-4e19-8981-8595f4da781d"
        TemplateName="STS#0"/>
    <FeatureSiteTemplateAssociation
        Id="2c2fd31b-d7c1-4e19-8981-8595f4da781d"
        TemplateName="DashboardSiteDefinition#0"/>
</Elements>

The Feature containing this element manifest would staple the Feature with the specified Id onto the default SharePoint Team Site (STS#0) and to a custom site definition called DashboardSiteDefinition with configuration 0. For all new sites created with any of those site definitions, the specified Feature would automatically be activated. Sites that are already created won’t benefit from the Feature stapling and the Feature must be activated manually or through code.

The final option, using a provisioning provider, allows you to programmatically add Web Parts and perform other logic operations in code that’s executed after the site is fully provisioned. Provisioning providers are only available for Site Definitions in SharePoint Server and are a part of the publishing infrastructure. A provisioning provider is a class derived from the SPWebProvisioningProvider class, and it’s specified in the site definition using the ProvisioningClass and ProvisioningAssembly. The same rules apply here; you can’t change the site definition once it’s in use but you can update the provisioning provider.

15.3. Summary

This was the final chapter of this book and I hope you enjoyed the ride as much as I have. Even though this chapter didn’t mention all the amazing things that can be done using Web Parts, it showed you how to combine several of the Web Part techniques to build a complete solution. Providing your end users with prebuilt dashboards is one thing that can greatly enhance the SharePoint experience and make users feel more comfortable with it if they aren’t used to the technology.

By now you should be thinking that you know everything about Web Parts. If you read and understand this book you know a great deal, but not everything. SharePoint is such a complex and amazing product and there are very few folks around the world who know every detail about it. I’ve intentionally left a few things out because they’re either seldom used or too specific for this book. Perhaps I’ll find more time and space to write about them in the future!