Walkthrough: Creating a Web Part for SharePoint

Article
02/04/2013

Web Parts enable users to directly modify the content, appearance, and behavior of SharePoint site pages by using a browser. This walkthrough shows you how to create a Web Part by using the Web Part item template in Visual Studio 2010.

The Web Part displays employees in a data grid. The user specifies the location of the file that contains the employee data. The user can also filter the data grid so that employees who are managers appear in the list only.

This walkthrough illustrates the following tasks:

Creating a Web Part by using the Visual Studio Web Part item template.
Creating a property that can be set by the user of the Web Part. This property specifies the location of the employee data file.
Rendering content in a Web Part by adding controls to the Web Part controls collection.
Creating a new menu item, referred to as a verb, that appears in the verbs menu of the rendered Web part. Verbs enable the user to modify the data that appears in the Web Part.
Testing the Web Part in SharePoint.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Working with Settings.

Prerequisites

You need the following components to complete this walkthrough:

Supported editions of Microsoft Windows and SharePoint. For more information, see Requirements for Developing SharePoint Solutions.
Visual Studio 2010 Professional or an edition of Visual Studio Application Lifecycle Management (ALM).

Creating an Empty SharePoint Project

First, create a Empty SharePoint project. Later, you will add a Web Part to the project by using the Web Part item template.

To create an Empty SharePoint Project

Start Visual Studio 2010 by using the Run as Administrator option.
On the File menu, point to New, and then click Project.

The New Project dialog box appears.
Open the New Project dialog box, expand the SharePoint node under the language that you want to use, and then select the 2010 node.
In the Templates pane, select Empty SharePoint Project, and then click OK.

The SharePoint Customization Wizard appears. This wizard enables you to select the site that you will use to debug the project and the trust level of the solution.
Select Deploy as a farm solution, and then click Finish to accept the default local SharePoint site.

Adding a Web Part to the Project

Add a Web Part item to the project. The Web Part item adds the Web Part code file. Later, you will add code to the Web Part code file to render the contents of the Web Part.

To add a Web Part to the Project

On the Project menu, click Add New Item.
In the Add New Item dialog box, in the Installed Templates pane, expand the SharePoint node, and then click 2010.
In the list of SharePoint templates, select Web Part, and then click Add.

The Web Part item appears in Solution Explorer.

Rendering Content in the Web Part

You can specify which controls you want to appear in the Web Part by adding them to the controls collection of the Web Part class.

To render content in the Web Part

In Solution Explorer, double-click WebPart1.vb (in Visual Basic) or WebPart1.cs (in C#).

The Web Part code file opens in Code Editor.
Add the following statements to the top of the Web Part code file.
```
Imports System.Data
```
```
using System.Data;
```
Add the following code to the WebPart1 class. This code declares the following fields:
- A data grid to display employees in the Web Part.
- Text that appears on the control that is used to filter the data grid.
- A label that displays an error if the data grid is unable to display data.
- A string that contains the path of the employee data file.
```
Private grid As DataGrid
Private Shared verbText As String = "Show Managers Only"
Private errorMessage As New Label()
Protected xmlFilePath As String
```
```
private DataGrid grid;
private static string verbText = "Show Managers Only";
private Label errorMessage = new Label();
protected string xmlFilePath;
```

Add the following code to the WebPart1 class. This code adds a custom property named DataFilePath to the Web Part. A custom property is a property that can be set in SharePoint by the user. This property gets and sets the location of a XML data file that is used to populate the data grid.

<Personalizable(PersonalizationScope.[Shared]), _
    WebBrowsable(True), WebDisplayName("Path to Employee Data File"), _
    WebDescription("Location of the XML file that contains employee data")> _
Public Property DataFilePath() As String
    Get
        Return xmlFilePath
    End Get
    Set(ByVal value As String)
        xmlFilePath = value
    End Set
End Property

[Personalizable(PersonalizationScope.Shared), WebBrowsable(true),
WebDisplayName("Path to Employee Data File"),
WebDescription("Location of the XML file that contains employee data")]
public string DataFilePath
{
    get
    {
        return xmlFilePath;
    }
    set
    {
        xmlFilePath = value;
    }
}

Replace the CreateChildControls method with the following code. This code performs the following tasks:

Adds the data grid and label that you declared in the previous step.
Binds the data grid to an XML file that contains employee data.

Protected Overloads Overrides Sub CreateChildControls()

    'Define the grid control that displays employee data in the Web Part.
    grid = New DataGrid()
    With grid
        .Width = Unit.Percentage(100)
        .GridLines = GridLines.Horizontal
        .HeaderStyle.CssClass = "ms-vh2"
        .CellPadding = 2
        .BorderWidth = Unit.Pixel(5)
        .HeaderStyle.Font.Bold = True
        .HeaderStyle.HorizontalAlign = HorizontalAlign.Center
    End With



    'Populate the grid control with data in the employee data file.
    Try
        Dim dataset As New DataSet()
        dataset.ReadXml(xmlFilePath, XmlReadMode.InferSchema)
        grid.DataSource = dataset
        grid.DataBind()
    Catch x As Exception
        errorMessage.Text += x.Message
    End Try

    'Add control to the controls collection of the Web Part.
    Controls.Add(grid)
    Controls.Add(errorMessage)
    MyBase.CreateChildControls()

End Sub

protected override void CreateChildControls()
{
    // Define the grid control that displays employee data in the Web Part.
    grid = new DataGrid();
    grid.Width = Unit.Percentage(100);
    grid.GridLines = GridLines.Horizontal;
    grid.HeaderStyle.CssClass = "ms-vh2";
    grid.CellPadding = 2;
    grid.BorderWidth = Unit.Pixel(5);
    grid.HeaderStyle.Font.Bold = true;
    grid.HeaderStyle.HorizontalAlign = HorizontalAlign.Center;

    // Populate the grid control with data in the employee data file.
    try
    {
        DataSet dataset = new DataSet();
        dataset.ReadXml(xmlFilePath, XmlReadMode.InferSchema);
        grid.DataSource = dataset;
        grid.DataBind();
    }
    catch (Exception x)
    {
        errorMessage.Text += x.Message;
    }

    // Add control to the controls collection of the Web Part.
    Controls.Add(grid);
    Controls.Add(errorMessage);
    base.CreateChildControls();
}

Add the following method to the WebPart1 class. This code performs the following tasks:

Creates a verb that appears in the Web Part verbs menu of the rendered Web part.
Handles the event that is raised when the user clicks the verb in the verbs menu. This code filters the list of employees that appears in the data grid.

Public Overrides ReadOnly Property Verbs() As WebPartVerbCollection
    Get
        Dim customVerb As New WebPartVerb("Manager_Filter_Verb", _
            New WebPartEventHandler(AddressOf CustomVerbEventHandler))

        customVerb.Text = verbText
        customVerb.Description = "Shows only employees that are managers"

        Dim newVerbs() As WebPartVerb = {customVerb}

        Return New WebPartVerbCollection(MyBase.Verbs, newVerbs)
    End Get
End Property

Protected Sub CustomVerbEventHandler(ByVal sender As Object, ByVal args As WebPartEventArgs)
    Dim titleColumn As Integer = 2

    Dim item As DataGridItem
    For Each item In grid.Items
        If item.Cells(titleColumn).Text <> "Manager" Then
            If item.Visible = True Then
                item.Visible = False
            Else
                item.Visible = True
            End If
        End If
    Next item
    If verbText = "Show Managers Only" Then
        verbText = "Show All Employees"
    Else
        verbText = "Show Managers Only"
    End If
End Sub

public override WebPartVerbCollection Verbs
{
    get
    {
        WebPartVerb customVerb = new WebPartVerb("Manager_Filter_Verb",
            new WebPartEventHandler(CustomVerbEventHandler));

        customVerb.Text = verbText;
        customVerb.Description = "Shows only employees that are managers";

        WebPartVerb[] newVerbs = new WebPartVerb[] { customVerb };

        return new WebPartVerbCollection(base.Verbs, newVerbs);
    }
}

protected void CustomVerbEventHandler(object sender, WebPartEventArgs args)
{
    int titleColumn = 2;

    foreach (DataGridItem item in grid.Items)
    {
        if (item.Cells[titleColumn].Text != "Manager")
        {
            if (item.Visible == true)
            {
                item.Visible = false;
            }
            else
            {
                item.Visible = true;
            }
        }

    }
    if (verbText == "Show Managers Only")
    {
        verbText = "Show All Employees";
    }
    else
    {
        verbText = "Show Managers Only";
    }
}

Testing the Web Part

When you run the project, the SharePoint site opens. The Web Part is automatically added to the Web Part Gallery in SharePoint. You can add the Web Part to any Web Part page.

To test the Web Part

Paste the following XML into a Notepad file. This XML file contains the sample data that will appear in the Web Part.

<?xml version="1.0" encoding="utf-8" ?>
    <employees xmlns="https://schemas.microsoft.com/vsto/samples">
       <employee>
           <name>David Hamilton</name>
           <hireDate>2001-05-11</hireDate>
           <title>Sales Associate</title>
       </employee>
       <employee>
           <name>Karina Leal</name>
           <hireDate>1999-04-01</hireDate>
           <title>Manager</title>
       </employee>
       <employee>
           <name>Nancy Davolio</name>
           <hireDate>1992-05-01</hireDate>
           <title>Sales Associate</title>
       </employee>
       <employee>
           <name>Steven Buchanan</name>
           <hireDate>1955-03-04</hireDate>
           <title>Manager</title>
       </employee>
       <employee>
           <name>Suyama Michael</name>
           <hireDate>1963-07-02</hireDate>
           <title>Sales Associate</title>
       </employee>
    </employees>

In Notepad, click File, and then click Save As.
In the Save As dialog box, in the Save as type drop-down list, select All Files.
In the File name box, type data.xml.
Select any folder by using the Browse Folders button and then click Save.
In Visual Studio, press F5.

The SharePoint site opens.
Click Site Actions, and then click More Options.
In the Create page, select Web Part Page, then click Create.
In the New Web Part Page page, name the page SampleWebPartPage.aspx, and then click Create.

The Web Part page appears.
Select any zone on the Web Part page.
At the top of the page, click Insert, and then click Web Part.
In the Categories pane, click the Custom folder, click the WebPart1 Web Part, and then click Add.

The Web Part appears on the page.

Testing the Custom Property

To populate the data grid that appears in the Web Part, specify the path of the XML file that contains data about each employee.

To test the custom property

Click the arrow that appears in the corner of the Web Part, and then click Edit Web Part.

A pane that contains properties for the Web Part appears on the right side of the page.
In the pane, expand the Miscellaneous node, type the path of the XML file that you created earlier, and click Apply, and then click OK.

Verify that a list of employees appears in the Web Part.

Testing the Web Part Verb

Show and hide employees that are not managers by clicking an item that appears in the Web Part verbs menu.

To test the Web Part verb

Click the arrow that appears in the corner of the Web Part, and then click Show Managers Only.

Only employees who are managers appear in the Web Part.
Click the arrow again, and then click Show All Employees.

All employees appear in the Web Part.