The following exercise shows how to create a basic Web Part using the appropriate template.

In the ASCX file you can now proceed as with any user control. There is a visual designer and a code editor window. There are no Web Part–specific modifications—you can program against the SharePoint API, and you can add ASP.NET as well as SharePoint controls.

<%@ Assembly Name="$SharePoint.Project.AssemblyFullName$" %>
<%@ Assembly Name="Microsoft.Web.CommandUI, Version=14.0.0.0,
                   Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls"
             Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral,
                       PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities"
             Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral,
                       PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="asp" Namespace="System.Web.UI"
             Assembly="System.Web.Extensions, Version=3.5.0.0, Culture=neutral,
                       PublicKeyToken=31bf3856ad364e35" %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Register Tagprefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages"
             Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral,
                       PublicKeyToken=71e9bce111e9429c" %>
<%@ Control Language="C#" AutoEventWireup="true"
            CodeBehind="VisualWebPart1UserControl.ascx.cs"
    Inherits="VisualWebPartProject1.VisualWebPart1.VisualWebPart1UserControl" %>
<asp:Label runat="server" ID="lbl1" Font-Size="Large">Hello World</asp:Label>

In this example, only the Label element has been added.

<?xml version="1.0" encoding="utf-8"?>
<webParts>
  <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
    <metaData>
      <type name="VisualWebPartProject1.VisualWebPart1.VisualWebPart1,
                  $SharePoint.Project.AssemblyFullName$" />
      <importErrorMessage>$Resources:core,ImportErrorMessage;</importErrorMessage>
    </metaData>
    <data>
      <properties>
        <property name="Title" type="string">My First VisualWebPart</property>
        <property name="Description" type="string">My First WebPart</property>
      </properties>
    </data>
  </webPart>
</webParts>

In this example the properties Title and Description has been changed.

As mentioned several times in this book, pages must derive from a master page supported by SharePoint. Web Part pages are no exception. Using the default.master page as the basis for internal pages ensures that SPWebPartManager's sole instance is present, if required. There are no further settings or actions needed.

If additional zones are required, we use a slightly different approach. SharePoint defines its own zone model, which derives from the WebPartZone class. Employ the Microsoft.SharePoint.WebPartPages namespace instead of the one provided with ASP.NET. (Note that contrary to the standard SharePoint namespace naming convention, the type does not have the SP prefix.)

SharePoint Web Parts are an integral part of a SharePoint web site. There are many built-in Web Parts a developer may use. Also, there are many Web Parts available on the Internet that could meet your requirements. The various built-in SharePoint Web Parts are categorized as follows:

Almost all the built-in SharePoint Web Parts are generic. That means that they have properties you can modify in SharePoint.

Consider the Content Editor Web Part, which, when in Edit mode, provides an option called Rich Text Editor, which allows the user to enter and format content. Another option is Source Editor, which allows you to edit the raw HTML that the Content Editor will render.

Similarly, in the Page Viewer Web Part, the user can set the link to display a web page, folder, or file in the Web Part. Therefore, the advantage of generic Web Parts is that users can configure them to suit their own requirements.

The method of creating a generic Web Part is more or less the same as creating an ASP.NET Web Part—the difference comes when you want to provide the user with the means to set some values or fields in the Web Part.

The developer has to set the fields as properties in the code to enable the user to edit the desired values. Apart from setting the fields as properties, you have to add several attributes to the property that are visible to the user when editing the Web Part. Apart from one for the category (SPWebCategoryName), all attributes are from the common ASP.NET namespace.

private string _name;

[
System.Web.UI.WebControls.WebParts.WebBrowsable(true),
System.Web.UI.WebControls.WebParts.Personalizable(PersonalizationScope.User),
System.Web.UI.WebControls.WebParts.WebDescription("Enter your name"),
Microsoft.SharePoint.WebPartPages.SPWebCategoryName("Custom Properties"),
System.Web.UI.WebControls.WebParts.WebDisplayName("Name")]
public string Name
{
   get { return _name; }
   set { _name = value; }
}

Several attributes, as shown in the example Name property, modify the design-time behavior of the Web Part. Here, design-time means both the control shown in a designer environment such as SharePoint Designer or Visual Studio 2010, and a Web Part page in Edit mode.

In the "Advanced Web Part Development" section later in the chapter, you'll find a complete description and further usage scenarios for these and other, more essential attributes.

All Web Parts render inside a chrome. The term refers to common UI elements such as titles and borders. You may interpret chrome as frame style. This style is simple but provides a consistent look and feel to all Web Parts. Primarily, it's designed to support the basic functionality that the SharePoint environment needs, such as the context menu that allows editing (which appears at the upper-right corner of the Web Part). The chrome functionality is part of the Web Part framework, which consists primarily of the WebPartZoneManager. If the Web Part is used as a simple control, without being in any zone, the chrome will not render. The Web Part will still be usable, but you're responsible for providing editing capabilities, if needed.

Web Parts provide a powerful way to extend the UI by adding features that have access to the API and allowing full control over parts of default pages. The security model protects you from just inserting a Web Part and letting it do something. This makes sense, because otherwise even end users could under certain conditions upload a Web Part and activate it. There are two ways to add a Web Part you trust to your installation. The first way is to use Code Access Security (CAS), or just adopt the corresponding settings from the built-in security models, such as WSS_Minimal or WSS_Medium. The other approach is to explicitly register a Web Part as safe, if you know exactly what it does. The second way is the default because it allows developers to gain control over the procedure. However, administrators will still have to execute the primary installation of a Web Part—and so, ultimately, they know what's going on. The methods described simplify the installation procedure.

Registering a Web Part as Safe

Whether you use the Visual Web Part or the regular Web Part project template, the procedure to register it as a safe control is somewhat automated. The file that contains the SafeControl instruction is named <webpart>.spdata. It is hidden by default. Usually you edit it by using the PropertyGrid and modifying the safe control entries file by file (see Figure 6-1). However, sometimes it's easier to edit the file directly, either if Visual Studio fails or you want to change several items at once. You must unhide all files in the project to view it. Usually there is no need to edit it—however, for example, if you change a namespace, the changes will not be tracked and the registration can fail. In these rare circumstances, you can use the property grid to edit the file.

Figure 6.1. Edit the safe control entries using the Properties Editor.

The properties defined here are specific to the Web Part. Select the Web Part item in Solution Explorer, press F4, and select the ellipses button in the Safe Control Entries row. Typically, the file these entries refer to looks like that shown in Listing 6-4.

<?xml version="1.0" encoding="utf-8"?>
<ProjectItem Type="Microsoft.VisualStudio.SharePoint.WebPart"

DefaultFile="CustomWebPart.cs" SupportedTrustLevels="All"
             SupportedDeploymentScopes="Site"
             xmlns="http://schemas.microsoft.com/VisualStudio/2010/
                    SharePointTools/SharePointProjectItemModel">
  <Files>
    <ProjectItemFile Source="Elements.xml" Target="CustomWebPart"
                     Type="ElementManifest" />
    <ProjectItemFile Source="CustomWebPart.webpart" Target="CustomWebPart"
                     Type="ElementFile" />
  </Files>
  <SafeControls>
    <SafeControl Name="CustomWebPart"
                 Assembly="$SharePoint.Project.AssemblyFullName$"
                 Namespace="WebPartPageProject.MyWebParts"
                 TypeName="*" IsSafe="true" />
  </SafeControls>
</ProjectItem>

The <SafeControl> element at the end is responsible for the setting copied to web.config. You can modify this to reapply settings not applied automatically.

Dealing with Built-In Security

There are three configuration files in the SharePoint root under the subfolder CONFIG: wss_minimaltrust.config, wss_mediumtrust.config, and wss_usercode.config. The latter, wss_usercode.config, is specifically for sandboxed solutions. When code runs in the sandbox, the web.config file that references the trust file in the subfolder UserCode is used. This typically contains the following:

<trustLevel name="WSS_Sandbox" policyFile="..configwss_usercode.config" />

Regular solutions use the common trust files. These come with a specific set of restrictions. The default configuration is wss_miminaltrust, which is quite limited. Table 6-1 outlines the permissions available.

This means that if you use any of the disallowed permissions mentioned in the table, the execution engine will reject the attempt with a security exception (see Figure 6-2).

Figure 6.2. Unexpected exception during Web Part import due to security violations

In the following example, the Web Part has code that attempts to write to the event log:

protected override void CreateChildControls()
{
    base.CreateChildControls();
    Label l = new Label();
    EventLog log = new EventLog("Application");
    log.WriteEntry("WebPart was Displayed", EventLogEntryType.Information,
                    10000, 4);
    l.Text = "Hello Security Web Part";
    Controls.Add(l);
}

Because the error message is not very instructive, and could be difficult even for an administrator to decipher, you should add a security permission attribute to your code:

[ToolboxItemAttribute(false)]
[EventLogPermission(System.Security.Permissions.SecurityAction.Demand)]
public class WebPartMinimalTrust : WebPart
{
    // Code removed for sake of clarity
}

In this case, the error occurs earlier (see Figure 6-3), and SharePoint can catch it before the Web Part is added.

Figure 6.3. Still an uninformative dialog for the security error

In fact, the error message from SharePoint is no better. But instead of an unexpected error being generated, the process is stopped by the permission check and the Web Part is not added.

If medium trust is sufficient, you can consider setting it as the default trust level. However, for Web Parts requiring classes you can't access with medium trust, you must provide a custom code access policy. Sandboxed solutions do not allow overwriting the CAS policy.

Providing Web Part–Specific CAS Policy

If a Web Part needs some specific CAS policy, you can add the information to the deployment package. In addition, the administrator must provide the -allowCasPolicies parameter when installing the solution using the stsadm tool. This ensures that the administrator has ultimate control over what a new Web Part can do.

To use a custom CAS policy, do the following:

Using the same Web Part as before and Visual Studio 2010 to create the package, this is very easy. First, set the Assembly Deployment property of the current Web Part project to WebApplication (see Figure 6-4). This deploys the assembly—not into the GAC, but into a less trusted file location of your project target.

Figure 6.4. Setting the Assembly Deployment property

Second, add the custom policy to the package designer. Open the package designer by double-clicking Package.package. Then select the Manifest tab and enter the CAS data into the template windows. The content is merged into the package file shown in the preview pane, as shown in Figure 6-5.

Figure 6.5. Adding the CAS policy to the current project's package

Third, add the required attribute to the assemblyinfo.cs file:

[assembly: AllowPartiallyTrustedCallers()]

Finally, build and deploy the package again. You can now add it to the current installation and use the formerly blocked classes. The CAS policy should be completed to allow at least the typical permissions a Web Part demands. The XML would then look as shown in Listing 6-5.

<CodeAccessSecurity>
 <PolicyItem>
  <PermissionSet class="NamedPermissionSet" version="1"
                 Description="Permission set for my Web Part">
  <IPermission class="AspNetHostingPermission" version="1" Level="Minimal" />
  <IPermission class="SecurityPermission" version="1"
               Flags="Execution,ControlPrincipal,
                       ControlAppDomain,ControlDomainPolicy,
                       ControlEvidence,ControlThread" />
  <IPermission class="Microsoft.SharePoint.Security.SharePointPermission,
               Microsoft.SharePoint.Security, Version=14.0.0.0, Culture=neutral,
               PublicKeyToken=71e9bce111e9429c"
               version="1" ObjectModel="True" />
  <IPermission class="System.Security.Permissions.EnvironmentPermission, mscorlib,
                       Version=2.0.0.0, Culture=neutral,
                       PublicKeyToken=b77a5c561934e089" version="1"
               Read="UserName" />

<IPermission class="System.Security.Permissions.FileIOPermission, mscorlib,
                       Version=2.0.0.0, Culture=neutral,
                       PublicKeyToken=b77a5c561934e089" version="1"
               Read="$AppDir$ "
               Write="$AppDir$"
               Append="$AppDir$"
               PathDiscovery="$AppDir$" />
 </PermissionSet>
 <Assemblies>
  <Assembly Name="VisualWebPartProject1" />
 </Assemblies>
</PolicyItem>
</CodeAccessSecurity>

It's necessary to add all these permissions because the custom CAS file does not merge. Instead, it replaces the common definitions. Thus, the definition must contain all permissions required to execute the Web Part.

The settings in the CAS file depend on the permissions you need. That's why the IPermission element is not described elsewhere. The only common attribute is the class attribute that specifies the fully qualified name of the permission class. In the next example, this is the EventLogPermissionAttribute. All the other attributes are extracted from the named parameters. Figure 6-6 illustrates how to view all the named parameters at once in Visual Studio.

Figure 6.6. Check the code editor to view the named parameters.

If you add enum values, the value is sufficient; the enum type does not need to be explicitly stated. The engine will extract it from the property's type.

The project provides several files that create the Web Part and define its appearance within the SharePoint site. By default, the feature is deployed to the referenced site collection. Figure 6-7 shows the standard structure that is created.

Figure 6.7. Structure of a Visual Web Part project

The folder VisualWebPart1 contains the Web Part itself. VisualWebPart1UserControl.ascx is the markup file (see Listing 6-7), which when first created contains the code shown in Listing 6-8.

<%@ Assembly Name="$SharePoint.Project.AssemblyFullName$" %>
<%@ Assembly Name="Microsoft.Web.CommandUI, ..." %>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls"
             Assembly="Microsoft.SharePoint, ..." %>
<%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities"
             Assembly="Microsoft.SharePoint, ..." %>
<%@ Register Tagprefix="asp" Namespace="System.Web.UI"
             Assembly="System.Web.Extensions, ..." %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Register Tagprefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages"
             Assembly="Microsoft.SharePoint, ..." %>

<%@ Control Language="C#" AutoEventWireup="true"
             CodeBehind="VisualWebPart1UserControl.ascx.cs"
Inherits="VisualWebPartDashboard.VisualWebPart1.VisualWebPart1UserControl" %>

This is simply time-saving and housekeeping code. The first line references the assembly that is created by your project, via a placeholder. The assembly is usually deployed to the GAC, and the line references it at runtime. The second line contains a reference to Microsoft.Web.CommandUI, the assembly that contains the ribbon support. The next few lines reference and import the corresponding namespaces to get access to the SharePoint controls. The last line defines the control itself and references the code-behind file.

The code-behind (see Listing 6-8) file is essentially empty, except for the Load event handler to get you started.

using System;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Utilities;

namespace Apress.SP2010.VisualWebPartProject
{
    public partial class VisualWebPart1UserControl : UserControl
    {
        protected void Page_Load(object sender, EventArgs e)
        {
        }
    }
}

In the same folder, the Web Part definition (.webpart) describes what you see within SharePoint when adding the Web Part to a page (Listing 6-9).

<?xml version="1.0" encoding="utf-8"?>
<webParts>
  <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
    <metaData>
      <type name="Apress.SP2010.VisualWebPartProject.VisualWebPart1,
                  $SharePoint.Project.AssemblyFullName$" />
      <importErrorMessage>$Resources:core,ImportErrorMessage;</importErrorMessage>
    </metaData>
    <data>
      <properties>
        <property name="Title" type="string">VisualWebPart1</property>
        <property name="Description" type="string">My Visual WebPart</property>
      </properties>
    </data>
  </webPart>
</webParts>

The metadata describes the class's name and the assembly's full name, again using the placeholder. The <importErrorMessage> element contains a message that appears if an end user can't import a Web Part previously exported by somebody else. Users can—if they have the appropriate permissions—export a Web Part as a file and import it elsewhere. That means that users can move Web Parts across site and server boundaries.

If there are Web Part dependencies that are not found on the target SharePoint system, the error message is displayed. In the preceding example, the message extracted from the resources of the core RESX file via the $Resources expression is the default one. You could replace it with any useful text here. Inside the <data> element, some properties are defined. (See the "Understanding Properties" section later in the chapter for more information regarding what you can write in here.) We recommend you provide at least a title and a short description, as these are helpful when dealing with the Web Part later.

The features manifest contains the manifest file elements.xml (see Listing 6-10). It specifies where to store the Web Part (Web Part catalog) and where the Web Part itself is defined (VisualWebPart1.webpart file, as shown previously).

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/" >
  <Module Name="VisualWebPart1" List="113" Url="_catalogs/wp">
    <File Path="VisualWebPart1VisualWebPart1.webpart"
          Url="VisualWebPartDashboard_VisualWebPart1.webpart"
          Type="GhostableInLibrary" >
      <Property Name="Group" Value="Custom" />
    </File>
  </Module>
</Elements>

In addition, the solution package and the feature definition are part of the template. This aspect is common to all deployable projects and explained in greater depth in Chapter 7. Primarily, it contains the name and description, and optionally an icon that represents the feature. It also contains the settings that define the scope in which the feature becomes visible.

As with any other class project, you are supposed to edit the AssemblyInfo.cs file. Because the project's assembly is deployed as part of the feature, someone can inspect the file, looking for metadata. Editing the AssemblyInfo.cs file is equivalent to editing the settings of the project's Properties pane. You can edit either of these to set the appropriate file data, such as copyright notice, file title and description, and company information.

[assembly: AssemblyTitle("My VisualWebPart")]
[assembly: AssemblyDescription("Something really useful")]
[assembly: AssemblyConfiguration("")]
[assembly: AssemblyCompany("Apress")]
[assembly: AssemblyProduct("VisualWebPart Product")]
[assembly: AssemblyCopyright("Copyright © Apress 2009")]
[assembly: AssemblyTrademark("")]
[assembly: AssemblyCulture("")]

The settings are preset when the project is created but are not updated to match your changes. The assembly title, for example, follows the project's name. However, if you change the project name later, the corresponding assembly title attribute remains unchanged.

To put an assembly into the GAC, it must have a strong name. The project template comes with a predefined key.snk file that contains a key to sign the assembly. We strongly recommend replacing this key file with one key file common to all your projects so that you have a unique token for all assemblies created as part of a project.

If you create a new Visual Web Part project, the Sandbox option appears disabled. That's a significant impediment. Loading a file from the root folder of the SharePoint installation—the 14 hive—is not allowed in a sandboxed solution. This is reasonable, as you can imagine what would happen if a hosting provider or Microsoft SharePoint Online installation allowed everybody to deploy such Web Parts to a shared host. However, that's exactly what the Visual Web Part project template does. Visual Studio knows this, so you cannot create a sandboxed Web Part. Even trying to fool it by creating an empty sandboxed solution and adding a Web Part to it will fail once you try to create the package (see Figure 6-8).

Figure 6.8. Sandboxed solutions can't contain files that deploy into the 14 hive.

If you really need a Web Part running in a sandboxed solution, you are supposed to use a regular (not Visual) Web Part. Create a new, empty SharePoint solution, add a Web Part to it, and you're done. However, the visual experience has gone—you are limited to building the UI via code only.

Creating Visual Web Parts using Visual Studio 2010 is relatively easy. The project template includes everything you need for a designer surface and the required deployment elements. Compared with SharePoint 2007, there is nothing special or new. The template simply follows the best practices. It creates a custom control (ASCX) file and uses Visual Studio's built-in designer to scaffold the control. It overrides the CreateChildControl method and loads the control dynamically.

The complete solution consists of the following Web Part–related elements:

For deployment support, the solution also contains the feature and solution package files. (See Chapter 9 for more information.) The deployment determines the way how a Web Part becomes part of a SharePoint application.

The basic code used to load a custom control is as shown in Listing 6-11.

using System;
using System.Runtime.InteropServices;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;

namespace SimpleWebPart.VisualWebPart1
{
    public class VisualWebPart1 : WebPart
    {
        protected const string _ascxPath = 

            @"˜/_CONTROLTEMPLATES/SimpleWebPart/VisualWebPart1/  

              VisualWebPart1UserControl.ascx";

        public VisualWebPart1()
        {
        }

        protected override void CreateChildControls()
        {
            try
            {
                Control control = this.Page.LoadControl(_ascxPath);
                Controls.Add(control);
            }
            finally
            {
                base.CreateChildControls();
            }
        }

        protected override void Render(HtmlTextWriter writer)
        {
            base.Render(writer);
        }
    }
}

This code implies that the Web Part's content is deployed as a custom control to the virtual CONTROLTEMPLATES folder. That makes the Web Part global to the server. To reiterate, Web Parts are reusable components that can be used in many applications on a server, so this is the most robust strategy for your controls. Of course, you can also use other methods, such as writing HTML to the output stream, to create the content.

Two additional XML files control how the Web Part is deployed. The Web Part appears in the Web Part gallery, as well as in several dialogs that end users access to add elements. The .webpart file provides additional information, as shown in Listing 6-12.

<?xml version="1.0" encoding="utf-8"?>
<webParts>
  <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
    <metaData>
      <type name="SimpleWebPart.VisualWebPart1.VisualWebPart1,
                  $SharePoint.Project.AssemblyFullName$" />
      <importErrorMessage>$Resources:core,ImportErrorMessage;</importErrorMessage>
    </metaData>
    <data>
      <properties>
        <property name="Title" type="string">VisualWebPart1 Title</property>
        <property name="Description" type="string">VisualWebPart1
                                                    Description</property>
      </properties>
    </data>
  </webPart>
</webParts>

The <property> element overrides the default settings of the corresponding property from the WebPart base class. That means you can either override these properties in code or set values in the .webpart file. The declarative way using the XML file is the preferred technique.

If a text portion begins with $Resources, it references an assembly containing compiled resource data. Here it's the core assembly that SharePoint comes with. You can replace this string with any hard-coded one or assign your own resource file. (For more information, see the Chapter 8.) Using resource files is the preferred way to implement localization.

The WebPartManager enables any layout of zones. Zones are rectangular areas constructed from any valid HTML—usually tables—and tagged with <asp:webpartzone> tags. Inside the tag, the <contenttemplate> element is used to define where the Web Part can appear. When a user opens a page for the first time, all the Web Parts appear in Browse mode. Technically, each Web Part supports three actions: minimize, maximize, and remove. If the page is in Design mode, the user can move Web Parts from one zone to another. In Edit mode, the user can modify the customizable properties of the currently selected Web Part. A predefined property zone is responsible for rendering the appropriate UI. Catalog mode gives access to currently invisible Web Parts so that a user can add them to the page. The five modes are

SharePoint provides several predefined Web Part pages. Adding such a page means that you add an ASPX page that has a layout with zones arranged in some way. You may want to add your own page if you create custom application pages or if you desire a different layout. (See Chapter 8 for more details on programming such pages.)

In the following exercise, an application page contains the Web Part zones. To create the project, perform the following steps.

Listing 6-13 shows a page with embedded code that allows two modes: Design and Browse.

<%@ Assembly Name="$SharePoint.Project.AssemblyFullName$" %>
<%@ Import Namespace="Microsoft.SharePoint.ApplicationPages" %>
<%@ Register TagPrefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls"
    Assembly="Microsoft.SharePoint, ..." %>
<%@ Register TagPrefix="SharePoint" Namespace="Microsoft.SharePoint.WebPartPages"
    Assembly="Microsoft.SharePoint, ..." %>
<%@ Register TagPrefix="Utilities" Namespace="Microsoft.SharePoint.Utilities"
    Assembly="Microsoft.SharePoint, ..." %>
<%@ Register TagPrefix="asp" Namespace="System.Web.UI"
    Assembly="System.Web.Extensions, ..." %>
<%@ Register TagPrefix="asp" Namespace="System.Web.UI.WebControls.WebParts"
    Assembly="System.Web.Extensions, ..." %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Assembly Name="Microsoft.Web.CommandUI, ..." %>

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="WebPartPage.aspx.cs"
         Inherits="WebPartPageProject.Layouts.WebPartPageProject.WebPartPage"
         DynamicMasterPageFile="˜masterurl/default.master" %>

<asp:Content ID="PageHead"
             ContentPlaceHolderID="PlaceHolderAdditionalPageHead" runat="server">

</asp:Content>
<asp:Content ID="Main" ContentPlaceHolderID="PlaceHolderMain" runat="server">
    <h1>
        Webpart Introduction</h1>
    <table width="100%" border="1">
        <tr>
            <td colspan="2">
                <asp:WebPartZone runat="server" ID="headerZone"
                                 HeaderText="Header Zone">
                </asp:WebPartZone>
            </td>
        </tr>
        <tr>
            <td style="width:50%">
                <asp:WebPartZone runat="server" ID="leftZone"
                                 HeaderText="Left Zone">
                </asp:WebPartZone>
            </td>
            <td style="width:50%">
                <asp:WebPartZone runat="server" ID="rightZone"
                                 HeaderText="Right Zone">
                </asp:WebPartZone>
            </td>
        </tr>
        <tr>
            <td colspan="2">
                <asp:CatalogZone runat="server" ID="catZone">
                    <ZoneTemplate>
                        <asp:PageCatalogPart runat="server" ID="catalogZonePart"
                                             Title="Page Parts">
                        </asp:PageCatalogPart>
                        <asp:DeclarativeCatalogPart runat="server"
                                     ID="declarativeZonePart" Title="Catalogue">
                            <WebPartsTemplate>
                                <SharePoint:ListViewWebPart runat="server"
                                  id="listView1" Title="Authors"
                                  ListName="32AF232D-375A-4504-9076-261F347448CF" />
                                <SharePoint:ListViewWebPart runat="server"
                                  id="listView2" Title="Tasks"
                                  ListName="4F6DEED2-3A62-49EE-A3F7-080E5BCBAB82" />
                            </WebPartsTemplate>
                        </asp:DeclarativeCatalogPart>
                    </ZoneTemplate>
                </asp:CatalogZone>
            </td>
        </tr>
        <tr>
            <td colspan="2">
                <asp:LinkButton runat="server" ID="lnkMode"
                      Text="Browse Mode" OnClick="lnkMode_Click"></asp:LinkButton>
                <asp:LinkButton runat="server" ID="lnkCatM"
                      Text="Catalog Mode"
                      OnClick="lnkCatMode_Click"></asp:LinkButton>
            </td>

</tr>
    </table>
</asp:Content>
<asp:Content ID="PageTitle" ContentPlaceHolderID="PlaceHolderPageTitle"
             runat="server">
    Application Page
</asp:Content>
<asp:Content ID="PageTitleInTitleArea" ContentPlaceHolderID="PlaceHolderPageTitleInTitleArea"
    runat="server">
    My WebPart Page
</asp:Content>

This page contains several zones to place Web Parts and a Catalog zone where the user can select more Web Parts. In the example, a table defines the position of the zones. This is usually the easiest way to place Web Parts at particular locations. (All styles and descriptive aspects are omitted for the sake of clarity. Consider adding more useful error-checking and validation code to extend the user experience when defining private Web Part pages, such as shown in Listing 6-14.)

using System;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;
using Microsoft.SharePoint.WebPartPages;
using System.Web.UI.WebControls.WebParts;

namespace WebPartPageProject.Layouts.WebPartPageProject
{
    public partial class WebPartPage : LayoutsPageBase
    {
        SPWebPartManager spWebPartManager;
        protected void Page_Load(object sender, EventArgs e)
        {
            spWebPartManager = WebPartManager.GetCurrentWebPartManager(this)
                               as SPWebPartManager;

            if (spWebPartManager.SupportedDisplayModes.Contains(
                                WebPartManager.CatalogDisplayMode))
            {
                lnkCatM.Visible = true;
            }
            else
            {
                lnkCatM.Visible = false;
            }
        }

        protected void lnkCatMode_Click(object sender, EventArgs e)
        {
            spWebPartManager.DisplayMode = WebPartManager.CatalogDisplayMode;
        }

        protected void lnkMode_Click(object sender, EventArgs e)
        {

if (spWebPartManager != null)
            {
                if (lnkMode.Text == "Design Mode")
                {
                    spWebPartManager.DisplayMode = WebPartManager.BrowseDisplayMode;
                    lnkMode.Text = "Browse Mode";
                }
                else
                {
                    spWebPartManager.DisplayMode = WebPartManager.DesignDisplayMode;
                    lnkMode.Text = "Design Mode";
                }
            }
        }

    }
}

The code-behind class contains only the LinkButton event handlers to change the zone modes. The SPWebPartManager is retrieved in the page's Load event. If Catalog mode is currently supported, the appropriate LinkButton is made visible (see Figure 6-11).

Figure 6.11. A simple custom Web Part page

On clicking the LinkButton control, the page switches into Design mode. You can now move Web Parts around—from zone to zone. This is performed by JavaScript that supports drag-and-drop operations. In the example, the current text displayed by LinkButton is set dynamically to represent the available state, determined from the SPWebPartManager control.

This merely demonstrates that it's possible to build Web Part–enabled application pages. When you use the predefined templates for Web Part pages, you simply develop the Web Part itself. The remaining section explains in depth the capabilities of Web Part development.

WebPartZone is a container that holds the Web Parts. Web Parts can't exist outside such a container. You can define Web Parts within a ZoneTemplate statically or let the user add one or more dynamically.

EditorZone allows for the editing of a Web Part's properties. To activate the Edit mode, set SPWebPartManager's DisplayMode property:

m.DisplayMode = WebPartManager.EditDisplayMode;

If the user has set something that makes the page no longer work properly, you can offer a reset option. This invokes the following method:

m.Personalization.ResetPersonalizationState();

CatalogZone can contain several catalogs. Catalogs allows users to select Web Parts from a predefined selection. User can remove Web Parts. To add a Web Part to the page again, a catalog is required, too. To switch to Catalog mode, use the following call:

m.DisplayMode = WebPartManager.CatalogDisplayMode;

There are three catalog controls available:

ConnectionsZone allows the definition of connections between data Web Parts. Typically, this creates a parent/child relationship or a list/details view using two different Web Parts.

A Web Part is a user control that implements at least the abstract WebPart base class. This includes several base classes and interfaces that the Web Part manager employs to interact with a custom Web Part (see Figure 6-12).

Figure 6.12. Base classes and interfaces for a custom Web Part

The WebControl class provides the basic behavior of a user control. The Panel class, next in the hierarchy, ensures that the control appears as a rectangle. The IWebPart interface provides the descriptive aspects, with such properties as Title, Description, and TitleIconImageUrl. IWebActionable provides the Verbs property, a collection of so-called verbs. A verb defines an action and usually appears in the context menu of the Web Part as a menu item. The WebPartVerb class is a Web Part–specific implementation that supports a checked state (Checked property), a ClientScriptHandler and ServerClickHandler to launch the action, and menu item–specific properties such as Enabled, Text, Visible, and ImageUrl.

Along with the Web Part's properties, many attributes can be used to modify the design-time experience. Remember that a Web Part's design time is when the user adds it to a Web Part page. The attributes decorating the Web Part properties are responsible for

Table 6-3 summarizes the attributes available.

The first five attributes are standard ASP.NET attributes found in the System.Web.UI.WebControls.WebParts namespace, while the others are SharePoint-specific attributes from the Microsoft.SharePoint.WebPartPages namespace.

Properties of a programming language like C# seem to be a simple thing. However, when a property controls the design of the property pane and the behavior in code, it's more than just a simple property.

A property consists of

A Web Part can control more of its own behavior by overriding properties and methods. For some functions, the implementation of additional classes is required.

Depending on their type, properties can create specific controls in the property pane. Table 6-4 shows the default mapping between types and controls.

You may wonder how the Height and Width properties in Figure 6-14 render with the more sophisticated control. The editing zone at the right of a Web Part page in Edit mode is indeed a <EditZone> control. There are several predefined editors that handle a subset of the default properties exposed by a Web Part (inherited from either a WebPart or Part class).

Figure 6.14. Predefined Web Part editor parts (from left to right: AppearanceEditorPart, LayoutEditorPart, and BehaviorEditorPart)

If you scroll down the editor pane, you'll find the categories you defined using the WebCategoryAttribute, and probably a section called Miscellaneous that contains all the editable properties that don't have a category. As shown in Figure 6-14, the internally used editors provide a more impressive user experience. (In the next section, you'll find more information about custom editor panes.)

There are a few attributes you can use to decorate a Web Part. ToolboxItemAttribute should be set to false to prevent the Web Part from being added to the Visual Studio toolbox:

[ToolboxItemAttribute(false)]

Using the standard approach of marking properties using specific attributes, you can make a Web Part editable as required. But the default user experience for editing is still suboptimal. Firstly, the properties to be edited are located in their own category at the bottom of the list—not easy to find for inexperienced or untrained users. Secondly, the properties often have dependencies and require validation.

ASP.NET contains an abstract class called EditorPart. This class is used with the ASP.NET WebPart class to create customized tool panes. By inheriting from this control, you can customize the appearance and functionality of the tool pane and use standard ASP.NET constructs such as auto postbacks and validations. Start with a new class that inherits from System.Web.UI.WebControls.WebParts.EditorPart. In this class, you have to override two abstract methods and add the controls that you want to use.

The custom editing section exists once per Web Part. Other than for common editor controls, you don't need an attribute to decorate a property. Instead, you must override the CreateEditorParts method. This method returns an EditorPartCollection that contains all EditorPart objects presented in the editor pane. That includes but is not limited to the standard parts explained previously. However, by default all properties get a generic input control. To avoid duplicate controls, you must exclude the property you wish to be editable in the customized part. This can be done by removing the WebBrowsable attribute or setting its initial value to false. The latter approach is recommended so that others reading the code can see that this is a publicly editable property with some controls found elsewhere:

[WebBrowsable(false)]

You can add one or more controls to a custom editor pane. If you have just one property, it's very simple:

public override EditorPartCollection CreateEditorParts()
{
    List<EditorPart> editorParts = new List<EditorPart>();
    EditorPart part = new CustomEditorPart();
    part.ID = this.ID + "_stateEditorPart";
    editorParts.Add(part);
    EditorPartCollection coll = base.CreateEditorParts();
    return new EditorPartCollection(coll, editorParts);
}

This method returns a merge of the existing EditorParts and the custom ones. In this example only one additional EditorPart, named CustomEditorPart, has been added. The ID property must be explicitly set to some unique name. Because only one instance of the EditorPart is usually present on a page, a static suffix is adequate. The skeleton of such a control looks as shown in Listing 6-15.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;

namespace Apress.SP2010.WebPartPageProject.MyWebParts
{
    public class CustomEditorPart : EditorPart
    {

        public CustomEditorPart()
            : base()
        {
        }

        protected override void CreateChildControls()
        {

base.CreateChildControls();
        }

        public override bool ApplyChanges()
        {
            EnsureChildControls();
            return true;
        }

        public override void SyncChanges()
        {
            EnsureChildControls();
        }
    }
}

The controls that appear in the editor must be added to the control collection in either the CreateChildControls or the Render method. This is similar to the way you create the content of a Web Part. In this example, the custom editor creates a list of RadioButton elements instead of a DropDown control. This requires some conversion between the underlying Enum type and the string types used for list items. A reference to the WebPart control gives access to the values to create the appropriate controls and write the values back:

private CustomWebPart webPart;
private readonly Type enumType = typeof(CustomWebPart.States);

Adding Controls

The controls are added in the CreateChildControls method. This is where you should place most of your control logic in editor parts, Web Parts, and so on.

private RadioButtonList rbl;

protected override void CreateChildControls()
{
   base.CreateChildControls();
   // Instead of a drop-down list, create a couple of radio buttons
   rbl = new RadioButtonList();
   webPart = (CustomWebPart)this.WebPartToEdit;

   var items = from i in Enum.GetNames(enumType)
               select new ListItem(i)
               {
                  Selected = Enum.GetName(enumType,
                                  webPart.ControlStatesDrop).Equals(i)
               };
   rbl.Items.AddRange(items.ToArray());
   base.Controls.Add(rbl);
}

This method creates the RadioButtonList, in which each item represents an Enum value. The LINQ statement converts the Enum values into ListItem controls and sets the currently selected item. The complete list appears with the current value set. Now you need to retrieve and apply changes.

Syncing Changes

The SyncChanges method is used by the EditorPart to get the values from the Web Part into the editor part.

public override void SyncChanges()
{
    EnsureChildControls();
    rbl.Items.FindByValue(Enum.GetName(enumType,
                           webPart.ControlStatesDrop)).Selected = true;
}

Firstly, the method ensures that all the controls are present. This calls the CreateChildControls method if required. Then the RadioButton element is retrieved, which matches the currently selected value. Again, the enumType field helps, using the Enum class to transform an enumeration value into a string representation.

Applying Changes

The ApplyChanges method is executed when you click OK or Apply, and sets the property values of your Web Part. SyncChanges is always called directly after the ApplyChanges method to make sure that the properties are in sync.

public override bool ApplyChanges()
{
    EnsureChildControls();
    if (rbl.SelectedIndex >= 0)
    {
        webPart.ControlStatesDrop = (CustomWebPart.States)Enum.Parse(enumType,
                                                          rbl.SelectedValue);
        return true;
    }
    else
    {
        return false;
    }
}

Again, the EnsureChildControls method call ensures that the controls are properly loaded. The currently selected value is parsed and written back to the Web Part's property.

Handling Validation Errors

In the previous examples we assumed that users don't make any mistakes. We accept any incoming value. That's far from real-world experience, and therefore some validation has to be added. As the properties render automatically, there must be some way to expose an error message. That's done by throwing a WebPartPageUserException.

[Personalizable(true)]
[WebBrowsable(true)]
public States ControlStatesDrop
{
     get
     {
         if (ViewState["States"] == null)
         {

ViewState["States"] = States.State2;
          }
         return (States) Enum.Parse(typeof(States), ViewState["States"].ToString());
     }
     set
     {
        if (value == States.State3)
        {
          throw new WebPartPageUserException("State 3
                                               is currently not supported");
        }
        ViewState["States"] = value;
     }
}

The exception puts a red message from the constructor's parameter into the editor pane and a generic message on top (see Figure 6-15).

Figure 6.15. An error message that is autogenerated from the exception

The message appears when the page is posted back, when either OK or Apply is clicked. The message appears above the controls if a custom EditorPart is used as shown in Figure 6-16.

Figure 6.16. An error message that is autogenerated within a custom EditorPart

The previous sections explained the basic tasks required to customize the editable section of a Web Part. In this section is an example of a complete Web Part together with a custom editor—putting all the pieces of the puzzle together. Custom editors are often advantageous if you deal with custom types, such as geographic coordinates. The Web Part explained here creates a little map using the Bing client library, and the custom editor allows the setting of the region as well as the coordinates of a pushpin—a specific location within the map. The error handler checks whether the coordinates of the pushpin are within the map region.

Figure 6.17. The Bing map with a default location, and the custom editor

The Web Part itself defines the minimum required properties. WebBrowsable is set to false to suppress the generic editors (Listing 6-16).

using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;
using System.Collections.Generic;

namespace Apress.SP2010.WebPartPageProject.BingWebPart
{
    [ToolboxItemAttribute(false)]
    public class BingWebPart : WebPart
    {
        private const string _ascxPath =
             @"˜/_CONTROLTEMPLATES/WebPartPageProject/
                BingWebPart/BingWebPartUserControl.ascx";

        public BingWebPart()
        {
        }

        protected override void CreateChildControls()
        {
            BingWebPartUserControl control = this.Page.LoadControl(_ascxPath)
                                             as BingWebPartUserControl;
            Controls.Add(control);
            base.CreateChildControls();
        }

        protected override void RenderContents(HtmlTextWriter writer)
        {
            base.RenderContents(writer);
        }

        public override EditorPartCollection CreateEditorParts()
        {
            List<EditorPart> parts = new List<EditorPart>();
            EditorPart edit = new CoordinatesEditorPart();
            edit.ID = this.ID + "_coordEditor";
            parts.Add(edit);
            return new EditorPartCollection(base.CreateEditorParts(), parts);
        }

        [WebBrowsable(false)]
        [Personalizable(true)]
        public Coordinates CenterCoordinate
        {
            get;

set;
        }

        [WebBrowsable(false)]
        [Personalizable(true)]
        public Coordinates PushPin
        {
            get;
            set;
        }

    }
}

This code defines the properties that center the map and define a pushpin (marker) that you can set into the map. The code to manage the map is based on JavaScript and defined in the Web Part's markup section (see Listing 6-17).

%@ Assembly Name="$SharePoint.Project.AssemblyFullName$" %>
<%@ Assembly Name="Microsoft.Web.CommandUI, Version=14.0.0.0, Culture=neutral,
             PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls"
             Assembly="Microsoft.SharePoint, ..." %>
<%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities"
             Assembly="Microsoft.SharePoint, ..." %>
<%@ Register Tagprefix="asp" Namespace="System.Web.UI"
             Assembly="System.Web.Extensions, ..." %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Register Tagprefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages"
             Assembly="Microsoft.SharePoint, ..." %>
<%@ Control Language="C#" AutoEventWireup="true"
    CodeBehind="BingWebPartUserControl.ascx.cs"
   Inherits="WebPartPageProject.BingWebPart.BingWebPartUserControl" %>
<script type="text/javascript"
        src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.2">
</script>
<script type="text/javascript">

/// <reference path="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.2" />
function GetMap() {
    var map = new VEMap('<% = spBingMap.ClientID %>'),
    var lat = document.getElementById('<% = latField.ClientID  %>').value;
    var lng = document.getElementById('<% = lngField.ClientID  %>').value;
    var latlng = new VELatLong(lat, lng);
    map.LoadMap(latlng, 10, 'r', false);
}
window.onload = function () {
    GetMap();
}
</script>
<div id="spBingMap" runat="server" style="position:relative; width:400px; height:300px"></div>
<asp:HiddenField runat="server" ID="latField" Value="52.222" />

<asp:HiddenField runat="server" ID="lngField" Value="13.297" />

Even this user control has a code-behind to set or get the values from hidden fields and the dimensions of the <div> container (see Listing 6-18).

using System;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Globalization;

namespace Apress.SP2010.WebPartPageProject.BingWebPart
{
    public partial class BingWebPartUserControl : UserControl
    {
        protected void Page_Load(object sender, EventArgs e)
        {
        }

        public Unit Width
        {
            get { return Unit.Parse(spBingMap.Style[HtmlTextWriterStyle.Width]); }
            set { spBingMap.Style[HtmlTextWriterStyle.Width] = value.ToString(); }
        }

        public Unit Height
        {
            get { return Unit.Parse(spBingMap.Style[HtmlTextWriterStyle.Height]); }
            set { spBingMap.Style[HtmlTextWriterStyle.Height] = value.ToString(); }
        }

        public decimal Longitude
        {
            get { return Convert.ToDecimal(latField.Value); }
            set { latField.Value = value.ToString(CultureInfo.InvariantCulture); }
        }

        public decimal Latitude
        {
            get { return Convert.ToDecimal(lngField.Value); }
            set { lngField.Value = value.ToString(CultureInfo.InvariantCulture); }
        }

    }
}

Using the Unit type is just a suggestion. Use the strongest possible type to simplify testing and validation.

Next, the user control is loaded within the CreateChildControls method. By overriding the CreateEditorParts method, the custom editor is shown to support the Coordinates type. This type is used to deal flexibly with complex values, like geographical coordinates (see Listing 6-19).

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Globalization;
using System.Web.UI;

namespace Apress.SP2010.WebPartPageProject.BingWebPart
{

    public struct DegMinSec
    {
        public int Deg { get; set; }
        public int Min { get; set; }
        public int Sec { get; set; }
    }

    public struct Coordinates
    {

        public Coordinates(DegMinSec lat, DegMinSec lng) : this()
        {
            SetLongitude(lng);
            SetLatitude(lat);

        }

        public static Coordinates Empty
        {
            get
            {
                return new Coordinates();
            }
        }

        public static bool operator ==(Coordinates c1, Coordinates c2)
        {
            return (c1.Latitude == c2.Latitude && c1.Longitude == c2.Longitude);
        }

        public static bool operator !=(Coordinates c1, Coordinates c2)
        {
            return (c1.Latitude != c2.Latitude || c1.Longitude != c2.Longitude);
        }

        public decimal Latitude { get; set; }
        public decimal Longitude { get; set; }

        public bool IsInRange(Coordinates from, Coordinates to)
        {
            return (

this.Longitude > from.Longitude && this.Latitude > from.Latitude &&
                this.Longitude < to.Longitude && this.Latitude < to.Latitude);
        }


        public DegMinSec LatitudeDegrees
        {
            get
            {
                return GetDegMinSec(Latitude);
            }
        }

        public DegMinSec LongitudeDegrees
        {
            get
            {
                return GetDegMinSec(Longitude);
            }
        }

        private static DegMinSec GetDegMinSec(decimal longlat)
        {
            int deg = (int)Math.Truncate(longlat);
            decimal mins = (longlat - deg) * 60;
            int min = (int)Math.Truncate(mins);
            int sec = (int)(mins - min) * 60;
            return new DegMinSec()
            {
                Deg = deg,
                Min = min,
                Sec = sec
            };
        }

        public void SetLongitude(DegMinSec t)
        {
            Longitude = t.Deg + t.Min + t.Sec;
        }

        public void SetLatitude(DegMinSec t)
        {
            Latitude = t.Deg + t.Min + t.Sec;
        }

        public override string ToString()
        {
            return String.Format(CultureInfo.CurrentCulture, "{0}:{1}",
                                  Latitude, Longitude);
        }

    }
}

The operator overloads make it easier when later checking the values. It makes sense to deal with business data objects like this instead of scalar types. The DegMinSec struct defined at the beginning simplifies converting values between the degrees/minutes/seconds format and the decimal format, which map libraries like Bing prefer. This makes designing the user controls simpler. The first user control is the definition for one triplet of data (see Listing 6-20).

<%@ Assembly Name="$SharePoint.Project.AssemblyFullName$" %>
<%@ Assembly Name="Microsoft.Web.CommandUI, Version=14.0.0.0, Culture=neutral,
             PublicKeyToken=71e9bce111e9429c" %>
<%@ Register TagPrefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls"
             Assembly="Microsoft.SharePoint, ..." %>
<%@ Register TagPrefix="Utilities" Namespace="Microsoft.SharePoint.Utilities"
             Assembly="Microsoft.SharePoint, ..." %>
<%@ Register TagPrefix="asp" Namespace="System.Web.UI"
             Assembly="System.Web.Extensions, ..." %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Register TagPrefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages"
    Assembly="Microsoft.SharePoint, ..." %>
<%@ Control Language="C#" AutoEventWireup="true"
            CodeBehind="CoordinatesEditor.ascx.cs"
            Inherits="WebPartPageProject.BingWebPart.CoordinatesEditor" %>
<fieldset>
    <legend>
        <asp:Label runat="server" ID="lblControl" Font-Bold="true"></asp:Label></legend>
    <fieldset title="Longitude">
        <legend>Longitude </legend>
        <asp:TextBox ID="TextBoxDegLng" runat="server" Width="50px"></asp:TextBox>
        &deg;
        <asp:TextBox ID="TextBoxMinLng" runat="server" Width="50px"></asp:TextBox>"
        <asp:TextBox ID="TextBoxSecLng" runat="server" Width="50px"></asp:TextBox>'
    </fieldset>
    <fieldset title="Latitude">
        <legend>Latitude </legend>
        <asp:TextBox ID="TextBoxDegLat" runat="server" Width="50px"></asp:TextBox>
        &deg;
        <asp:TextBox ID="TextBoxMinLat" runat="server" Width="50px"></asp:TextBox>"
        <asp:TextBox ID="TextBoxSecLat" runat="server" Width="50px"></asp:TextBox>'
    </fieldset>
</fieldset>

The code-behind file (see Listing 6-21) sets or gets the values.

using System;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using WebPartPageProject.BingWebPart;

namespace Apress.SP2010.WebPartPageProject.BingWebPart
{

public partial class CoordinatesEditor : UserControl
    {
        protected void Page_Load(object sender, EventArgs e)
        {
        }

        public Coordinates Coordinate
        {
            set
            {
                DegMinSec lat = value.LatitudeDegrees;
                DegMinSec lng = value.LongitudeDegrees;
                TextBoxDegLat.Text = lat.Deg.ToString();
                TextBoxMinLat.Text = lat.Min.ToString();
                TextBoxSecLat.Text = lat.Sec.ToString();
                TextBoxDegLng.Text = lng.Deg.ToString();
                TextBoxMinLng.Text = lng.Min.ToString();
                TextBoxSecLng.Text = lng.Sec.ToString();
            }
            get
            {
                DegMinSec lat = new DegMinSec();
                DegMinSec lng = new DegMinSec();
                lat.Deg = Int32.Parse(TextBoxDegLat.Text);
                lat.Min = Int32.Parse(TextBoxMinLat.Text);
                lat.Sec = Int32.Parse(TextBoxSecLat.Text);
                lng.Deg = Int32.Parse(TextBoxDegLng.Text);
                lng.Min = Int32.Parse(TextBoxMinLng.Text);
                lng.Sec = Int32.Parse(TextBoxSecLng.Text);
                return new Coordinates(lat, lng);
            }
        }

        public string Title
        {
            get { return lblControl.Text; }
            set { lblControl.Text = value; }
        }
    }
}

There is nothing ambitious here. The code does not contain any validation or error checking, for the sake of clarity. Consider adding the necessary validator controls and exposing error messages to the Web Part control. This user control is used twice to define the custom editor for the coordinates and the pushpin value. This is done in the EditorPart implementation shown in Listing 6-22.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.WebControls;

namespace Apress.SP2010.WebPartPageProject.BingWebPart
{
    public class CoordinatesEditorPart : EditorPart
    {

        private const string _ascxPath = @"˜/_CONTROLTEMPLATES/WebPartPageProject/
                                          BingWebPart/CoordinatesEditor.ascx";

        public CoordinatesEditorPart()
            : base()
        {
        }

        BingWebPart webPart;
        CoordinatesEditor center;
        CoordinatesEditor pushp;

        protected override void CreateChildControls()
        {
            center = this.Page.LoadControl(_ascxPath) as CoordinatesEditor;
            center.Title = "Center Coordinates";
            pushp = this.Page.LoadControl(_ascxPath) as CoordinatesEditor;
            pushp.Title = "PushPin Coordinates";
            Controls.Add(center);
            Controls.Add(pushp);
            base.CreateChildControls();
            webPart = (BingWebPart)this.WebPartToEdit;
            center.Coordinate = webPart.CenterCoordinate;
            pushp.Coordinate = webPart.PushPin;
        }

        public override bool ApplyChanges()
        {
            EnsureChildControls();
            if (pushp.Coordinate != Coordinates.Empty)
            {
                webPart.CenterCoordinate = center.Coordinate;
                webPart.PushPin = pushp.Coordinate;
            }
            return true;
        }

        public override void SyncChanges()
        {
            EnsureChildControls();
            webPart.CenterCoordinate = center.Coordinate;
            webPart.PushPin = pushp.Coordinate;
        }
    }
}

The CreateChildControls method creates the two sections that comprise the user control. They are bound to the Web Part by the SyncChanges and ApplyChanges methods. It's recommended that you add the appropriate error-checking code to ApplyChanges to avoid invalid values being saved. Now all the pieces of a complex Web Part with a custom editor are available. The two user controls can be saved to the CONTROLTEMPLATES folder. In the Visual Studio project, the XML in Listing 6-23 defines the target.

<?xml version="1.0" encoding="utf-8"?>
<ProjectItem Type="Microsoft.VisualStudio.SharePoint.VisualWebPart"
             SupportedTrustLevels="FullTrust" SupportedDeploymentScopes="Site"
             xmlns="http://schemas.microsoft.com/VisualStudio/2010/
                    SharePointTools/SharePointProjectItemModel">
  <Files>
    <ProjectItemFile Source="Elements.xml" Target="BingWebPart"
                     Type="ElementManifest" />
    <ProjectItemFile Source="BingWebPart.webpart" Target="BingWebPart"
                     Type="ElementFile" />
    <ProjectItemFile Source="..BingWebPartBingWebPartUserControl.ascx"
                     Target="CONTROLTEMPLATESWebPartPageProjectBingWebPart"
                     Type="TemplateFile" />
    <ProjectItemFile Source="..BingWebPartCoordinatesEditor.ascx"
                     Target="CONTROLTEMPLATESWebPartPageProjectBingWebPart"
                     Type="TemplateFile" />
  </Files>
  <SafeControls>
    <SafeControl Name="SafeControlEntry1"
                 Assembly="$SharePoint.Project.AssemblyFullName$"
                 Namespace="WebPartPageProject.BingWebPart" TypeName="*"
                 IsSafe="true" />
  </SafeControls>
</ProjectItem>

The entries correspond with the settings for the path to the ASCX file defined in the user control.

With all this, you can create and deploy the Web Part and get the results, as shown previously in Figure 6-17.

Even if it is possible to use a custom editor pane, it is sometimes better to hook into SharePoint's client framework. This is especially true if the data types become more complex. For the pop-up that appears when the ellipses button (...) is clicked, you have to provide a regular web page.

To accomplish this, decorate the property you want to edit with such a pop-up with HtmlDesignerAttribute. It's defined in the Microsoft.SharePoint.WebPartPages namespace. Adding this with the using statement is not recommended, because in this namespace several classes have the same name as in System.Web.UI.WebControls.WebParts, and name resolution conflicts will result. Instead, use the using statement with a named assignment:

using WPP = Microsoft.SharePoint.WebPartPages;

The property is decorated as shown in the prior sections. There is just one new attribute:

[WebBrowsable(true)]
[Personalizable(true)]
[WebDisplayName("Complex Url")]
[WPP.HtmlDesignerAttribute(@"/_layouts/VisualWebPartEditor/PopupEditor.aspx",
     DialogFeatures = "center:yes; dialogHeight:40px",
     HtmlEditorBuilderType = BrowserBuilderType.Dynamic)]
public string ComplexUrl
{
    get;
    set;
}

The attribute requires at least a URL for the pop-up. This can be any folder to which your SharePoint web has access. In the example, the LAYOUTS folder is used. The attribute cannot resolve the ˜ token, so you must provide a completely resolved relative name here. The DialogFeatures parameter takes JavaScript values that are similar to those used in the window.open() function. Finally, set the HtmlEditorBuilderType to the Dynamic option—the only one supported in this context.

This is sufficient to make the page pop up on demand. The page requires some JavaScript code to retrieve the current value and return the modified one. In addition, you can use the very simple dialog.master master page to ensure a consistent look and feel. This master page provides head and body sections, as well as predefined buttons to close and cancel.

A minimal but complete page could look like Listing 6-24.

<%@ Assembly Name="$SharePoint.Project.AssemblyFullName$" %>
<%@ Import Namespace="Microsoft.SharePoint.ApplicationPages" %>
<%@ Register TagPrefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls"
    Assembly="Microsoft.SharePoint, ..." %>
<%@ Register TagPrefix="Utilities" Namespace="Microsoft.SharePoint.Utilities"
    Assembly="Microsoft.SharePoint, .." %>
<%@ Register TagPrefix="asp" Namespace="System.Web.UI"
    Assembly="System.Web.Extensions, ..." %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Assembly Name="Microsoft.Web.CommandUI, ..." %>

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="PopupEditor.aspx.cs"
         Inherits="VisualWebPartEditor.Layouts.VisualWebPartEditor.PopupEditor"
         MasterPageFile="˜/_layouts/dialog.master" %>

<asp:Content runat="server" ContentPlaceHolderID="PlaceHolderAdditionalPageHead">
    <script language="javascript" type="text/javascript">

    var isOkay = false;
    var oldValue = "";

    function addOnLoadEvent(func) {
        var oldonload = window.onload;

if (typeof window.onload != 'function') {
            window.onload = func;
        } else {
            window.onload = function () {
                if (oldonload) {
                    oldonload();
                }
                func();
            }
        }
     }

     function addOnUnLoadEvent(func) {
         var oldonunload = window.onunload;
         if (typeof window.onunload != 'function') {
             window.onunload = func;
         } else {
             window.onunload = function () {
                 if (oldonunload) {
                     oldonunload();
                 }
                 func();
             }
         }
     }

     addOnLoadEvent(function () {
         var input = window.dialogArguments;
         var field = document.getElementById("<%= urlField.ClientID %>");
         oldValue = input;
         field.value = input;
     });

     addOnUnLoadEvent(function () {
         var field = document.getElementById("<%= urlField.ClientID %>");
         window.returnValue = (isOkay) ? field.value : oldValue;
     });

    function CloseOkButton() {
        isOkay = true;
        doCancel();
    }
    </script>
</asp:Content>
<asp:Content runat="server" ContentPlaceHolderID="PlaceHolderDialogDescription">
    Edit the URL field.
</asp:Content>
<asp:Content runat="server" ContentPlaceHolderID="PlaceHolderDialogBodyMainSection">
    Please enter a valid URL:
   <asp:TextBox runat="server" ID="urlField" />
</asp:Content>

The major part is the script code required to add the window.onload and window.onunload events to take over the current parameter and write back to the Web Part. Two helper functions ensure that the events are added to probably existing events. The load event function reads window.dialogArguments, a string passed to the pop-up internally via the showModalDialog function. It is written into the TextBox control. For more ambitious solutions, consider writing the value into a hidden field for further reference. During the unload event, the current value is written into window.returnValue. The Web Part receives this internally and without further coding.

One final step is required to change the behavior of the supplied OK button from the dialog.master page. In the page's code-behind, the client click event is changed to invoke a private function, CloseOkButton. It sets the variable isOkay to indicate that the value should be taken and then forces the dialog to close. The default behavior is to simply post back the page and leave it open.

namespace VisualWebPartEditor.Layouts.VisualWebPartEditor
{
    public partial class PopupEditor : LayoutsPageBase
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            ((Microsoft.SharePoint.WebControls.DialogMaster)Master).
                          OkButton.OnClientClick = "CloseOkButton();";
        }
    }
}

The code assumes that you indeed use the dialog.master page and the associated code from the DialogMaster class. Here you have access to the controls defined on this page.

If everything is deployed and run, it creates a dialog with some predefined styles taken from the master page. The result is shown in Figure 6-18.

Figure 6.18. Clicking the ellipses button in the property pane opens an attractive dialog.

The example page is an ASPX page that allows you to use the master page. However, you can create a simple page using plain HTML and code the complete active portion on the client side using JavaScript. Consider using web services or other advanced scripting techniques for more comprehensive tasks.

The package defines what SharePoint receives as a solution. This includes the assembly, as well as the settings for web.config (as shown in Listing 6-25).

<Solution xmlns="http://schemas.microsoft.com/sharepoint/"
          SolutionId="62ad2e91-9449-45ca-a42d-42f7762fad72">
  <Assemblies>
    <Assembly Location="WebPartPageProject.dll"
              DeploymentTarget="GlobalAssemblyCache">
      <SafeControls>
        <SafeControl Assembly="WebPartPageProject, ..."

Namespace="WebPartPageProject.ConnectedWebPart"
                     TypeName="SourceWebPart"
                     SafeAgainstScript="True" Safe="True" />
        <SafeControl Assembly="WebPartPageProject, ..."
                     Namespace="WebPartPageProject.ConnectedWebPart"
                     TypeName="TargetWebPart"
                     SafeAgainstScript="True" Safe="True" />
      </SafeControls>
    </Assembly>
  </Assemblies>
  <FeatureManifests>
    <FeatureManifest Location="WebPartPageProject_Feature1Feature.xml" />
  </FeatureManifests>
</Solution>

The file contains the instructions to register the Web Parts as "safe," along with the feature definition file:

<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
        Title="WebPartPageProject Feature1"
        Id="cd61bb69-d05b-4572-8532-de6a2b0ea90d" Scope="Site">
  <ElementManifests>
    <ElementManifest Location="TargetWebPartElements.xml" />
    <ElementFile Location="TargetWebPartTargetWebPart.webpart" />
    <ElementManifest Location="SourceWebPartElements.xml" />
    <ElementFile Location="SourceWebPartSourceWebPart.webpart" />
  </ElementManifests>
</Feature>

This includes the manifest files and the Web Part definitions. For the sake of clarity, these files are simplified as much as possible. The source Web Part's manifest file is shown in Listing 6-26.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/" >
  <Module Name="SourceWebPart" List="113" Url="_catalogs/wp">
    <File Path="SourceWebPartSourceWebPart.webpart" Url="SourceWebPart.webpart"
          Type="GhostableInLibrary">
      <Property Name="Group" Value="Custom" />
    </File>
  </Module>
</Elements>

The *.webpart definition referenced there is shown in Listing 6-27.

<?xml version="1.0" encoding="utf-8"?>
<webParts>
  <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
    <metaData>
      <type name="WebPartPageProject.ConnectedWebPart.SourceWebPart,
                  $SharePoint.Project.AssemblyFullName$" />
      <importErrorMessage>$Resources:core,ImportErrorMessage;</importErrorMessage>

</metaData>
    <data>
      <properties>
        <property name="Title" type="string">SourceWebPart</property>
        <property name="Description" type="string">Source of a connected WebPart</property>
      </properties>
    </data>
  </webPart>
</webParts>

The target Web Part is very similar. First, Listing 6-28 shows the manifest file.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/" >
  <Module Name="TargetWebPart" List="113" Url="_catalogs/wp">
    <File Path="TargetWebPartTargetWebPart.webpart" Url="TargetWebPart.webpart" Type="GhostableInLibrary">
      <Property Name="Group" Value="Custom" />
    </File>
  </Module>
</Elements>

Second, Listing 6-29 shows the *.webpart definition file.

<?xml version="1.0" encoding="utf-8"?>
<webParts>
  <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
    <metaData>
      <type name="WebPartPageProject.ConnectedWebPart.TargetWebPart,
                  $SharePoint.Project.AssemblyFullName$" />
      <importErrorMessage>$Resources:core,ImportErrorMessage;</importErrorMessage>
    </metaData>
    <data>
      <properties>
        <property name="Title" type="string">TargetWebPart</property>
        <property name="Description" type="string">Target of a connected WebPart
        </property>
      </properties>
    </data>
  </webPart>
</webParts>

Now we have all the definitions to get the Web Parts deployed and running. Next, let's inspect the code.

The goal for the pair of Web Parts in the preceding example is an image selector. The source part should show a list of images from which the user can select one. Once selected, the second (target) Web Part should display the selected image. The data transferred from one component to the other is the file name. This is exactly what you have to define in the interface as part of your project:

using System;

namespace WebPartPageProject.ConnectedWebPart
{
    public interface IImageSelectorProvider
    {
        string ImageName { get; }
    }
}

The source Web Part uses some SharePoint controls, especially the SPGroupedDropDownList. This simplifies the selection process by grouping the images using their file extensions.

The code for the complete sender control is shown in Listing 6-30.

using System;
using System.IO;
using System.ComponentModel;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;
using Microsoft.SharePoint.Utilities;
using System.Web.UI.HtmlControls;

namespace Apress.SP2010.WebPartPageProject.ConnectedWebPart
{
    [ToolboxItemAttribute(false)]
    public class SourceWebPart : WebPart, IImageSelectorProvider
    {

        private GroupedDropDownList list;

        public SourceWebPart()
        {
        }

        protected override void CreateChildControls()
        {
            base.CreateChildControls();
            try
            {

// Few controls with IDs sent to target
                string path = SPUtility.GetGenericSetupPath("TEMPLATE\IMAGES");
                // Group Drop Box
                SPHtmlSelect dlGroup = new SPHtmlSelect();
                dlGroup.ID = this.ID + "dlGroup";
                dlGroup.Height = 22;
                dlGroup.Width = 100;
                Controls.Add(dlGroup);
                SPHtmlSelect dlCandidate = new SPHtmlSelect();
                dlCandidate.ID = this.ID + "dlCandidate";
                dlCandidate.Height = 22;
                Controls.Add(dlCandidate);
                Button b = new Button();
                b.Text = "Select Image";
                Controls.Add(b);
                Controls.Add(new HtmlGenericControl("br"));
                HtmlGenericControl lblText = new HtmlGenericControl("span");
                lblText.ID = this.ID + "lblText";
                lblText.InnerText = "No image selected";
                Controls.Add(lblText);
                list = new GroupedDropDownList();
                list.GroupControlId = dlGroup.ID;
                list.CandidateControlId = dlCandidate.ID;
                list.DescriptionControlId = lblText.ID;
                string filter = (Page.IsPostBack && dlGroup.Items.Count > 0) ?
                                dlGroup.Items[dlGroup.SelectedIndex].Value : "*.*";
                foreach (string file in Directory.GetFiles(path, filter))
                {
                    list.AddItem(
                        Path.GetFileName(file),
                        Path.GetFileNameWithoutExtension(file),
                        file,
                        Path.GetExtension(file).ToLowerInvariant());
                }
                Controls.Add(list);
            }
            catch
            {
            }
        }

        protected override void RenderContents(HtmlTextWriter writer)
        {
            base.RenderContents(writer);
        }

        public string ImageName
        {
            get
            {
                return (list == null) ? null : list.Value;
            }
        }

[ConnectionProvider("Image Name", AllowsMultipleConnections=false)]
        public IImageSelectorProvider GetCustomerProvider()
        {
            return this;
        }

    }
}

To make the Web Part into a connected one, you have to implement the IImageSelectorProvider interface. (Actually, as mentioned earlier, any interface that defines the data object you wish to transfer will do.) Furthermore, one method must be decorated with the ConnectionProvider attribute. In the preceding example, the ConnectionProvider attribute is defined with a name, "Image Name," which appears in the connection dialog.

As you can see in Figure 6-19, the connection menu dialog creates a virtual item named Send <Provider Name> To (in this example, it's Send Image Name To). Keep this in mind when naming the provider so that you create useful and self-explanatory menu items. The ConnectionProvider attribute has several properties. The most important ones are

Figure 6.19. Establish a connection between two Web Parts.

Our example Web Part uses the GroupedDropDownList control. This control creates a client-side environment to select values using a two-stage drop-down list. This requires two <select> elements created by HtmlSelect and a <span> element that shows the final selection. The span is created using the HtmlGenericControl class. Once the appropriate IDs have been set to associate the drop-down lists with the GroupedDropDownList control, the UI appears as shown in Figure 6-19. The control itself has no UI. You must perform all layout changes with HTML elements. At a minimum, you should set the element's height, as the default value is inappropriate.

The advantage of the GroupedDropDownList control is how easily you can fill it with items. Merely define a group as a string value, and the items get grouped in the first drop-down and filtered automatically in the second.

Because the Web Part appears in two stages—after the first call and after a regular postback—you must recognize this and set the filters appropriately:

string filter = (Page.IsPostBack && dlGroup.Items.Count > 0) ?
                                dlGroup.Items[dlGroup.SelectedIndex].Value : "*.*";

In this code, the current selection is taken to use the value of the group drop-down to filter the selection drop-down. A simple GetFiles call applies the filter:

foreach (string file in Directory.GetFiles(path, filter))

{
  list.AddItem(
    Path.GetFileName(file),
    Path.GetFileNameWithoutExtension(file),
    file,
    Path.GetExtension(file).ToLowerInvariant());
}

The whole grouping is done internally. A foreach loop adds all values using the GetExtension method to create the grouping instruction.

That's all you need to add the Web Part to a page. It will start interrogating the images folder and create a UI, as shown in Figure 6-20.

Figure 6.20. The source Web Part is fully functional.

Next, we require the target Web Part to receive the selection. This Web Part is much easier to build and simply displays either an error message or an image (see Listing 6-31).

using System;
using System.ComponentModel;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Utilities;

namespace Apress.SP2010.WebPartPageProject.ConnectedWebPart
{
    [ToolboxItemAttribute(false)]
    public class TargetWebPart : WebPart
    {

        private IImageSelectorProvider customerProvider;

        public TargetWebPart()
        {

}

        [ConnectionConsumer("Image Name")]
        public void RegisterCustomerProvider(IImageSelectorProvider provider)
        {
            this.customerProvider = provider;
        }

        protected override void CreateChildControls()
        {
            base.CreateChildControls();
            Image img = new Image();
            if (customerProvider != null && customerProvider.ImageName != null)
            {
                string path = "/_layouts/images/";
                img.ImageUrl = SPContext.Current.Web.Url + path
                               + customerProvider.ImageName;
                Controls.Add(img);
            }
            else
            {
                Label l = new Label();
                if (customerProvider == null)
                {
                    l.Text = "No Connection established.";
                }
                else
                {
                    l.Text = "No image selected.";
                }
                l.ForeColor = System.Drawing.Color.Red;
                Controls.Add(l);
            }
        }

        protected override void RenderContents(HtmlTextWriter writer)
        {
            base.RenderContents(writer);
        }
    }
}

The vital code is the method decorated with the ConnectionConsumer attribute. It must match the name of the ConnectionProvider attribute. The transferred object matches the interface. The name of the method doesn't matter—something self-explanatory is always recommended. Once the provider control is present, the consumer control has access to it. You must check in the CreateChildControls method whether the provider is already present. The first time, when the page loads and nothing is selected, the provider returns null. If the page loads again and the postback source is not the provider Web Part, the source property will return null again. Both values are used to create an appropriate error message, as shown in Figure 6-20. If everything works, the transferred image name is used to construct an absolute path and the image is displayed on the page (see Figure 6-21).

Figure 6.21. The target Web Part shows the image selected in the source.

The established connection can now interact between the two Web Parts, wherever they are on the page. Imagine that such a channel can be established between one source and many targets, allowing the user to choose a Web Part from several that display the same data in different forms and styles, all from the same source. This greatly improves the flexibility and power of Web Parts at little cost.

ASP.NET's Web Part support includes three interfaces that support generic connections:

All three interfaces (see Figure 6-22) provide a callback method and a delegate to support it.

Figure 6.22. Generic data connection interfaces

The delegates are FieldCallback, RowCallBack, and TableCallback, respectively. TableCallback accepts an ICollection type to support multiple tables, while the others accept any object. The following example shows a Web Part that contains a list of data. The user's current selection is provided by the IWebPartField interface to a consuming Web Part.

The next example retrieves all the lists from the current web and exposes a connection using the IWebPartField interface to trigger another Web Part to consume this connection. The master Web Part, created first, displays the data using an SPGridView control (see Listing 6-32).

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

using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using Microsoft.SharePoint;

namespace Apress.SP2010.WebPartPageProject.ConnectedWebParts
{
    [ToolboxItemAttribute(false)]
    public class MasterWebPart : WebPart, IWebPartField
    {

        private SPGridView webLists;
        public string ListName { get; set; }

        public MasterWebPart()
        {
        }

        protected override void CreateChildControls()
        {
            base.CreateChildControls();
            SPWeb web = SPContext.Current.Web;
            var lists = web.Lists.Cast<SPList>();
            webLists = new SPGridView();
            webLists.AutoGenerateColumns = false;
            webLists.DataSource = lists;
            webLists.Columns.Add(new BoundField()
            {
                DataField = "Title",
                HeaderText = "List Name"
            });
            webLists.Columns.Add(new BoundField()
            {
                DataField = "ItemCount",
                HeaderText = "No Items"
            });
            webLists.Columns.Add(new CommandField()
            {
                HeaderText = "Action",
                ControlStyle = { Width = new Unit(70) },
                SelectText = "Show Items",
                ShowSelectButton = true
            });
            webLists.DataKeyNames = new string[] { "Title" };
            webLists.DataBind();
            Controls.Add(webLists);
            webLists.SelectedIndexChanged +=
                new EventHandler(webLists_SelectedIndexChanged);
        }

        void webLists_SelectedIndexChanged(object sender, EventArgs e)
        {
            ListName = webLists.SelectedValue.ToString();
        }


        public void GetFieldValue(FieldCallback callback)
        {
            callback(Schema.GetValue(this));
        }

        public PropertyDescriptor Schema
        {
            get
            {
                PropertyDescriptorCollection props =
                                TypeDescriptor.GetProperties(this);
                return props.Find("ListName", false);
            }
        }

        [ConnectionProvider("List Name Selection Provider")]
        public IWebPartField GetFieldInterface()
        {
            return this;
        }

    }
}

The SPGridView is constructed with three columns, and uses the Title field as the key to retrieve the selected value. The grid shows just the Title and the ItemCount properties. A command field is used to create a callback that retrieves the current value and sends it to the connected detail Web Part (shown next). There are three crucial parts in the master Web Part:

Once the connection details are completed, the consumer Web Part can be constructed. Since it is only a consumer, its code is less complicated, as shown in Listing 6-33.

using System;
using System.ComponentModel;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using Microsoft.SharePoint;

namespace Apress.SP2010. WebPartPageProject.ConnectedWebParts

{
    [ToolboxItemAttribute(false)]
    public class DetailWebPart : WebPart
    {
        public DetailWebPart()
        {
            dataLabel = new Label();
        }

        private Label dataLabel;

        protected override void CreateChildControls()
        {
            base.CreateChildControls();
            Controls.Add(dataLabel);
        }

        [ConnectionConsumer("List Name Consumer",
                             AllowsMultipleConnections = false)]
        public void SetFieldInterface(IWebPartField field)
        {
            field.GetFieldValue(new FieldCallback(SetLabel));
        }

        private void SetLabel(object fieldData)
        {
            if (fieldData != null)
            {
                SPList list = SPContext.Current.Web.Lists[fieldData.ToString()];
                dataLabel.Text = String.Format("List {0} with {1} items.",
                    list.Title,
                    list.ItemCount);
            }
        }

    }
}

The SetFieldInterface method is again needed to inform the Web Part manager to which Web Part it can connect. The attribute is again the key—the name doesn't matter. The method can now use the predefined callback that it hands over to the producer Web Part. This means that the master calls the SetLabel method implicitly. The fieldData parameter is whatever the master exposes. It's of type object, which is both easy to use (since you can transfer any value) and problematic (because users might connect to Web Parts that expose values your code can't handle). Consider adding error-checking routines here, or at least put a try...catch clause around the consumer's methods. In the examples, all such code is stripped out for the sake of clarity. Figure 6-23 shows the result the example code produces.

Figure 6.23. Master and detail Web Part in action

The other predefined interfaces come with similar object relationships that make advanced connection scenarios easy to build. We won't include any examples, as they would simply repeat the preceding example, with minor changes.

In the previous examples, you saw how to connect Web Parts. Transferring the value the classic way via postbacks is well known and available out of the box. Users might expect today that things are becoming more "magical"—with Ajax being used in the background. SharePoint 2010 uses Ajax at many points, and a well-developed custom Web Part designed for such an environment should use it as well. In Chapter 2, you got a first insight into Ajax as a base technology. Based on that knowledge, you can now enhance the Web Parts to make them Ajax-driven.

Ajax-enabled Web Parts are quite similar to their non-Ajax counterparts. However, they require three fundamental changes:

The easiest way to do this is to use controls that support Ajax out of the box. In the following example, an UpdatePanel encapsulates both the control that invokes the callback and the region that is updated silently. The following project does exactly the same as the last example—it retrieves some images from a folder and updates another Web Part to display the selected image. For the sake of brevity, the initial steps and configuration files are skipped. The required changes are in the interface definition, its implementation, and the additional controls created in the CreateChildControls method.

The interface looks like this:

public interface IEventWebPartField
{
   event EventHandler ImageChanged;
   string ImageName { get; }
}

The event is necessary to invoke the update in the target, called from the source when the user changes the selected image. Listing 6-34 shows the implementation.

[ToolboxItemAttribute(false)]
public class AjaxSourceWebPart : System.Web.UI.WebControls.WebParts.WebPart,
                                 IEventWebPartField
{

    private GroupedDropDownList list;

    public AjaxSourceWebPart()
    {
    }

    protected override void OnInit(EventArgs e)
    {
        base.OnInit(e);
        WebPartManager.ConnectionsActivated +=
              new EventHandler(WebPartManager_ConnectionsActivated);
    }

    void WebPartManager_ConnectionsActivated(object sender, EventArgs e)
    {
        if (!Page.IsPostBack)
        {
            //
        }
    }

    protected override void CreateChildControls()
    {
         base.CreateChildControls();
         try
         {

             // Few controls with IDs sent to target
             string path = SPUtility.GetGenericSetupPath("TEMPLATE\IMAGES");

// Group Drop Box
             SPHtmlSelect dlGroup = new SPHtmlSelect();
             dlGroup.ID = this.ID + "dlGroup";
             dlGroup.Height = 22;
             dlGroup.Width = 100;
             Controls.Add(dlGroup);
             SPHtmlSelect dlCandidate = new SPHtmlSelect();
             dlCandidate.ID = this.ID + "dlCandidate";
             dlCandidate.Height = 22;
             Controls.Add(dlCandidate);
             // Put the button into the panel
             UpdatePanel panel = new UpdatePanel()
             {
                 ID = this.SkinID + "updatePanel",
                 ChildrenAsTriggers = false,
                 UpdateMode = UpdatePanelUpdateMode.Conditional
             };
             Button b = new Button();
             b.Text = "Select Image";
             b.Click += new EventHandler(Button_OnClick);
             panel.ContentTemplateContainer.Controls.Add(b);
             Controls.Add(panel);
             // Register for async
             ScriptManager sc = ScriptManager.GetCurrent(Page);
             if (sc != null)
             {
                 sc.RegisterAsyncPostBackControl(b);
             }
             //
             Controls.Add(new HtmlGenericControl("br"));
             HtmlGenericControl lblText = new HtmlGenericControl("span");
             lblText.ID = this.ID + "lblText";
             lblText.InnerText = "No image selected";
             Controls.Add(lblText);
             list = new GroupedDropDownList();
             list.GroupControlId = dlGroup.ID;
             list.CandidateControlId = dlCandidate.ID;
             list.DescriptionControlId = lblText.ID;
             string filter = (Page.IsPostBack && dlGroup.Items.Count > 0) ?
                              dlGroup.Items[dlGroup.SelectedIndex].Value : "*.*";
             foreach (string file in Directory.GetFiles(path, filter))
             {
                list.AddItem(
                    Path.GetFileName(file),
                    Path.GetFileNameWithoutExtension(file),
                    file,
                    Path.GetExtension(file).ToLowerInvariant());
             }
             Controls.Add(list);
         }
         catch
         {

}
     }

     protected void Button_OnClick(object sender, EventArgs e)
     {
           OnImageChanged();
     }


     protected override void RenderContents(HtmlTextWriter writer)
     {
          base.RenderContents(writer);
     }

     public string ImageName
     {
          get
          {
               return (list == null) ? null : list.Value;
          }
     }

     [ConnectionProvider("Image Name", AllowsMultipleConnections=false)]
     public IEventWebPartField GetCustomerProvider()
     {
          return this;
     }

     public event EventHandler ImageChanged;

     protected void OnImageChanged()
     {
          if (ImageChanged != null)
          {
              ImageChanged(this, EventArgs.Empty);
          }
     }
}

The first thing you need is an UpdatePanel, added in CreateChildControls. It contains the button that used to post back the form. To capture the button click as a server event instead, the button (b) is registered as an asynchronous source within the ScriptManager:

ScriptManager sc = ScriptManager.GetCurrent(Page);
if (sc != null)
{
    sc.RegisterAsyncPostBackControl(b);
}

It's nice to know that SharePoint 2010 is Ajax-enabled by default, and you don't need to register, configure, or enable anything to get it working. The button's Click event invokes the private event defined through the interface. The target Web Part hooks its handler to this event and receives the click (see Listing 6-35). Thus, as it did in the last example, it can retrieve the image's file name.

[ToolboxItemAttribute(false)]
public class AjaxTargetWebPart : WebPart
{

        private IEventWebPartField customerProvider;
        private UpdatePanel panel;

        public AjaxTargetWebPart()
        {
        }

        [ConnectionConsumer("Image Name")]
        public void RegisterCustomerProvider(IEventWebPartField provider)
        {
            this.customerProvider = provider;
            this.customerProvider.ImageChanged += new
                  EventHandler(customerProvider_ImageChanged);
        }

        void customerProvider_ImageChanged(object sender, EventArgs e)
        {
            panel.Update();
        }

        private string ImageName
        {
            get
            {
                return customerProvider.ImageName;
            }
        }

        protected override void CreateChildControls()
        {
            base.CreateChildControls();
            Image img = new Image();
            panel = new UpdatePanel();
            if (customerProvider != null && ImageName != null)
            {
                string path = "/_layouts/images/";
                img.ImageUrl = SPContext.Current.Web.Url + path + ImageName;
                panel.ContentTemplateContainer.Controls.Add(img);
            }
            else
            {
                Label l = new Label();
                if (customerProvider == null)
                {
                    l.Text = "No Connection established.";
                }

else
                {
                    l.Text = "No image selected.";
                }
                l.ForeColor = System.Drawing.Color.Red;
                panel.ContentTemplateContainer.Controls.Add(l);
            }
            Controls.Add(panel);
        }

     protected override void RenderContents(HtmlTextWriter writer)
     {
         base.RenderContents(writer);
     }

}

The Image element is also placed in another UpdatePanel. There is nothing to register here. The click event from source Web Part is finally routed through to the Update method of the UpdatePanel. The registration happens within the RegisterCustomerProvider method, which is called when the connection is established. That's all you need to get two Web Parts working smoothly together.

Your Web Part should handle all exceptions, rather than risk the possibility of causing the Web Part page to stop responding. If an exception is not handled properly, it could prevent the user from using the editing mode of the page, and as a last resort, remove the Web Part. SharePoint 2010 provides some techniques to restore a previous version of the page or remove a nonfunctional Web Part. However, maintaining control over what happens with your code is preferable.

You can achieve this by placing the sections of code that might throw exceptions in a try block and writing code to handle these exceptions in a catch block:

private void SetSaveProperties()
{
   if (this.Permission !=
      Microsoft.SharePoint.WebPartPages.Permissions.None)
   {
      try
      {
         SaveProperties = true;
      }

      catch (Exception ex)
      {
      // Setting SaveProperties can throw many exceptions.
      // Two examples are:

// 1) SecurityException if the user doesn't have the "ObjectModel"
      //    SharePointPermission or the "UnsafeSaveOnGet"
      //    SharePointPermission
      // 2) WebPartPageUserException if the user doesn't have sufficient
      //    rights to save properties (e.g., the user is a Reader)
         errorText = ex.Message;
      }
   }
}

Because Web Parts are managed by the user at runtime, you should render your Web Part with a UI that is appropriate for each user's permissions. To do this, always check the Permissions property before rendering the Web Part—if the value is None, you should suppress the portions of your Web Part UI that require certain permissions. For example, if a Web Part displays a Save button, you can disable or hide it if the user does not have permissions to save changes. Catching the exception that the runtime will throw if you launch an action without proper permissions is not a good practice. An exception is not intended for handling foreseeable situations. Missing permissions can occur, and therefore you should handle them explicitly in code.

If a user is unable to use your Web Part as you designed it, two things could be happening:

You can edit property values in a number of places outside of your Web Part's UI:

Because of this, whenever you attempt to save changes to the database, you should not make assumptions about the state of your properties. For example, you cannot assume that properties are unchanged because you disabled them in the UI, or that properties are valid because you validated them when they were entered in the UI.

To ensure that you account for all the different places those properties can be set; we recommend that you place your validation code in the property's setter method.

By default, when an exception occurs, the Web Part infrastructure redirects the user to an error page and renders a generic error message. To specify your own error message to the end user, use the WebPartPageUserException class:

if (ex is WebPartPageUserException)

{
   errorText.Text = ex.Message;
}

As with any web control or application, you should thoroughly validate all user-supplied data before performing operations with that data. This validation can help to protect your code, not only against accidental misuse, but also from deliberately malicious attacks that use the UI to target the code.

There are some ways to render client-side script for a Web Part page:

If you have multiple Web Parts that share client-side script, you can improve performance and simplify maintenance by placing the script in an external file or web reference and registering the script for the page. In this way, the code is cached on the client computer on first use and does not need to be resent to the client for each subsequent request. In addition, the page registration ensures that the code is only added once to the page, even if the same Web Part is used several times.

To register client-side script shared by multiple Web Parts via a web reference, proceed as shown in the next exercise.

If your Web Part is working with large amounts of data, you can significantly improve its performance by using the following techniques in your code.

Asynchronous Data Fetching

Use an asynchronous pattern for any external operation that could take a significant amount of time. In particular, if a database or HTTP request is made, an asynchronous fetch allows other parts to continue processing without being blocked. (See the "Asynchronous Web Parts" section earlier in the chapter for more information.)

Caching

Use a Web Part cache to store property values and to expedite data retrieval. Values are stored in the Web Part cache on a per-part or per-user basis by specifying the storage type in the call to the PartCacheRead and PartCacheWrite methods. You can also determine the type of cache to use—either the content database or the ASP.NET Cache object—by setting the value of the WebPartCache element in the web.config file. The cache objects must be serializable.

When you export a Web Part, you create a Web Part description (.webpart) file automatically. The .webpart file is an XML document that represents the Web Part and its property values. Users can import this file to add the Web Part with all the properties set.

By default, each property is included in the .webpart file whenever you export a Web Part. However, you may have properties that contain sensitive information (e.g., a date of birth). The Web Part infrastructure enables you to identify a property as controlled, allowing you or the user to choose to exclude the value if the Web Part is exported. Only properties that are exported when the user is in personal view can be controlled; in shared view, all property values are exported because it is unlikely that sensitive information would be included on a shared page.

There are two properties that cooperate to provide this functionality:

[WebPartStorage (Storage.Personal, ControlledExport=true)]

The ExportControlledProperties property maps directly to the Export Mode drop-down in the Advanced category of the tool pane (see Figure 6-25), enabling the user to set this value at runtime. By default, this check box is not selected, which prevents controlled properties from being exported. The user has to explicitly select this check box to allow different behavior. This option applies only to controlled properties.

Figure 6.25. The Advanced category as viewed in the tool pane

The Advanced category in the tool pane appears only in the view in which the Web Part was added. For example, if the Web Part is added in shared view, the Advanced section appears in the tool pane only when you are modifying properties in the shared page. If it is added in personal view, the Advanced section of the tool pane appears only when you are modifying properties in personal page of a My Site scenario. In either case, the setting determines how properties are exported only when the user is exporting in personal view.

Implement the IDesignTimeHtmlProvider interface in your Web Part to ensure correct rendering on designer surfaces. If you do not implement this interface, and a user opens a Web Part page in design view, your part appears only as the message, "There is no preview available for this part."

Following is an example of a simple IDesignTimeHtmlProvider implementation:

namespace Apress.SP2010.WebParts.MyWebParts
{
   [XmlRoot(Namespace = "MyNamespace")]
   public class DesignTimeHTMLSample :
      Microsoft.SharePoint.WebPartPages.WebPart, IDesignTimeHtmlProvider
   {
      private string designTimeHtml = "This is the design-time HTML.";
      private string runTimeHtml = "This is the run-time HTML.";

      public string GetDesignTimeHtml()
      {
         return SPEncode.HtmlEncode(designTimeHtml);
      }
      protected override void RenderWebPart(HtmlTextWriter output)
      {
         output.Write(this.ReplaceTokens(runTimeHtml));
      }
   }
}

Because the tool pane is where users modify Web Part properties, you should be aware of how your properties appear in it. Following are some attributes (see Table 6-6) you should use to ensure that your users can work with your Web Part properties easily in the tool pane.

A custom property is also placed in the Miscellaneous category if you attempt to include it in the Appearance, Layout, or Advanced categories. These categories are reserved for base class properties only.

For example, the following statements demonstrate the attributes for a custom property that is a string displayed as a text box in the tool pane.

// Create a custom category in the tool pane.
[Category("Custom Properties")]
// Assign the default value.
[DefaultValue(c_MyStringDefault)]
// Make the property available in both Personalization
// and Customization modes.
[WebPartStorage(Storage.Personal)]
// The caption that appears in the tool pane.
[FriendlyNameAttribute("My Custom String")]
// The tooltip that appears when pausing the mouse pointer over
// the friendly name in the tool pane.
[Description("Type a string value.")]
// Display the property in the tool pane.
[Browsable(true)]

You can customize the appearance of your properties in the tool pane in several ways. You can expand or collapse specific categories when the pane opens. Use the Expand method of either the WebPartToolPart or CustomPropertyToolPart class to expand selected categories.

You can also hide base class properties. Use the Hide method of the WebPartToolPart class to hide selected properties. To control the order of tool parts within a tool pane, use the array passed to the GetToolParts method of the WebPart class.

Use the HTMLEncode method of the SPEncode class as a security precaution to help prevent malicious script blocks from being able to execute in applications that execute across sites. You should use HTMLEncode for all input that is rendered to the client. This will convert dangerous HTML tags to more secure escaped characters.

Following is an example of using the HTMLEncode method to render HTML to a client computer:

protected override void RenderWebPart(HtmlTextWriter output)
{
   output.Write("<font color='" + SPEncode.HTMLEncode(this.Color) + "'>"
      + "Your custom text is: <b>" + SPEncode.HTMLEncode(this.Text)
      + "</b></font><hr>");
}

Web Part zones have properties that control whether a user can persist changes. If you attempt to save changes to a Web Part without the correct permissions, it could result in an unhandled exception. For this reason, you should account for any combination of permissions for your Web Part.

Following are the properties in the WebPartZone class that determine whether a Web Part can save properties:

Fortunately, the Web Part infrastructure does a lot of the work. You can check the Permissions property, which takes into account the values of the zone's AllowCustomization and AllowPersonalization properties. If, however, your UI permits changes to the properties controlled by the LockLayout property, you must explicitly check this value, typically in the property setter.

The following code illustrates how you can get a reference to a Web Part's containing zone to check the LockLayout property:

WebPartZone myParent = (this.Page.FindControl(this.ZoneID));

Web Part property values can be specified in one of two ways. One way is as XML elements contained in the Web Part. For example:

<WebPartPage:ContentEditorWebPart runat=server>
<WebPart>
   <title>My content Web Part</title>
   <description>This is cool</description>
</WebPart>
</WebPartPages:ContentEditorWebPart>

The other way, commonly used for ASP.NET controls, uses attributes of the Web Part:

<WebPartPage:ContentEditorWebPart runat=server title="My content Web Part" description="this is cool" />

Because of how the Web Part infrastructure handles property values, we recommend that you define your properties as simple types so that they work correctly if specified as attributes of the Web Part. As shown in the examples, the editor can handle the attributes as strings only. Any type other than System.String would need a serialization/deserialization round trip. For numbers or colors this might be effortless, but for more complex types this could become painful for the user of the Web Part. If your code requires a value to be a complex type, you can convert the string value to a complex type as required by your program.

There is no guarantee of the order that properties are displayed in the tool pane. For this reason, you should avoid writing Web Part properties that are dependent on each other and that both appear in the tool pane.

Web Part galleries can contain numerous custom Web Parts, so the Web Part infrastructure provides search functionality to help users quickly find the Web Part they need (see Figure 6-26).

Figure 6.26. Adding a Web Part to a page

The search function uses the Title and Description properties of your Web Part to build the response, so you should provide comprehensive information in these fields to increase the chance of your Web Part being discovered by Search. In addition, each Web Part in the Web Part list has an icon that appears on the left. By default, the Web Part infrastructure uses generic icons for each Web Part; however, you can customize this icon using the PartImageLarge property.

Be sure to create previews for your Web Parts so that administrators are able to review the parts included in the Web Part gallery.

In your RenderWebPart method, you can determine whether you are in preview mode using the following code:

if (this.Parent.GetType().Fullname = "Microsoft.SharePoint.WebPartPages.WebPartPreview")

If you are in preview mode, you should render the HTML for the content you want to appear in the preview—typically an image. The chrome and title bar are provided by the infrastructure, with the Web Part title appearing in the title bar. The next exercise explains how to display the Web Part preview.

We recommend that you localize the FriendlyName, Title, and Description attributes. By planning for localization in the development phase, you can provide a more customer-friendly UI and save on the costs associated with localizing your Web Part after development. The Web Part infrastructure provides a simple way to localize certain attributes (FriendlyName, Category, and Description) of your custom properties, making it easier for users to work with them in the tool pane. (See Chapter 8 for more information.)

Ensure that when anonymous access is on, the user can view the Web Part page without logging in. You do not want to prompt users for a login if the site has anonymous access enabled. You can determine whether anonymous access is enabled by querying the AllowAnonymousAccess property of the SPWeb class. If this value is true, anonymous access is enabled, and you should not perform any action that requires credentials.

If you use resources, it's possible to get confused regarding the exact names of the embedded data. Even using the formula Namespace + Path + File, you don't always get the whole string correct. If you are in a debug session and are able to use the Immediate window, you can read all the names of the embedded resources using the code shown in Figure 6-27.

Figure 6.27. You can retrieve embedded resource names using the Immediate window.

If it is not displayed here, it is not an embedded resource in this assembly. First check the build action (as shown in Figure 6-28) and the AssemblyInfo.cs file to make sure that the resource is embedded as a web resource. If it is present and your code still doesn't work, double-check the string—it's case sensitive.

Figure 6.28. Declare an item as an embedded resource.