månadsarkiv: april 2016

Minimal Download Strategy. Simple

There are many correct ways (1, 2, 3, 4, 5…) of making scripts work with the Minimal Download Strategy Feature (MDS) in SharePoint 2013 and 2016. But to be honest – every time I need it, I get confused. So now it is time to find a simple solution for that.

Who is better at it than the developers of the SharePoint themselves? Look at the MDS code in the built-in Display Templates:

mds-001

Let’s keep it as simple as Item_Default.js, let’s take it as it is and create our own scripts. Here is a skeletton of and MDS-ready script:

function runMyCode() {
	var time = new Date().toISOString();
	console.log('runMyCode', time );
}
runMyCode();
if (typeof(RegisterModuleInit) == 'function') {
	var scriptUrl = '/Style Library/runMyCode.js';
  RegisterModuleInit(scriptUrl, runMyCode);
}

function runMyCode() {

var time = new Date().toISOString();

console.log('runMyCode', time );

}

runMyCode();

if (typeof(RegisterModuleInit) == 'function') {

var scriptUrl = '/Style Library/runMyCode.js';

RegisterModuleInit(scriptUrl, runMyCode);

}

Which boils down to this in pseudocode:

Execute your code
Determine if MDS is enabled
If MDS is enabled
Register your code for execution

That’s it. No more overcomplicating.

Related findings

External scripts (outside SharePoint Site Collection, from CDN) within ScriptBlock of a custom action (like AddJSLink in PnP) work withou any MDS-adjustments. The ScriptBlock adds a script tag to the head of the html document, and it the js reference is added to every AjaxDelta load. I would need more time to find out why. The good news is: it is an argument for using more CDN solutions in SharePoint.

Old stuff

A while ago I wrote two blog posts about MDS. Now I realise they were overcomplicated and the solution required customizations of the master page and 3rd-party scripts.

Minimal Display Template

We want to use our own Display Templates on Non-publishing sites – our team sites. Without the Publishing Feature activated you have to create an own javascript file. Here is short and concise instructions how to install it: Display Templates on Non-publishing Sites.

As described on that blog, you can make copy of an existing Item_Default.js and adjust to your needs.

I also asked Elio Struyf and I got the same tip. I did create my starter template. Here I want to share this very minimal javascript based Display Template:

(function() {
  var config = {
    templateName: 'Item_Minimal';
  }

  var tolleUrl = ['~sitecollection', '_catalogs', 'masterpage',
    'Display Templates', 'Search', 'my-company', 'Item_Minimal.js'].join('u002f');

  function getHtml(plainItem) {
    return ['
&amp;lt;div&amp;gt;', title, '&amp;lt;/div&amp;gt;
'].join('');
  }

  function DisplayTemplate_Minimal(ctx) {
    var cachePreviousTemplateData = ctx.DisplayTemplateData;
    ctx.DisplayTemplateData = {
      'TemplateUrl': tolleUrl,
      'TemplateType': 'Item',
      'TargetControlType': 'SearchResults',
      'ManagedPropertyMapping': {
        'Title':['Title']
      }
    };
    var cachePreviousItemValuesFunction = ctx.ItemValues;
    ctx.ItemValues = function(slotOrPropName) {
      return Srch.ValueInfo.getCachedCtxItemValue(ctx, slotOrPropName)
    };
    ctx.ItemValues = cachePreviousItemValuesFunction;
    ctx.DisplayTemplateData = cachePreviousTemplateData;
    var plainItem = {
      title: $getItemValue(ctx, &amp;quot;Title&amp;quot;)
    }
    return getHtml(plainItem);
  }

  window.RegisterTemplate_Minimal = function() {
    var srchLoaded = Srch &amp;amp;&amp;amp; Srch.U &amp;amp;&amp;amp; Srch.registerRenderTemplateByName;
    if (srchLoaded) {
      Srch.U.registerRenderTemplateByName(config.templateName, DisplayTemplate_Minimal);
    }

    if ('undefined' != typeof (Srch) &amp;amp;&amp;amp;
      'undefined' != typeof (Srch.U) &amp;amp;&amp;amp;
      typeof(Srch.U.registerRenderTemplateByName) == 'function') {
      Srch.U.registerRenderTemplateByName(tolleUrl, DisplayTemplate_Minimal);
    }
  };

  window.RegisterTemplate_Minimal();

  if (typeof(RegisterModuleInit) == &amp;quot;function&amp;quot; &amp;amp;&amp;amp; typeof(Srch.U.replaceUrlTokens) == &amp;quot;function&amp;quot;) {
    RegisterModuleInit(Srch.U.replaceUrlTokens(tolleUrl), window.RegisterTemplate_Minimal);
  }
})();

(function() {

var config = {

templateName: 'Item_Minimal';

}

var tolleUrl = ['~sitecollection', '_catalogs', 'masterpage',

'Display Templates', 'Search', 'my-company', 'Item_Minimal.js'].join('u002f');

function getHtml(plainItem) {

return ['

&lt;div&gt;', title, '&lt;/div&gt;

'].join('');

}

function DisplayTemplate_Minimal(ctx) {

var cachePreviousTemplateData = ctx.DisplayTemplateData;

ctx.DisplayTemplateData = {

'TemplateUrl': tolleUrl,

'TemplateType': 'Item',

'TargetControlType': 'SearchResults',

'ManagedPropertyMapping': {

'Title':['Title']

}

};

var cachePreviousItemValuesFunction = ctx.ItemValues;

ctx.ItemValues = function(slotOrPropName) {

return Srch.ValueInfo.getCachedCtxItemValue(ctx, slotOrPropName)

};

ctx.ItemValues = cachePreviousItemValuesFunction;

ctx.DisplayTemplateData = cachePreviousTemplateData;

var plainItem = {

title: $getItemValue(ctx, &quot;Title&quot;)

}

return getHtml(plainItem);

}

window.RegisterTemplate_Minimal = function() {

var srchLoaded = Srch &amp;&amp; Srch.U &amp;&amp; Srch.registerRenderTemplateByName;

if (srchLoaded) {

Srch.U.registerRenderTemplateByName(config.templateName, DisplayTemplate_Minimal);

}

if ('undefined' != typeof (Srch) &amp;&amp;

'undefined' != typeof (Srch.U) &amp;&amp;

typeof(Srch.U.registerRenderTemplateByName) == 'function') {

Srch.U.registerRenderTemplateByName(tolleUrl, DisplayTemplate_Minimal);

}

};

window.RegisterTemplate_Minimal();

if (typeof(RegisterModuleInit) == &quot;function&quot; &amp;&amp; typeof(Srch.U.replaceUrlTokens) == &quot;function&quot;) {

RegisterModuleInit(Srch.U.replaceUrlTokens(tolleUrl), window.RegisterTemplate_Minimal);

}

})();

Benefits of js approach

If you choose to directly upload and mantain a javascript file you’ll get following benefits:

You can use the same display templates on Non-publishing sites and they work directly in SharePoint Foundation
You’ll get intellisense
You can run static code analysis agains your javascript code and you can create unit tests
It is more readable understandable from developer to developer
It is easier to follow best practices for javascript
It encourages reusing javascript components for Display Templates, CSR (JSLink) Templates.
You like TypeScript? Well, then it is best to skip the “grey” code in html comments.

Findings

You cannot use ‘use strict’ in your js file.

How to create a Display Template

Rename the Item_Minimal.js file to your name, update some properties.

Upload it to _catalogs/masterpage/Display Templates/Search/<your-folder>

Use ContentType: Display Template Code

displaytemplate-002

Template Level: Item and Managed Property Mappings displaytemplate-003

Create a new Result Type. Every time you update the Display Template (item properties) you have to update the Result Type.

displaytemplate-001

Moving from Minimal to Better

Of course the minimal display template is not enough. There is a whole lot of things we can do, I prepared some tips (my own “best practices”):

Learn the Search Display Template Syntax: Corey Roth – Useful js for Display Templates
Follow Elio Struyf’s 10 tips for working with Display Templates (except the first one – javascript is better )
Prefer JavaScript Display Templates if you are a developer and you want to have a better control
Never update the built-in Display Templates.
Centralize reused parts of Display Templates – utilities, common parts, css. Use a CDN site for that.
Check out the SPCSR github repo, there are many Display Templates that you can use or be inspired from.
Create your own folder in _catalogs/masterpage/Display Template/Search to have all your Display Templates within a site collection.

SharePoint Utilities – a promising JavaScript Framework

My colleagues at Bool have developed a new JavaScript framework for SharePoint – sharepoint utilities. It started on our DevDay last year – a whole free day when we could learn new things, try out new techniques or build something that was not even requested from a customer. I was not working on sharepoint utilities, so I almost forgot it until…

I recently re-discovered sharepoint utilities. It is on Github, it is MIT licensed and contributions are welcome. The core of sharepoint utilities (sputils) is a set of wrappers for Search, TermStore, REST that allow you be more productive as a developer.

What I find especially compelling with that it contains some other fundamental stuff that every SharePoint developer needs:

XHR, you only need to use sputils.rest.get or sputils.rest.post to make Ajax requests to SharePoint, no need for jQuery or sprequestexecutor.js
Promise, it contains a minimalist Promise framework – no need for jQuery.Deferred. All calls to SharePoint _api are wrapped in promises. So there is a better way of making calls to SharePoint.
DateTime, it contains some useful functions for working with dates and time.
Functional JavaScript. No need for underscore.js or lodash.js.

To me, XHR and Promises are two important parts that I need in every solution. So instead of linking jQuery and preparing reusable XHR functions for SharePoint, I’d recommend using sharepoint-utilities.