Customizing the Content Query Web Part and Custom Item Styles

With Microsoft Office SharePoint Server (MOSS) 2007 and Windows SharePoint Services (WSS) 3.0, we can use the
Content Query Web Part (CQW or CQWP) to display SharePoint content from another source on a SharePoint page.
This web part is rather nifty and one of my new favorite things about MOSS 2007.
At first glance you tend to pass it by, then when you see what it can do, it is
pretty cool.  Imagine if you will, creating a list in SharePoint 2003 and
then adding it as a web part to your WSS home page or SPS portal area.  You
are then limited to controlling the view through the Web Part Tool Pane by
hiding or showing various columns.   With the CQWP, you can now
control how that content is displayed. You can wrap HTML code and styles to
format the display nearly however you wish.  Here is a quick example of a CQWP
used on the site:

Sample CQWP

The data that is used here is stored in a Pages library for a News site, which of course is just
a list. Through Item Styles used by the CQWP, I can control the
display of the data nearly any way I wish.

Creating the Custom Item Style

First, hands down this is a fantastic blog post to read on the subject:

Configuring and Customizing the Content Query Web Part
on the
ECM Blog.   That
post is what I followed to create custom Item Styles.  This article is just
to help fill in the blanks on how to use this process for your own site.

I am going to breeze through some of the steps that are documented on the ECM
blog, and go into others in more detail that are not documented in that post.

Add a CQWP To The Site

  1. Add a Content Query Web Part to a page in the site. By
    default the CQWP will display all of the pages in the site.
  2. Now choose to Modify the Shared Web Part and in the
    Web Part Tool Pane, expand Query and
    change the Source
    settings to the site or list where you want to query the data from.Query settings in the Tool Pane
  3. Optionally update other settings to further refine the data view, such
    as Content Type and Filters. Select Apply.
  4. For more details, look and Steps 1 and 2 in the

    Configuring and Customizing the Content Query Web Part

Create the Custom Item Style

Now we have a rather boring view of some data. We use Item Styles
to jazz up the formatting and selectively show various content, such as
Title, Description and Body.  There are already several Item Styles
available out-of-the-box, but in my opinion, they have limited use. Go ahead and
play around with what is available, there maybe something there that is perfect
for your needs and it helps you to see what you can do with an Item Style.
In the Tool Pane, expand Presentation and experiment with the
drop down options under Styles. Select Apply
to see the changes.

Before we style any content, we need to have the web part pull in the content we want
to display. Some
content is already pulled in by default, such as Title.  For anything else that is not
pulled by default, we need to tell the web part to get those fields. But how do
we know which fields are already being pulled in?  It is a bit of a chicken
and the egg ordeal, so here are my suggested steps for working all of this
information out:

Heads up!  Here is where we deviate from the

Configuring and Customizing the Content Query Web Part


  1. Open the site in SharePoint Designer (SPD). Navigate
    to Style Library, then XSL Style Sheets.
    Open ITEMSTYLE.XSL.  Now doing this will customize (uhghost)
    the file! But we can always reset this back to the Site Definition and
    restore it to it’s original state.  Be sure to check out the file via
    SPD or the Site Content and Structure screen in the site.
  2. Take a minute to look at the file.  Every time you see “<xsl:template…”
    that is the start of a new Item Style.  There is one for each of
    the out-of-the-box Item Styles that show up in the Styles drop down in the
    Web Part Tool Pane.  For every custom Item Style that is needed, a new
    xsl:template block will have to be created.
  3. Scroll down to the bottom of the file. Copy the last
    code block and paste it above the closing xsl:stylesheet
  4. Change the name and match properties
    in the Templatetag to a unique name of your choice:<xsl:template name=”MyCustomStyle” match=”Row[@Style=’MyCustomStyle‘]”
  5. Next we will add a little snippet of code within the Template tags that
    will render the names of the fields that are being passed.  Note that
    this code will be temporary! We don’t want to leave this in the finished
    Item Style.<xsl:template name=”MyCustomStyle” match=”Row[@Style=’MyCustomStyle’]”
    <xsl:for-each select=”@*”>
    P:<xsl:value-of select=”name()” />
  6. Save the file.  Return to the site (in the browser) and refresh
    the page.  Open the Web Part Tool Pane for the CQWP and expand
    , then under Styles change the
    Item Style
    to the new custom style in the drop down.  Select
  7. The CQWP will now list out all of the fields that are being passed.CQWP Passed Fields

    After each P: is the internal column name for each field
    that is being passed.  These internal column names are what is
    referenced later in the code to display the data.  For example:

    <div class=”description”>
    <xsl:value-of select=”@Description” />

    Description is the internal column name that is being
    wrapped and styled with a DIV tag and is the content that will display on
    the page.  So we can look at the names displayed in the CQWP and see
    what data is already available for our use.  For example, in this
    particular case we have Title, Author, Publishing Rollup Image and
    Publishing Date (PubDate).

Find the Additional Data

Our first goal was to determine what content is already being pulled into the
web part.  Now that we have done that, next we need to tell the web
part to pull the other data we need. To do this we will need to get the internal
column names for the necessary column(s) from the Content Type that is being
used for the list.

  1. In the site, open Site Settings, then select
    Site Content Types
    .  Locate the Content Type that the list is
    using.  For example:

    • If you are querying a site and showing pages, look under Page Layout
      Content Types.
    • If you are querying a list, look under List Content Types.
  2. Select the Content Type name to view the Columns. Locate the column that
    needs to display in the custom item style. Locate the internal column
    name one of two ways:

    1. Way One: Click the column name.  In the Change Site Content Type
      screen, hover over the Edit site column in new
      link and note the URL that appears in the Status Bar.
      The internal column name appears after Field=. It also
      appears on the Site Content Type screen we just came from in
      the Status Bar, it is just inline with a lot of other characters. Often
      the string is too long in the Status Bar to display the Field property.Internal column name
    2. Way Two: Right click the link and
      select Properties.Content Type Columns

      The URL listed in the General tab has the info we need,
      just hidden below the viewable area.  Select the URL with your cursor,
      hit Ctrl + A to select the full URL, the copy and paste the
      URL into Notepad.

      Copy the URL

      In the pasted URL in Notepad, locate Field=.
      The name that follows in the internal column name.

      Internal Column Name

Now that we have our internal column name, we can return to the
instructions in the

Configuring and Customizing the Content Query Web Part

post and proceed with their Step 3.

Modify the CQWP to Include Additional Data

  1. In your site, in the CQWP, select Export from the web part’s Edit menu.
    Save the .WEBPART file locally.
  2. Open the .WEBPART file in Notepad and search for “CommonViewFields“.
    Replace the Property tag line of code with the code listed below, using your internal column
    name and the corresponding field type. It is very
    important that the field type listed is the correct type for the the data.
    If the field type is wrong, it won’t break the site, but the Item Style
    won’t display the content. Available values are:

      • Text
      • Note
      • Number
      • Currency
      • Integer
      • Boolean
      • DateTime
      • Threading
      • Lookup
      • Choice
      • URL
      • Counter
      • DisplayOnly (DisplayOnly field type has no storage of its own)

    And I have either used or seen these used, but have not seen them documented anywhere:

    • RichHTML
    • Image

    Some field types are easy to figure out.  If we are calling a date, use
    DateTime. For Title use Text, for body content use
    String together multiple entries with a semicolon between each pair: Name, RichHTML; Name2, Text.

    <property name=”CommonViewFields” type=”string”>InternalColumnNameGoesHere,

    For example: <property name=”CommonViewFields” type=”string”>Comments,

    At the end of this article I cover how to find out the field type.

  3. Save the file and import it back into the site. (Add a Web Part
    Import – select the .WEBPART file – Upload
    – Drag and drop the web part onto the page).

Now we have two CQWPs on the page.  We can remove the original
one. We should also see the newly added internal column name(s) appear in the
list of fields.  Yay!!  18 steps later and now we are ready to style!!
No, really, this process moves pretty fast.  Now it is time to return to
the XSL file and start making things pretty.

Style the Data in the Item Style

  1. Return to SharePoint Designer and your custom template in ITEMSTYLE.XSL.
  2. For every internal column name that has been included in the web part and
    needs to display in the Item Style, add it to the template using the
    tag:<xsl:value-of select=”@InternalColumnNameGoesHere” />

    For example: <xsl:value-of select=”@Comments” />

  3. Wrap HTML around the tag to format the data. 
    Please note!!
    the page renders the CQWP, the site grabs the Item Style for each line of
    data.  So we can’t add a table and expect that each line of data will
    be in a row.  Instead we get a full table for each line of data.
    Keep this in mind as you style the HTML around the data.
  4. Save the file, go to the site and refresh the page.  The new styled
    content will appear.
  5. To remove markup tags, please refer to about the middle of Step 4 in the

    Configuring and Customizing the Content Query Web Part
  6. When done styling the Item Style, remove the code that lists the fields.

    <xsl:for-each select=”@*”>
    P:<xsl:value-of select=”name()” />

The Other Internal Column Names & Finding Field Types

If by some odd reason you were following along with this article and trying
to do a CQWP Item Style on an events list, like I was, at the end of this you
were probably scratching your head as to why no content would display on your
site.  While writing this article I discovered that the internal column
name listed in the Content Type isn’t necessary the internal content name that
should be used for Item Styles.  I am sure I will make some developer have
a heart attack with my terminology or what have you, but after a lot of
searching I tracked down the real internal column names in the SCHEMA.XML file
for each feature (every list type is a Feature). Once I pulled the right
internal column name in my .WEBPART file and in ITEMSTYLE.XSL, things worked
like a charm.  Consequently, SCHEMA.XML also lists out the field types for
each column.

  1. On the web server, open the SCHEMA.XML file for the Feature. The
    Features are located in the Feature directory:
    Local Drive:Program FilesCommon FilesMicrosoft Sharedweb server
    extensions12TEMPLATEFEATURES(Feature Name)
  2. Locate the SCHEMA.XML file.  It will be in one of the two
    subdirectories in the Feature.  Open the file in Notepad.
  3. Locate the FIELDS element.  Within Fields are all of the FIELD
    elements used in the Feature.  Each one lists the column Type (field
    type) and Name (internal column name).Schema file
  4. Use this column type and name in the .WEBPART file and in the

To wrap up my commentary with the Events list, I changed “Comments” to “Description” and the CQWP
successfully displayed the content in the CQWP.

Custom Item Style Samples

Here are some samples you can check out to see how it all comes together:

Code: Download
Screenshot: Sample Item Style
Code: Download
Screenshot: Sample Item Style

Dustin Miller and Heather Solomon from SharePoint Experts