Web Parts Connections Overview

The Web Parts control set enables you to create connections between server controls, so that the total value and usefulness of the connected controls exceeds that of the individual, unconnected controls. A complete, integrated set of connection components is provided, so that with a minimal number of steps, a few lines of code, and no need to handle all the underlying complexity and synchronization of data, you can equip existing WebPart (or server or user) controls to form connections. With controls that are enabled for connections, you can create dynamic, programmatic connections between the controls at run time, as well as static, predefined connections declared in the markup of a Web page. You can also provide users with a user interface (UI) that enables them to connect or disconnect controls at run time, and to manage existing connections.

Connections offer advantages to users and developers. By using connections, users can find new and meaningful ways to view their data. Suppose you build an application in which a server control contacts a Web service, returns historical records of average daily temperatures for a state, and lists the data in tabular form. If a user wants the flexibility to view that data in different ways, the server control could be connected to a charting control that can consume tabular data and display it in various chart views. The user could even be given the option of whether to display the data in a table or connect the temperature data to the charting control. With new views of the data, users might notice new trends and relationships in temperatures that were harder to visualize with the data in tabular form.

By using connections, developers can discover new opportunities for code reuse and for combining the functionality of isolated controls. Suppose a developer creates a control that saves address information for the user, including a postal code, and makes this information always available to fill in the shipping address form when the user orders something. Then the developer adds other controls that depend on a specific postal code, such as controls to display weather information and news headlines in the user's area, as well as a control that looks up businesses by category within a given postal code. Rather than design each new control with the same feature of saving a postal code, the developer could design each control to require the input of a postal code. Then the developer could simply connect the control that already saves the postal code to the weather, news, and business listing controls that take a postal code as an input. Each connection extends the usefulness of the original control and eliminates redundancy in the code of the new controls.

Connections Concepts

A Web Parts connection is a link or association between two server controls that enables them to share data. A connection always involves exactly two controls: one is the provider of data, and the other is the consumer of the data from the provider. A control can be both a consumer and a provider, and any type of server control, whether a WebPart control, a custom control, or a user control, can be designed to participate in connections. A provider control by default can establish connections with multiple consumers at the same time (like the previous example of a postal code control that provides a postal code to a weather information control, a news headline control, and a business listing control). A consumer control by default can connect to only one provider at a time.

Connections always take place in the context of a Web Parts application, which means that at a minimum, besides the two server controls participating in the connection, two additional controls are required on the Web page. One of them is the WebPartManager control, which is present on every page that contains Web Parts controls. The second required control is a zone that inherits from the WebPartZoneBase class, such as the WebPartZone control. Any two server controls, in order to form a connection, must reside within a WebPartZoneBase type of zone.

In a connection relationship, the consumer and the provider each have at least one associated object called a connection point. Based on the ConnectionPoint class, a connection point contains the details necessary for a server control to connect to another control, such as the type of the control itself, the type of data the control recognizes, an ID for the connection point object, and whether the control can form multiple connections. A server control can have multiple connection points. A provider's connection points are defined by instances of the ProviderConnectionPoint class, and the consumer's are defined by instances of the ConsumerConnectionPoint class.

To form a connection, the consumer and provider must both recognize the same type of data, which in Web Parts connections is passed by means of an interface instance. The type of data that a control recognizes is specified in the control's associated connection point, in the InterfaceType property. If the provider and consumer recognize the same type of data, they are compatible. If a provider and consumer are incompatible, a developer must use a special transformer object to translate the provider's data into a form the consumer can work with. This transformer object inherits from the base WebPartTransformer class, and a developer can either inherit from the base class to develop a custom transformer, or use one of the provided transformer objects (RowToFieldTransformer or RowToParametersTransformer).

After a connection has been created, it is contained in a WebPartConnection object. The connection object encapsulates all the details about a connection, including references to its consumer and provider objects, the IDs of the consumer and provider, references to any connection points and their IDs, references to any transformers associated with the connection, and details about the state of the connection, such as whether it is active and whether it is static or dynamic.

You can provide users with a way to create and manage connections by using the ConnectionsZone control. You can declare an <asp:connectionszone> element on a Web page, which provides users with a run-time UI that allows them to connect or disconnect controls, and to configure certain connection details.

How Connections Work

Web Parts connections are based on a "pull" model of connectivity, where the consumer gets data from the provider. To create a connection, a control acting as a data provider defines a communication contract indicating the data it can provide. Another control, acting as the consumer and with knowledge of the communication contract, retrieves that data.

The mechanism for establishing a connection is a special callback method: one in the consumer and one in the provider. However, the Web Parts control set handles all the callback and communication details, so the steps required of developers are minimal. As a developer, if you want to use the simplest approach, all you have to do is select a method in the provider to use as the callback method, and mark it in the source code with a ConnectionProvider attribute. Then within that method, return the interface instance containing the data to pass to the consumer. The interface instance can be very simple (for example, a single property that contains a string value such as a postal code). A provider can implement one of the provided interfaces (IWebPartField, IWebPartRow, or IWebPartTable), but in most cases it is preferable to create a simple, custom interface with one or more properties or methods containing the data you want to share with a consumer, and implement that interface in the provider. The consumer's callback method retrieves the instance of the interface from the provider. Again, all that is required of a developer is to identify which method in the consumer (using a ConnectionConsumer attribute) will retrieve the interface instance, and assign it to some internal variable for processing and rendering. Note that the data from the provider is passed during the prerendering phase of the page and control cycle, so you should plan to process the data and update any logic in the consumer after prerendering is complete.

Note
As mentioned previously, the consumer and provider must be compatible with regard to the interface type, or else they must use a WebPartTransformer object to establish the connection.

The pipelines through which data is exchanged are the connection points for the consumer and provider. You can create a connection point for a control in several ways. As mentioned in the preceding paragraph, you can use the ConnectionConsumerAttribute or ConnectionProviderAttribute classes, which each create a connection point for you. In this approach, you can add a ConnectionConsumer attribute to the consumer's callback method in the source code, and similarly add a ConnectionProvider attribute to the provider's callback method. This identifies the respective callback methods, and allows you to specify some details about the connection point, such as an ID and a display name (which appears in the UI for users to form connections). As another alternative, you can create a custom connection point by inheriting from ConnectionPoint, or you can use or inherit from the ConsumerConnectionPoint or ProviderConnectionPoint classes. As noted previously, a control acting as either a consumer or a provider can have multiple connection points.

A connection between controls can be either static or dynamic. Static connections are coded declaratively in the hosting page and created during the prerendering phase of the page. This ensures that the connection is active when a user views the page. For an example, see How to: Declare a Static Connection between Two Web Parts Controls. Dynamic connections can be created either programmatically in the control's code or declaratively on the hosting page. If you declare two compatible server controls within a WebPartZoneBase zone on a Web page, and declare an instance of the ConnectionsZone control on the page, users can create and configure a dynamic connection between the controls at run time.

Web Part Connections and Other ASP.NET Features

Connections contrast in several ways with the other ASP.NET techniques for transferring information between controls in a Web application:

• Connections are a feature of Web Parts. You can only connect controls that are designed for Web Parts connections and that reside within a WebPartZoneBase zone.

  Note
  As noted previously, any ASP.NET server control, custom control, or user control can be used as a Web Parts control to take advantage of connections.

• Connections are different from data binding. Connections between controls in a Web Parts zone use an interface to create a contract between the controls. Data binding is a connection between a control and a storage device or back-end database. Web Parts connections move data only between controls on a page.

• Connections can be personalized. Connection settings that indicate which controls are connected can be safely stored with other personalization data. For more information on personalization, see Web Parts Personalization Overview.

Essential Connections Classes

The following table shows three components in the Web Parts control set that are essential to connections, and that you work with directly or indirectly whenever you use connections.

Web Parts control	Description
WebPartManager	Manages all connections between controls in the Web Parts zone on a page. One (and only one) WebPartManager control is required for every Web Parts page.
WebPartZoneBase WebPartZone	The WebPartZoneBase base class provides the required context in which server controls can connect and exchange data. You can inherit from the base class to create a custom zone, or use the WebPartZone control as the actual zone to contain the server controls involved in a connection.
WebPartConnection	Represents a connection, with references to the provider and consumer, and all the other required components of a connection.
ConnectionPoint ProviderConnectionPoint ConsumerConnectionPoint	The ConnectionPoint base class defines an object that is associated with a consumer or provider and contains the details necessary to exchange data. The ProviderConnectionPoint is associated with the provider, and the ConsumerConnectionPoint is associated with the consumer.
ConnectionsZone	Provides a UI that enables users to create run-time, dynamic connections between server controls.

See Also

Tasks

How to: Declare a Static Connection between Two Web Parts Controls

Reference

Web Parts Control Set Overview
WebPartConnection
ConnectionPoint

Concepts

ASP.NET Web Parts Overview