I would like to preface this blog post with the recognition that it is a very lengthy blog post. I’m sure I could have condensed it to a much shorter post, but I believe what we are able to accomplish with the Ratings & CQWP is quite powerful and wanted to ensure the full details were documented.
When SharePoint 2010 debuted, with it came some very cool new Social Features. One of those features is Ratings on individual list/library items. The Ratings Feature allows users to rate each list item, using a 1-to-5 Star Scale (1 being worst and 5 being best).
 |
| Ratings in the List View Page |
After a user provides their own personal rating on an item, that value is stored in the SharePoint database and a SharePoint Timer Job is run, whose interval is configurable, taking all of the ratings provided from all users on each list item and generating the average rating for that specific list item.
Once the timer job has finished running, when that list item is viewed again the display of the star ratings displays the average rating to the nearest half star.
 |
| Ratings in list view page after timer job has run. |
On a recent project, the request was to provide the ratings functionality outside of the typical list view when editing the list. Specifically, the desire was to use a CQWP (Content Query Web Part) to roll up all images stored throughout the site collection into a single view on a landing page so users could view the images and rate them all in one central location.
I will began by providing an overview to the process I went through to identify if and how to successfully implement this request and then I will show in detail how to accomplish providing the full ratings functionality in a CQWP by using the custom .xsl file(s) I provide in this post for download.
The request was certainly reasonable. My opinion is that for the standard everyday user, the look and feel of the system based list view page leaves alot to be desired, even when you apply a custom master page to the system pages.
If we could/would fulfill this request it would be very cool and open a wide range of ways the ratings could be interacted with, but the concern was without using compiled .net code, would it be possible?
I began investigating first by seeing what ratings information about the list item was exposed to the CQWP. What I first found was the Average Rating value is returned using the standard customizing methods for the CQWP, which included modifying the .webpart file and adding the ratings field to the “CommonViewFields” property. The value returned is a numeric decimal value. This was great if all you wanted to do was display the average rating as a static, non-interactive value for the list items.
 |
| Average Rating value being returned as decimal value |
My next step was to take the actual list view web part for my list and drop that onto a page, ensuring that the ratings column was displayed by modifying the view. I wanted to see if the SharePoint Out-Of-The-Box (OOB) web part provided the fully functioning ratings feature that you have when directly editing the list itself.
Sure enough, the list view web part did provide the fully functional ratings feature, but again, a list view web part is not as configurable and brandable as the CQWP can be, so I continued my research.
 |
| List view web part providing full ratings functionality |
FUNCTIONAL DISCOVERY
Using FireFox with FireBug installed, I started analyzing the HTML output of the ratings section of the list view web part and found the following:
1. The ratings functionality is driven by a combination of CSS and JavaScript. A javascript file named “ratings.js” was now included on the page and is located in the “_layouts” folder.
 |
| Ratings.js now being referenced in the page. |
 |
| Custom unique <SPAN> ID |
 |
| Custom unique JavaScript function |
NOTE: This actually causes a bug to occur if you were to load more then one list view web part on a single page. I will expand on this later.
 |
| SharePoint web service call for Ratings |
Knowing that the list view web part uses XSL and with a little help from Google searching on the information I gathered above, I located the OOB SharePoint XSL files and found an XSL file that stood out named “fldtypes_Ratings.xsl”.
 |
| SharePoint OOB XSL files in “_Layouts/XSL” folder |
After analyzing the XSL in this file, I found that this was indeed the XSL file responsible for generating the ratings HTML output as well as the JavaScript functions needed to provide fully functioning ratings interaction.
 |
| Code in fldtypes_Ratings.xsl |
CQWP INTEGRATION
Now that we know how the ratings functionality works as well as what XSL code is used to generate the functionality, the next step was to integrate this XSL code into my CQWP XSL.
This step was certainly more lengthy and painful than I can possibly describe. Anyone who works with SharePoint, CQWP & custom XSL knows that when your XSL generates an error, SharePoint is less then descriptive about what the error is.
Without boring you and reliving the HOURS and HOURS of trial and error I spent, I found that three additional files were associated in part or in whole to the “fldtypes_Ratings.xsl” file. Those were:
- “fldtypes.xsl” (2345 lines of code)
- “vwstyles.xsl” (2407 lines of code)
- “main.xsl” (mostly xsl parameter declarations)
My analysis of the “fldtypes_Ratings.xsl” led me to believe that not all of the code found in the additional XSL files were needed. I also found that the “fldtypes_Ratings.xsl” needed some slight modifications to work with my CQWP XSL. The following are the steps I took to integrate the “fldtypes_Ratings.xsl” and associated files/code into my CQWP XSL.
STEP 1:
Since we know what four XSL files were needed to make the ratings functionality work, I took a copy of each of them from the “_layouts/xsl” folder and uploaded them into my “XSL Style Sheets” folder in the “Style Library” of my root site. “main.xsl” imports “fldtypes.xsl” and “vwstyles.xsl”, so you must modify “main.xsl” to import from the “Style Library” and not the “_layouts/xsl” folder
 |
| Modify newly created Main.xsl to import from the Style Library |
I also modified my CQWP to use a custom “ItemStyle.xsl” & “ContentQueryMain.xsl” file. Additionaly within my custom ContentQueryMain.xsl file, I imported the two XSL files needed to provide the ratings functionality.
 |
| Import Main.xsl and fldtypes_Ratings.xsl into Your ContentQueryMain.xsl |
STEP 2:
In my analysis of the “fldtypes_Ratings.xsl” I found that it uses the Average Rating value that I can retrieve from the list item that I described previously, so I ensured my CQWP was returning this value by modifying the “CommonViewFields” property within the .webpart file.
 |
| Edit the CommonViewFields in the .webpart to include the AverageRating Value |
What I also found in the “fldtypes_Ratings.xsl” was that it’s XSL template was executing based on a match to the fields guid. Although I wanted to be able to execute the template manually within my CQWP ItemStyle XSL for each list item. So the first change I made to this file was to provide the ratings template a name allowing me to call the template manually. I provided the template the name “RatingsTemplate”.
 |
| New template name to call manually in the ItemStyle |
STEP 3:
After I ensured that the AverageRating value was being returned in my XSL and including the four XSL files needed for the ratings functionality did not generate any errors, I attempted to call the “RatingsTemplate” XSL template.
 |
| Manually calling my “RatingsTemplate” within my ItemStyle.xsl |
SUCCESS!!!!!!!!!!!!
My CQWP successfully provided fully interactive ratings for the each list item my CQWP was returning.
 |
| On page load, you can see the average rating in blue. |
 |
| Upon hover of the Stars, you can see the current rating in the tooltip |
STEP 4:
My next step, which is where I spent many hours, was to condense those four XSL files down to just the required XSL code needed to provide the ratings functionality. One of the biggest frustrations is many of the templates within each of the additional XSL files had dependencies on each other. One template in “fldtypes.xsl” would reference another template in “vwstyles.xsl”. This mean’t I could not just simply delete the entire files altogether.
With that in mind, I went template by template and removed the templates individually, ensuring that it didn’t break the CQWP.
I was also able to find all the additional XSL code the “fldtypes_Ratings.xsl” needed and included it directly in that file, allowing me to condense all the functionality into a single “Ratings.xsl” file.
NOTE: If your average rating value is returning 0 or blank, be sure you have rated the list item(s) and the timer job has ran to compile the average rating value.
STEP 5:
After condensing all the code into a single XSL file, I performed further testing and found some additional changes that needed to be made to the “Ratings.xsl” XSL code.
The first change I found that was needed proved to actually be a bug in how SharePoint implements the ratings functionality, even when you use OOB List View Web Parts. As described above, each list item has a unique ID associated to its <SPAN> wrapper for the ratings HTML and a corresponding uniquely named JavaScript function.
The problem is the uniqueness of the ID and JavaScript function name is tied to the list item’s numeric list ID value. Where this causes a problem is if you have two different list view web parts on a single page and the web part is displaying a list item from each list where the ID’s are the same. This means if each list were to only have one item, both list items would have a numeric list ID value of “1”. This breaks the uniqueness of the <SPAN> ID and JavaScript function name that the ratings JavaScript relys on.
This will cause only one of the items ratings functionality to work. The other will simply not respond to any hover events of the mouse.
To fix this problem within my custom “Ratings.xsl”, I modified the XSL to create a unique id by taking the list item numeric ID and appending the first 8 characters of the list guid. This allowed us to ensure a completely unique value would be used for each item.
 |
| Custom XSL to ensure unique ID for <SPAN> and JavaScript function |
STEP 6:
I also found that the tool tip hover event of the ratings control, which displays your selected rating and/or if no ratings have been selected and that verbiage was not displaying any data. While I would like to investigate why, I have not had time to do so. To fix this temporarily, I simply hard coded the alert verbiage in the “Ratings.xsl”. This does not hard code the ratings value included in the tool tip, just the descriptive text.
 |
| Hard coded labels for hover tool tip |
CQWP IMPLEMENTATION
You can download my custom “Ratings.xsl” file below. You simply need to include a import reference to the file in your custom “ContentQueryMain.xsl” file and call the “RatingsTemplate” template where you want the Ratings HTML and JavaScript to be output in your custom CQWP.
DOWNLOAD COMING SOON
I will soon provide the fully functional web part you see in the example screenshots above as a downloadable ZIP file. I will provide it as a WSP File that can be simply deployed as a Feature as well as provide a version that can be manually implemented by uploading all of the appropriate files (XSL, CSS, etc.) to the appropriate libraries in SharePoint. I will include documentation on how to do all of that.
Feel free to provide comments or questions below.
Awesome post. I'm doing the same thing except with published pages. Looking forward to your download. Let me know when it's ready.
Thanks
great post :), reduced lots of time;
could you please let know where we can download your "Ratings.xsl" file? I didnt find the link here.