Subclassing Content Query Web Part to override CAML query

The Content Query Web Part (CQWP) in MOSS is one of the popular out-of-the-box Publishing components which is used in content management sites, allowing you to get results from different sources.

But sometimes out of the box functionality is not enough to meet your requirements, and you need to customize CQWP. There are several resources describing how to do this - 1, 2, 3, 4

The most important features which are missed in CQWP are:

  • overriding query to use custom CAML
  • enabling web-part connections

To implement these functionality you need to subclass ContentByQueryWebPart class and override several methods.

Below I will describe what exactly need to be done to achieve desired behaviour.

Query Override

To have custom CAML query in your Web part you need to override CreateChildControls base method. You can find samples how to do this in the references above, but it's done so implicitly, that you can easily spend hours to find out why you code doesn't work and gives you different errors

The crucial part is in the way sending the query to the base class within overrided CreateChildControls

   1: protected override void CreateChildControls()
   2: {
   3:     this.QueryOverride = customQueryString;
   4:  
   5:     base.CreateChildControls();
   6:  
   7:     QueryOverride = string.Empty;
   8:  
   9:     CommonViewFields = string.Empty;
  10: }

First, you need to set your custom query to the "this.QueryOverride" to inform base class about query - line 3

Second, call base CreateChildControls() allowing your query being executed - line 5

Third and last - CLEAN query and view fields properties - line 7,9. Without this step you will get errors when open your Web Part in edit mode

Enabling Connection

The Content Query WP doesn't accept any connections by default. You need to implement this too. Everything you need to to is just add ConnectionConsumer attribute. But trick in setting the right attribute which is used in Parameter dialog box, when you connect two web-parts.

   1: [ConnectionConsumer("Another WebPart", "IFilterValues", AllowsMultipleConnections = true)]
   2: public void SetConnectionInterface(IFilterValues filterProvider)
   3: {
   4:     if (filterProvider != null)
   5:     {
   6:         // save provider with values
   7:         providerValues = filterProvider.ParameterValues;
   8:         _filterProviders.Add(filterProvider);  // variable declaration is List<IFilterValues> _filterProviders = new List<IFilterValues>();
   9:         List<ConsumerParameter> parameters = new List<ConsumerParameter>();
  10:         
  11:         // add params
  12:         parameters.Add(new ConsumerParameter("param1",
  13:                 ConsumerParameterCapabilities.SupportsSingleValue |
  14:                 ConsumerParameterCapabilities.SupportsEmptyValue));
  15:         parameters.Add(new ConsumerParameter("param2",
  16:                 ConsumerParameterCapabilities.SupportsMultipleValues |
  17:                 ConsumerParameterCapabilities.SupportsAllValue |
  18:                 ConsumerParameterCapabilities.SupportsEmptyValue));
  19:  
  20:         filterProvider.SetConsumerParameters(new ReadOnlyCollection<ConsumerParameter>(parameters));
  21:  
  22:         }
  23: }

Method name can be any, but pay attention which provider you are using . WebPart providers send data via different provider interfaces, for example when you are working with Filtering web parts (like "Current User Filter" web part) then you need to "listen" your incoming connections via IFilterValues (thx Mutaz for this findings), for other WB it could be IWebPartField or IWebPartRow.

If you are expecting to get data from WP via unsupported provider you connection link will be dimmed

Practical Sample

@d2design kindly asked to provide practical sample, for example how to use current user as a keyword :)

Actually, it's good example which shows how use both features I described.

To do this you need to have:

  1. ShareServices (SSP) with UserProfile, where current userName is stored
  2. "Current User Filter" WebPart, to get the userName from SSP. It returns you logged user name by default (not necessary actually, as well as SSP, because you could resolve you user name via standard asp.net User class when construct custom query)
  3. Enable WebPart connections as I described above. You need to use IFilterValue interface for "Current User Filter" and store your incoming user name in variable.
  4. Override query to include your userName in resulted custom query.

TIPS:

  1. When you are quering content which is not published and approved (like pages) you wont be able to see that content on the page in final view. You data will be available in page edit mode only, because they are treated as "draft" data.
  2. <OrderBy>CAML tag is not parsed by CQWP, you need to remove it from your query and set the related order field of CQWP class