Customising the Content Query Webpart

I recently went through the process of customising a SharePoint 2007 webpart, the Content Query Web Part, to overcome some limitations with it as it comes ‘out of the box’. It would be nice if the Content Query webpart allow you to select a list AND a view of the list but it only allows you to select the list.
First the problem. I have a custom list with a large number of custom columns within a parent site. Below this site are a number of related sites that I wish to display a information within that is pulled from the custom list in the parent site. Each of the custom column relates to one of the subsites and contains either a role description or and X (indicating the row is not applicable for that web site). For example the web part in the Safetysubsite should only fields display the rows in the custom list that have a role description in the Safety column. The other issue is that we want to display custom fields for these records as well.
Now the step I went through to solve the problem. Let’s assume the custom list will be called Departments.
  1. Create the custom Departments list and columns (Safety, HR, Environment, Finance etc.) in the parent site. Populate it with data.
  2. Add the Content Query webpart to the subsite, in this example Safety.
  3. Modify the webpart Query section Source properties to show items from the custom list, the List Type to be ‘Custom List’ and the Content Type to be ‘List Content Types’ with ‘Item’
  4. Modify the webpart Presentation section Styles to have a Group Style of ‘Default’ and Item Style of ‘Title and Description’.
  5. Apply these settings. Unless your custom list uses the standard Title and Description columns you probably wont see any content from you list yet.
  6. Update the Title field in the Appearance section to contain a relevant title for your web part content. In this case I added ‘Department Contacts’
  7. Now open the Edit menu from the web part, select Export and save the webpart xml file to your local disk.
  8. We have to edit the properties of the webpart to recognise and display our custom fields. Open the webpart file in SharePoint Designer or your preferred XML editing tool. Notepad will do if you have nothing else.
  9. Locate the CommonViewFields property. This property is used to specify the additional fields we want to display in our customised webpart. Add the internal names of the columns and the type e.g.
    <property name="CommonViewFields" type="string">Dept_x0020_Title,Text;Staff_x0020_Name, Text;Safety,Text;HR,Text;Environment,Text;</property>

    Note: You cannot use your columns’ display names here. It is necessary to use the internal column names. To find them check the properties of the column in the list or document library. Right-click the column, and then click Properties. The internal name of a column appears in the Address (URL) property after 'Field='.

  10. Next we have to map the internal column names to the columns’ Title and Description present in the default XSLT transformations. To do this, edit the DataColumnRenames property. INclude renames for all the columns you included in the CommonViewFields property. In this example I’m mapping the custom column ‘Staff Name’ to the Title field and the standard ‘Phone’ column to the Description field e.g.
    <property name="DataColumnRenames" type="string">Staff_x0020_Name,Title;Phone,Description</property>
  11. Save the wepart file.
  12. Delete the current Content Query webpart from the sub site.
  13. Now we can import the customised .webpart file and add the new webpart to the relevant zone in the sub site. To import the .webpart file, click  Add a Web Part in the relevant zone, and then click the Advanced Web Part gallery and options link at the bottom of the screen. Click the Browse button in the Add Web Parts area on the right and select Import. Browse to the .webpart file, and then click Upload.
  14. Drag the imported webpart to the appropriate zone in the page. The webpart now displays the staff member name and their phone number for EVERY row in the custom list. What we now ned to do is modify the XSLT to filter the records for us and add any additional custom fields and formatting we want. In this case I’d like to display the person role within the department next to their name.
  15. Open the root level SharePoint site in Microsoft Office SharePoint Designer and locate the file ItemStyle.xsl. It should be in /Style Library/XSL Style Sheets/
  16. Check out ItemStyle.xsl
  17. Locate the xsl:template element that most closely matches the style we want, in this case the Default one, and copy the entire element e.g. <xsl:template name="Default" match="*" mode="itemstyle">  through to its matching </xsl:template> tag. Paste it at the end of the file before the closing tag.
  18. Change the name attribute of the copied xsl:template. I used "SafetyDptRolesStyle".
  19. Change the match attribute to "Row[@Style=’SafetyDptRolesStyle’]".
  20. Next, within the new xsl:template element change the  XSL from:
                <a href="{$SafeLinkUrl}" target="{$LinkTarget}" title="{@LinkToolTip}">
                        <xsl:value-of select="$DisplayTitle"/>
                    <div class="description">
                        <xsl:value-of select="@Description" />

    to the following which will display the contents of the Safety column, their role in the Safety Department, next to their name. The identifier used here is equivalent to that referenced in the CommonViewFields property in the webpart definition.
                 <a href="{$SafeLinkUrl}" target="{$LinkTarget}" title="{@LinkToolTip}">
                         <xsl:value-of select="$DisplayTitle"/> – <xsl:value-of select="@Safety"/>
                     <div class="description">
                         <xsl:value-of select="@Description" />
  21. Now we have the customised content displaying but it is still showing all rows in the custom list. To filter this list we need to modify the XSLT again. Locate the <div id="linkitem" class="item"> tag within the xsl:template element we’ve just changed and add the following conditional code immediately after it:
                     <xsl:if test="@Safety != ‘X’">
    Don’t forget to close off the xsl:if statement by adding </xsl:if> in the appropriate location e.g.
  22. Save ItemStyles.xml and check it back in.
  23. If you now modify the webpart and look at the Presentation section the Item Style menu should now contain the new SafetyDptRolesStyle style. If you select this and apply it you should now see the filtered and customised content from the custom list in the parent web site.

Some notes on my experience with this approach….
Firstly I suspect that similar filtering could be achieved using the filter properties within the webpart definition but there doesn’t seem to be any information around about how to do this in Beta2 or the Tech Refresh yet.
Next, using this approach I have to define a specific Item Style for each sub site as the filtering lives within the XSLT. Lots of sites means lots of styles that in reality can only be used within one site  but will appear in the Item Styles menu for all Content Query Web parts across the farm.
Finally, it looks like there is some form of caching going on in SharePoint 2007 with the webpart definition and Styles as when I had completed this and asked my customer for feedback they couldn’t see the effect of the XSLT work for a while after I could see it. It is more than likely either Cross-List Query Caching or Output Caching that is causing this but I haven’t had time to look into it further.

23/10/06 Postscript: I found that users were still have the problem view the changed style and infact were receiving an error message whereever the Content Query webpart was used. Upon a little more investigation I found that although I have checked in the ItemStyle.xml file in SharePoint Designer it was only checked in as  minor version and hence could not be seen by anyone but me. Once I went to the parent site, clicked View All Site Content, selected Style Library followed by XSL Style Sheets and finally did a Publish Major Version on the ItemStyles.xml file the problems went away.


Leave a comment

Filed under Microsoft Office Sharepoint Server 2007

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s