Share via


IRowConsumer interface

NOTE: This API is now obsolete.

Enables a Web Part to communicate with a Web Part that implements the IRowProvider interface (or that supports a suitable transformer) to work with a row of data.

Namespace:  Microsoft.SharePoint.WebPartPages.Communication
Assembly:  Microsoft.SharePoint (in Microsoft.SharePoint.dll)

Syntax

'Declaration
<ObsoleteAttribute("Use System.Web.UI.WebControls.WebParts.IWebPartRow instead")> _
Public Interface IRowConsumer
'Usage
Dim instance As IRowConsumer
[ObsoleteAttribute("Use System.Web.UI.WebControls.WebParts.IWebPartRow instead")]
public interface IRowConsumer

Remarks

The IRowConsumer interface should be implemented in Web Parts that need to consume a collection of data that can be characterized as a row, such as a row in a table. The IRowConsumer interface has the ability to receive initialization arguments from the provider Web Part. When connecting a Web Part that implements the IRowConsumer interface to a IRowProvider Web Part, the connection is direct, so no transformer dialog box will be displayed. To use the passed values appropriately, the consuming Web Part may need to be designed with an understanding of the schema of the data being sent by the provider Web Part.

Examples

The following code example shows a simple Web Part that implements the IRowConsumer interface and supports running its connection implementation only on the server. It can be connected to another Web Part that implements the IRowProvider interface on the server. Its user interface displays the row of values received from the IRowProvider Web Part.

There are seven steps specific to making this a connectable Web Part. These steps are numbered and commented in the following code sample.

' 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

' DataRow namespace
Imports System.Data

'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 IRowConsumer interface.
   
   Public Class ServerSideRowConsumer
      Inherits WebPart
      Implements IRowConsumer
      
      ' 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 Row Provider Web Part."
      Private _selectRowMsg As String = "Please select a row from the connected Row Provider Web Part."
      
      ' Declare variables for Web Part user interface.
      Private _connectedWebPartLabel As String = "Connected to Web Part"
      Private _selectionStatus As String = String.Empty
      
      ' Declare variables for row information.
      Private _rowFieldDisplayNames() As String
      Private _rowFieldValues(0) As DataRow
      
      ' Step #3: Override the EnsureInterfaces() method and call the 
      ' RegisterInterface method.
      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 IRowConsumer 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 IRowConsumer interface is not allowed to connect 
            ' across pages.</param>
            RegisterInterface("MyRowConsumerInterface", InterfaceTypes.IRowConsumer, WebPart.LimitOneConnection, ConnectionRunAt.Server, Me, "", "Consume Row From", "Consumes a single row from another Web Part.") 
         
         Catch se As SecurityException
            _registrationErrorOccurred = True
         End Try
      End Sub
      
      ' Step #4: Override the CanRunAt() method.
      ' CanRunAt() 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 the connection state.
         If interfaceName = "MyRowConsumerInterface" Then
            _connected = True
            _connectedWebPartTitle = SPEncode.HtmlEncode(connectedPart.Title)
         End If
      End Sub
      
      ' Step #6: Implement the RowProviderInit 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="rowProviderInitEventArgs">The args passed by the 
      ' provider Web Part</param>
      Public Sub RowProviderInit(sender As Object, rowProviderInitEventArgs As RowProviderInitEventArgs) _
         Implements IRowConsumer.RowProviderInit
         ' Store the field list
         _rowFieldDisplayNames = rowProviderInitEventArgs.FieldDisplayList
      End Sub
       
      ' Step #7: Implement the RowReady 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="rowReadyEventArgs">The args passed by the provider 
      ' Web Part</param>
      Public Sub RowReady(sender As Object, rowReadyEventArgs As RowReadyEventArgs) _
         Implements IRowConsumer.RowReady
         ' Store the row values.
         If Not (rowReadyEventArgs.Rows Is Nothing) Then
            If Not (rowReadyEventArgs.Rows(0) Is Nothing) Then
               _rowFieldValues(0) = rowReadyEventArgs.Rows(0)
            End If
         End If
         _selectionStatus = rowReadyEventArgs.SelectionStatus
      End Sub
      
      ' Render the Web Part.
      Protected Overrides Sub RenderWebPart(output As HtmlTextWriter)
         ' Check for connection interface registration error.
         If _registrationErrorOccurred Then
            output.Write(_registrationErrorMsg)
            Return
         End If
         
         ' Check if connected.
         If _connected Then
            Dim index As Integer = 0
            Dim fieldName As String
            
            ' Check if a row has been selected.
            If _selectionStatus = "Standard" Then
               ' Generate results table from received row.
               output.RenderBeginTag(HtmlTextWriterTag.Table)
               For index = 0 To _rowFieldDisplayNames.Length - 1
                  fieldName = _rowFieldDisplayNames(index)
                  
                  output.RenderBeginTag(HtmlTextWriterTag.Tr)
                  output.RenderBeginTag(HtmlTextWriterTag.Td)
                  output.RenderBeginTag(HtmlTextWriterTag.B)
                  output.Write((fieldName + ": "))
                  output.RenderEndTag() 'End <B>
                  output.RenderEndTag() 'End <TD>
                  output.RenderBeginTag(HtmlTextWriterTag.Td)
                  output.Write(_rowFieldValues(0)(fieldName).ToString())
                  output.RenderEndTag() 'End <TD>
                  output.RenderEndTag() 'End <TR>
               Next index
               output.RenderEndTag() 'End <Table>
            Else
               output.RenderBeginTag(HtmlTextWriterTag.B)
               output.Write(_selectRowMsg)
               output.RenderEndTag()
            End If
            
            ' Line break.
            output.RenderBeginTag(HtmlTextWriterTag.Br)
            output.RenderEndTag()
            
            ' Render the 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
   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;

// DataRow namespace
using System.Data;

//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 IRowConsumer interface.
    public class ServerSideRowConsumer : WebPart, IRowConsumer
    {    

        // 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 Row Provider Web Part.";
        private string _selectRowMsg = "Please select a row from the connected Row Provider Web Part.";

        // Declare variables for Web Part user interface.
        private string _connectedWebPartLabel = "Connected to Web Part";
        private string _selectionStatus = string.Empty;

        // Declare variables for row information.
        private string[] _rowFieldDisplayNames;
        DataRow[] _rowFieldValues = new DataRow[1];

        // Step #3: Override the EnsureInterfaces() method and call the 
        // RegisterInterface method.
        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 IRowConsumer 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 
                // which appears in the UI</param>
                // <param name="description">Description of the 
                // interface which 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 IRowConsumer interface is not allowed to connect 
                // across pages.</param>
                RegisterInterface("MyRowConsumerInterface",                 //InterfaceName    
                    InterfaceTypes.IRowConsumer,                            //InterfaceType
                    WebPart.LimitOneConnection,                             //MaxConnections
                    ConnectionRunAt.Server,                                 //RunAtOptions
                    this,                                                   //InterfaceObject
                    "",                                                     //InterfaceClientReference
                    "Consume Row From",                                     //MenuLabel
                    "Consumes a single row from another Web Part.");        //Description
            }
            catch(SecurityException se)
            {
                _registrationErrorOccurred = true;
            }
        }


        // Step #4: Override the CanRunAt() method.
        // CanRunAt() 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 the connection state.
            if (interfaceName == "MyRowConsumerInterface")
            {
                _connected = true;
                _connectedWebPartTitle = SPEncode.HtmlEncode(connectedPart.Title);
            }
        }

        // Step #6: Implement the RowProviderInit 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="rowProviderInitEventArgs">The args passed by 
        // the provider Web Part</param>
        public void RowProviderInit(object sender, RowProviderInitEventArgs rowProviderInitEventArgs)
        {
            // Store the field list
            _rowFieldDisplayNames = rowProviderInitEventArgs.FieldDisplayList;

        }

        // Step #7: Implement the RowReady 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="rowReadyEventArgs">The args passed by the 
        // provider Web Part</param>
        public void RowReady(object sender, RowReadyEventArgs rowReadyEventArgs)
        {
            // Store the row values.
            if(rowReadyEventArgs.Rows!= null)
            {
               if(rowReadyEventArgs.Rows[0]!= null)
               {
                  _rowFieldValues[0] = rowReadyEventArgs.Rows[0];
                }
            }

            _selectionStatus = rowReadyEventArgs.SelectionStatus;
        }

        // Render the Web Part.
        protected override void RenderWebPart(HtmlTextWriter output)
        {
            // Check for connection interface registration error.
            if (_registrationErrorOccurred)
            {
                output.Write(_registrationErrorMsg);
                return;
            }

            // Check if connected.
            if(_connected)
            {
                int index = 0;
                string fieldName;

                // Check if a row has been selected.
                if (_selectionStatus == "Standard")
                {
                    // Generate results table from received row.
                    output.RenderBeginTag(HtmlTextWriterTag.Table);
                    for (index = 0; index < _rowFieldDisplayNames.Length; index++)
                    {
                        fieldName = _rowFieldDisplayNames[index];
                    
                        output.RenderBeginTag(HtmlTextWriterTag.Tr);
                        output.RenderBeginTag(HtmlTextWriterTag.Td);
                        output.RenderBeginTag(HtmlTextWriterTag.B);
                        output.Write(fieldName + ": ");
                        output.RenderEndTag(); //End <B>
                        output.RenderEndTag(); //End <TD>

                        output.RenderBeginTag(HtmlTextWriterTag.Td);
                        output.Write(_rowFieldValues[0][fieldName].ToString());
                        output.RenderEndTag(); //End <TD>
                        output.RenderEndTag(); //End <TR>
                    }
                    output.RenderEndTag(); //End <Table>
                }
                else
                {
                    output.RenderBeginTag(HtmlTextWriterTag.B);
                    output.Write(_selectRowMsg);
                    output.RenderEndTag();
                }


                // Line break.
                output.RenderBeginTag(HtmlTextWriterTag.Br);
                output.RenderEndTag();

                // Render the 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);
            }
        }
    }
}

See also

Reference

IRowConsumer members

Microsoft.SharePoint.WebPartPages.Communication namespace