Microsoft Office SharePoint Server 2007 offers a number of filter webparts. These can be used to gather filtering options from a number of different sources. The filter value(s) selected by the users can be sent to other SharePoint webparts. This connection is supported through the normal webpart connections. The webpart that sends the filter values is called the provider. The webpart that receives and handles the values is called the consumer. Providers can normally send values to filter the consumer or to set the default value for the consumer. Examples of filter providers are:
- Business Data Catalog Filter
- Choice Filter
- Current User Filter
- SharePoint List Filter
Examples of filter consumers are:
- SharePoint ListView WebPart
- Excel Web Access
In this post I will show you how you can write your own provider and consumer.
Step 1 – Create the provider webpart
Our provider webpart is a very simple webpart that just show 4 checkboxes with 4 regions. When the user selects the checkboxes, the selected values are sent to the connected consumers. It exposes just 1 parameter called “Region”. When added to the page, our provider looks like this (page is in edit mode):
The first thing to do is create a new webpart that implements the ITransformableFilterValues interface (from the Microsoft.SharePoint.WebPartPages namespace):
public class FilterProvider :
System.Web.UI.WebControls.WebParts.WebPart,
ITransformableFilterValues
We add a private member to our class for the CheckBoxList and setup the control in CreateChildControls:
private CheckBoxList _regions;
protected override void CreateChildControls()
{ base.CreateChildControls();
_regions = new CheckBoxList();
_regions.Items.Add(new ListItem("North")); _regions.Items.Add(new ListItem("South")); _regions.Items.Add(new ListItem("West")); _regions.Items.Add(new ListItem("East")); _regions.AutoPostBack = true;
this.Controls.Add(_regions);
}
To implement the interface, we add these properties/methods:
public bool AllowEmptyValue
{ get { return false; } }
public bool AllowAllValue
{ get { return true; } }
public bool AllowMultipleValues
{ get { return true; } }
public string ParameterName
{ get { return "Region"; } }
public ReadOnlyCollection<string> ParameterValues
{ get
{ EnsureChildControls();
List<string> regions = new List<string>();
for (int i = 0; i < _regions.Items.Count; i++)
{ if (_regions.Items
.Selected)
{ regions.Add(_regions.Items.Value);
}
}
ReadOnlyCollection<string> result = new ReadOnlyCollection<string>(regions);
return result;
}
}
Our webpart does not support empty values (we don’t send values if nothing is selected). Our webpart supports the “All” value . The first two properties therefore return false. Because we have 4 checkboxes, we do support multiple values and therefore AllowMultipleValues returns true. These properties are important when the connection to the consumer is made. These options either show or hide connection parameters. The property ParameterName returns the name of the parameter that is used when the provider is connected to the consumer:
In our case this is “Region”. The last property ParameterValues returns the selected values as a readonly collection of strings. The last thing to do is create a new method in our webpart with the “ConnectionProvider” attribute. This makes the WebPartManager expose the connection to available consumers.
[ConnectionProvider(
"Region",
"UniqueIDForRegionConnection",
AllowsMultipleConnections = true)]
public ITransformableFilterValues SetConnection()
{ return this;
}
This attribute takes (in the overload I used) three parameters:
- The displayname. This is the name that you will see when setting up the connection:
I have set this to “Region”, as you can see in the screenshot above.
- ID – a unique id for the provider connection point
- Named Parameters – this allows you to set AllowsMultipleConnections. My providers can provider its values to multiple consumers, so I have set this to true.
Step 2 – Test the provider
After compiling the assembly and deploying the webpart, we are ready to test the provider. I have created a new document library called “MyDocs” and added a new multivalued Choice field called “DocumentRegion”. After that I added a ListView webpart and configured it to show the DocumentRegion field. After connection the 2 webparts, selecting one of the checkboxes will filter the list of documents:
Warning: although our provider supports and sends multiple values, the list view webpart seems not to handle this correctly.
Step 3 – Create the consumer webpart
Our provider is now ready to send filters to consumers and we will now create our own provider. This again is a very simple webpart that does nothing but render all values for incoming filters. Again we start to create a new webpart:
public class FilterConsumer :
System.Web.UI.WebControls.WebParts.WebPart
We create a private member to hold the incoming filter values (IFilterValues from the Microsoft.SharePoint.WebPartPages namespace). We also add a property for the and initialize it in the constructor:
private List<IFilterValues> _filterProviders;
private List<IFilterValues> FilterProviders
{ get { return _filterProviders; } }
public FilterConsumer()
{ _filterProviders = new List<IFilterValues>();
}
In this example I do not handle the incoming filters in a specific way, but just render the incoming values in the Render method:
protected override void Render(System.Web.UI.HtmlTextWriter writer)
{ foreach (IFilterValues filter in FilterProviders)
{ writer.WriteLine(string.Format("Parameter: {0} <br>", filter.ParameterName)); if (filter.ParameterValues != null)
{ foreach (string value in filter.ParameterValues)
if (!string.IsNullOrEmpty(value))
writer.WriteLine(string.Format(" value: {0} <br>", value)); }
}
base.Render(writer);
}
The last thing to do to get the consumer working is add a method to configure the connection. We need to add the ConnectionConsumer attribute (System.Web.UI.WebControls.WebParts namespace). This attribute takes the same 3 parameters:
- displayname – I set this to “filter”. This displayname is used to configure the connection when we initiate the connection from the consumer instead of the provider webpart:
- id – a unique name assigned to the consumer connection point.
- Named parameter – In case our webpart needs to support multiple incoming connections, we pass true for the AllowsMultipleConnections parameter.
[ConnectionConsumer(
"filter",
"UniqueIDForConsumer",
AllowsMultipleConnections = true)]
public void SetFilter(IFilterValues filterValues)
{ if (filterValues != null)
{ EnsureChildControls();
List<ConsumerParameter> parameters = new List<ConsumerParameter>();
parameters.Add(new ConsumerParameter(
"Region",
ConsumerParameterCapabilities.SupportsMultipleValues |
ConsumerParameterCapabilities.SupportsAllValue));
parameters.Add(new ConsumerParameter(
"Status",
ConsumerParameterCapabilities.SupportsMultipleValues |
ConsumerParameterCapabilities.SupportsAllValue));
filterValues.SetConsumerParameters(
new System.Collections.ObjectModel.ReadOnlyCollection<ConsumerParameter>(parameters));
this.FilterProviders.Add(filterValues);
}
}
The SetFilter method above serves 2 purposes. It stored details about the incoming connections and values. It also exposes the parameters the our consumer exposes and the properties of these parameters. Matching combinations of these parameters and the options of the provider webpart allow you to connect the provider and consumer. If these options do not match, the parameter will not show up when configuring the connection. In my example, the consumer webpart exposes 2 parameters; Region and Status. The options used for these parameters (SupportsMultipleValues and SupportsAllValue) allow me to connect to our own provider, to the Choice Filter webpart and the Text Filter provider webpart. A provider webpart that supports the “All” “value for example can never connect to a consumer parameter the does not have the SupportsAllValue option. This parameter simply does not show up in the “Configure Connection” dialog.
Step 4 – Test the consumer
To test the consumer, I have added our own provider, a Text Filter webpart and a Choice Filter webpart that supports multiple values to the page. These are all connected to our custom consumer. After selecting values in each of the 3 providers, our consumer looks like this:
Filter webparts are a very flexible, very powerful way to organize content on your pages. In the next post, I will describe how you can use filter providers to pass a default value to other webparts and how you can provide a value to a parameter in an Excel sheet in the EWA webpart. If you are looking for more information, this page is an excellent start: