Adding Custom Functionality - Share Point 2010

Now that you’ve got a good understanding of how a SharePoint page is constructed and what factors are important in determining the overall look and feel of a site, let’s move on to look at how you can add additional functionality to a page.

Web Parts

You’ve seen how you can use tools such as InfoPath forms services to customize input forms. But what if you want to add functionality that goes beyond the capabilities of InfoPath? Let’s look at a few options—the first is to create a custom web part. Two types of web parts can be used within SharePoint: legacy web parts that are derived from the Microsoft. SharePoint. WebPartPages. WebPart base class, and standard ASP.NET web parts that are derived from the System. Web. UI. WebControl. Webparts. WebPart base class. The recommended approach for creating new web parts is to use the ASP.NET model.

Web Part Infrastructure

Before we delve into a discussion on how to create web parts for use with SharePoint, let’s recap how the ASP.NET web part infrastructure works and what it does. A web part is a server control that exposes functionality that allows it to be configured or personalized by nontechnical users. In a sense, web parts are like building blocks: we can choose the web parts that we need to build something and stick them on the page wherever we want them. To provide this functionality, the web part infrastructure has a few additional elements that should be included on a page. One of the first is the WebPartManager control, which is used to manage the configuration information for each web part on a page. As well as a WebPartManager, to allow designers some control over where web parts can be placed, the web part infrastructure makes use of WebPartZone controls that represent zones within a page where web parts can be added.

The SharePoint platform defines custom WebPartManager and WebPartZone controls that are derived from their ASP.NET counterparts. This allows web part settings to be persisted and controlled in a way that better suits the SharePoint page rendering mechanism. For example, one of the new features in SharePoint 2010 is the ability to version web part configuration along with other elements on a page. This functionality makes use of the custom SPWebPartManager class. Earlier we looked at the default v4.master page that provides the basis for rendering all SharePoint pages. It’s worthwhile to note that this master page contains a SPWebPartManager control, so all pages that are derived from this master page can make use of web parts.

Web Part Security

Web parts are a bit like building blocks; users can build whatever they like with them. However, left unchecked, users can potentially build resource-hogging monstrosities that can kill a site for all other users. To prevent this and to give administrators some control over the web parts that can be included on a page, SharePoint requires that all controls be registered as safe before they are allowed to be included. Safe controls are specified using a series of SafeControl elements within the site’s web.config file. In addition to requiring controls to be explicitly specified as safe for a given site, web parts can also make use of code access security to restrict the actions of web part code even more.

Creating a Web Part

To demonstrate how web parts can be created and used within a SharePoint page, let’s work through an example. We’ll create a simple web part that accepts two property values: a color and the name of a SharePoint list. The web part will display a list of items in the list using the selected colors. Although this is a trivial example, it will illustrate the key elements that are used when building more useful web parts.

1. In Visual Studio, choose File | New | Project. In the New Project dialog, select Empty SharePoint Project. Name the project ChapterWebPart, as shown:



2. Set the local site to use for debugging to the demo site that we created earlier and select the Deploy As Farm Solution option.
3. Choose Project | Add New Item. In the Add New Item dialog, select Web Part. Name the web part DemoWebPart.
4. In the file DemoWebPart.cs, add the following code:
[ToolboxItemAttribute(false)] public class DemoWebPart : System.Web.UI.WebControls.WebParts.WebPart { private ColorEnum _textColor = ColorEnum.Black; private string _listName = string.Empty; public enum ColorEnum { Red, Green, Blue, Black, White } [Personalizable(true), WebBrowsable(true), WebDescription("Select the font color used to display text"), WebDisplayName("Text Color") , SPWebCategoryName("Color")] public ColorEnum TextColor { get { return _textColor; } set { _textColor = value; } } [Personalizable(true), WebBrowsable(true), WebDescription("Select the list name from which text will be retrieved"), WebDisplayName("List Name")] public string ListName { get { return _listName; } set { _listName = value; } } protected override void CreateChildControls() { HtmlGenericControl div = new HtmlGenericControl("div"); SPList list=SPContext.Current.Web.Lists.TryGetList(ListName); if (list != null) { SPQuery query = new SPQuery(); query.RowLimit = 50; SPListItemCollection items = list.GetItems(query); StringBuilder sb = new StringBuilder(); sb.Append("<ul style="color:" + System.Enum.GetName(typeof(ColorEnum), TextColor) + "";>"); foreach (SPListItem item in items) { sb.Append("<li>" + item.Title + "</li>"); } sb.Append("</ul>"); div.InnerHtml = sb.ToString(); } else { div.InnerHtml = "List not found"; } this.Controls.Add(div); } }

We’re querying the configured list and creating an unordered list of the title of the top 50 items. Notice that the attributes that are applied to the TextColor and ListName properties. For the property to be visible in the Property Editor pane, WebBrowsable must be set to true.

5. To see how the web part works on a page, select Deploy WebPart from the Build menu.
6. In the browser, navigate to the home page of the demo site that we set up earlier, and then choose Site Actions | Edit Page. From the Insert tab on the ribbon, select Web Part.
7. From the Custom category, select DemoWebPart, and then click Add:



8. Since we haven’t configured a list, the web part will display “List not found.” To edit the web part properties, right-click the arrow to the right of the web part and select Edit Web Part from the context menu, as shown:
9. Our custom properties appear in the Color section and the Miscellaneous section, as configured by the attributes that we applied to the properties. By placing the cursor over the property name, you’ll see the description text that we added as a tooltip. In the List Name text box, enter Web Part Gallery as the name of the list, and then click OK.

Improving the Property Editing Experience: Editor Parts

For our sample web part, we’ve used a text box to allow users to enter the name of a list. While this works as we expected, it’s not exactly an ideal interface. A better approach would be to show a drop-down list of available lists and allow the user to select one. To implement this functionality, we’ll use an editor part. Editor parts are also server controls and work in a similar fashion to web parts. However, editor parts are rendered within the Property Editor pane, and their primary function is to enhance the design-time experience for users.

To add a new editor part, take the following steps:

1. Within the DemoWebPart folder in Visual Studio, add a new class file named ListPickerEditor.cs. Add the following code:
   class ListPickerEditor : EditorPart { private HtmlSelect _listsDropdown; private string _selectedValue = ""; [Personalizable(true), WebBrowsable(false)] public string selectedValue { get { return _selectedValue; } set { _selectedValue = value; } } public ListPickerEditor(string webPartId) { this.ID = "ListPickerEditor" + webPartId; this.Title = "List Picker"; } protected override void CreateChildControls() { _listsDropdown = new HtmlSelect(); Controls.Add(_listsDropdown); } public override bool ApplyChanges() { EnsureChildControls(); DemoWebPart _part = WebPartToEdit as DemoWebPart; _part.ListName = _listsDropdown.Items [_listsDropdown.SelectedIndex].Value. ToString(); return true; } public override void SyncChanges() { DemoWebPart _part = WebPartToEdit as DemoWebPart; EnsureChildControls(); selectedValue = _part.ListName; PopulateDropDown(); if(_listsDropdown.Items.FindByValue(_selectedValue)!=null) { _listsDropdown.Value = selectedValue; } } private void PopulateDropDown() { SPListCollection lists = SPContext.Current.Web.Lists; _listsDropdown.Items.Clear(); foreach (SPList list in lists) { if (list.Fields.ContainsField("Title")) { _listsDropdown.Items.Add(list.Title); } } } }
2. To hook up this editor part to our web part, we need to implement the IWebEditable interface. In DemoWebPart.cs, change the class definition to this: public class DemoWebPart : WebPart, IWebEditable
3. Add the following overrides to the DemoWebPart.cs file:
EditorPartCollection IWebEditable.CreateEditorParts() { List<EditorPart>editors = new List<EditorPart>(); editors.Add(new ListPickerEditor(this.ID)); return new EditorPartCollection(editors); } object IWebEditable.WebBrowsableObject { get { return this; } }
4. Finally, since we have an editor for our ListName property, we don’t need to display the text box default implementation. So that our ListName property is not shown in the Editor pane, change the WebBrowsable attribute to false. We can now deploy this revised web part and use a drop-down list to configure the list to be displayed rather than having to type it manually.

Visual Web Parts

In our examples so far, we’ve adopted the standard ASP.NET approach to building web parts. Because a web part is a server control, the user interface needs to be manually constructed. In our simple examples, this didn’t cause too much trouble; however, as the user interface gets more complicated, this approach becomes a problem due to the lack of a design-time interface and the extra code required to hook up controls to their events. Once again, the folks at Microsoft realized that this was a major pain for SharePoint developers, and in SharePoint 2010 introduced the Visual Web Part. A Visual Web Part is a web part that loads an embedded user control. Since user controls have a design-time interface in Visual Studio, creating complex web parts becomes much simpler.

To create a Visual Web Part, take the following steps:

1. In the WebPart project that we created earlier, choose Project | Add New Item.
2. In the Add New Item dialog, create a new Visual Web Part named DemoVisualWebPart, as shown:



3. In the DemoVisualWebPartUserControl.ascx, drag an UpdatePanel control from the toolbox. Drag a Label control into the UpdatePanel. From the AJAX Extensions category in the toolbox, drag a Timer control. Set the timer interval to 5000.
4. Set the Triggers property of the UpdatePanel control to use the Tick event of the timer, as shown:



5. In the DemoVisualWebPart.cs file, add the following code:
public class DemoVisualWebPart : WebPart { private const string _ascxPath = @"~/ _CONTROLTEMPLATES/Chapter7WebPart .DemoWebPart/DemoVisualWebPart/DemoVisualWebPartUserControl.ascx"; protected override void CreateChildControls() { DemoVisualWebPartUserControl control = Page.LoadControl (_ascxPath) as DemoVisualWebPartUserControl; control.ListName = this._listName; Controls.Add(control); } private string _listName = string.Empty; [Personalizable(true), WebBrowsable(true), WebDescription("Select the list name from which text will be retrieved"), WebDisplayName("List Name")] public string ListName { get { return _listName; } set { _listName = value; } } }
6. In the code-behind file from the user control (DemoVisualWebPartUserControl.ascx.cs), add the following code:
public partial class DemoVisualWebPartUserControl : UserControl { public string ListName { get; set; } protected void Page_Load(object sender, EventArgs e) { GetNextListName(); } private void GetNextListName() { SPList list = SPContext.Current.Web.Lists. TryGetList(ListName); if (list == null) { Label1.Text = "List not found"; ViewState.Remove("ItemId"); Timer1.Enabled = false; return; } SPQuery query = new SPQuery(); query.RowLimit = 50; SPListItemCollection items = list.GetItems(query); if (items.Count > 0) { int nextIndex = 0; if (ViewState["ItemId"] != null) { int currentValue = (int)ViewState["ItemId"]; if (currentValue >= items.Count - 1) { nextIndex = 0; } else { nextIndex = currentValue + 1; } } Label1.Text = items[nextIndex].Title; ViewState["ItemId"] = nextIndex; } else { Label1.Text = "No Items found"; ViewState.Remove("ItemId"); } Timer1.Enabled = true; } }

When this web part is deployed and then added to a page, it performs a function similar to that in our earlier example. The difference is that this web part makes use of Asynchronous JavaScript and XML (AJAX) to cycle periodically through the items in the configured list. Of course, we could have created a similar web part without the benefit of a visual designer, but I’m sure you’ll agree that using a Visual Web Part makes the job much simpler.