Click here to Skip to main content
65,938 articles
CodeProject is changing. Read more.
Articles / web / HTML

Using SPLoader.js for SharePoint 2013 - 2019

0.00/5 (No votes)
31 Dec 2018CPOL2 min read 4.5K   24  
Using SPLoader.js to create UI components that read its content from Lists and Libraries in minutes using only HTML

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

  1. Basic SharePoint administration knowledge
  2. Basic HTML knowledge
  3. 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:

HTML
<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.

Image 1

and the code below, striped from bootstrap styling:

HTML
<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:

JavaScript
//An array of all components with many useful info, like the used queries and errors and more
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.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)