Filter Web Parts Overview

Filter Web Parts can be very useful in data-rich business intelligence sites. They provide a user interface (usually, and can be hidden) that allows the user to provide search or filter criteria for a query on data such as a database table or a list. When you connect a filter Web Part to one or more Web Parts on the page that have filtering capability, they display filtered results of the query.

Benefits of Filter Web Parts

Filter Web Parts offer advantages to users and developers. By using filters, users can find new and meaningful ways to view their data. Suppose you build an application in which a Web Part contacts a Web service, returns historical records of average daily temperatures for all states in the United States, and lists the data in tabular form. If a user wants the flexibility to view the data based on a set of states or just a particular state, he or she can connect the Web Part to a filter Web Part that can enable the user to choose different states at run time and see different results.

By using filters, developers can discover new opportunities for code reuse and for combining the functionality of isolated Web Parts. Suppose a developer creates a Web Part 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 Web Parts that depend on a specific postal code, such as Web Parts to display weather information and news headlines in the user's area, as well as a Web Part that looks up businesses by category within a given postal code. Rather than design each new Web Part with the same feature of saving a postal code, the developer could design each Web Part to require the input of a postal code. Then the developer could simply connect the Web Part that already provides the postal code to the weather, news, and business listing Web Parts that take a postal code as an input. Each connection extends the usefulness of the original Web Part and eliminates redundancy in the code of the new Web Parts.

Implementing and Consuming Filter Web Parts

Windows SharePoint Services 3.0 uses the ASP.NET Web Part connection framework to pass the filter criteria from one Web Part to other Web Parts before the query is run. ASP.NET Web Part connections are based on the notion of providers and consumers. A provider Web Part supplies information to one or more consumer Web Parts through a programmatic interface. The provider exposes some data through a well-defined interface, which the consumer knows how to use. A Filter Web Part is just a special provider that provides filter values that other Web Parts can use to filter data.

ASP.NET provides an integrated set of connection components, 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 Web Parts to form connections. Windows SharePoint Services makes use of the connection framework and provides additional interfaces called IFilterValues and IItransformableFilterValues to make it even easier to create Web Part connections for filtering scenarios.

With Filter Web Parts, you can create dynamic, programmatic connections between Web Parts at run time, as well as static, predefined connections declared in the markup of a Web page. Windows SharePoint Services also provides users with a user interface (UI) that enables users to connect or disconnect Web Parts at run time.

Web Parts connections are based on a "pull" model of connectivity, where the consumer Web Part gets data from the provider Web Part. To create a connection, a Web Part acting as a data provider defines a communication contract indicating the data it can provide. Another Web Part, 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 Part base class 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 for creating filter providers, 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, make sure that it doesn't take any input parameters and it returns the ITransformableFilterValues interface instance containing the filter data to pass to the consumer. The interface instance can be simple (for example, a single property that contains a string value such as a postal code).

The ITransformableFilterValues interface provides a means of specifying filter capabilities such as multiselect, and support for ALL or Null values. This interface also enables Windows SharePoint Services 3.0 to internally use interface transformers that allow different interface types to communicate with each other.

The consumer's callback method retrieves the instance of the IFilterValues 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 Web Part cycle, so you should plan to process the data and update any logic in the consumer after prerendering is complete.

Additionally, because parameter names need not always map to each other in the provider and consumer, Windows SharePoint Services provides a ConsumerParameters interface that the consumer should provide with the parameter names to the provider.

What Happens at Run Time

At run time, Web Part connections are managed by the WebPartManager, as follows:

1. For each registered provider, the WebPartManager calls its provider connection point method.

2. The provider part returns an instance of the communication interface.

3. For each consumer registered for this provider, the WebPartManager calls its consumer connection point method, passing an instance of the interface.

4. The consumer part calls properties and methods on the interface instance.

Out-of-the-Box Filter Web Parts

Office SharePoint Server 2007 provides the following filters in the Web Part gallery, by default:

• Analysis Services Filter

• Authored List Filter

• Business Data Catalog Filter

• Current User Filter

• Date Filter

• Page Field Filter

• Query String (URL) Filter

• SharePoint List Filter

• Text Filter

• UserProfile Filter

You can consume any of these filters in your custom Web Parts. For more information, see Walkthrough: Writing a Simple Filter Consumer Web Part.

See Also

Other Resources

Walkthrough: Writing a Simple Filter Consumer Web Part Sample
How to: Write a Region CheckBox Filter
How to: Write a Headlines Consumer Web Part