Using Font Awesome with SharePoint CQWP URL List

A few months ago as we were looking at some of the design aspects of our SharePoint implementation, I realized that the issue of icons really needed to be addressed.  Up until that point we had not done much with icons so users got a lot of unbroken text, and what we were doing was just a matter of finding something to work at the moment.  

So I set a few guidelines for what I wanted:

  • cohesive package: All of the icons should have a similar look.  This makes the page look like it is planned.  A package also provides a lot of options quickly when you need an icon.
  • economically feasible: I am willing to pay for quality, but I don’t have a very large budget.  So cheaper is better.
  • retina support: A good portion of new devices, particularly mobile, have very high resolutions screens.  The icons should always look crisp.
  • small file size: Many of our users are on connections with very limited bandwidth.  The icons should quickly load even on slow connections.

With these concepts in mind, it did not take long for me to become aware of icon fonts, and in particular Font Awesome. It fit all of my needs quite nicely being a full package of icons, it is free, fonts are vector so scale well, and they are all in a small font file.

I really like the idea behind the built-in summary link web part in SharePoint, but there were three things that did not work for me.  First, it only allows for standard image icons, and I am now using font icons.  Second, it is not very intuitive for end-users to add web links.  Finally, the data is not stored in a list so it does not work the same way as the rest of SharePoint which limits my ability to customize it.

So, I set out to build my own.  I have been becoming more fond of the Content Query Web Part (CQWP) because of the level of control that you have over the HTML code it produces.  It is also all done server side so there is less of a hit on my clients on slow connections.  Of course the first step in a coding project is to find somebody else who has done something similar and grab their code.  Thankfully Marc Anderson had written a blog post on building a URL link list in CQWP (which he had grabbed from another source).

Below is the code that I came up by tweaking what Marc posted and adding in support for font icons, followed by comments below about specific things I was trying to achieve.

<xsl:template name="LinkListWithIcons" match="Row[@Style='LinkListWithIcons']" mode="itemstyle">
   <xsl:variable name="SafeLinkUrl">
      <xsl:call-template name="OuterTemplate.GetSafeLink">
         <xsl:with-param name="UrlColumnName" select="@URL"/>
   <xsl:variable name="DisplayTitle">
      <xsl:call-template name="OuterTemplate.GetTitle">
         <xsl:with-param name="Title" select="@URL"/>
         <xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>
   <xsl:variable name="TheLink">
      <xsl:value-of select="substring-before($DisplayTitle,',')"/>
   <xsl:variable name="TheLinkTarget">
         <xsl:when test="contains($TheLink, '')">_self</xsl:when>
   <xsl:variable name="faIconName">
         <xsl:when test="string-length(@faIcon) &gt; 0">
            <xsl:value-of select="@faIcon"/>
   <div id="linkitem" class="lbt-LinkListWithIcons" >
      <xsl:call-template name="OuterTemplate.CallPresenceStatusIconTemplate"/>
      <i class="fa fa-fw {$faIconName} lbt-LinkList-Icon"> </i>
      <a href="{$TheLink}" target="{$TheLinkTarget}" title="{$TheLink}">
      <xsl:value-of select="substring-after($DisplayTitle,',')"/>

There are a few things that I want to point out:

  • The variable for the “TheLinkTarget” chooses whether the link will open in a new window/tab or in the current window.  If the URL contains “” then I know that the link is within the SharePoint site and so should open within the current window/tab.  Links to external sites open a new window/tab.
  • There is a place for a field in the SharePoint URL list to provide the name of the Font Awesome icon for each link.  In the description of the field, I provide a link to the Font Awesome cheat sheet so the user can pick the icon that they think is the most appropriate.  Of course there are going to be times where an icon is not selected.  In those cases, the XSL above selects a default icon, the “fa-external-link-square”.
  • A lesson that I learned with the CQWP is that the <i> element cannot be empty.  If it is, for some reason when it is converted to HTML the ending tag gets added much later which makes for some very interesting page layouts.  The only solution that I have found is to put a non-breaking space into it by way of the code point (I can’t get it to display here, but if you look at the XSL code image you will see it in red).
  • I added two classes for styling, “lbt-LinkListWithIcons” on the div, and “lbt-LinkList-Icon” on the icon.  The div just has some padding to separate the links and adjusts font size and color.  For the icon, I put a background on it that matches the rest of the branding on the page.  Note that the padding on the right is smaller to compensate for the extra space from the non-breaking space that I had to add to the <i> element. Font Awesome has a system for stacked icons with a circle behind, but it just got too large and complicated since the <i> elements cannot be empty.

I am still working on the styling, so if you use this and come up with a better looking list, please post back.


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