Introduction

The FilterZen Filter Web Part lets you to filter other SharePoint Web Parts, such as List View Web Parts and Data View Web Parts, using a comprehensive range of filtering methods.

Being a Web Part, you can add FilterZen's versatile filtering tools to all kinds of SharePoint pages, including but not limited to:

The FilterZen Filter Web Part lets you to filter "everything that's filterable":

The FilterZen Filter Web Part lets you set up the following kinds of filters:

Have a filtering need that FilterZen cannot help you accomplish?

If your specific filtering needs cannot be met by FilterZen's built-in filtering methods, please let us know in the FilterZen discussion forum or by writing us directly — we're happy to help.

Solution Installation and Feature Activation

1. The FilterZen Setup Package

The FilterZen setup package (the roxority_FilterZen.zip file) is a zipped archive containing:

Extract the setup package to any file-system folder. Do not just run Deploy.exe directly from inside the setup archive — it needs to run from a file system directory that also contains all the supporting files from the setup archive.

2. Installing the FilterZen Solution Package

Run Deploy.exe and when the Welcome screen is displayed, click Next to start a series of system checks. To proceed with the installation, all system checks need to succeed:

Click Next and on the following screen, select the Web Applications to deploy FilterZen to. You can also de-select those Site Collections you do not want the setup wizard, upon successful deployment, to activate the Web Part Feature immediately for you on. (Even when FilterZen is deployed in a Web Application, before you can add and start using the FilterZen Filter Web Part on Web Part Pages inside a web site, the FilterZen Filter Web Part Feature needs to be activated for the parent Site Collection, as described in the Feature Activation section below. For now, the setup wizard performs these activations for you.)

Click Next to start the installation and wait for the deployment jobs and Feature activation to complete. This process can take up to a few minutes.

After deployment and Feature activation have completed, review the installation log:

Once you have successfully completed the setup wizard, you can start using the FilterZen Filter Web Part on Web Part Pages inside the previously selected Site Collections immediately.

3. Activating the Site Collection Feature

The FilterZen Filter Web Part is a SharePoint Site Collection-scoped Feature, which needs to be 'activated' on each Site Collection it is to be used in.

  1. Start from the Web Part Page you want to use the Web Part on. Select Site Settings from the Site Actions menu.
  2. The Site Settings page contains the Site Collection Administration section. In this section, click the Site collection features link. If it doesn't exist, click the Go to top level site settings link in the Site Collection Administration section instead, and on the root web's Site Settings page now displayed, click the Site collection Features link inside the Site Collection Administration section.
  3. The Site Collection Features page should contain a row titled FilterZen Filter Web Part.

Walkthrough: using FilterZen

1. It's a Web Part

Filtering data, information, Lists, Libraries and other Web Parts with FilterZen always involves using the FilterZen Filter Web Part. It is the sole mechanism to define filters and connect them to your data.

That however does not necessarily imply that you can use FilterZen "only on Web Part Pages". Technically and strictly speaking, it does — but more pages in SharePoint are Web Part Pages than you might know. In addition to the Web Part Pages you create yourself from the Create page (or by clicking New in a Document Library with the Web Part Page document template), all of the following types of SharePoint pages are actually Web Part Pages, so you can can customize their appearance and behavior by adding Web Parts to then:

In all these places, you can use FilterZen to filter the information displayed. After you have installed the FilterZen solution package and activated the site collection feature, you can add the FilterZen Filter Web Part to any Web Part Page in the accustomed way. After having switched to page Edit Mode from the Site Actions menu and having clicked the Add Web Part button in the Web Part Zone of your choice, you will find it in the Add Web Parts dialog:

(If the Web Part is not available in the Add Web Parts dialog, (re)activate the FilterZen Filter Web Part Feature under Site Collection Features, as described in the last section of the Solution Installation & Feature Activation chapter.

Add a FilterZen Filter Web Part to the Web Part Page that contains the List View or Data View web part that you want to filter. (A List View Web Part is automatically created by SharePoint every time you add a list or document library to a Web Part zone using the Add Web Parts dialog or other page editing tools such as SharePoint Designer.)

2. Connect the Web Part

The Web Part points out to you that it is not 'connected'. By 'connecting' the Web Part, you tell it which Web Parts should receive the filters you will set up shortly. Connect it to to the List View or Data View Web Parts on your Web Part Page that you want to filter by using the Edit / Connections Web Part menu:

This notification, and other output produced by the FilterZen Filter Web Part is only ever rendered in Edit Mode by default, so that the Filter Web Part is invisible to page visitors (unless you have set up dynamically generated or manually created interactive filters).

After connecting the FilterZen Filter Web Part to at least one other Web Part, its appearance changes to display relevant contextual status information and potentially helpful hints about your filters and its connections — again, only in Edit mode by default, keeping the Filter Web Part invisible to your visitors.

3. Set up your filter(s)

Once you have the FilterZen Filter Web Part connected to other Web Parts and have set up and enabled at least one filter for it, it will send them filters, each composed of a filter name and a filter value, whenever the Web Part Page is rendered, by determining the filter names and values from the context and logic provided by your individual filters. When connecting to List View or Data View Web Parts, the filter name ultimately corresponds to a Column name.

In this walk-through, we will filter a Tasks List View to only display tasks assigned to the current user that are due 'tomorrow'. To start, choose Modify in the edit Web Part menu. In the Web Part tool pane, in the All Filters section, select the type of filter you want to add to the Filter Web Part — to implement the filtering requirement outlined above, we will need both a Date Filter and a User Filter — and click the Add this new filter icon. So start by selecting Date Filter and clicking the '+' icon:

This will bring up the embedded Date Filter editor right in the Web Part tool pane. Below, we have already set up the filter as this example requires it. This setup will filter the Due Date column (with the internal name DueDate) to only yield values representing 'tomorrow':

By saving the DueDate filter and then applying the Web Part modifications, the connected Web Part will be filtered accordingly already. Repeat the same steps as above, but this time select the User Filter type before clicking the '+' icon, to create the required user filter. The following set up will filter the Assigned To column (with the internal name AssignedTo) by the current user:

The only settings that are relevant to this very example are the Column / filter name setting at the top, and the default filter value setting just below. You may ignore the other User Filter settings (hidden from the above screenshot) for now, they are explained in the User Filters chapter.

Once all filters and Web Part modifications have been saved, your connected Web Parts will again be filtered as specified.

General Filter Settings

The following settings apply across all filter types.

Column / Filter Name

This name is the name used to identify a filter among other filters in your FilterZen Filter Web Part. It is also the filter name sent to connected Web Parts.

Different kinds of Web Parts may vary in their requirements for filter names. When connected to a List View Web Part (or a Data View Web Part whose data source is a SharePoint list or document library), those out-of-the-box, filter-receiving SharePoint Web Parts require the FilterZen Filter Web Part to send filter names that correspond exactly to internal Column names (which never change once a Column has been created) rather than their current display names (Column titles, which can be changed by end-users at any time).

The internal name of a Column is set when a it is first created, and it never changes, even though the Column title might be changed repeatedly from SharePoint's Edit Column page later on. The patterns for internal names vary: for some built-in Columns from SharePoint's out-of-the-box List definitions there are internal names such as AssignedTo for the Tasks List's "Assigned To" Column, or _ModerationComments for any List's "Approver Comments" Column. A user-created Column with an initial title of "Test-Link" will get an internal name of Test_x002d_Link.

FilterZen cannot change this requirement (to send filter names corresponding exactly to internal Colum names) — it was built right into SharePoint. You therefore need to specify filter names corresponding to the internal Column names.

To make this as easy as possible for you, we built a useful tool right into the Web Part's configuration tool pane that empowers you to instantly figure out the proper filter name to use for the Column you want to filter, that is, its internal Column name. Once you expand this tool by clicking the Filtering List Data link, you can immediately select the list you are filtering to see all its Columns. Now select the Column and you will see its internal name. Just copy and paste it into the Column / filter name text box, or click the Use as filter name link:

If you are filtering a Data View Web Part sourcing its data from a list in another web site or site collection, just enter the web site's URL in the tool's text box and click OK to be able to locate the list in the drop-down box.

Enabling and Disabling Filters

The FilterZen Filter Web Part only ever sends those of your filters that are marked enabled. Tick or untick the This filter is enabled check box to enable or disable a filter. You need to enter a filter name before you can enable a filter, because a filter name is required to send a filter to conencted Web Parts.

Default Filter Value

All filter types that optionally support an interactive mode (i.e. all filter types except Page Column Filter and Page Request / URL Filter) also have a setting to set a default filter value, even though they vary in their semantics and user interface depending on the filter type. The default filter value is the filter value initially sent, and in interactive mode, also the one initially presented to end users, which they may then change.

About "Empty" Filter Values

For each filter you create, you need to decide which approach to dealing with empty filter values is optimal given the particular filtering context:

Every filter type provides the Send filter value even if empty check box to control this setting.

Fallback Filter Value

All filter types, including the non-interactive ones, let you specify an optional fallback filter value that will only ever be sent if the filter value is empty.

"Interactive" Filters

All filters except Page Column Filters and Page Request / URL Filters offer an optional interactive mode that you can turn on or off via the Allow users to enter/pick a filter value check box. In interactive mode, the FilterZen Filter Web Part will render into the Web Part Page a visible, interactive user interface control for changing the filter value of each interactive filter. This user interface control will be a single-line text box for Text Filters, a date picker for Date Filters, and a drop-down list for Choice Filters, List Lookup Filters, User Filters, SQL Data Filters and BDC Filters. You can optionally specify a label text in the filter label text box, which will then be prepended to the filtering user interface control by the FilterZen Filter Web Part, to let your users know what this control is actually for. There are also additional Web Part settings for further customizing the appearance and behavior of all interactive filtering user controls.

Pre-Filtering of Choice, List Lookup, SQL Data, BDC and User Filters

Tick the Pre-filtering — only offer pickable choices that also exist in a List column check box in a Choice Filter, List Lookup Filter, SQL Data Filter, BDC Filter or User Filter editor to be able to enter a List View URL and an internal Column name both used to eliminate from the drop-down list of available choices all those that do not exist as exact values in the specified List Column.

Locking out specific filter values

In the drop-down list labelled Always suppress certain filter values, select an item other than Don't suppress any filter values to show a multi-line text box allowing you to enter specific filter values. Your drop-down choice then controls whether the filter values entered are the only ones allowed to be sent (Suppress all filter values except...), or the only ones that should never be sent (Suppress no filter values except...).

Text Filters

Text filters are the simplest of all filter types. In addition to the general filter settings they share with all other filter types, text filters let you enter any filter value to send into the text box labelled default filter value. Using a text filter, you can filter all column types, including lookup, date, user and numeric columns. By enabling interactive mode, you can let your users enter their own filter values in a text box rendered right into the FilterZen Filter Web Part.

Choice Filters

Create a choice filter to let users pick a filter value from a drop-down list limited to a static set of choices pre-defined by you. (Note: to offer available choices dynamically based on list data, use a List Lookup Filter instead.)

Date Filters

Create a date filter to let users enter or pick a date filter value, or to send a filter value that is always based on the current date. You may also optionally specify a number of days to always add to or subtract from the date filter value just before sending it, so as to easily accomplish relative date-filtering concepts such as yesterday / tomorrow, one week ago / next week etc.

Special Date Values

Valid Date Locales

Language (Country)

Short name

 

Numeric locale ID

Afrikaans

af

 

1078

Albanian

sq

 

1052

Arabic - United Arab Emirates

ar-ae

 

14337

Arabic - Bahrain

ar-bh

 

15361

Arabic - Algeria

ar-dz

 

5121

Arabic - Egypt

ar-eg

 

3073

Arabic - Iraq

ar-iq

 

2049

Arabic - Jordan

ar-jo

 

11265

Arabic - Kuwait

ar-kw

 

13313

Arabic - Lebanon

ar-lb

 

12289

Arabic - Libya

ar-ly

 

4097

Arabic - Morocco

ar-ma

 

6145

Arabic - Oman

ar-om

 

8193

Arabic - Qatar

ar-qa

 

16385

Arabic - Saudi Arabia

ar-sa

 

1025

Arabic - Syria

ar-sy

 

10241

Arabic - Tunisia

ar-tn

 

7169

Arabic - Yemen

ar-ye

 

9217

Armenian

hy

 

1067

Azeri - Latin

az-az

 

1068

Azeri - Cyrillic

az-az

 

2092

Basque

eu

 

1069

Belarusian

be

 

1059

Bulgarian

bg

 

1026

Catalan

ca

 

1027

Chinese - China

zh-cn

 

2052

Chinese - Hong Kong SAR

zh-hk

 

3076

Chinese - Macau SAR

zh-mo

 

5124

Chinese - Singapore

zh-sg

 

4100

Chinese - Taiwan

zh-tw

 

1028

Croatian

hr

 

1050

Czech

cs

 

1029

Danish

da

 

1030

Dutch - Netherlands

nl-nl

 

1043

Dutch - Belgium

nl-be

 

2067

English - Australia

en-au

 

3081

English - Belize

en-bz

 

10249

English - Canada

en-ca

 

4105

English - Caribbean

en-cb

 

9225

English - Ireland

en-ie

 

6153

English - Jamaica

en-jm

 

8201

English - New Zealand

en-nz

 

5129

English - Phillippines

en-ph

 

13321

English - Southern Africa

en-za

 

7177

English - Trinidad

en-tt

 

11273

English - Great Britain

en-gb

 

2057

English - United States

en-us

 

1033

Estonian

et

 

1061

Farsi

fa

 

1065

Finnish

fi

 

1035

Faroese

fo

 

1080

French - France

fr-fr

 

1036

French - Belgium

fr-be

 

2060

French - Canada

fr-ca

 

3084

French - Luxembourg

fr-lu

 

5132

French - Switzerland

fr-ch

 

4108

Gaelic - Ireland

gd-ie

 

2108

Gaelic - Scotland

gd

 

1084

German - Germany

de-de

 

1031

German - Austria

de-at

 

3079

German - Liechtenstein

de-li

 

5127

German - Luxembourg

de-lu

 

4103

German - Switzerland

de-ch

 

2055

Greek

el

 

1032

Hebrew

he

 

1037

Hindi

hi

 

1081

Hungarian

hu

 

1038

Icelandic

is

 

1039

Indonesian

id

 

1057

Italian - Italy

it-it

 

1040

Italian - Switzerland

it-ch

 

2064

Japanese

ja

 

1041

Korean

ko

 

1042

Latvian

lv

 

1062

Lithuanian

lt

 

1063

F.Y.R.O. Macedonia

mk

 

1071

Malay - Malaysia

ms-my

 

1086

Malay – Brunei

ms-bn

 

2110

Maltese

mt

 

1082

Marathi

mr

 

1102

Norwegian - Bokml

no-no

 

1044

Norwegian - Nynorsk

no-no

 

2068

Polish

pl

 

1045

Portuguese - Portugal

pt-pt

 

2070

Portuguese - Brazil

pt-br

 

1046

Raeto-Romance

rm

 

1047

Romanian - Romania

ro

 

1048

Romanian - Republic of Moldova

ro-mo

 

2072

Russian

ru

 

1049

Russian - Republic of Moldova

ru-mo

 

2073

Sanskrit

sa

 

1103

Serbian - Cyrillic

sr-sp

 

3098

Serbian - Latin

sr-sp

 

2074

Setsuana

tn

 

1074

Slovenian

sl

 

1060

Slovak

sk

 

1051

Sorbian

sb

 

1070

Spanish - Spain (Traditional)

es-es

 

1034

Spanish - Argentina

es-ar

 

11274

Spanish - Bolivia

es-bo

 

16394

Spanish - Chile

es-cl

 

13322

Spanish - Colombia

es-co

 

9226

Spanish - Costa Rica

es-cr

 

5130

Spanish - Dominican Republic

es-do

 

7178

Spanish - Ecuador

es-ec

 

12298

Spanish - Guatemala

es-gt

 

4106

Spanish - Honduras

es-hn

 

18442

Spanish - Mexico

es-mx

 

2058

Spanish - Nicaragua

es-ni

 

19466

Spanish - Panama

es-pa

 

6154

Spanish - Peru

es-pe

 

10250

Spanish - Puerto Rico

es-pr

 

20490

Spanish - Paraguay

es-py

 

15370

Spanish - El Salvador

es-sv

 

17418

Spanish - Uruguay

es-uy

 

14346

Spanish - Venezuela

es-ve

 

8202

Southern Sotho

st

 

1072

Swahili

sw

 

1089

Swedish - Sweden

sv-se

 

1053

Swedish - Finland

sv-fi

 

2077

Tamil

ta

 

1097

Tatar

tt

 

1092

Thai

th

 

1054

Turkish

tr

 

1055

Tsonga

ts

 

1073

Ukrainian

uk

 

1058

Urdu

ur

 

1056

Uzbek - Cyrillic

uz-uz

 

2115

Uzbek – Latin

uz-uz

 

1091

Vietnamese

vi

 

1066

Xhosa

xh

 

1076

Yiddish

yi

 

1085

Zulu

zu

 

1077

List Lookup Filters

Create a List lookup filter to send filters based on List data. Whether you let users pick a List item to use in interactive mode, or specify the source item to use directly, the filter value being sent is always the current, live value of a Column you chose.

View URL of the Lookup List

Specify the URL of the View used to access the List and retrieve its data. The View provides initial pre-filtering and sorting. A View URL includes the file name of the View page (such as AllItems.aspx).

You can specify a full, absolute URL (those starting with http:// or https:// ). Also supported are site-relative URLs (those starting with / ), to which the site collection root web URL will be prepended at run time, and web-relative URLs (those neither starting with http:// nor https:// nor with / ), to which the current web URL will be prepended at run time.

Value Column and Display Column

Specify the internal name of the Column in the lookup List providing the filter value to be sent. Typically this is also the Column you will want to use for displaying filter choices, however, you may also optionally specify another internal name for the display Column.

User Filters

Create a user filter to send user filter values. The user filter is internally a specialized type of List lookup filter that is pre-configured to always use the User Information List (at /_catalogs/users) of the current Site Collection, and therefore shares some of the settings and capabilities of List lookup filters.

Page Column Filters

Page column filters only work on Web Part Pages that are stored inside a Document Library. Their filter value is always dynamically derived from the value of any specified Document Library Column associated with the Web Part Page. The page column filter is internally a specialized type of List lookup filter that is pre-configured to always use the Document Library containing the current Web Part Page, and therefore shares some of the settings and capabilities of List lookup filters.

URL / Page Request Filters

Use page request parameters to derive the filter value from the current Web Part Page HTTP request context:

The Page Request / URL Filter is capable of parsing various request parameter formats. Observe how the Matching URL format example area changes immediately in response to your changes to see exactly what kind of input the filter expects with the current setup. (In principle this applies even when using a request mode other than URL query string.)

Sub-Parameter Bundling

If the specified request parameter bundles multiple name-value pairs in a single parameter value, an individual sub-parameter value can be derived by entering the sub-parameter name, if the parameter value conforms to the syntax that is also used by Microsoft Office SharePoint Server Advanced Search forms / results pages ( name:"value" name:"value" name:"value"  filters are separated by spaces, names and values are separated by colons and values are always in quotation marks, regardless of the column type).

SQL Data Filters

Create a SQL data filter to send filters based on any data stored in ADO.NET-accessible data sources such as relational databases. Whether you let users pick a record set to use in interactive mode, or specify the data row to use directly, the filter value being sent is always the current, live value from the specified data source.

Data Source Connection

To connect to your data source, you select the data source provider to use and specify a connection string. If unsure, your database administrator can help you with this. The following ADO.NET data source providers can be used out of the box:

Data source providers can be added and removed on the Configuration page in the FilterZen Studio at
http://farm_url/_layouts/roxority_FilterZen/default.aspx?cfg=cfg.

SQL Query, Value Column and Display Column

For the SQL data filter to obtain filter values from your data source, you need to specify, in SQL (or any other query language dialect supported by your data source provider), the query sent to the data source to fetch a result set of filter values. In order for this filter to work as expected, it is mandatory that the result set of filter values is guaranteed by your query to always be returned in a consistent sort order, so in SQL you should add an ORDER BY clause. Per the SQL standard, unless your query specifies the sort order explicitly, the default sort order of data rows is undefined and thus may change randomly at any time.

Your query will need to return a stream of record sets (which your query may also pre-filter and sort as preferred) with at least one data column. The name of the column containing the filter value may be identical to the database column or changed to another name by your query — however, you need to specify the result set column name to be used as the value column, i.e. the name of the column providing the filter value. In interactive mode, if you want to display to the user another column value than the one sent as the filter value, specify the name of the display column.

Business Data Connectivity (BCS/BDC) Filters

Note: this filter type requires SharePoint 2010 (any edition, including Foundation) or Microsoft Office SharePoint Server 2007 (Enterprise Edition), with the Business Data Connectivity (BCS/BDC) features enabled in both scenarios.

Create a Business Data Connectivity (BCS/BDC) filter to send filters based on any data stored in any external data sources integrated into your Business Data Connectivity Service. Whether you let users pick an external data record or entity instance to use in interactive mode, or specify the record to use directly, the filter value being sent is always the current, live value from the specified data source.

To connect to your data source, first select the BDC external system and external content type type to use. Now you simply select which column values are displayed to users in interactive mode, and which column values are sent as filter values to connected Web Parts. You may also want to review any of the general filter settings that are naturally also available to your BDC filters.

FilterZen Web Part Settings

Suppressing 'Unknown' Filters

This setting is not necessary nor recommended unless you are using a filter that determines filter names to be sent dynamically, rather than using a fixed one you entered for the filter, such as catch-all Page Request / URL Filters.

Connected Web Parts may or may not inform the FilterZen Filter Web Part about the names of filterable columns. This information is not always necessarily complete. For example, when you connect to a List View Web Part with three visible List Columns, then it will notify the FilterZen Filter Web Part about these three filterable Columns — they become 'known filter names'. However, you can still validly use any other Column Name present in the List but not the List View, and filtering will still work as expected.

If this setting is activated, filter values will never be sent if the corresponding filter name is not in the list of 'known' filter names. This setting may work against you because the list of 'known' filter names is not always exhaustive. It may be useful, however, to build a single "catch-all" Page Request Filter that takes all URL parameters as filter name-value-pairs, but sends only those that are known, visibly filterable Columns.

Overriding Settings from URL Parameters

By ticking the Override Web Part and filter settings from URL parameters checkbox, every filter setting or Web Part setting is overridden by the appropriate URL (query string) parameter value, if it exists. See the possible parameter names and values in the reference chapter.

Interactive Filters

All filter types (except Page Column Filters and Page Request / URL Filters) support the so-called interactive mode which you enable by ticking the Allow users to enter / pick a value check box. If interactive mode is enabled for at least one of your filters, the FilterZen Filter Web Part renders an interactive filtering user control appropriate for the filter type (date pickers for Date Filters, drop-down lists for Choice Filters, User Filters, List Lookup Filters, SQL Data Filters and BDC Filters, and text boxes for Text Filters into the Web Part Page, allowing your page visitors to change the filtering on-the-fly. The appearance of this Web Part output can be customized via CSS.

If interactive mode is enabled for at least one of your filters, the following additional Web Part settings are available:

Interactively input filter values are applied during the next server post-back, whether the above option is active or not, and regardless of how exactly the post-back was initiated. You can force such a server post-back by calling the roxRefreshFilters(filterWebPartID) JavaScript method. Just below the Web Part settings described above, there is also a text area for you to enter additional HTML mark-up code to be rendered into the Web Part area, depending on your choice either prepended or appended to the interactive filtering user controls.

Dynamically Generating Temporary Interactive Filters

Want to offer interactive filtering user controls for all your columns without having to set up all these filters manually?

You can have the FilterZen Filter Web Part generate the appropriate interactive filtering user controls for you automatically, on-the-fly during each Web Part rendering for all available 'known' filter names. This time-saving feauture generates drop-down filtering lists for choice and lookup Columns (appropriately pre-populated and pre-filtered), date pickers for date Columns and text boxes for all other Columns. To activate dynamically generated temporary interactive filters, from the drop-down list labelled dynamically generated temporary enabled interactive filters for all 'known' filter names if possible, select Prepend or Append.

Debug Mode

When a filter does not seem to work as expected, it can be helpful to find out which filters exactly the FilterZen Filter Web Part constructs and sends, given its current settings. The FilterZen Filter Web Part will render just that information whenever the page is in edit mode, so on the page that does not result in the filter you want, select Edit Page from the Site Actions menu and you will see all filters produced from the current setup. Also shown are all the filter values that were not sent, if any, and the reason. Unless the FilterZen Filter Web Part is minimized or hidden, its Debug Mode output looks like this:

"How do I...?" Recipes

Online FilterZen How-To Tutorials:

The following articles from the FilterZen Blog further describe how to accomplish commonly-requested tasks with FilterZen:

FilterZen BCS/BDC Item Builder Web Part

Note: this Web Part requires Microsoft Office SharePoint Server 2010 or 2007 Enterprise Edition with the Business Data Connectivity (BCS/BDC) features enabled.

The FilterZen BCS/BDC Business Data Item Builder Web Part initially serves the same purpose as the built-in Business Data Item Builder Web Part provided by Microsoft Office SharePoint Server Enterprise Edition: to obtain the ID of a Business Data Connectivity (BCS/BDC) entity instance and broadcast that instance to compatible Web Parts. However, the FilterZen BCS/BDC Business Data Item Builder Web Part goes beyond the built-in equivalent Web Part in many ways:

Obtaining the External Content Type / Entity Instance ID

The out-of-the-box Web Part can only ever obtain the required entity instance ID from a pre-defined URL Parameter named ID, whereas the FilterZen Business Data Item Builder Web Part obtains the required entity instance ID from any connected Web Part. So while you can "recreate" the original behaviour by connecting the FilterZen Business Data Item Builder Web Part to a MOSS URL (Query String) Filter Web Part, or a FilterZen Filter Web Part (containing a Page Request / URL Filter), there are now innumerable additional ways for the item builder to obtain the entity instance ID (including any built-in or custom FilterZen filter types and the out-of-the-box provider Web Parts, for example List Views) and send all entity instance data to any consumer Web Part.

Simply choose your preferred entity instance ID provider Web Part from the Connections / Get BCS/BDC Entity Instance ID From sub-menu.

Sending the selected Entity Instance to BCS/BDC Web Parts

Simply select from the Connections / Send Selected Item To sub-menu any Business Data Actions or Business Data Item Web Part to send the entity instance associated with the current entity instance ID. You can only connect to Web Parts that have been pre-configured for a specific Business Data Connectivity application and external content type. For the FilterZen BCS/BDC Business Data Item Builder Web Part to become aware of the Business Data Connectivity application, data type and entity columns to use, you need to make at least one such connection.

Sending any Entity Instance Column values to any Web Parts

Once you have made at least one such connection and the FilterZen BCS/BDC Business Data Item Builder Web Part became aware of the Business Data Connectivity (BCS/BDC) application, data type and entity columns to use, you can now also send live BCS/BDC column values of the selected entity instance to any kind of consumer Web Part: simply select from its Connections sub-menu the FilterZen Business Data Item Builder Web Part and follow the on-screen Connection Properties dialog.

Configuration Settings

The following configuration settings are available to administrative users on the Configuration page in your FilterZen Studio, which you can access via Site Settings / FilterZen Studio / Configuration Settings.

Each setting has a global value scoped to the SharePoint server farm, and this value can optionally be overridden on the Site Collection level. The following settings are available:

User Interface Language

FilterZen has been localized for multiple languages. In addition to English and German, if you have added partial translations in other languages (via Site Settings / FilterZen Studio / DIY User Interface Localization), these languages will be available for selection here. Changing this setting affects all FilterZen user interfaces except captions and descriptions of Features, List Templates, Column Types, Content Types or Web Part Templates (those are always loaded directly by SharePoint based on the current Web Site locale).

You can pick one of the following options on the Configuration page in the FilterZen Studio:

Hard limit for pickable choices in drop-down filters

Interactive drop-down filters (such as Choice, List Lookup, SQL, User and BCS/BDC Filters) use this threshold to limit the number of visibly pickable choices. This is recommended both for usability and performance reasons. To disable the limit (not recommended), set this setting to 0. If you don't specify a valid integer number, the default value of 150 will be used.

After you have customized this setting, you can click the Reset to Default Value link on the Configuration page in the FilterZen Studio to restore the following default value:

150

How to deal with 'Edit in Datasheet'

Datasheet Views don't support Web Part Connections and instead of simply ignoring these, unfortunately they usually just fail to display. As a result, when a user clicks 'Edit in Datasheet' in your FilterZen-connected List View, an error message is displayed in place of the data. You can resolve this by either ticking the On pages with nothing but a single List View, automatically filter it connectionless check-box option in the Advanced Filtering Settings section of the FilterZen Web Part's settings tool-pane (SharePoint 2010 only) — or alternatively, if you manually add a new, separate, dedicated (public) Datasheet View to the List, then FilterZen can automatically redirect your users to this separate Datasheet View page when they select 'Edit in Datasheet' in any View.

Select the 'Auto-redirect' choice to allow this kind of redirection of users to your dedicated Datasheet View when they click 'Edit in Datasheet' on a non-Datasheet View. If you select 'Ignore', then 'Edit in Datasheet' on a connected List View page may result in the error message: "There is no valid configuration for these connected parts to run in." (Note: SharePoint 2010 also lets you disable datasheet views on a per-List basis via List Settings / Advanced Settings.)

You can pick one of the following options on the Configuration page in the FilterZen Studio:

In CAML Direct filtering mode, override List View Web Part folder display only when filters are active (only limited support for this feature in SharePoint 2010)

The CAML Direct filtering mode allows you to "override the default display of folders" when connected to List View Web Parts. On the Configuration page in the FilterZen Studio, tick this check box to only attempt this override when active filter values have been sent, instead of always.

Custom image URL for "Loading..." spinner animation

When filters are applied or cleared, FilterZen by default shows a SharePoint-typical animation (the green spinner) to indicate that an operation is in progress. If desired for design customization or branding purposes, you can enter an alternative picture URL to use for this animation. This can be an absolute or a server-relative URL such as /_layouts/images/roxority_FilterZen/k.gif for example.

In Text filters' List-based AutoSuggest drop-downs, 1-character entries use BeginsWith instead of Contains

When connected to List View Web Parts, Text Filters can be set up to offer end users a "List-based AutoSuggest drop-down, if possible", providing find-as-you-type suggestions for assisted input completion. This drop-down (always limited to the maximum number of entries configured below) invokes an AJAX search against the connected List for the Column targeted by the Text Filter, and returns values containing the current text box input. For huge datasets, it might be more desirable to only match values that start with (rather than contain) the currently typed in letter as long as only a single one has been typed, so that entering B shows all values starting with B. The drawback to this might be end user confusion because the AutoSuggest drop-down will revert to "contains" logic as soon as more letters are typed. (Note: when the Text Filter has its own filter operator set to Begins with, the AutoSuggest will always use begins-with instead of contains logic.) On the Configuration page in the FilterZen Studio, tick this check box to use begins-with rather than contains for single-letter inputs.

Maximum number of choices in Text filters' List-based AutoSuggest drop-downs

In an AutoSuggest drop-down, when more than say 20-30 items are displayed, users are much more likely to further refine their text input rather than scan hundreds of choices, and a low limit drastically improves performance of List-based auto-completion drop-downs in Text filters. To customize this, enter an integer number higher than 1, otherwise the default value of 40 will be used as the limit.

After you have customized this setting, you can click the Reset to Default Value link on the Configuration page in the FilterZen Studio to restore the following default value:

40

End-user instructions for Text Filters' List-based AutoSuggest drop-downs

If desired, use this setting to compose an explanatory note for end users, to be displayed at the bottom of all Text Filters' List-based AutoSuggest drop-downs.

After you have customized this setting, you can click the Reset to Default Value link on the Configuration page in the FilterZen Studio to restore the following default value:

(Showing max. 40 results)

No-Filter Parameter Names (URL / Page Request Filters)

When using catch-all URL / Page Request Filters, optionally specify the request parameter names (one per line) that should never be sent as filters. Including the SharePoint-typical URL parameters in this setting's default value is recommended.

After you have customized this setting, you can click the Reset to Default Value link on the Configuration page in the FilterZen Studio to restore the following default value:

ContentTypeId
DisplayMode
FolderCTID
InitialTabId
IsDlg
Paged
PageView
PageFirstRow
RootFolder
SortDir
SortField
Source
View
VisibilityContext
p_ID
p_FSObjType
p_FileLeafRef
p_Title
FilterField1
FilterValue1
FilterField2
FilterValue2
FilterField3
FilterValue3
FilterField4
FilterValue4
FilterField5
FilterValue5
FilterField6
FilterValue6

ADO.NET Database Connection Providers for SQL Data Access

Specify the ADO.NET database connection providers that your Database/SQL Data Sources should support (one per line, using the pattern "Provider display name: full provider IDbConnection Type name, full assembly name").

After you have customized this setting, you can click the Reset to Default Value link on the Configuration page in the FilterZen Studio to restore the following default value:

SQL Server: System.Data.SqlClient.SqlConnection, System.Data
Oracle: System.Data.OracleClient.OracleConnection, System.Data.OracleClient
ODBC: System.Data.Odbc.OdbcConnection, System.Data
OLE DB: System.Data.OleDb.OleDbConnection, System.Data

Delimiter for indenting nested pickable List Lookup filter choices

If you (think you) need this feature, please read or join the related support forum thread.

Never offer the following pages in List View Pickers

The "List View Picker" filter type lets end users select a different List View to apply to the connected List View Web Part. View pages whose URL paths contain any one of the values specified here (one per line) will NOT be offered for end user selection by this filter type.

combine.aspx refers to the built-in Merge Documents view, repair.aspx to the built-in Relink Documents view, webfldr.aspx to the 2007 Explorer view. These are generally not desirable in a List View Picker context.

After you have customized this setting, you can click the Reset to Default Value link on the Configuration page in the FilterZen Studio to restore the following default value:

/forms/combine.aspx
/forms/repair.aspx
/forms/webfldr.aspx

External Filter Types

Specify the additional or third-party FilterZen filter types to make available to FilterZen Filter Web Parts in this Farm (one per line, using the pattern "full roxority_FilterZen.FilterBase inheritor class type name, full assembly name"). CAUTION: uninstalling an external filter type assembly will break all Filter Web Parts that still use a filter of that type.

When remembering filter values, store by name only (and share across FilterZen Web Parts)

FilterZen Web Parts can be set to 'Remember filter values last used for each user'. By default these stored values are unique to the user, the filter name and the FilterZen Web Part storing them. On the Configuration page in the FilterZen Studio, tick this check box to store and restore values only based on the user and filter name instead, which lets you share filter values of the same name between multiple individual FilterZen Web Parts.

Storage location for 'Remembered filter values last used'

FilterZen Web Parts can be set to 'Remember filter values last used for each user'. By default these values are stored both in the user agent (browser) and in the SharePoint content database, but this configuration settings lets you override that default hybrid storage model. Client-side cookies may be cleared by users or blocked due to corporate security policies. Server-side storage may in rare configurations fail silently due to administrative access restrictions even for elevated code, or with large user bases may inflate the content database over time.

You can pick one of the following options on the Configuration page in the FilterZen Studio:

Remove Parameters from URL

Enter the URL Parameters that FilterZen should remove from the URL when in use (if the Web Part's Override Web Part settings from URL parameters check-box option is ticked), one per line.

Enable Web Part Connections menu option 'Send single data value to'

When this option is selected, FilterZen Filter Web Parts will act not only as 'filter providers' and 'data row providers' but also as 'data cell providers'. This is usually not necessary because row providers can always also be used as cell providers and provide a better user experience for the Web Part Page designer. If unsure, don't select this option.

By default, no inclusion of jQuery library v1.6.1 (NOT recommended)

Some FilterZen end user-facing artifacts require (and load into the respective host pages) the jQuery library, version 1.6.1. Embedding jQuery more than once in a single page can cause JavaScript warnings in Internet Explorer with some few jQuery plugins (and only if any are used in your farm at all). On the Configuration page in the FilterZen Studio, tick this check box only if your master pages, web pages or third-party extensions also already include jQuery globally (not just on some individual pages) and independently of FilterZen to prevent FilterZen from loading jQuery too. If you do so, you need to make sure jQuery 1.6.1 or higher is loaded on each page hosting also hosting FilterZen user interface artifacts, or FilterZen will appear broken. This is a global default setting that can be optionally overridden locally where applicable.

Reference: URL Setting Parameters

About URL-overridable Settings

(If you are looking for URL-based filtering, see the chapter on Page Request / URL Filters.)

When the Override Web Part and filter settings from URL parameters check box is ticked (in Web Part settings), every filter setting or Web Part setting is overridden by the appropriate URL (query string) parameter value, if it exists. See the possible parameter names and values below.

Note: a URL override of a Web Part setting will affect all FilterZen Filter Web Parts present on the current Web Part Page with the Override Web Part and filter settings from URL parameters option ticked. A URL override of a filter setting will affect all dynamically generated and manually defined filters in all FilterZen Filter Web Parts present on the current Web Part Page with the Override Web Part and filter settings from URL parameters option ticked.

Overridable Web Part Settings

Overridable Filter Settings: All Filter Types

Overridable Filter Settings: Choice, Date, List Lookup, Text, SQL Data, BCS/BDC and User Filters

Overridable Filter Settings: Choice, List Lookup, SQL Data, BCS/BDC and User Filters

Overridable Filter Settings: Choice Filters

Overridable Filter Settings: Date Filters

Overridable Filter Settings: List Lookup Filters

Overridable Filter Settings: List Lookup and User Filters

Overridable Filter Settings: List Lookup, Page Column and User Filters

Overridable Filter Settings: Page Request / URL Filters

Overridable Filter Settings: Page Request and BCS/BDC Filters

Overridable Filter Settings: BCS/BDC Filters

Overridable Filter Settings: SQL Data Filters

Overridable Filter Settings: Text Filters

Reference: CSS Classes

When dynamically generated or manually created interactive filters are present, enabled and their filtering user controls are rendered into the FilterZen Filter Web Part, it wraps them in HTML span elements decorated with the CSS class names detailed below, allowing for full customizability of their visual appearance. Unless otherwise noted, these elements are pre-styled in /_layouts/roxority_FilterZen/roxority_FilterZen.css.

Release Notes

Version 3.8 (9th August 2010)

Version 3.7 (16th April 2010)

Version 3.6 (26th January 2010)

Version 3.5 (6th December 2009)

Version 3.4 (11th September 2009)

Version 3.3 (7th September 2009)

Version 3.2 (19th August 2009)

Version 3.1 (5th July 2009)

Version 3.0 (19th June 2009)

Version 2.6 (19th May 2009)

Version 2.5 (18th May 2009)

Version 2.4 (12th May 2009)

Version 2.3 (11th May 2009)

Version 2.2 (29th April 2009)

Version 2.1 (28th April 2009)

Version 2.0 (27th April 2009)

Version 1.0 (09th April 2009)

End-User License Agreement (EULA)

END-USER SOFTWARE LICENSE AGREEMENT FOR ROXORITY SOFTWARE PRODUCTS

THIS IS A LEGALLY BINDING AGREEMENT BETWEEN YOU (EITHER AN INDIVIDUAL OR A SINGLE ENTITY) AND ROXORITY LTD. (ROXORITY) FOR ROXORITY SOFTWARE, ASSOCIATED MEDIA AND PRINTED MATERIALS, AND MAY INCLUDE ONLINE OR ELECTRONIC DOCUMENTATION ("SOFTWARE"). BY INSTALLING, COPYING, OR OTHERWISE USING THE ROXORITY SOFTWARE PRODUCT, YOU ARE AGREEING TO BE BOUND BY THE TERMS AND CONDITIONS OF THIS AGREEMENT, INCLUDING THE SOFTWARE LICENSE AND DISCLAIMER OF SOFTWARE WARRANTY BELOW. PLEASE READ THIS DOCUMENT CAREFULLY BEFORE USING THE SOFTWARE. IF YOU DO NOT AGREE WITH THE TERMS AND CONDITIONS OF THIS AGREEMENT, YOU MUST NOT INSTALL OR USE THE SOFTWARE.

LICENSE GRANT

"You" or "your" as used herein means the person or company who is being licensed to use the Software, as defined below. "We," "us" and "our" as used herein means ROXORITY Ltd.

The "Software" as referred to herein means the ROXORITY Software "FilterZen", a product that extends "Microsoft SharePoint" web sites to provide additional capabilities.

We hereby grant you a perpetual, non-exclusive, non-transferable, revocable license to use the Software on your server and client computers.

The total number of SharePoint "Site Collections" or "server farms" that the Software can be "activated" on (after 45 days of free trial use) shall be limited to the number of licenses which you purchase. For example, if you purchase 4 Site Collection licenses, you may activate the Software on up to 4 SharePoint Site Collections; if you purchase 2 server farm licenses, you may active the Software on unlimited Site Collections within up to 2 server farms.

Each license is issued to one unique Site Collection or server farm and cannot be transferred to another Site Collection or server farm.

TITLE

The Documentation as referred to herein shall mean the written materials that you may receive in connection with the Software. We will remain the sole and exclusive owners of all right, title and interest in and to the Software and the Documentation.

ARCHIVAL OR BACKUP COPIES

You may copy the Software for back-up and archival purposes only, provided however, that at all times herein, the original and each copy is kept in your possession and that your installation and use of the Software does not exceed that allowed in the "License Grant" section above.

THINGS YOU MAY NOT DO

You agree and acknowledge that the Software and Documentation are proprietary works that are protected by the copyright laws of various nations. You may only use the Software and Documentation for the purposes and in accordance with the terms of this Agreement. You may not, without limitation:

You acknowledge that any violation of this paragraph will cause us immediate and irreparable harm and that the damages which we will suffer may be difficult or impossible to measure. Therefore, upon any actual or impending violation of this paragraph, we shall be entitled to the issuance of a restraining order, preliminary and permanent injunction without bond, restraining or enjoining such violation by you, your successors or assignees or any entity or person acting in concert with you. Such remedy shall be additional to and not in limitation of any other remedy which may otherwise be available to us by law.

TRANSFERS

You may assign all your license to use the Software and Documentation to another person or legal entity (the "Assignee"), provided however, that prior to such assignment, the Assignee undertakes in writing to be bound by your obligations under this Agreement. Any attempt to assign or transfer the license to the Software, the Documentation or this Agreement shall be ineffective, unless the assignment complies with the terms of this paragraph. Upon assignment of your license hereunder, you agree to transfer to the Assignee all of your copies of the Software and Documentation, including all copies of updates and prior versions of the Software and Documentation and you further agree and that you will retain no copies, including, without limitation, electronic copies stored on computer discs or drives.

DISCLAIMER OF WARRANTY

Except as otherwise provided herein, we warrant that the Software is free from defects in material and workmanship and will perform substantially in accordance with the Software documentation under normal use for one hundred eighty (180) days after the receipt of the Software. If you notify us within such one hundred eighty (180) day period of any claimed defect in the Software, we will at our sole option and expense, and as you sole remedy, either repair or replace the defective Software. Or, if we cannot repair or replace the Software then we will accept the return of the Software at our expense and refund the purchase price of the Software.

EXCEPT AS STATED HEREIN, THE SOFTWARE AND SERVICES OFFERED BY US ARE PROVIDED ON AN "AS IS" AND "AS AVAILABLE" BASIS WITHOUT WARRANTIES OF ANY OTHER KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF TITLE, NONINFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. WE DO NOT WARRANT THAT THE SOFTWARE WILL BE UNINTERRUPTED, TIMELY, RELIABLE, SECURE OR ERROR-FREE AND EXPRESSLY DISCLAIM ANY WARRANTIES AS TO THE MATERIALS CONTAINED THEREIN, THE SERVERS USED OR THE GOODS OR SERVICES OFFERED BY US.

EXCLUSION OF CERTAIN DAMAGES

IN NO EVENT WILL EITHER PARTY BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING FROM THE USE OR THE INABILITY TO USE THE SOFTWARE (EVEN IF A PARTY OR AN AUTHORIZED DEALER OR DISTRIBUTOR HAS BEEN ADVISED OF THE POSSIBILITY OF THESE DAMAGES), OR FOR ANY CLAIM BY ANY OTHER PARTY. EXCLUDED FROM THE ABOVE LIMITATION OF LIABILITY IS LIABILITY FOR INDEMNIFICATION AS STATED HEREIN AND DAMAGES CAUSED BY THE GROSS NEGLIGENCE OR WILLFUL MISCONDUCT OF A PARTY.

TERM AND TERMINATION

This Agreement takes effect upon your acceptance of the terms of this Agreement and remains effective until terminated by either party in accordance with this Agreement. You may terminate this Agreement at any time by destroying all copies of the Software and Documentation in your possession and giving us prompt notice of same. This Agreement will automatically terminate if you fail to comply with any term or condition of this Agreement. Upon termination of this Agreement, you warrant and represent that you will immediately destroy all copies of the Software and Documentation or other materials provided to you hereunder, if any, that are still in your possession and provide us prompt written assurance of same.

CONFIDENTIALITY

Non-disclosure. You agree and acknowledge that the Software, its algorithms, protocols or interfaces, and the Documentation constitute proprietary and confidential information that belong to us (the "Confidential Information"). You also understand and agree that misuse and/or unauthorized disclosure of our Confidential Information could adversely affect our business. Accordingly, you agree that at all times you will (a) use and reproduce the Confidential Information only for the purposes of this Agreement and only to the extent necessary for such purpose; (b) restrict disclosure of the Confidential Information to your employees, consultants or independent contractors with a need to know and (c) not disclose the Confidential Information to any third party without our prior written approval. Notwithstanding the foregoing, it shall not be a breach of this Agreement for You to disclose Confidential Information if required to do so under law or in a judicial or other governmental investigation or proceeding, provided however, that You give us prior notice of the disclosure sought and You seek all reasonably available safeguards against widespread dissemination prior to such disclosure.

Remedies. You acknowledge that any violation of this paragraph may cause us immediate and irreparable harm and that the damages which we will suffer may be difficult or impossible to measure. Therefore, upon any actual or impending violation of this paragraph, we shall be entitled to the issuance of a restraining order, preliminary and permanent injunction without bond, restraining or enjoining such violation by you, your successors or assigns or any entity or person acting in concert with you. Such remedy shall be additional to and not in limitation of any other remedy which may otherwise be available to us by law.

INDEMNITY

We will at our own expense defend and hold you fully harmless against any action asserted against you (and specifically including costs and reasonable attorneys' fees associated with any such action) to the extent that it is based on a claim that use of the Software and any documentation or other materials being licensed by or provided to you under this Agreement infringes any patent, copyright, license or other proprietary right of any third party. You shall promptly notify us in writing of any such claim. If as a result of any claim of infringement against any patent, copyright, License or other proprietary right of any third party, you are enjoined from using the Software, or if we believe that the Software are likely to become the subject of a claim of infringement, We will at our option and expense will procure the right for you to continue to use the Software, or replace or modify the Software so as to make them non-infringing, or if it cannot do so within a reasonable time period, refund the Software fees paid by you pursuant to the Agreement.

GENERAL PROVISIONS

  1. This Agreement constitutes the entire agreement between you and us concerning the Software and Documentation and supersedes any prior or contemporaneous negotiations, discussions, understandings, purchase orders, communications, advertising or representations concerning the subject matter hereof.
  2. This Agreement may be modified or amended only in writing signed by you and us.
  3. In the event of litigation between you and us concerning the Software or Documentation, the prevailing party in the litigation will be entitled to recover attorneys' fees and expenses from the other party.
  4. You agree that the Software will not be shipped, transferred or exported into any country or used in any manner prohibited by any export laws, restrictions or regulations.
  5. The failure or delay of of either party to exercise any of its rights under this Agreement or upon any breach of this Agreement shall not be deemed a waiver of those rights or of the breach.
  6. If any provision of this Agreement shall be held by a court of competent jurisdiction to be contrary to law that provision will be enforced to the maximum extent permissible and the remaining provisions of this Agreement will remain in full force and effect.