Introduction
This tip explains how SPLoader.js works and how to use it to create dynamic components without any JavaScript or C# code with example.
Prerequisites
- Basic SharePoint administration knowledge
- Basic HTML knowledge
- Admin permissions on your SharePoint farm
Background
Usually, if you want to create UI components that read their content from Lists or Libraries, you need to write some JavaScript or C# code to call SharePoint's REST APIs or using JSOM (JavaScript Object Model).
SPLoader.js lets you skip these steps and create dynamic components using HTML only and SPLoader
will use JSOM in the background to load all your components for you.
Setup
Upload SPLoader.js to your site and add references to JQuery and SPLoader.js in your master page or page layout:
<head>
...
<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<script src="/Style Library/JS/SPLoader.js"></script>
...
</head>
Using the Code
SPLoader
components are HTML elements with few custom attributes to tell SPLoader
what to do. Here are all the attributes that you might use:
sp-element
= no value needed, used on the root element of the component to be processed sp-list-title = "list title"
sp-web-url = "/web"
sp-filter-field
= "Boolean field internal name" sp-item-count = "10"
sp-onload
= callback to call after the component is loaded sp-repeat
= no value needed, used on the element that should be repeated for each item in the results sp-bind
= "a binding is a pair of field, attribute you can chain bindings like this: 'FieldName1,attr1;FieldName2,attr2;FieldName3,attr3
'" e.g.: <img sp-bind="FileRef,src;Name,title" />
. You can use attribute: html
to map to inner html. Don't use spaces. sp-order = "desc" | "asc"
sp-order-field = "Field Internal Name"
Here is a simple example for a component that lists three pages from your site.
and the code below, striped from bootstrap styling:
<div sp-element="" sp-web-url="/"
sp-list-title="Pages" sp-item-count="3"
sp-order-field="ArticleStartDate" sp-order="desc">
<div sp-repeat>
<a sp-bind="FileRef,href">
<img sp-bind="PublishingRollupImage,src;Title,title">
<p sp-bind="Title,html"></p>
<p sp-bind="ArticleStartDate,html"></p>
</a>
</div>
</div>
You can use your preferred way to add the HTML to your page, I prefer uploading the HTML components as text files and link them in Content Editor Webparts.
You can access all components after they are loaded using JavaScript:
window.spLoader.components
How It Works
SPLoader.js finds all elements with the attribute sp-element
and extracts all the information needed to retrieve the data, then, it uses JSOM (JavaScript Object Model) to query for the data, after that, it maps all fields from the results to the corresponding elements in the repeat template (the element with attribute sp-repeat
).
Note
SPLoader.js is not tested for SharePoint Online, but it should work fine since it uses JSOM which is supported in SharePoint Online.
Points of Interest
I found that this way, I can centralize the mechanism in which all data is retrieved, save lots of development time and limit the places that bugs can hide in, and the fact that SPLoader.js uses JSOM means that it is supported across all modern browsers and SharePoint versions from 2013 and above.