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 ShareSquared.com site:

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. 
   
   
   
   
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 post.

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 post.

5. 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.
6. 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.
7. Scroll down to the bottom of the file. Copy the last xsl:template code block and paste it above the closing xsl:stylesheet tag.
8. Change the name and match properties in the Template tag to a unique name of your choice:
   
   <xsl:template name="MyCustomStyle" match="Row[@Style='MyCustomStyle']" mode="itemstyle">
   
9. 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']" mode="itemstyle">
   <xsl:for-each select="@*">
       P:<xsl:value-of select="name()" />
   </xsl:for-each>
   
10. 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 Presentation, then under Styles change the Item Style to the new custom style in the drop down.  Select Apply.
11. The CQWP will now list out all of the fields that are being passed.
    
    
    
    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" />
    </div>
    
    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.

12. 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.
13. 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 Column screen, hover over the Edit site column in new window 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.
       
       
       
       
    2. Way Two: Right click the link and select Properties.
       
       
       
       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.
       
       
       
       In the pasted URL in Notepad, locate Field=.  The name that follows in the 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

16. In your site, in the CQWP, select Export from the web part's Edit menu. Save the .WEBPART file locally.
17. 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 RichHTML. String together multiple entries with a semicolon between each pair: Name, RichHTML; Name2, Text.
    
    <property name="CommonViewFields" type="string">InternalColumnNameGoesHere, FieldType</property>
    
    For example: <property name="CommonViewFields" type="string">Comments, Note</property>
    
    At the end of this article I cover how to find out the field type.
    
    
18. 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

19. Return to SharePoint Designer and your custom template in ITEMSTYLE.XSL.
20. 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 xsl:value tag:
    
    <xsl:value-of select="@InternalColumnNameGoesHere" />
    
    For example: <xsl:value-of select="@Comments" />
    
    
21. Wrap HTML around the tag to format the data. 
    Please note!! When 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.
22. Save the file, go to the site and refresh the page.  The new styled content will appear.
23. To remove markup tags, please refer to about the middle of Step 4 in the Configuring and Customizing the Content Query Web Part post.
24. When done styling the Item Style, remove the code that lists the fields.
    <xsl:for-each select="@*">
        P:<xsl:value-of select="name()" />
    </xsl:for-each>

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 Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\(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).
   
   
   
4. Use this column type and name in the .WEBPART file and in the ITEMSTYLE.XSL file.

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:
Code:	Download
Screenshot: