WebPart.Connections Property

  • Article

Gets or sets the connection information that is stored with a connected Web Part.

Namespace:  Microsoft.SharePoint.WebPartPages
Assembly:  Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Available in Sandboxed Solutions: No

Syntax

'Declaration
<WebPartStorageAttribute(Storage := Storage.Shared)> _
<BrowsableAttribute(False)> _
Public Property Connections As String
    Get
    Set
'Usage
Dim instance As WebPart
Dim value As String

value = instance.Connections

instance.Connections = value

[WebPartStorageAttribute(Storage = Storage.Shared)]
[BrowsableAttribute(false)]
public string Connections { get; set; }

Property Value

Type: System.String
A string value that specifies connection information. The default value is String.Empty for an unconnected Web Part.

Remarks

The string that specifies the Connections property has the following format for each connection stored with a Web Part.

ConsumerPartID,ProviderPartID,ConsumerInterfaceName,ProviderInterfaceName,ConsumerIntefaceGroupName,ProviderIntefaceGroupName, XformInfo,CrossPageConnectionID,CrossPageURL,CrossPageInitEventArgs

This format is repeated for each connection stored with a Web Part with each connection separated by semicolons (;). There should be no semicolon after the last connection stored.

The following table describes each of the parts of the Connections property string.

Name

Description

ConsumerPartID

The ConnectionID of the consumer Web Part.

ProviderPartID

The ConnectionID of the provider Web Part. However, if the user is in personalization mode when the connection is created, and the provider Web Part is a shared part that does not already have a ConnectionID, the Web Part infrastructure will use the webPartID property to identify the Web Part instead. This is because the ConnectionID cannot be assigned and saved when a Web Part is in personalization mode.

ConsumerInterfaceName

The interfaceName of the consumer Web Part (as defined by the RegisterInterface method of the connection interface). It will be a string such as:

myRowConsumer_WPQ_.

ProviderInterfaceName

The interfaceName of the provider Web Part (as defined by the RegisterInterface method of the connection interface). It will be a string such as:

myRowProvider_WPQ_.

ConsumerInterfaceGroupName

The interfaceName of the consumer Web Part. This setting is identical to that of the ConsumerInterfaceName parameter.

ProviderInterfaceGroupName

The interfaceName of the provider Web Part. This setting is identical to that of the ProviderInterfaceName parameter.

XFormInfo

(Optional) A string in which a transformer can save any disambiguation information it needs to perform its logic during run time. The following definitions and examples are for the transformers provided with the Web Part infrastructure.

  • IRowProvider to ICellConsumer

    A single string value that corresponds to the column name for the data that will be sent from the IRowProvider to the ICellConsumer in the form IRowProviderColumnName. The following example shows the string for an IRowProvider specifying a column named First Name.

    First%20Name

  • IRowProvider to IFilterConsumer

    A pair of strings corresponding to the two column names that will be matched for filtering in the form: IFilterConsumerColumn = IRowProviderColumn. The following example shows the string for an IFilterConsumer specifying a filter on the column named Surname using a column named Last Name provided by an IRowProvider.

    Surname=Last%20Name

  • IRowProvider to IParametersInConsumer

    A set of matching pairs of columns that display the same data in the form: (IRowProviderColumn = IParametersInConsumerPropertyName ).

    (First%20Name=FName)(Last%20Name=LName)(Phone%20Number=Phone)(Company=Co)

  • IParametersOutProvider to IParametersInConsumer

    A set of matching pairs of columns that display the same data in the form: (IParametersOutProviderPropertyName = IParametersInConsumerPropertyName )...

    (First=FName)(Last=LName)(Number=Phone)(Employer=Co)

CrossPageConnectionID

(Optional) For a cross-page connection, this is the unique identifier of the connection on the other page to which the Web Part is being connected. The crosspageconnectionid parameter is a Guid and must be unique on both pages. The authoring tool should generate this ID.

CrossPageURL

(Optional) For a cross-page connection, this is the URL of the page to which the Web Part is connected.

CrossPageInitEventArgs

(Optional) For a cross-page connection, this is the InitEventArgs structure of the interface on the other page to which the Web Part is being connected formatted as an XML fragment. The following is an example of an IFilterConsumerInitEventArgs structure formatted for the CrossPageInitEventArgs parameter.

<FilterConsumerInitEventArgs>><Field FieldName="First Name" FieldDisplayName="First Name"/><Field FieldName="Surname" FieldDisplayName="Sur Name"/><Field FieldName="Phone" FieldDisplayName="Phone Number"/><Field FieldName="Company" FieldDisplayName="Company"/></FilterConsumerInitEventArgs>

The following is an example of an IParametersInConsumerInitEventArgs structure formatted for the CrossPageInitEventArgs parameter.

<ParametersInConsumerInitEventArgs><Parameter ParameterName="LName" ParameterDisplayName="Last Name" Required="True" Description="Last Name of an employee."><Parameter ParameterName="FName" ParameterDisplayName="First Name" Required="True" Description="First Name of an employee."><Parameter ParameterName="Co" ParameterDisplayName="Company" Required="False" Description="Company the employee previously worked for."><Parameter ParameterName="Phone" ParameterDisplayName="Business Phone" Required="False" Description="Business Phone Number of an employee."></ParametersInConsumerInitEventArgs>

A comma is used to delimit individual parameters of a connection. A semicolon is used to delimit entire connections. White space is not allowed before or after delimiters. If a comma, semicolon, or percent sign are used within any of the parameters, the Web Part infrastructure encodes the delimiter as shown in the following table.

Delimiter

Encoding

,

%2C

;

%3B

%

%25

The value of the Connections property is stored on only one side (Web Part) of a connection unless it is a cross-page connection. For cross-page connections, the connection is stored with both sides of a connection. By default, the Web Part infrastructure stores the value of the Connections property with the consumer Web Part although the infrastructure will support storing a connection on the provider side for static Web Parts (a Web Part outside of a WebPartZone control) and for cross-page connections.

This property cannot be personalized by individual users. The value of its WebPartStorageAttribute is Storage.Shared, which specifies that the property is stored with the same value for all users. Only users with the Write web pages right can set this property. It can be set only programmatically.

Examples

The following is an example of a Connections property setting for a direct connection between ICellProvider and ICellConsumer Web Parts on the same Web Part page.

f690a578-6d1b-4d04-b081-011a93fa23bf,332f8676-875b-44eb-a537-8f946edb7e5f,MyCellConsumer_WPQ_,MyCellProvider_WPQ_,MyCellConsumer_WPQ_,MyCellProvider_WPQ_

The following is an example of Connections property settings for both sides of a cross-page connection between an IFilterConsumer Web Part and an IRowProvider Web Part using a transformer.

The Connection property setting for the Web Part on the source page (source ASPX) follows:

a93e4d5a-835b-4a80-80c0-a0e23149ed03,69c42cf9-e98b-4f6e-954a-42c7b46ba32e,MyFilterConsumerInterface_WPQ_,RowProviderInterface,MyFilterConsumerInterface_WPQ_,RowProviderInterface,Surname=Last%20Name,0e194b89-eaf0-4fcb-93f9-fe6c0a7a88d1,target.aspx,<FilterConsumerInitEventArgs>><Field FieldName="First Name" /><Field FieldName="Surname" /><Field FieldName="Phone" /><Field FieldName="Company" /></FilterConsumerInitEventArgs>

The Connection property setting for Web Part on the target page (target ASPX) follows:

a93e4d5a-835b-4a80-80c0-a0e23149ed03,69c42cf9-e98b-4f6e-954a-42c7b46ba32e,MyFilterConsumerInterface_WPQ_,RowProviderInterface,MyFilterConsumerInterface_WPQ_,RowProviderInterface,,0e194b89-eaf0-4fcb-93f9-fe6c0a7a88d1,source.aspx,

See Also

Reference

WebPart Class

WebPart Members

Microsoft.SharePoint.WebPartPages Namespace