IListConsumer Interface
NOTE: This API is now obsolete.
Defines methods that a Web Part can implement so that it can consume an entire list (rowset) of data from another Web Part that implements the IListProvider interface.
Namespace: Microsoft.SharePoint.WebPartPages.Communication
Assembly: Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Syntax
'Declaration
<ObsoleteAttribute("Use System.Web.UI.WebControls.WebParts.IWebPartTable instead")> _
Public Interface IListConsumer
'Usage
Dim instance As IListConsumer
[ObsoleteAttribute("Use System.Web.UI.WebControls.WebParts.IWebPartTable instead")]
public interface IListConsumer
Remarks
The IListConsumer interface should be implemented for Web Parts that need to consume a collection of data that can be characterized as a list, such as a table of data. A Web Part that implements the IListConsumer interface has the ability to receive initialization arguments from the provider part. Connecting the IListConsumer to the IListProvider interface is a direct connection, so no transformer dialog is displayed. To use the passed values appropriately, the consuming Web Part may need to be designed with an understanding of the data sent by the provider part.
Examples
The following code example is a simple server-side IListConsumer Web Part. It can be connected to another Web Part that implements the IListProvider interface on the server. Its user interface displays the list that it receives from an IListProvider Web Part.
There are eight steps specific to making this a connectable Web Part. These steps are numbered and commented in the sample code.
For an overview of the steps of creating a connectable Web Part, see Creating a Connectable Web Part.
' Common .NET required namespaces
Imports System
Imports System.ComponentModel
Imports System.Web.UI
' Web Part required namespaces
Imports Microsoft.SharePoint.WebPartPages
Imports System.Xml.Serialization
Imports System.Web.UI.WebControls
' Code Access Security namespaces
Imports System.Security
Imports Microsoft.SharePoint.Utilities
' DataGrid and user interface namespaces
Imports System.Data
Imports System.Drawing
'Step #1: Make a Reference to the Communication namespace.
Imports Microsoft.SharePoint.WebPartPages.Communication
Namespace ConnectionCodeSamples
' Step #2: Inherit from the WebPart base class and implement the
' IListConsumer interface.
Public Class ServerSideListConsumer
Inherits WebPart
Implements IListConsumer
' Declare variables for keeping track of connection state.
Private _connected As Boolean = False
Private _connectedWebPartTitle As String = String.Empty
Private _registrationErrorMsg As String = "An error has occurred trying to register your connection interfaces."
Private _registrationErrorOccurred As Boolean = False
Private _notConnectedMsg As String = "NOT CONNECTED. To use this Web Part connect it to a List Provider Web Part."
' Declare variables for Web Part user interface.
Private _connectedWebPartLabel As String = "Connected to Web Part"
Private _dataGrid As DataGrid
' Step #3: Override EnsureInterfaces method and call
' RegisterInterface method.
' EnsureInterfaces() is called by the Web Part infrastructure
' during the ASP.NET PreRender event
' and allows the part to register all of its connection
' interfaces.
Public Overrides Sub EnsureInterfaces()
' If your Web Part is installed in the bin directory and the
' Code Access Security (CAS) setting doesn't
' allow Web Part Connections, an exception will be thrown. To
' allow your Web Part to behave
' well and continue working, a try/catch block should be used
' when attempting to register interfaces.
' Web Part Connections will only work if the level attribute
' of the <trust> tag in the web.config file is set to
' WSS_Minimal, WSS_Medium, or Full. By default a new
' SharePoint site is installed with the trust level set to
' WSS_Minimal.
Try
' Register the IListConsumer interface
' <param name="interfaceName">Friendly name of the
' interface that is being implemented.</param>
' <param name="interfaceType">Specifies which interface is
' being implemented.</param>
' <param name="maxConnections">Defines how many times this
' interface can be connected.</param>
' <param name="runAtOptions">Determines where the interface
' can run.</param>
' <param name="interfaceObject">Reference to the object
' that is implementing this interface.</param>
' <param name="interfaceClientReference">Name used to
' reference the interface on the client.
' This is a server side example so the value is set to
' empty string.</param>
' <param name="menuLabel">Label for the interface that
' appears in the UI</param>
' <param name="description">Description of the interface
' that appears in the UI</param>
' <param name="allowCrossPageConnection">Specifies if the
' interface can connect to a Web Part
' on a different page. This is an optional parameter with a
' default of false. Note that only some
' server side interfaces are allowed to connect across
' pages by the Web Part infrastructure.
' The IListConsumer interface is not allowed to connect
' across pages.</param>
RegisterInterface("MyListConsumerInterface", InterfaceTypes.IListConsumer, WebPart.LimitOneConnection, ConnectionRunAt.Server, Me, "", "Consume List From", "Consumes a list from another Web Part.")
Catch se As SecurityException
_registrationErrorOccurred = True
End Try
End Sub
' Step #4: Override the CanRunAt method.
' The CanRunAt method is called by the Web Part infrastructure
' during the ASP.NET PreRender event
' to determine where the Web Part can run based on its current
' configuration.
Public Overrides Function CanRunAt() As ConnectionRunAt
' This Web Part can run on the server.
Return ConnectionRunAt.Server
End Function
' Step #5: Override the PartCommunicationConnect method.
' PartCommunicationConnect() is called by the Web Part
' infrastructure to notify the Web Part that it
' is connected during the ASP.NET PreRender event. Relevant
' information is passed to the part such as
' the interface it is connected over, the Web Part it is being
' connected to, and where the part will be running,
' either client or server side.
' <param name="interfaceName">Friendly name of the interface that
' is being connected</param>
' <param name="connectedPart">Reference to the other Web Part
' that is being connected to</param>
' <param name="connectedInterfaceName">Friendly name of the
' interface on the other Web Part</param>
' <param name="runAt">Where the interface should execute</param>
Public Overrides Sub PartCommunicationConnect(interfaceName As String, connectedPart As WebPart, connectedInterfaceName As String, runAt As ConnectionRunAt)
' Keep track of connection state.
If interfaceName = "MyListConsumerInterface" Then
_connected = True
_connectedWebPartTitle = SPEncode.HtmlEncode(connectedPart.Title)
End If
End Sub
' Step #6: Implement the ListProviderInit event handler.
' The connected provider part(s) will call this method during its
' PartCommunicationInit phase to pass initialization information
' to the consumer Web Part.
' <param name="sender">Reference to the Consumer Web Part</param>
' <param name="listProviderInitEventArgs">The args passed by the
' provider Web Part</param>
Public Sub ListProviderInit(sender As Object, listProviderInitEventArgs As ListProviderInitEventArgs) _
Implements IListConsumer.ListProviderInit
End Sub
' Because this class implements the IListConsumer interface, it
' must implement the interface member ListProviderInit. However,
' this example doesn't use any initialization data that is passed
' in here.
' Step #7: Implement the ListReady event handler.
' The connected provider part(s) will call this method during its
' PartCommunicationMain phase to pass their primary data to the
' consumer Web Part.
' <param name="sender">Reference to the provider Web Part</param>
' <param name="listReadyEventArgs">The args passed by the
' provider Web Part</param>
Public Sub ListReady(sender As Object, listReadyEventArgs As ListReadyEventArgs) _
Implements IListConsumer.ListReady
' Ensure that all of the Web Part's controls are created.
EnsureChildControls()
' Store the List that was passed by the provider Web Part.
If Not (listReadyEventArgs.List Is Nothing) Then
_dataGrid.DataSource = listReadyEventArgs.List
'Bind the data grid
_dataGrid.DataBind()
End If
End Sub
' Step #8: Implement the PartialListReady event handler.
' The connected provider part(s) will call this method during its
' PartCommunicationMain phase to pass partial amounts of their
' primary data to the consumer Web Part. This is useful in
' scenarios involving large datasets that need to be streamed.
' <param name="sender">Reference to the provider Web Part</param>
' <param name="partialListReadyEventArgs">The args passed by the
' provider Web Part</param>
Public Sub PartialListReady(sender As Object, partialListReadyEventArgs As PartialListReadyEventArgs) _
Implements IListConsumer.PartialListReady
End Sub
' Because this class implements the IListConsumer interface, it
' must implement the interface member PartialListReady. However,
' this example doesn't use any data that may be passed in here.
Protected Overrides Sub RenderWebPart(output As HtmlTextWriter)
' Check for connection interface registration error
If _registrationErrorOccurred Then
output.Write(_registrationErrorMsg)
Return
End If
' Ensure that all of the Web Part's controls are created.
EnsureChildControls()
' Check if connected.
If _connected Then
If Not (_dataGrid.DataSource Is Nothing) Then
' Line break.
output.RenderBeginTag(HtmlTextWriterTag.Br)
output.RenderEndTag()
' Render the DataGrid control.
_dataGrid.RenderControl(output)
' Line break.
output.RenderBeginTag(HtmlTextWriterTag.Br)
output.RenderEndTag()
End If
' Render connected Web Part title.
output.Write((_connectedWebPartLabel + ": "))
output.RenderBeginTag(HtmlTextWriterTag.I)
output.Write(_connectedWebPartTitle)
output.RenderEndTag()
output.Write("<br>")
Else
' The Web Part isn't connected.
output.Write(_notConnectedMsg)
End If
End Sub
' Create Web Part user interface controls.
Protected Overrides Sub CreateChildControls()
' Create the DataGrid
_dataGrid = New DataGrid()
_dataGrid.ID = "DataGrid"
' Format DataGrid.
_dataGrid.HeaderStyle.Font.Bold = True
_dataGrid.HeaderStyle.ForeColor = Color.DarkBlue
End Sub
End Class
End Namespace
// Common .NET required namespaces
using System;
using System.ComponentModel;
using System.Web.UI;
// Web Part required namespaces
using Microsoft.SharePoint.WebPartPages;
using System.Xml.Serialization;
using System.Web.UI.WebControls;
// Code Access Security namespaces
using System.Security;
using Microsoft.SharePoint.Utilities;
// DataGrid and user interface namespaces
using System.Data;
using System.Drawing;
//Step #1: Make a Reference to the Communication namespace.
using Microsoft.SharePoint.WebPartPages.Communication;
namespace ConnectionCodeSamples
{
//Step #2: Inherit from the WebPart base class and implement the
//IListConsumer interface.
public class ServerSideListConsumer : WebPart, IListConsumer
{
// Declare variables for keeping track of connection state.
private bool _connected = false;
private string _connectedWebPartTitle = string.Empty;
private string _registrationErrorMsg = "An error has occurred trying to register your connection interfaces.";
private bool _registrationErrorOccurred = false;
private string _notConnectedMsg = "NOT CONNECTED. To use this Web Part connect it to a List Provider Web Part.";
// Declare variables for Web Part user interface.
private string _connectedWebPartLabel = "Connected to Web Part";
private DataGrid _dataGrid;
// Step #3: Override EnsureInterfaces method and call
// RegisterInterface method.
// EnsureInterfaces() is called by the Web Part infrastructure
// during the ASP.NET PreRender event
// and allows the part to register all of its connection
// interfaces.
public override void EnsureInterfaces()
{
// If your Web Part is installed in the bin directory and
// the Code Access Security (CAS) setting doesn't
// allow Web Part Connections, an exception will be thrown.
// To allow your Web Part to behave
// well and continue working, a try/catch block should be
// used when attempting to register interfaces.
// Web Part Connections will only work if the level
// attribute of the <trust> tag in the
// web.config file is set to WSS_Minimal, WSS_Medium, or
// Full. By default a new SharePoint site
// is installed with the trust level set to WSS_Minimal.
try
{
// Register the IListConsumer interface
// <param name="interfaceName">Friendly name of the
// interface that is being implemented.</param>
// <param name="interfaceType">Specifies which
// interface is being implemented.</param>
// <param name="maxConnections">Defines how many times
// this interface can be connected.</param>
// <param name="runAtOptions">Determines where the
// interface can run.</param>
// <param name="interfaceObject">Reference to the
// object that is implementing this interface.</param>
// <param name="interfaceClientReference">Name used to
// reference the interface on the client.
// This is a server side example so the value is set to
// empty string.</param>
// <param name="menuLabel">Label for the interface
// that appears in the UI</param>
// <param name="description">Description of the
// interface that appears in the UI</param>
// <param name="allowCrossPageConnection">Specifies if
// the interface can connect to a Web Part
// on a different page. This is an optional parameter
// with a default of false. Note that only some
// server side interfaces are allowed to connect across
// pages by the Web Part infrastructure.
// The IListConsumer interface is not allowed to
// connect across pages.</param>
RegisterInterface("MyListConsumerInterface", //InterfaceName
InterfaceTypes.IListConsumer, //InterfaceType
WebPart.LimitOneConnection, //MaxConnections
ConnectionRunAt.Server, //RunAtOptions
this, //InterfaceObject
"", //InterfaceClientReference
"Consume List From", //MenuLabel
"Consumes a list from another Web Part."); //Description
}
catch(SecurityException se)
{
_registrationErrorOccurred = true;
}
}
// Step #4: Override the CanRunAt method.
// The CanRunAt method is called by the Web Part infrastructure
// during the ASP.NET PreRender event
// to determine where the Web Part can run based on its current
// configuration.
public override ConnectionRunAt CanRunAt()
{
// This Web Part can run on the server.
return ConnectionRunAt.Server;
}
// Step #5: Override the PartCommunicationConnect method.
// PartCommunicationConnect() is called by the Web Part
// infrastructure to notify the Web Part that it
// is connected during the ASP.NET PreRender event. Relevant
// information is passed to the part such as
// the interface it is connected over, the Web Part it is being
// connected to, and where the part will be running,
// either client or server side.
// <param name="interfaceName">Friendly name of the interface
// that is being connected</param>
// <param name="connectedPart">Reference to the other Web Part
// that is being connected to</param>
// <param name="connectedInterfaceName">Friendly name of the
// interface on the other Web Part</param>
// <param name="runAt">Where the interface should
// execute</param>
public override void PartCommunicationConnect(string interfaceName,
WebPart connectedPart,
string connectedInterfaceName,
ConnectionRunAt runAt)
{
// Keep track of connection state.
if (interfaceName == "MyListConsumerInterface")
{
_connected = true;
_connectedWebPartTitle = SPEncode.HtmlEncode(connectedPart.Title);
}
}
// Step #6: Implement the ListProviderInit event handler.
// The connected provider part(s) will call this method during
// its PartCommunicationInit phase
// to pass initialization information to the consumer Web Part.
// <param name="sender">Reference to the Consumer Web
// Part</param>
// <param name="listProviderInitEventArgs">The args passed by
// the provider Web Part</param>
public void ListProviderInit(object sender, ListProviderInitEventArgs listProviderInitEventArgs)
{
// Because this class implements the IListConsumer
// interface, it must implement the interface member
// ListProviderInit. However, this example
// doesn't use any initialization data that is passed in
// here.
}
// Step #7: Implement the ListReady event handler.
// The connected provider part(s) will call this method during
// its PartCommunicationMain phase
// to pass their primary data to the consumer Web Part.
// <param name="sender">Reference to the provider Web
// Part</param>
// <param name="listReadyEventArgs">The args passed by the provider Web Part</param>
public void ListReady(object sender, ListReadyEventArgs listReadyEventArgs)
{
// Ensure that all of the Web Part's controls are created.
EnsureChildControls();
// Store the List that was passed by the provider Web Part.
if(listReadyEventArgs.List != null)
{
_dataGrid.DataSource = listReadyEventArgs.List;
//Bind the data grid
_dataGrid.DataBind();
}
}
// Step #8: Implement the PartialListReady event handler.
// The connected provider part(s) will call this method during
// its PartCommunicationMain phase to pass partial amounts of
// their primary data to the consumer Web Part. This is useful
// in scenarios involving large datasets that need to be
// streamed.
// <param name="sender">Reference to the provider Web
// Part</param>
// <param name="partialListReadyEventArgs">The args passed by
// the provider Web Part</param>
public void PartialListReady(object sender, PartialListReadyEventArgs partialListReadyEventArgs)
{
// Because this class implements the IListConsumer
// interface, it must implement the interface member
// PartialListReady. However, this example
// doesn't use any data that may be passed in here.
}
protected override void RenderWebPart(HtmlTextWriter output)
{
// Check for connection interface registration error
if (_registrationErrorOccurred)
{
output.Write(_registrationErrorMsg);
return;
}
// Ensure that all of the Web Part's controls are created.
EnsureChildControls();
// Check if connected.
if(_connected)
{
if (_dataGrid.DataSource != null)
{
// Line break.
output.RenderBeginTag(HtmlTextWriterTag.Br);
output.RenderEndTag();
// Render the DataGrid control.
_dataGrid.RenderControl(output);
// Line break.
output.RenderBeginTag(HtmlTextWriterTag.Br);
output.RenderEndTag();
}
// Render connected Web Part title.
output.Write(_connectedWebPartLabel + ": ");
output.RenderBeginTag(HtmlTextWriterTag.I);
output.Write(_connectedWebPartTitle);
output.RenderEndTag();
output.Write("<br>");
}
else
{
// The Web Part isn't connected.
output.Write(_notConnectedMsg);
}
}
// Create Web Part user interface controls.
protected override void CreateChildControls()
{
// Create the DataGrid
_dataGrid = new DataGrid();
_dataGrid.ID = "DataGrid";
// Format DataGrid.
_dataGrid.HeaderStyle.Font.Bold = true;
_dataGrid.HeaderStyle.ForeColor = Color.DarkBlue;
}
}
}