Month: December 2016

Extending csrShim for Custom XML (JSLink)

theChrisKent Client Side Rendering, SharePoint , , , , , ,
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!