Walkthrough: Creating Connectable Web Parts in SharePoint Foundation

Applies to: SharePoint Foundation 2010

This programming task describes how to create two connectable Web Parts: a Web Part that provides a string and another Web Part that consumes and displays the value of that string.

This walkthrough illustrates the following tasks:

1. Creating an interface to define the string that is being provided.

2. Creating a Web Part by using the Microsoft Visual StudioWeb Part item template.

3. Creating a provider Web Part that defines a string.

4. Creating a consumer Web Part that uses and displays the string.

5. Creating a Web Parts page and connecting the provider and consumer Web Parts.

For a related code sample, see Creating Connectable Web Parts in SharePoint Foundation. For a related video demonstration, see Creating Connectable Web Parts in SharePoint Foundation.

Important

The Web Part infrastructure in Microsoft SharePoint Foundation is built on top of the Microsoft ASP.NET Web Part infrastructure, and Web Parts that derive from the ASP.NETWebPart class are completely supported in SharePoint, including the ASP.NET connection model. Whenever possible, you should create ASP.NET Web Parts, and use the ASP.NET connection model to connect your Web Parts.

For more information about choosing the best WebPart base class from which to derive, see Developing Web Parts in Windows SharePoint Services. For more information about ASP.NET Web Parts and connection model, see Web Parts Connections Overview in the ASP.NET documentation.

Prerequisites

You need the following components to complete this walkthrough:

• Visual Studio 2010 Professional or an edition of Visual Studio Application Lifecycle Management (ALM).

• SharePoint Foundation 2010 or SharePoint Server 2010.

• Windows Server 2008 or Windows Server 2008 R2.

Creating an Empty SharePoint Project

This programming task defines the process of creating a Visual Studio solution to develop and deploy the interface, provider Web Part, and consumer Web Part.

To create an Empty SharePoint Project

1. Start Visual Studio 2010 in administrator mode.

2. On the File menu, point to New, and then click Project. If Visual Studio is set to use Visual Basic development settings, on the File menu, click New Project.

3. In the New Project dialog box, expand the SharePoint node under the language that you want to use, and then select the 2010 node.

4. In the Templates pane, select Empty SharePoint Project.

5. For the name of the project, type ConnectableWebParts, and then click OK.

6. In the What local site do you want to use for debugging? drop-down list, select the local site that you want to use for debugging.

7. Select Deploy as a farm solution, and then click Finish.

Creating an Interface

This programming task defines the process of creating a class that implements all of the necessary methods and events for a connection interface.

To create an interface

1. In Solution Explorer, click the ConnectableWebParts project.

2. On the Project menu, click Add New Item.

3. In the Installed Templates pane, click Code.

4. Click Interface.

5. Type ITextBoxString for the name of the interface, and then click Add.

6. In the ITextBoxString.cs or ITextBoxString.vb code file, mark or verify that the ITextBoxString class is public.

   public interface ITextBoxString
   

   Public Interface ITextBoxString
   

7. Replace the interface with the following code to define the string member of this interface.

   public interface ITextBoxString
   {  
       string TextBoxString { get; set; }
   }
   

   Public Interface ITextBoxString
       Property TextBoxString() As String
   End Interface
   

To test the code

• On the Build menu, click Build ConnectableWebParts (Visual Basic) or click Build Solution (Visual C#).

  The solution builds without errors.

Creating a Provider Web Part

The following procedure demonstrates how to create a Web Part that provides a string for other Web Parts to consume.

To create a provider Web Part

1. In Solution Explorer, click the ConnectableWebParts project.

2. On the Project menu, click Add New Item.

3. In the Installed Templates pane, expand the SharePoint node, and then click 2010.

4. Click Web Part, type StringProvider for the name of the Web Part, and then click Add.

5. In the StringProvider.cs or StringProvider.vb code file, add the following code to indicate that the StringProvider class implements the ITextBoxString interface.

   public class StringProvider : WebPart, ITextBoxString
   

   Public Class StringProvider 
       Inherits WebPart
       Implements ITextBoxString
   

6. Add the following code to create a text box, a string, and a button.

   private TextBox myTextBox;
   private String _textBoxString = String.Empty;
   private Button myButton;
   

   Private myTextBox As TextBox
   Private _textBoxString As String = String.Empty
   Private WithEvents myButton As Button
   

7. Implement the get and set methods of the ITextBoxString interface by adding the following code.

    [Personalizable()]
   public string TextBoxString
   {
       get
       {
           return _textBoxString;
       }
       set
       {
           _textBoxString = value;
       }
   }
   

   <Personalizable()> _
   Public Property TextBoxString() As String Implements ITextBoxString.TextBoxString
       Get
          Return _textBoxString
       End Get
   
       Set(ByVal value As String)
           _textBoxString = value
       End Set
   End Property
   

8. To add the text box and button to the Web Part, replace the CreateChildControls method with the following code. The code clears all the controls from the Web Part, instantiates a control, and then adds the new control to the Web Part.

   protected override void CreateChildControls()
   {
       Controls.Clear();
       myTextBox = new TextBox();
       Controls.Add(myTextBox);
   
       myButton = new Button();
       myButton.Text = "Change Text";
       Controls.Add(myButton);
       myButton.Click += new EventHandler(myButton_Click);
   }
   

   Protected Overrides Sub CreateChildControls()
       Controls.Clear()
       myTextBox = New TextBox()
       Me.Controls.Add(myTextBox)
   
       myButton = New Button()
       myButton.Text = "Change Text"
       Me.Controls.Add(myButton)
   End Sub
   

9. Add the following code to handle the Click event for the button that you added in the previous step.

   void myButton_Click(object sender, EventArgs e)
   {
       if (myTextBox.Text != String.Empty)
       {
           TextBoxString = myTextBox.Text;
           myTextBox.Text = String.Empty;
       }
   }
   

   Private Sub myButton_Click(ByVal sender As Object, ByVal e As EventArgs) Handles myButton.Click
       If myTextBox.Text <> String.Empty Then
           TextBoxString = myTextBox.Text
           myTextBox.Text = String.Empty
       End If
   End Sub
   

10. Create a method to return the ITextBoxString object to share with other Web Parts. Apply the ConnectionProviderAttribute attribute to identify the callback method that acts as the provider in a Web Parts connection.

     [ConnectionProvider("Provider for String From TextBox", "TextBoxStringProvider")]
    public ITextBoxString TextBoxStringProvider()
    {
        return this;
    }
    

    <ConnectionProvider("Provider for String From TextBox", "TextBoxStringProvider")> _
    Public Function TextBoxStringProvider() As ITextBoxString
        Return Me
    End Function
    

To test the code

• On the Build menu, click Build ConnectableWebParts (Visual Basic) or click Build Solution (Visual C#).

  The solution builds without errors.

Creating a Consumer Web Part

The following procedure demonstrates how to create a Web Part that consumes and displays a string from a provider Web Part.

To create a consumer Web Part

1. In Solution Explorer, click the ConnectableWebParts project.

2. On the Project menu, click Add New Item.

3. In the Installed Templates pane, expand the SharePoint node, and then click 2010.

4. Click Web Part, type StringConsumer for the name of the interface, and then click Add.

5. In the StringConsumer.cs or StringConsumer.vb code file, add the following code to create objects for an ITextBoxString provider and a text box.

   private ITextBoxString _myProvider;
   private Label myLabel;
   

   Private _myProvider As ITextBoxString
   Private myLabel As Label
   

6. Change the text of the label to the string from the StringProvider class by adding the following code. This code first verifies that the provider is not null and then sets the label text to the string from the provider Web Part.

   protected override void OnPreRender(EventArgs e)
   {
       EnsureChildControls();
       if (_myProvider != null)
       {
           myLabel.Text = _myProvider.TextBoxString;
       }
   }
   

   Protected Overrides Sub OnPreRender(ByVal e As System.EventArgs)
       EnsureChildControls()
       If (Me._myProvider IsNot Nothing) Then
           myLabel.Text = _myProvider.TextBoxString
       End If
   End Sub
   

7. To add the label to the consumer Web Part, replace the CreateChildControls method adding the following code. The default text is added to indicate if the consumer Web Part is connected to the provider Web Part.

   protected override void CreateChildControls()
   {
       Controls.Clear();
       myLabel = new Label();
       myLabel.Text = "Default text";
       Controls.Add(myLabel);
   }
   

   Protected Overrides Sub CreateChildControls()
       Controls.Clear()
       myLabel = New Label()
       myLabel.Text = "Default text"
       Me.Controls.Add(myLabel)
   End Sub
   

8. Create a method to assign the ITextBoxString object from the provider Web Part to the private ITextBoxString object in this consumer Web Part. Apply the ConnectionConsumerAttribute attribute to identify the callback method acting as the consumer in a Web Parts connection.

    [ConnectionConsumer("String Consumer", "StringConsumer")]
   public void TextBoxStringConsumer(ITextBoxString Provider)
   {
       _myProvider = Provider;
   }
   

   <ConnectionConsumer("String Consumer", "StringConsumer")> _
   Public Sub TextBoxStringConsumer(ByVal Provider As ITextBoxString)
       _myProvider = Provider
   End Sub
   

To test the code

• On the Build menu, click Build ConnectableWebParts (Visual Basic) or click Build Solution (Visual C#).

  The solution builds without errors.

Testing the Web Parts Connection

The following procedure demonstrates how you can connect the two Web Parts.

To connect the provider and consumer Web Parts

1. In Visual Studio, press F5.

   A browser window opens to the SharePoint server on the development computer.

2. Click Site Actions, and then click More Options.

3. In the Create page, click Web Part Page, and then click Create.

4. In the New Web Part Page page, type ConnectableWebParts as the name, and then click Create.

5. Click Add a Web Part in any zone on the Web Parts page.

6. In the Categories pane, click Custom.

7. Click StringProvider, and then click Add.

   The Web Part is added to the page, and displays a text box and a Change Text button.

8. Click Add a Web Part in any zone on the Web Parts page.

9. In the Categories pane, click Custom.

10. Click StringConsumer, and then click Add.

    The Web Part is added to the page, and displays Default Text.

11. Click the StringConsumer Web Part, and then click the drop-down arrow in the upper-right section of the Web Part.

12. In the verbs menu, point to Connections, point to Get String Consumer From, and then click String Provider.

    The StringConsumer Web Part is connected to the StringProvider Web Part, and the Default Text label goes away.

13. In the StringProvider Web Part, type text into the text box, and then click Change Text.

    The typed text appears as the label. For example, if you typed "This is a new label" in the StringProvider Web Part, the StringConsumer Web Part also displays "This is a new label".

14. In the ribbon, on the Page tab, click Stop Editing.

See Also

Concepts

Building Block: Web Parts

Other Resources

Web Parts Connections Overview