Extending csrShim for Custom XML (JSLink)

Applies to SharePoint 2013, 2016, Office 365

Introduction

csrShim can be used to enable Client Side Rendering (CSR) with a variety of XML Feeds when used with the XMLViewer web part (RSS, RDF, Atom, and Atom2). Additionally, csrShim provides easy extension points to map Custom XML into the ContextInfo (ctx) object allowing developers to use CSR (JSLink) capabilities with custom XML formats.

This is not a comprehensive guide to the XMLViewer web part or csrShim but provides the information necessary to extend csrShim. For additional details about how to use csrShim see the csrShim Documentation on GitHub. For additional details about using csrShim with the XMLViewer web part see the Client Side Rendering (JSLink) with XML Feeds tutorial.

How to Get the Code

The example created using the steps in this document can be found in full as part of the csrShim repository:
https://github.com/thechriskent/csrShim/tree/master/Examples/Custom%20XML

The full project can be found on GitHub:
https://github.com/thechriskent/csrShim

You can download or clone the repository directly from that site. You can also view the code directly on the site.

Background

Standard Client Side Rendering

Client Side Rendering (CSR), often referred to as JSLink, is a technology introduced with SharePoint 2013 that provides extension points to use JavaScript to render SharePoint data. CSR continues to be supported in SharePoint 2016 and Office 365.

Additional information about how to use standard client side rendering with list views can be found in my earlier List View Client Side Rendering (JSLink) Primer series.

SharePoint does not support using standard CSR with XMLViewers (No JS Link property is defined). However, csrShim exposes parameters that will enable this functionality including the same set of event callbacks and templates described in the above guide.

csrShim

csrShim is an open source solution that fills the gap of many of the limitations presented by the OOTB client side rendering.

csrShim is an XSLT solution that can be used to:

csrShim is available through GitHub at:
https://github.com/thechriskent/csrShim

Getting Started

In the following example, we will be targeting on premise SharePoint 2013. We will be using a publicly available XML feed from the City of New York providing statistics about the average daily population of inmates year over year. We will be taking advantage of csrShim’s JSLink parameter’s multiple file option to also load Google’s charting API.

csrShim Setup

To use csrShim, an XMLViewer web part only needs the csrShim.xsl stylesheet from the csrShim project. However, an XSL Wrapper will also be required to pass parameters.

Upload the csrShim.xsl stylesheet to a library on your site (The Style Library of the root site of a site collection is a great spot for this!).

XSL Wrapper

The XMLViewer webpart does not expose XSLT Parameter properties as do the XSLTListView and Content by Query web parts. There are no ParameterBindings elements to be found in their definition.

In order to pass parameters to csrShim, an XSL Wrapper stylesheet is required. This is a very simple file (A sample wrapper is included in the csrShim Examples folder). Here is what ours will look like:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:x="http://www.w3.org/2001/XMLSchema"
   xmlns:d="http://schemas.microsoft.com/sharepoint/dsp"
   version="1.0"
   exclude-result-prefixes="xsl msxsl x d ddwrt asp SharePoint ddwrt2 o __designer"
   xmlns:ddwrt="http://schemas.microsoft.com/WebParts/v2/DataView/runtime"
   xmlns:asp="http://schemas.microsoft.com/ASPNET/20"
   xmlns:__designer="http://schemas.microsoft.com/WebParts/v2/DataView/designer"
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   xmlns:msxsl="urn:schemas-microsoft-com:xslt"
   xmlns:SharePoint="Microsoft.SharePoint.WebControls"
   xmlns:ddwrt2="urn:frontpage:internal"
   xmlns:o="urn:schemas-microsoft-com:office:office"
   ddwrt:ghost="show_all">

    <xsl:import href="/Style Library/csrShim/csrShim.xsl"/>
    <xsl:variable name="BaseViewID" select="55"/>
    <xsl:variable name="JSLink" select="'https://www.gstatic.com/charts/loader.js|/intranet/Style Library/csrShim/inmates.js'"/>
</xsl:stylesheet>

This is a standard XSL Wrapper for csrShim. However, your custom XML will be ignored currently since there is no defined handler for your XML as of yet. In actuality, csrShim will attempt to map the root element and set the ShimType to Unknown. This won’t throw any errors, but it isn’t really the result you want either.

The only other item of note is that we are taking advantage of the JSLink parameter’s ability to load multiple files by separating them with a pipe | character. In this case we are bringing in Google Charts.

Enabling Support for your Custom XML

To enable support for correct ctx generation we have to tell csrShim how to map our custom XML to rows.

First, we must create an XSL template to catch our custom XML. In the case of the feed from New York City, we can target the root element since this is not used in any of the standard csrShim templates.

Sample of XML from NYC feed:

<response>
    <row>
        <row _id="1" _uuid="5FFABA05-6B70-4B11-8233-2F03C549AB00" _position="1" _address="http://data.cityofnewyork.us/resource/_26ze-s5bx/1">
            <fiscal_year>2010</fiscal_year>
            <inmate_population>13049</inmate_population>
        </row>
        <row _id="2" _uuid="643F7B18-2480-4C29-9F78-520D2D2042A7" _position="2" _address="http://data.cityofnewyork.us/resource/_26ze-s5bx/2">
            <fiscal_year>2009</fiscal_year>
            <inmate_population>13362</inmate_population>
        </row>
        ...
    </row>
</response>

Just add the following template to your XSL Wrapper after your xsl:variable elements:

    <xsl:template match="response">
        <xsl:call-template name="routeToShim">
            <xsl:with-param name="dsType" select="'NY'"/>
            <xsl:with-param name="Rows" select="/response/row/row"/>
            <xsl:with-param name="Rows_UseElements" select="true()"/>
        </xsl:call-template>
    </xsl:template>

A completed version of this wrapper is available here: inmateWrapper.xsl

What’s happening up there:

  • Line 21 is a template that will match the root response node
  • Line 22 is the template that will hook your data into csrShim
  • Line 23 passes the dsType parameter which will be used as the ShimType property on the ctx object
  • Line 24 passes the Rows parameter which will be used to extract the properties to the final ctx.ListData.Row array
  • Line 25 indicates that the row properties should come from element values. If this is omitted, then attributes are extracted from the rows instead

routeToShim Parameters

  • dsType
    • Optional, defaults to Unknown
    • DataSource type
    • This property will be used in the ctx.ShimType property (unless overridden by the ShimType parameter)
  • Rows
    • Required
    • The elements to be used in the row mapping (ctx.ListData.Row array)
  • Rows_UseElements
    • Optional, defaults to false
    • When false, row element attributes will be mapped to the properties
    • When true, row children values will be mapped to the properties
  • Root
    • Optional
    • When included, the ctx.RootData object will pull it’s properties from this element
  • Root_UseElements
    • Optional, defaults to false
    • When false, the root element’s attributes will be mapped to the RootData properties
    • When true, the root element’s children values will be mapped to the RootData properties
  • Root_Exclude
    • Optional
    • This is the name of an element you want to exclude when pulling root data’s children (Root_UseElements is true)
    • This is necessary in cases like RSS where the channel element contains both the root properties and all all items (rows)

Examples of all of the above can be found in csrShim itself.

Upload the XSL Wrapper stylesheet to a library within your site (The Style Library of the root site of a site collection is a great spot!).

Script Setup

A simple JSLink file, inmates.js, has been put together (available in the Example folder in the csrShim project) to display this particular feed.

For details about how CSR templates and event callbacks work see the List View Client Side Rendering (JSLink) Primer series. For this sample, we’ll just take a look at the parts unique to this solution.

The inmates JSLink file supplies a Header and Item template and takes advantage of the PostRender event callback.

The Header template is a simple placeholder with some sizing information. This is just a div that Google Charts will use to contain the generated chart.

The Item template is just a blank string. This prevents the default template from drawing the values out.

The PostRender event callback is where the real work happens. We load the charts from Google. Once those are loaded, we process the ctx.ListData.Row array to build a dataArray to be used by Google Charts to build a simple Bar Chart. Details about how this charting works can be found in their documentation: https://developers.google.com/chart/interactive/docs/gallery/columnchart

Upload the inmates.js file to a library within your site (The Style Library of the root site of a site collection is a great spot!).

Configuring an XMLViewer to use csrShim

Adding an XMLViewer to a Page

On a web part page where you want to display your feed:

  1. Edit the page
  2. Click the Add a Web Part button in the zone where you wish your feed to end up
  3. Choose XML Viewer under Content Rollup

XMLViewer Configuration

  1. Using the web part dropdown, choose Edit Web Part to open the toolpane
  2. Set the value of the XML Link property to:
    https://data.cityofnewyork.us/api/views/26ze-s5bx/rows.xml?accessType=DOWNLOAD
    csrcxml01

Using csrShim

  1. Set the value of the XSL Link to the XSL Wrapper uploaded earlier (NOT csrShim directly):
    csrcxml02
  2. Click OK
  3. Stop Editing the Page

The XMLViewer should now use the custom display:

csrcxml03

Extending csrShim to map Custom XML formats is super easy! If you map a common format that is not yet included in csrShim, consider contributing to the open source project!

Client Side Rendering (JSLink) with RSS Feeds

Applies to SharePoint 2013, 2016, Office 365

Introduction

Standard Client Side Rendering (CSR) cannot be applied to RSS feeds when consumed through the RSSViewer or XMLViewer web parts. However, using the open source csrShim stylesheet, XMLViewer web parts can consume XML based feeds while utilizing JavaScript based rendering.

This is not a comprehensive guide to the XMLViewer web part or csrShim but provides the information necessary to enable CSR. For additional details about how to use csrShim see the csrShim Documentation on GitHub.

How to Get the Code

The example created using the steps in this post can be found in full as part of the csrShim repository:
https://github.com/thechriskent/csrShim/tree/master/Examples/XML%20Feeds

The full project can be found on GitHub:
https://github.com/thechriskent/csrShim

You can download or clone the repository directly from that site. You can also view the code directly on the site.

Background

Why the XMLViewer and not the RSSViewer

The RSSViewer does not allow the execution of code within script blocks generated by XSL. XMLViewer is able to support all of the same feed types as the RSSViewer but it allows csrShim script blocks to be executed.

Supported Feeds

  • RSS
  • RDF
  • Atom
  • Atom2

Additionally, csrShim can easily be extended to support custom XML Feeds.

Standard Client Side Rendering

Client Side Rendering (CSR), often referred to as JSLink, is a technology introduced with SharePoint 2013 that provides extension points to use JavaScript to render SharePoint data. CSR continues to be supported in SharePoint 2016 and Office 365.

Additional information about how to use standard client side rendering with list views can be found in my earlier List View Client Side Rendering (JSLink) Primer series.

SharePoint does not support using standard CSR with XMLViewers (No JS Link property is defined). However, csrShim exposes parameters that will enable this functionality including the same set of event callbacks and templates described in the above guide.

csrShim

csrShim is an open source solution that fills the gap of many of the limitations presented by the OOTB client side rendering.

csrShim is an XSLT solution that can be used to:

csrShim is available through GitHub at:
https://github.com/thechriskent/csrShim

Getting Started

In the following example, we will be targeting on premise SharePoint 2013. We will be using a publicly available RSS feed from Netflix regarding their DVD service. However, csrShim easily handles other common feed types as well.

csrShim Setup

To use csrShim, an XMLViewer web part only needs the csrShim.xsl stylesheet from the csrShim project. However, an XSL Wrapper will also be required to pass parameters.

Upload the csrShim.xsl stylesheet to a library on your site (The Style Library of the root site of a site collection is a great spot for this!).

XSL Wrapper

The XMLViewer webpart does not expose XSLT Parameter properties as do the XSLTListView and Content by Query web parts. There are no ParameterBindings elements to be found in their definition.

In order to pass parameters to csrShim, an XSL Wrapper stylesheet is required. This is a very simple file (A sample wrapper is included in the csrShim Examples folder). Here is what ours will look like:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:x="http://www.w3.org/2001/XMLSchema"   xmlns:d="http://schemas.microsoft.com/sharepoint/dsp"   version="1.0"   exclude-result-prefixes="xsl msxsl x d ddwrt asp SharePoint ddwrt2 o __designer"   xmlns:ddwrt="http://schemas.microsoft.com/WebParts/v2/DataView/runtime"   xmlns:asp="http://schemas.microsoft.com/ASPNET/20"   xmlns:__designer="http://schemas.microsoft.com/WebParts/v2/DataView/designer"   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"   xmlns:msxsl="urn:schemas-microsoft-com:xslt"   xmlns:SharePoint="Microsoft.SharePoint.WebControls"   xmlns:ddwrt2="urn:frontpage:internal"   xmlns:o="urn:schemas-microsoft-com:office:office"   ddwrt:ghost="show_all">

    <xsl:import href="/Style Library/csrShim/csrShim.xsl"/>
    <xsl:variable name="BaseViewID" select="50"/>
    <xsl:variable name="JSLink" select="'/intranet/Style Library/csrShim/FeedDisplay.js'"/>
</xsl:stylesheet>

Here’s what’s happening up there:

  • Lines 1-14 are just standard XSL boilerplate. Just copy this into your own, you shouldn’t need to change this at all.
  • Line 16 imports the csrShim stylesheet (just adjust the href value to point to your csrShim location (relative to the site))
  • Line 17 sets the value for the BaseViewID parameter
  • Line 18 sets the value for the JSLink parameter. Update this to point to your JSLink file(s) relative to the domain

Upload the XSL Wrapper stylesheet to a library within your site (The Style Library of the root site of a site collection is a great spot!).

Script Setup

A simple JSLink file, FeedDisplay.js, has been put together (available in the Example folder in the csrShim project) to display this particular feed.

For details about how CSR templates and event callbacks work see the List View Client Side Rendering (JSLink) Primer series. For this sample, we’ll just take a look at the parts unique to this solution.

The header and footer templates take advantage of the csrShim ContextInfo (ctx) object’s RootData property since this contains additional information about the feed itself. In this case the title of the feed and the description are used. These values are not guaranteed and are up to the feed provider.

The item template could be an item template for standard list items. The only thing of note here is that the Netflix feed supplies an HTML description and we are breaking it apart to show the included picture next to the description (rather than above it as it comes from the feed).

Upload the FeedDisplay.js file to a library within your site (The Style Library of the root site of a site collection is a great spot!).

Configuring an XMLViewer to use csrShim

Adding an XMLViewer to a Page

On a web part page where you want to display your feed:

  1. Edit the page
  2. Click the Add a Web Part button in the zone where you wish your feed to end up
  3. Choose XML Viewer under Content Rollup

XMLViewer Configuration

  1. Using the web part dropdown, choose Edit Web Part to open the toolpane
  2. Set the value of the XML Link property to: http://dvd.netflix.com/Top25RSS?gid=307
    csrxml01

Using csrShim

  1. Set the value of the XSL Link to the XSL Wrapper uploaded earlier (NOT csrShim directly):
    csrxml02
  2. Click OK
  3. Stop Editing the Page

The RSS feed should now use the CSR display:

csrxml03

The craziest part of this whole solution is how outdated these movies are!

Best Practices for csrShim with XMLViewers

  • Always use an XSL Wrapper around csrShim so that you can set parameters
  • Provide a unique BaseViewID to prevent conflicts with the default value of 1 (standard CSR with list views uses this value)
  • If reusing JSLink files between CQWPs, list views, and/or feeds, use the ctx.ShimType property to create conditional property retrieval as needed
  • Explore the ctx object to see what properties are available in the RootData and the ListSchema objects
  • Feed properties are not guaranteed. Always check for the values existence before using it
  • Wrap your JS Link code in an Immediately Invoked Function Expression (IIFE)
  • Unlike an RSSViewer web part, there is no row limit property for the XMLViewer. If you wish to restrict the number of results, increment a count in the Item template and stop returning values when that count is exceeded

Client Side Rendering (JSLink) with Content by Query Web Parts

Applies to SharePoint 2013, 2016

Introduction

Standard Client Side Rendering (CSR) cannot be applied to Content by Query web parts (CQWP). However, using the open source csrShim stylesheet, CQWPs can also utilize JavaScript based rendering.

Content by Query Web Parts were heavily utilized in earlier versions of SharePoint but have fallen out of favor due to their complexity and limitations. However, they have proven to be performant options (in on premises deployments) that can continue to solve a variety of problems.

When used in appropriate situations, CQWPs can be very powerful assets. Unfortunately, the Out Of The Box (OOTB) limitation against CSR has made it inaccessible to newer developers. However, csrShim enables CSR for CQWPs using OOTB configurations and rendering tools.

This is not a comprehensive guide to using CQWPs or csrShim but provides the tools needed to bridge the gaps and enable CSR. For additional details about how to use csrShim see the csrShim Documentation on GitHub.

How to Get the Code

The example created using the steps in this document can be found in full as part of the csrShim repository:
https://github.com/thechriskent/csrShim/tree/master/Examples/CQWP

The full project can be found on GitHub:
https://github.com/thechriskent/csrShim

You can download or clone the repository directly from that site. You can also view the code directly on the site.

Background

Content by Query Web Parts

The Content by Query Web Part (CQWP), often just called the Content Query Web Part is part of SharePoint’s Enterprise Content Management (ECM) toolset. CQWPs aggregate list items across a site hierarchy while providing query optimization and caching.

Benefits

  • Aggregation of list items across a single site collection
    • Can aggregate items from a single list, multiple lists by list type or contenttype, and more
  • Basic queries can be configured using OOTB web part tool pane
  • Respects Audiences
  • Powerful caching leading to high performance in on-premises deployments
  • Is not subject to search’s limitations (use of managed properties, crawl delay, search language, etc.)
  • OOTB display templates

Limitations

  • Cannot cross site collections
  • Advanced configuration can be difficult
  • Custom display requires complicated XSL (unless using csrShim)
  • Caching benefits are nullified when used in Office 365 leading to poor performance
  • Does not have some of search’s benefits (pre-aggregated results, cross site collection, extreme scalability, etc.)
  • Some fields (such as user fields) do not return as much detail as list view web parts

When to Use

You can use the CQWP when:

  • You are using Audiences with list items
    • Standard list views and APIs do NOT support audience filtering
  • You are aggregating across lists/contenttypes and the search crawl delay is unacceptable (or the configuring of search schema is prohibited)

Don’t use the CQWP when:

  • You need to cross site collections
  • Targeting Office 365
  • Search can be used instead

Standard Client Side Rendering

Client Side Rendering (CSR), often referred to as JSLink, is a technology introduced with SharePoint 2013 that provides extension points to use JavaScript to render SharePoint data. CSR continues to be supported in SharePoint 2016 and Office 365.

Additional information about how to use standard client side rendering with list views can be found in my earlier List View Client Side Rendering (JSLink) Primer series.

SharePoint does not support using standard CSR with CQWPs (No JS Link property is defined). However, csrShim exposes a parameter that will enable this functionality including the same set of event callbacks and templates described in the above guide.

csrShim

csrShim is an open source solution that fills the gap of many of the limitations presented by the OOTB client side rendering.

csrShim is an XSLT solution that can be used to:

csrShim is available through GitHub at:
https://github.com/thechriskent/csrShim

Getting Started

In the following examples, we will be targeting on premise SharePoint 2013 using SharePoint Designer 2013. We will be using a publishing site to have access to the Content by Query web part.

Additionally, we will be using the same list from the List View Client Side Rendering (JSLink) Primer series (with the exception that the Person field has a different Show field property). The CSR JavaScript file has also been adapted from the HallOfFame.js file created with that guide. Thus, many of the details around how CSR works are left out of this post. However, if you are already familiar with CSR basics you shouldn’t have any trouble following along.

The goal of this post, and this example, is not how CSR works but only how to use it with CQWPs.

List Setup

For this example, we will be using a custom list with just 3 columns:

  • Title (Text)
  • Person (User)
  • Color (Choice)

A HallOfFame.xml PnP template with this list is available if you are familiar with how to apply PnP provisioning templates.

Otherwise, to manually create the list:

  1. From a site where you have full control or design permissions, using the Site Actions menu (gear) choose Add an App
  2. Choose Custom List
  3. Name the list Hall of Fame and click Create
  4. From Site Contents, hover over the Hall of Fame icon and click the ellipsis to show the panel and choose Settings:
    cqwp01
  5. Under Columns, click Create column
  6. Give a name of Person and set the type to Person or Group and set the Show field to Account then click OK:
    cqwp02
  7. Under Columns, click Create column again
  8. Give a name of Color and set the type to Choice (menu to choose from). Replace the choices with Tomato, YellowGreen, DeepSkyBlue, Gold (each on separate lines):
    cqwp03
  9. Navigate to the Hall of Fame list and add several entries:
    cqwp04

You now have a basic list and you could simply use standard CSR to display the contents if that’s all you wanted. For this example, we will only have the one list since our goal is to demonstrate how to use the CQWP with csrShim.

Generally, however, you might have multiple copies of this list across several subsites and you would use a CQWP to roll all the results up to a single view. In this scenario, standard CSR would be unavailable to you and is exactly where csrShim fills that gap.

Also, note that we specifically set the Person Field’s Show field property to Account. Unlike with list views, CQWPs get very little information from user fields. Most of the Show field options will return the user’s name (and nothing else). List views return many properties including ID, account, email, etc. So, we must choose carefully so that we retrieve additional information if needed (in this case the profile picture).

Script Setup

We will be using a modified version of the JSLink file created with the List View Client Side Rendering (JSLink) Primer series. This script is available at the sample code location mentioned in the introduction (HallOfFame.js).

A full description of each of the templates/functions was provided in the primer series and should be consulted for any questions. The primary differences between that version and this one are:

  • The BaseViewID has been set to 40
    • This isn’t strictly necessary but is recommended when using csrShim so that you know your JSLink is very specifically targeted and can therefore be hosted alongside standard CSR and other csrShim implementations without conflict
  • The Item template was modified
    • Since the CQWP doesn’t return a full user object, we can’t simply get the profile picture from the Person field. So, the photo is always set to the placeholder image and has its visibility set to hidden
    • The user URL is also not set since we don’t have a user ID
  • The PostRender callback was modified
    • Code has been added to retrieve the PictureUrl and UserUrl from the User Profiles for each of the users based on their account name. Once those properties have been retrieved, the placeholder image is replaced (where appropriate) and visibility is set to visible. The href for the link is also set to the retrieved UserUrl.

Upload the HallOfFame.js file to a library within your site (The Style Library of the root site of a site collection is a great spot!).

csrShim Setup

To use csrShim, a CQWP only needs 2 files:

Place these in a library within your site (The Style Library of the root site of a site collection is great spot for these!).

Configuring a CQWP to use csrShim

Adding a CQWP to a Page

On a web part page where you want to display your CQWP:

  1. Edit the page
  2. Click the Add a Web Part button in the zone where you wish your CQWP to end up
  3. Choose Content Query under Content Rollup (if you don’t have this option then the publishing features are not enabled)
  4. Using the web part dropdown, choose Edit Web Part to open the toolpane
  5. Expand the Query section and select Show items from the following list then click Browse and locate the Hall Of Fame list created earlier:
    cqwp05
  6. Again, this is a simple example (generally a single list CQWP view is not a great use case for a CQWP). However, any query that returns results with the CQWP (even complicated ones) can still take advantage of CSR display using csrShim.
  7. Click OK and choose to Stop Editing the page
    cqwp06

You now have results on the page but only the Title field is showing and there is no custom display at all.

CQWP Configuration

Basic queries and sorting can be applied using the toolpane. However, you are fairly limited in how these results are displayed (including which fields are returned) and even in how complicated you can make your filters (query).

For all but the most basic CQWPs, you’ll likely end up manually editing the CQWP configuration either through SharePoint Designer or by exporting the definition, making your edits, and reimporting.

Since we used a web part page, we will simply use SharePoint Designer (SPD) to edit the configuration of the part directly. Other types of pages cannot always be edited in SharePoint Designer. In which case, you must apply the following changes into an exported web part definition file (XML). These changes are the same, but end up looking different from this example (You use property elements rather than setting the properties directly).

The easiest way to overcome this limitation is to use a web part page temporarily until your web part is properly configured using the below methods. Then export the web part from there and import into your other page types.

To edit the web part in SharePoint Designer:

  1. Connect to your site in SharePoint Designer
  2. In the navigation pane choose the library where you stored your page (if not listed, use the All Files node)
  3. Right-click on your page and choose Edit File in Advanced Mode
  4. SharePoint Designer often “helpfully” changes things that can cause problems. For instance, it is very common that it will escape double quotes within existing script blocks that should not be escaped. This will throw errors on your page.
  5. Look for the following:
    <SharePoint:ScriptBlock runat="server">
    var navBarHelpOverrideKey = &quot;WSSEndUser&quot;;
    </SharePoint:ScriptBlock>
    
  1. You will need to replace the values with actual double quotes (Again, this has nothing to do with this solution, this is just a common problem with SPD that may come up repeatedly):
    <SharePoint:ScriptBlock runat="server">
    var navBarHelpOverrideKey = “WSSEndUser”;
    </SharePoint:ScriptBlock>
    
  1. Look for the following:
    <SharePoint:ScriptBlock runat="server">
    if(typeof(MSOLayout_MakeInvisibleIfEmpty) == &quot;function&quot;)
    {MSOLayout_MakeInvisibleIfEmpty();}</SharePoint:ScriptBlock>
    
  1. Again, you will need to replace the values with actual double quotes:
    <SharePoint:ScriptBlock runat="server">
    if(typeof(MSOLayout_MakeInvisibleIfEmpty) == “function”)
    {MSOLayout_MakeInvisibleIfEmpty();}</SharePoint:ScriptBlock>
    
  1. Go ahead and save the page. In the Site Definition Page Warning dialog, click Yes:
    cqwp07

Using csrShim

To use csrShim, you need to tell the CQWP to use the csrShim stylesheet. The CQWP uses 3 stylesheets (Main, Item, and Header). Unlike most web parts with a single XslLink property, the CQWP has one for each.

We will only use the Main, but you must provide a link for the Item and Header values or your web part will get an error. That is where the EmptyStyleSheet included with csrShim comes in handy.

  1. Add the MainXslLink property directly to the ContentByQueryWebPart element on your page and give it the address of the xsl stylesheet
  2. Add the HeaderXslLink property directly to the ContentByQueryWebPart element on your page and give it the address of the xsl stylesheet
  3. Add the ItemXslLink property directly to the ContentByQueryWebPart element on your page and give it the address of the xsl stylesheet
    cqwp08
  4. Save the page in SPD and refresh it in the browser. You should now see many more fields in a strange display (this is the OOTB template-less CSR view)
    cqwp09

Adjusting the Query

Now we’re getting somewhere! Clearly, this isn’t the display we’re going for just yet but csrShim is in place and ready to have a JS Link file applied.

First, however, it’s a good idea to get your query adjusted before introducing the complication of custom rendering. Often, you’ll accomplish this by using the QueryOverride attribute with your own CAML. For this example, we want to return all the items but we want it sorted in order of creation, ascending. For simple sort changes, we’ll just use existing properties (we could have done this in the toolpane as well).

  1. By default, the SortBy attribute should already be set to Created. The SortByDirection is set to Desc by default. Change this to Asc and Save the page in SPD.

Additional Fields

If you look through the many fields that are returning on the page, you’ll notice that the Person and Color fields are missing. You can request additional fields using the CommonViewFields property:

  1. Add the CommonViewFields property directly to the ContentByQueryWebPart element on your page and give it the value of Title,Text;Person,User;Color,Text;
    cqwp10
  2. Save the page in SPD

Refreshing the page in the browser will show that the values for these columns are now showing up, yay!

A Note about Field Types

Although there is a Choice option for the type (the text following the comma after the internal name), Text always works and Choice only sometimes. In the sample’s case, either is fine, but a multi-choice column will cause your CQWP to not return any data if Choice is used but will work fine with Text. Therefore, it is recommended to always use Text for Choice columns.

Other types that can be used:

  • Text
  • Note
  • Number
  • Currency
  • Integer
  • Boolean
  • DateTime
  • Threading
  • Lookup
  • Choice
  • URL
  • Counter
  • DisplayOnly
  • RichHTML
  • Image

Applying Client Side Rendering

Technically, we’ve already applied client side rendering simply by using csrShim as the stylesheet. If you check using your development tools, you’ll find a ContextInfo object in the global namespace (likely ctx500).

cqwp11

Now to apply our JS Link file to the CQWP!

With list views, you can simply open the toolpane and put your script reference(s) in the JS Link property of the XSLTListView web part. There is no JS Link property on the CQWP. Instead, csrShim exposes several parameters including a JSLink parameter where we can specify these. This is done through the CQWPs ParameterBindings element.

  1. Add a ParameterBindings Add a ParameterBinding element with a Name of BaseViewID and a Default value of 40. Add another ParameterBinding element with a Name attribute of JSLink and a Default value of the address to the HallOfFame.js file we uploaded earlier.
    cqwp12

    <ParameterBindings>
      <ParameterBinding Name="BaseViewID" Default="40"/>
      <ParameterBinding Name="JSLink" Default="/Intranet/Style Library/csrShim/HallOfFame.js"/>
    </ParameterBindings>
    

If you refresh the page, you’ll see the glory that is CSR with a CQWP!

cqwp13

Best Practices for csrShim with CQWPs

  • Set the XslLink for ALL 3 CQWP properties
    • MainXslLink = address of csrShim.xsl
    • ItemXslLink = address of EmptyStyleSheet.xsl
    • HeaderXslLink = address of EmptyStyleSheet.xsl
  • Use the CommonViewFields property of the CQWP to include additional fields
  • Use Text for Choice fields in the type portion of the CommonViewFields property
  • If fields are coming back as GUIDs instead of their internal name, use the DataMappings property of the CQWP
  • Provide a unique BaseViewID to prevent conflicts with the default value of 1 (standard CSR with list views uses this value)
  • If reusing JSLink files between CQWPs, list views, and/or feeds, use the ctx.ShimType property to create conditional property retrieval as needed

Client Side Rendering Best Practices

Applies To: SharePoint 2013, 2016, Office 365

List View Client Side Rendering Primer: 5 of 5

About This Series

This series provides a brief overview of Client Side Rendering for List Views (often referred to as JSLink). Basic extension points and examples are included. The goal of this series is to get developers unfamiliar with this programming model quickly up to speed.

CSR Best Practices

  • Use SPURLs (~site, ~sitecollection, ~layouts, ~sitecolletionlayouts, ~sitelayouts etc.) when referencing JSLink files in the XSLTListView web part
    • Not yet supported in csrShim
  • Specify multiple JavaScript files (like jQuery) using a pipe to separate the URLs (they will be loaded in order)
  • Wrap your JS Link code in an Immediately Invoked Function Expression (IIFE)
  • Specify the BaseViewID and the ListTemplateType when targeting your list view
  • Use Template Functions for all but the simplest templates
  • Don’t rely on the Footer template to close elements from either the Header or Item template
  • If there are no items returned, the Item template will never be called, so add logic to close the elements from the header when ctx.ListData.Row.length == 0
  • Use csrShim when placing multiple CSR list views on a single page
  • Use csrShim when using CSR with Content by Query web parts
  • Use csrShim when using CSR with RSS, RDF, Atom, or Atom2 feeds
  • Use csrShim when using CSR with custom XML

List View Extension Points (CSR)

Applies To: SharePoint 2013, 2016, Office 365

List View Client Side Rendering Primer: 4 of 5

About This Series

This series provides a brief overview of Client Side Rendering for List Views (often referred to as JSLink). Basic extension points and examples are included. The goal of this series is to get developers unfamiliar with this programming model quickly up to speed.

How to Get the Code

The example created using the steps in this series can be found in full as part of the csrShim repository:
https://github.com/thechriskent/csrShim/tree/master/Examples/CSR%20Primer

The full project can be found on GitHub:
https://github.com/thechriskent/csrShim

You can download or clone the repository directly from that site. You can also view the code directly on the site. csrShim is not used in this example and is not required.

In the following examples, we will be targeting on premise SharePoint 2013 using SharePoint Designer 2013.

List View Extension Points

You can override one or more parts of the rendering of your list view. You do not need to specify all the following, but be aware that specifying a single template will use the default render for the other templates (this is different from the OOTB view).

CTX

The CTX object contains all the information about your list view – including all the returned data. This object is provided to the event callback functions and to any template functions.

Although there are many properties (especially when using standard CSR vs csrShim), here are the key properties to pay attention to:

  • CurrentItem
    • This property is only set when passed to the Item template
    • Provides quick access to all properties for the current item
    • Properties match the internal name of the field
    • Properties can sometimes contain periods and therefore these properties cannot be accessed using the standard dot notation
      //Standard Access
      var created = ctx.CurrentItem.Created;
      
      //Access Properties with Periods
      var createdF = ctx.CurrentItem["Created.FriendlyDisplay"];
      
  • firstRow
    • When true, the item is the first item returned
  • lastRow
    • Only available with csrShim!
    • When true, the item is the last item returned
  • Row
    • The array of returned items with their properties
    • These are equivalent to CurrentItem objects
    • This allows access to ALL rows from any template including the Item template
  • FirstRow
    • Available with standard CSR and csrShim with Lists (not feeds/XML)
    • The item ID of the first item returned
  • LastRow
    • Available with standard CSR and csrShim with Lists (not feeds/XML)
    • The item ID of the last item returned
  • ListSchema
    • In standard CSR, contains several properties about the underlying list structure and the view configuration
  • Field
    • Array of the fields returned with the view
    • In standard CSR, several properties (like DisplayName) can be very helpful for dynamic displays. csrShim only provides the Name (internal name).

Event Callbacks

There are 2 events (OnPreRender and OnPostRender) where you can provide callback functions.

OnPreRender

To have a callback function executed BEFORE your templates are applied to the list data, you can specify an anonymous or named function to the OnPreRender property of your CSR object.

The PreRender event can be helpful to declare any necessary SOD dependencies, verify existence of elements, contact additional web service, etc.

(function(){

    var myCSR = {
        BaseViewID: 1,
        ListTemplateType: 100,
        OnPreRender: myFunction
    };

    function myFunction(ctx){
        //Do Stuff
    }
})();

Example

In our HallOfFame.js example from earlier we will add a console message so we know when our rendering is about to start:

    var HallOfFame = {
        BaseViewID: 1,
        ListTemplateType: 100,
        OnPreRender: hofPreRender
    };

    function hofPreRender(ctx){
        if(window.console && window.console.log){
            console.log('Begin Hall Of Fame!');
        }
    }

Here’s what we just did:

  • Line 5 we added a comma to ensure we could add another property
  • Line 6 we added the OnPreRender property and gave it a reference to our function hofPreRender
  • Line 9 this is our callback function
  • Line 10-12 safely logs a message to the console (the checks prevent IE from throwing errors when the console is not visible)

Refreshing the page with the developer tools visible (F12) should show our message. If you don’t see a console message, verify the JS Link property is pointing to the correct page. Also note that console messages logged before the developer tools were open (in IE) will not show and you may need to refresh.

OnPostRender

To have a callback function executed AFTER your templates are applied to the list data, you can specify an anonymous or named function to the OnPostRender property of your CSR object.

The PostRender event can be helpful to attach events or run any other code dependent on your HTML being in place.

(function(){

    var myCSR = {
        BaseViewID: 1,
        ListTemplateType: 100,
        OnPostRender: myFunction
    };

    function myFunction(ctx){
        //Do Stuff
    }
})();

Example

In our HallOfFame.js example from earlier we will add another console message so we know when our rendering is all done:

var HallOfFame = {
        BaseViewID: 1,
        ListTemplateType: 100,
        OnPreRender: hofPreRender,
        OnPostRender: hofPostRender
    };

    function hofPreRender(ctx){
        if(window.console && window.console.log){
            console.log('Begin Hall Of Fame!');
        }
    }

    function hofPostRender(ctx){
        if(window.console && window.console.log){
            console.log('Finished Hall Of Fame!');
        }
    }

Here’s what we just did:

  • Line 6 we added a comma to ensure we could add another property
  • Line 7 we added the OnPostRender property and gave it a reference to our function hofPostRender
  • Line 16 this is our callback function
  • Line 17-19 safely logs a message to the console (the checks prevent IE from throwing errors when the console is not visible)

Refreshing the page with the developer tools visible (F12) should show both our PreRender and PostRender messages in the proper order.

Templates

There are several templates that can be specified using the Templates property of your CSR object. You can specify simple strings, “magic” strings, and full functions that return a string.

(function(){

    var myCSR = {
        BaseViewID: 1,
        ListTemplateType: 100,
        Templates: {
            Header: "
<div>I'm the Header!</div>
",
            Item:   "
<div>I'm an Item!</div>
",
            Footer: "
<div>I'm the Footer!</div>
"
        }
    };

})();

Available Templates

  • Header
  • Item
  • Fields
  • Footer

Note – The Footer template is often misused to close any open tags from the header or item templates. This will result in invalid HTML. Although most modern browsers will auto close these open items for you, this may cause hard to track down display issues! The Footer template is rendered inside a div element outside the hierarchy of the Header and Item templates and is designed for standalone paging. It can be used for other things, but it is separate from anything generated in the other templates.

Magic Strings

In the most basic forms, templates can be specified as simple strings (as in the example above). Additionally, when specified as strings you can use special notation to have “magic strings” resolved automatically.

(function(){

    var myCSR = {
        BaseViewID: 1,
        ListTemplateType: 100,
        Templates: {
            Header: "
<div>My BaseViewID is <#=ctx.BaseViewID#></div>
"
        }
    };

})();

The format is to include <#=ctx. Before the name of the property and followed by #>

In nearly every case you will be better supplying a function to the template properties (even for simple strings) since this will give you more flexibility, better readability, and easier extensibility.

Functions

You can specify anonymous or named functions (named functions are best practice coding) to each of the template properties. These functions will be provided with the CTX object as the parameter.

(function(){

    var myCSR = {
        BaseViewID: 1,
        ListTemplateType: 100,
        Templates: {
            Header: myFunction
        }
    };

    function myFunction(ctx){
        //Do Stuff
    }
})();

Example Header

Although it would be better to use an external stylesheet, for this simple example we will be declaring an inline style block to set our CSS for the rest of the list view. We will do this in the header. Additionally, we’d like to show a title box.

    var HallOfFame = {
        BaseViewID: 1,
        ListTemplateType: 100,
        OnPreRender: hofPreRender,
        Templates: {
            Header: hofHeader
        },
        OnPostRender: hofPostRender
    };

    function hofHeader(ctx){
        var styles = '
<style type="text/css">' +
                     '.halloffame{' +
                     ' text-align:center;' +
                     ' width:504px;}' +
                     '.halloffame div{'+
                     ' box-sizing:border-box;}' +
                     '.hof-header{' +
                     ' font-size:18px;' +
                     ' font-weight:bold;' +
                     ' border:solid black 4px;' +
                     ' padding:6px;}' +
                     '.hof-items{' +
                     ' border-right:solid black 4px;}' +
                     '.hof-items:after{' +
                     ' clear:both;' +
                     ' content:"";' +
                     ' display:block;}' +
                     '.hof-item{' +
                     ' float:left;' +
                     ' width:125px;' +
                     ' border-left:solid black 4px;' +
                     ' border-bottom:solid black 4px;' +
                     ' height:100px;}' +
                     '.hof-item div{' +
                     ' color:black;' +
                     ' font-weight:bold;' +
                     ' font-size:15px;}' +
                     '.hof-item:hover{' +
                     ' filter:brightness(75%);}' +
                     '.hof-footer{' +
                     ' border:solid black 4px;' +
                     ' border-top:none;' +
                     ' padding:3px;' +
                     ' font-size:10px;}' +
                     '</style>

';
        var header = '
<div class="halloffame">
<div class="hof-header">- Hall of Fame -</div>
<div class="hof-items">';
        return styles + header;
    }

Here’s what we just did:

  • Line 7 we added a Templates property
  • Line 8 we added a Header property to our Templates object and gave it a reference to our hofHeader function
  • Line 19 this is our template function
  • Lines 20-54 is a massive string to define our style block
  • Line 55 this is our actual HTML. We begin with a wrapper div (that we don’t close in this template) with a class of halloffame since this allows us to target our CSS classes very specifically. We also provide a div to hold our title text
  • Line 56 we return the combined styles and header strings

When you refresh the page now you will get this monstrosity:

lve01

Example Item

We’d like to show each of the items as a box showing the Title and the picture of the Person field. Additionally, we’d like to color the box based on the value of the Color field. When someone clicks on a box, they should be taken to the user’s profile page.

    var HallOfFame = {
        BaseViewID: 1,
        ListTemplateType: 100,
        OnPreRender: hofPreRender,
        Templates: {
            Header: hofHeader,
            Item: hofItem
        },
        OnPostRender: hofPostRender
    };

    function hofItem(ctx){
        var sip = ctx.CurrentItem.Person[0].sip;
        var photoUrl = '/_layouts/15/images/PersonPlaceholder.96x96x32.png';
        if(ctx.CurrentItem.Person[0].picture){
            photoUrl = ctx.CurrentItem.Person[0].picture;
        }
        var photo = '/_layouts/15/userphoto.aspx?accountname=' + sip + '&size=L&url=' + photoUrl;
        var userUrl = _spPageContextInfo.siteServerRelativeUrl + '/_layouts/15/userdisp.aspx?ID=' + ctx.CurrentItem.Person[0].id;                           

        var item = '<a href="' + userUrl + '">' +
                   '
<div class="hof-item" style="background-color:' + ctx.CurrentItem.Color + ';">' +
                   '
<div>' + ctx.CurrentItem.Title + '</div>
' +
                   '  <img style="max-height:72px;max-width:72px;" src="' + photo + '"/>' +
                   '</div>
' +
                   '</a>';
        if(ctx.ListData.LastRow == ctx.CurrentItem.ID){
            var closures = '</div>
</div>
';
            return item + closures;
        } else {
            return item;
        }
    }

Here’s what we just did:

  • Line 9 we added an Item property to our Templates object and gave it a reference to our hofItem function
  • Line 60 this is our template function
  • Lines 61-66 is the building of the profile picture image.
    • In standard CSR, a person field is returned as an array of objects with additional properties about a person. One of those properties is the picture property which is the URL to the profile picture for a given user.
    • If a user does not have a profile picture, this property is not included
    • So, we ensure that if the picture is not available we use the standard person placeholder image instead
    • Additionally, if your My Site web application is hosted at a different domain (even sub domain) users using machines not joined to the domain (IE iPads) may be prompted to log in for each profile picture you display.
    • So, instead of using the profile picture directly, we use the userphoto.aspx page to provide us the picture without leaving the domain
  • Line 67 builds the URL to the user profile page using the user id property
  • Lines 69-74 builds our actual HTML for each item.
    • We wrap everything in a link to the user profile
    • We use an inline style to set the background-color to the choice field
      • This is not a good idea and is only used as an obvious example, generally you should not directly incorporate values into markup like this. It would be easy to break simply by adding a choice for a color that is not one of the named HTML colors.
    • Line 67 checks if this item is the last item returned
      • In csrShim we could simply check ctx.CurrentItem.lastRow
      • If this is the last item, we close the wrapper divs left open in the header template and return those after the item.
      • This is necessary since the Footer template will be in a different div and leaving open HTML tags can cause display issues
    • If this wasn’t the last item, we just return the basic item box in line 80

When you refresh the page now things are looking truly amazing:

lve02

Example Footer

We’d like to add some instructions to the bottom to remind people to click on these boxes.

    var HallOfFame = {
        BaseViewID: 1,
        ListTemplateType: 100,
        OnPreRender: hofPreRender,
        Templates: {
            Header: hofHeader,
            Item: hofItem,
            Footer: hofFooter
        },
        OnPostRender: hofPostRender
    };

    function hofFooter(ctx){
        var footer = '
<div class="halloffame">
<div class="hof-footer">Click on a person to learn more</div>
</div>
';
        return footer;
    }

Here’s what we just did:

  • Line 10 we added a Footer property to our Templates object and gave it a reference to our hofFooter function
  • Line 84 this is our template function
  • Line 85 builds standalone HTML to be used as our footer. We provide another wrapper with the halloffame class so that our global styles still get applied. Then we give an unnecessary message encouraging clicks.
  • Line 86 we return the footer

When you refresh the page now you will now be struck at the beauty of our creation:

lve03

Continue?

That’s pretty well everything you need to know about client side rendering with list views. However, the final post in the series provides a quick list of best practices to keep in mind while applying CSR to List Views:

Getting Started (List View CSR)

Applies To: SharePoint 2013, 2016, Office 365

List View Client Side Rendering Primer: 3 of 5

About This Series

This series provides a brief overview of Client Side Rendering for List Views (often referred to as JSLink). Basic extension points and examples are included. The goal of this series is to get developers unfamiliar with this programming model quickly up to speed.

How to Get the Code

The example created using the steps in this series can be found in full as part of the csrShim repository:
https://github.com/thechriskent/csrShim/tree/master/Examples/CSR%20Primer

The full project can be found on GitHub:
https://github.com/thechriskent/csrShim

You can download or clone the repository directly from that site. You can also view the code directly on the site. csrShim is not used in this example and is not required.

In the following examples, we will be targeting on premise SharePoint 2013 using SharePoint Designer 2013.

List Setup

For this example, we will be using a custom list with just 3 columns:

  • Title (Text)
  • Person (User)
  • Color (Choice)

To create the list:

  1. From a site where you have full control or design permissions, using the Site Actions menu (gear) choose Add an App
  2. Choose Custom List
  3. Name the list Hall of Fame and click Create
  4. From Site Contents, hover over the Hall of Fame icon and click the ellipsis to show the panel and choose Settings:
    gs01
  5. Under Columns, click Create column
  6. Give a name of Person and set the type to Person or Group then click OK:
    gs02
  7. Under Columns, click Create column again
  8. Give a name of Color and set the type to Choice (menu to choose from). Replace the choices with Tomato, YellowGreen, DeepSkyBlue, Gold (each on separate lines):
    gs03
  9. Navigate to the Hall of Fame list and add several entries:
    gs04
  10. On a page, choose to Edit and click the Add a Web Part button
  11. Under Apps, choose Hall of Fame
  12. Click Stop Editing

By default, you have a very OOTB view of the list as a table with column headers and not a lot of excitement. So, let’s customize it!

Script Setup

To use the JS Link property of the XSLTListView web part we added in the steps above (step 11), we’ll need a JavaScript file to point to.

  1. Open your site in SharePoint Designer
  2. Using the All Files navigation option, open a Document Library (generally, the Style Library is a great location for these types of resources)
  3. In the File dropdown choose JavaScript:
    gs05
  4. Name the file js
  5. Return to the page (in the browser) where you added the web part
  6. Edit the page and using the dropdown on the web part choose Edit Web Part
  7. In the web part tool pane, expand the Miscellaneous section
  8. In the JS Link box, Provide the path (You can use SPURLs) to the JavaScript file we created earlier then click OK:
    gs06
  9. Nothing will happen (we haven’t provided any code yet). Click Stop Editing on the page
  10. Return to SharePoint Designer and Right-Click on the HallOfFame.js file and choose Edit File in Advanced Mode
  11. Enter the code from the CSR Boilerplate Code below

CSR Boilerplate Code

(function(){

    var HallOfFame = {
        BaseViewID: 1,
        ListTemplateType: 100
    };

    SP.SOD.executeFunc('clienttemplates.js','SPClientTemplates',function(){
        SPClientTemplates.TemplateManager.RegisterTemplateOverrides(HallOfFame);
    });

})()

The above code is simply boilerplate for the extension points we will fill in below. Here is what this code currently does:

  • Line 1 is the declaration of an immediately invoked function expression (IFFE) that will ensure our code will not be placed in the global namespace. This convention should always be used with JS Link files.
  • Lines 3-6 is the beginning of our template object. Soon we will be adding more properties to help determine how the list is formatted. For now, we’ve specified the BaseViewID and the ListTemplateType which is how we target the Custom List (type 100) so that SharePoint knows what data to provide us.
  • Line 8 uses a Script On Demand (SOD) method to only call our function once the clienttemplates.js file has loaded and the SPClientTemplates object is ready to be used. This is essential to prevent our script from executing before SharePoint is ready.
  • Line 9 registers our template object with the SharePoint CSR engine

Refreshing at this point will still not apply anything since we did not provide any Templates just yet.

Continue?

Everything is in place for us to provide some actual CSR templates, but in order to do so we need to understand what templates are even available and how to use them. So, check out the next post in this series:

Benefits of Client Side Rendering

Applies To: SharePoint 2013, 2016, Office 365

List View Client Side Rendering Primer: 2 of 5

About This Series

This series provides a brief overview of Client Side Rendering for List Views (often referred to as JSLink). Basic extension points and examples are included. The goal of this series is to get developers unfamiliar with this programming model quickly up to speed.

XSLT Alternative

Extensible Stylesheet Language (XSL) is the XML based language used to transform XML generally into either HTML or XML. XSL Transformations (XSLT) is the set of XSL templates to be used in specific transformations.

Benefits

  • Rendering performed Server-Side
  • Very Fast
  • Generally, great caching
  • Many traditional SP developers already have XSL knowledge

Limitations

  • Difficult to learn
  • Out Of The Box (OOTB) examples are overly complex
  • Impossible to debug
  • SP limits use to XSLT 1.0 which, even with the ddwrt functions, is not equivalent to the power of XSLT 2.0+
  • Office 365’s server distribution model negates many of the caching benefits seen in on premises versions (although still fast, large datasets and complicated transforms suffer from more performance issues in the cloud)
  • Non-XSL integrations (JavaScript, CSS, etc.) can be very difficult

XSLT is continuing to be supported (and even improved) in current versions of SharePoint. Many of the OOTB features continue to take advantage of it and there is little alternative in SharePoint 2010/2007.

XSLT continues to be an easy way to make minor tweaks to OOTB rendering. Additionally, there is no reliance on end user technologies (JavaScript and, depending on the complexity, modern browsers) since the rendering is performed on the server before being delivered to the client.

 

Client Side Rendering Benefits

  • Data retrieved Server Side
  • “Faster” page loads since only the data and the formatting logic is downloaded to the client and the markup is created there. Practically speaking, standard pages will not see much benefit from this.
  • Rapid development (debugging, simplified templates, etc.)
  • Many more JavaScript developers
  • Flexible Targeting
  • Easy integration with web services, JavaScript frameworks, etc.

Client Side Rendering Limitations

  • Potential for flashing based on client performance
  • Not fully supported – Display templates are used in some search web parts, but only the XSLTListView web part provides the JS Link property
  • Targeting multiple list views on the same page requires fragile or hacky workarounds

csrShim

csrShim is an open source solution that fills the gap of many of the limitations presented by OOTB client side rendering.

csrShim is an XSLT solution that can be used to:

  • Enable JSLink CSR with Content by Query web parts
  • Enable JSLink CSR with XMLViewer web parts supporting RSS, RDF, Atom, and Atom2
  • Can be easily extended to enable JSLink CSR with XMLViewer web parts and custom XML
  • Solve the multiple list views per page issue through simple parameter configuration

csrShim is available through GitHub at:
https://github.com/thechriskent/csrShim

jslink-pronunciation

Continue?

Alright, now you know why CSR is usually better than its predecessor, XSLT. You’ve gotten a small introduction to csrShim (although not required in any way for this series, the methods and techniques discussed for list view CSR will apply there too).

“CSR sounds awesome!!”, you scream. Well, since you’re super excited to give this thing a go and avoiding eye contact with your coworkers is probably a good idea right now, head on over to the next post in this series: