I always wanted to do a series about easy to build, real life customer requests for SharePoint modifications. And as with most ideas, never really found the time to do it. Well, now’s as good a time as any!
Other parts:
So here is part 2, the custom Content Query Web Part Item Style
Aaahh, the Content Query Web Part, or CQWP for short. The Swiss Army Knife no real SharePoint solution architect can do without. If you are not familiar with the Content Query Web Part in SharePoint, here is a small introduction. I won’t go in depth on all the different advanced options you might have configuring the CQWP, because there are lots of good articles about that out there. I do focus on how you would package and deploy such a customization using Visual Studio 2010.
Introduction
The Content Query Web Part (CQWP) was first introduced in SharePoint MOSS 2007. It allows for querying and presenting SharePoint data in a very flexible and customizable way and is considered one of the most important Web Parts in SharePoint. It can roll up SharePoint items:
- Throughout your site collection.
- In one specific site and all of its sub sites.
- In one specific list.
As an example, say you want to do an aggregation (“roll up”) of all news articles from your news site and show the latest 3 with a thumbnail image on your home page? Easy with the help of the CQWP:
Image may be NSFW.
Clik here to view.
You start with configuring the CQWP through the settings in the Web Part toolbox.
| Image may be NSFW. Clik here to view.  |
Image may be NSFW. Clik here to view.  |
Image may be NSFW. Clik here to view.  |
The Query part determines where you will get your items from:
- Source: the scope of the query.
- List Type: choose the list type your items are in. In this case we pick Pages Library because our news articles are based on Publishing Pages stored in the default Pages library.
- Content Type: we only want to return Article Pages and not Web Part pages.
The Presentation part determines how the items will be presented on the page:
- Grouping and Sorting: speaks for itself. We pick 3 items, sorted by Article Date Descending.
- Styles: the group style is used when we group the items and is not used in this example. The Item style is the most interesting part and controls how the items are rendered. There are several options, so be sure to check them all out. For now we pick the default “Image on left”.
Fields to display:
This part is a new feature of the CQWP in SharePoint 2010. These fields are called “Slots” and are used to bind item fields to XSL properties. Every item style template can have its own set of configurable fields.
Customization
This post is about configuring and customizing the CQWP if you are not *that* happy with the standard behavior of the available Item Styles. My most requested style for instance, is not available out of the box:
Image may be NSFW.
Clik here to view.
- the title on top
- the image on the left, just beneath the title
- the byline to the right of the image
- the first 200 characters of the article content, beneath the byline
- a read more link
The standard CQWP gets its configuration from files in the Site Collection Style Library. These files are shared among all default Content Query Web Parts in your site. Let’s take a closer look at these files and the best way to do this is using SharePoint Designer. Just open up your site and navigate to the All Files section. Here you will find the Style Library with the XSL Style Sheets:
Image may be NSFW.
Clik here to view.
The file we are interested in is the ItemStyle.xsl. If you take a peek at the contents of this file, you will find several <xsl:template> elements which correspond to the different Style options you see configuring the CQWP. The names of the template should mostly speak for themselves. One exception, the “Image Left” is called “Default”.
Important:If you are not familiar with XSL you might want to read up on the subject. We keep our customization fairly simple, so you will just need a basic understanding.
We could of course modify the OOTB file using SharePoint Designer and create our customization that way. And that is a perfectly supported scenario, but with three major downsides:
- This is an OOTB file and if it is modified it is saved to the content database. If someone chooses to reset it to the site definition all your changes would be lost.
- Coexistence with other applications could be hard since you would have to share the default ItemStyle.xsl among them.
- If you mess up the default ItemStyle.xsl it could affect other Content Query Web Parts in the Site Collection.
So the best way around these issues is to supply our own style sheet with our Web Part.
To start, create a Visual Studio 2010 Empty SharePoint solution. Since we don’t have an assembly that needs Full Trust (see my earlier post about Sandbox solutions), we select a sandboxed solution.
Image may be NSFW.
Clik here to view.
Add a SharePoint module:
Image may be NSFW.
Clik here to view.
After the module is added to the project, delete the Sample.txt
Next we add the XSLT Style Sheet: Add New Item/ Data / Style Sheet. Remember to give it a .xsl extension instead of .xslt to be in line with OOTB SharePoint files.
Your Solution should now look like this:
Image may be NSFW.
Clik here to view.
My next step is to copy the content of the OOTB file in my new file to start off with.
Open the default file in SharePoint Designer and answer “No” to the question if you want to check the file out (see downside no. 1). Copy and Paste the contents in your new file in Visual Studio, clearing the current contents of the file.
You now effectively made a copy of the OOTB file and are ready to create your own rendering template (the actual CQWP Item Style customization).
To give yourself a head start, it is easiest to copy a similar one. In this case that would be “Image Left”, which is called “Default” in the ItemStyle.xsl. Just copy and paste the complete template (everything between and including the <xsl:template name=”Default” match=”*” mode=”itemstyle”> and </xsl:template> tags).
Rename our template to something like “ImageWithArticleContent” and replace the wildcard match (“*”) with our specific style.
<xsl:template name=”ImageWithArticleContent” match=”Row[@Style='ImageWithArticleContent']” mode=”itemstyle”>
The next step is to reorganize the template to match our requested design. Basically it just starts with the title and the image and finally the Byline (“description”). We then add a new property “Content” and display the first 200 characters and the Read More link. Because we add a property a new slot will be created in the CQWP toolbox as we’ll see later.
<xsl:template name="ImageWithArticleContent" match="Row[@Style='ImageWithArticleContent']" mode="itemstyle">
<xsl:variable name="SafeLinkUrl">
<xsl:call-template name="OuterTemplate.GetSafeLink">
<xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="SafeImageUrl">
<xsl:call-template name="OuterTemplate.GetSafeStaticUrl">
<xsl:with-param name="UrlColumnName" select="'ImageUrl'"/>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="DisplayTitle">
<xsl:call-template name="OuterTemplate.GetTitle">
<xsl:with-param name="Title" select="@Title"/>
<xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>
</xsl:call-template>
</xsl:variable>
<div class="item">
<div class="link-item">
<xsl:call-template name="OuterTemplate.CallPresenceStatusIconTemplate"/>
<a href="{$SafeLinkUrl}" title="{@LinkToolTip}">
<xsl:if test="$ItemsHaveStreams = 'True'">
<xsl:attribute name="onclick">
<xsl:value-of select="@OnClickForWebRendering"/>
</xsl:attribute>
</xsl:if>
<xsl:if test="$ItemsHaveStreams != 'True' and @OpenInNewWindow = 'True'">
<xsl:attribute name="onclick">
<xsl:value-of disable-output-escaping="yes" select="$OnClickTargetAttribute"/>
</xsl:attribute>
</xsl:if>
<xsl:value-of select="$DisplayTitle"/>
</a>
</div>
<xsl:if test="string-length($SafeImageUrl) != 0">
<div class="image-area-left">
<a href="{$SafeLinkUrl}">
<xsl:if test="$ItemsHaveStreams = 'True'">
<xsl:attribute name="onclick">
<xsl:value-of select="@OnClickForWebRendering"/>
</xsl:attribute>
</xsl:if>
<xsl:if test="$ItemsHaveStreams != 'True' and @OpenInNewWindow = 'True'">
<xsl:attribute name="onclick">
<xsl:value-of disable-output-escaping="yes" select="$OnClickTargetAttribute"/>
</xsl:attribute>
</xsl:if>
<img class="image" src="{$SafeImageUrl}" title="{@ImageUrlAltText}">
<xsl:if test="$ImageWidth != ''">
<xsl:attribute name="width">
<xsl:value-of select="$ImageWidth" />
</xsl:attribute>
</xsl:if>
<xsl:if test="$ImageHeight != ''">
<xsl:attribute name="height">
<xsl:value-of select="$ImageHeight" />
</xsl:attribute>
</xsl:if>
</img>
</a>
</div>
</xsl:if>
<div class="description">
<xsl:value-of select="@Description" />
</div>
<div class="content">
<xsl:value-of select="substring(@Content, 0, 200)" disable-output-escaping="yes"/>
<a href="{$SafeLinkUrl}">...Read More</a>
</div>
</div>
</xsl:template>
Important: Because we are cutting off the output rendering we potentially leave open HTML tags! See this post about a solution.
Unfortunately, there is no SharePoint GUI way to link our custom Item Style to the Content Query Web Part. The way around this, is to deploy a pre-configured Web Part file with our solution.
Add a Web Part to our project:
Image may be NSFW.
Clik here to view.
Delete the Web Part class file, since we are only interested in the .webpart file.
Add an empty (unconfigured) CQWP to your SharePoint Page and export this Web Part.
Open the exported file in notepad or Visual Studio and copy the contents.
Paste this in the .webpart file in our Visual Studio project.
- Set the Title and Description to the required values.
- Set the ItemLimit to 3
Modify the ItemXslLink property to link our custom style sheet:
<property name="ItemXslLink" type="string" >/Style%20Library/Xsl/CustomItemStyle.xsl</property>
Modify the ItemStyle property to match our custom style:
<property name="ItemStyle" type="string">ImageWithArticleContent</property>
Save the file.
Important: since our solution doesn’t need an assembly, we need to exclude it from the package. Select your project and set the “Include Assembly In Package” to false.
We can now deploy our solution and test our work.
Image may be NSFW.
Clik here to view.
Image may be NSFW.
Clik here to view.
You can download the Visual Studio 2010 solution here.
Image may be NSFW.
Clik here to view.
Image may be NSFW.Clik here to view.
