How-To, Tutorial, Szenario

User Custom Actions können einem spezifischem Web, einer Site, oder einer Liste (für unsere Zwecke eher uninteressant) zugewiesen werden. Sie bieten einem die Möglichkeit mittels ScriptLink Javascript einzubinden, ohne die Masterpage anrühren zu müssen. Generell stehen einem hierfür zwei Lösungsansätze zur Verfügung: Das Client Side Object Model (CSOM), oder die Sharepoint REST-API. Wir werden im Laufe dieses Artikels einige Anwendungsbeispiele mit REST anführen.

Jede User Custom Action besitzt die Eigenschaft „Location“, welche immer angegeben werden muss. Sie legt fest wo und wie die User Custom Action eingebunden wird. Um Beispielsweise eine Javascript Datei einzubinden muss der Wert „ScriptLink“ angegeben werden.

Folgende Parameter sind beim Einbinden von Scripts von Bedeutung:

• Location: „ScriptLink“ gibt an dass es sich um ein Script handelt, dass eingebunden werden soll
• Sequence: eine ganze Zahl, legt fest in welcher Reihenfolge Scripts eingebunden werden sollen
• ScriptSrc: Der Pfad zur Datei, gleichzusetzten mit dem „src“-Attribute eines „script“-Tags in HTML
• ScriptBlock: Optional, hier könnte direkt Javascript Code angegeben werden. Nicht empfehlenswert, da die Reihenfolge (Sequence) dann nicht eingehalten werden kann, jedoch notwendig um Stylesheets einzubinden.
• Title & Description: Titel und Beschreibung der User Custom Action
• ID: Optional, hier kann eine eigene ID angegeben werden. Falls nicht vorhanden wird von Sharepoint eine ID generiert

Wichtig: ScriptSrc darf in Sharepoint 2010 und 2013 keine absoluten Pfade beinhalten. Dies ist unbedingt zu vermeiden da Sharepoint sonst gar keine Seiten mehr anzeigt. In Sharepoint Online und Sharepoint 2016 lassen sich auch absolute Pfade problemlos einbinden.

Im folgenden Beispiel wird demonstriert, wie jQuery in eine Site eingebunden werden kann und somit auf allen Pages und Subsites dieser Site verfügbar ist.

$.post({
	url: "/pfad/zur/site/_api/site/usercustomactions",
	data: JSON.stringify({
		"__metadata": { "type": "SP.UserCustomAction" },
		"Location":"ScriptLink",
		"Sequence":"0",
		"Title":"jQuery 3.0.0",
		"Description":"User Custom Action zum Einbinden von jQuery",
		"ScriptSrc" : "~sitecollection/siteassets/css/jquery-3.0.0.min.js"
	}),
	headers: { 
		"X-RequestDigest": $("#__REQUESTDIGEST").val(),
		"content-type": "application/json;odata=verbose",
	},
	success: successHandler,
	error: errorHandler
});

Der angeführte REST-Call liefert einem nach erfolgreichem Erstellen der User Custom Action die eben erstellte UCA als Objekt oder in Form von XML zurück. Sie besitzt eine eindeutige ID (selber angegeben oder von Sharepoint generiert), mit deren Hilfe sie nachträglich wieder bearbeitet oder gelöscht werden kann.

Das folgende Beispiel zeigt wie man Änderungen an einer UCA vornimmt. Wir werden die Eigenschaft „ScriptSrc“ der eben erstellen UCA ändern, um eine aktuellere Version von jQuery zu laden.

$.post({
	url: "/pfad/zur/site/_api/site/usercustomactions('<GUID>')",
	data: JSON.stringify({
		"__metadata": { "type": "SP.UserCustomAction" },
		"ScriptSrc":"~sitecollection/siteassets/css/jquery-3.1.0.min.js"
	}),
	headers: { 
		"X-RequestDigest": $("#__REQUESTDIGEST").val(),
		"content-type": "application/json;odata=verbose",
		"X-HTTP-Method": "MERGE"
	},
	success: successHandler,
	error: errorHandler
});

Das folgende Beispiel zeigt wie die User Custom Action wieder gelöscht werden kann.

$.post({
	url: "/pfad/zur/site/_api/site/usercustomactions('<GUID>')",
	headers: { 
		"X-RequestDigest": $("#__REQUESTDIGEST").val(),
		"X-HTTP-Method": "DELETE"
	},
	success: successHandler,
	error: errorHandler
});

Da es auch Sinn macht Stylesheets einzubinden, ohne die Masterpage bearbeiten zu müssen, werden wir uns nun diesem Problem widmen. In Sharepoint hat man standardmäßig die Möglichkeit eine einzelne CSS Datei einzubinden (Websiteeinstellungen > Gestaltungsvorlage > Alternative URL für CSS-Datei). Dieses Feature hat jedoch einige Nachteile.

• Es kann nur eine einzige Datei eingebunden werden
• Erstellt man nachträglich eine Unterseite, muss die Einstellung erneut gespeichert werden damit diese auch für die neue Unterseite gilt.

Die Nutzung von User Custom Actions zum Einbinden von CSS Dateien ist wesentlich flexibler.

User Custom Actions bieten generell keine Möglichkeit, Stylesheets einzubinden. Es kann jedoch die „ScriptBlock“ Eigenschaft genutzt werden um eine Datei mit Javascript einzubinden.

Javascript zum einbinden einer CSS Datei:

(function(){
	var head = document.getElementsByTagName('head')[0];
	var link = document.createElement('link');
	link.type = 'text/css';
	link.rel = 'stylesheet';
	link.href = '~site/pfad/zu/einer/datei.css';
	head.appendChild(link);
})();

Alternatives Javascript zum einbinden einer CSS Datei (ab Sharepoint 2013):

(function(){ registerCssLink('~site/pfad/zu/einer/datei.css') })();

Einbinden eines Stylesheets mittels User Custom Action, diesmal nur für ein spezifisches Web (z.B. eine Unterseite):

var url = "~site/pfad/zu/einer/datei.css";

var block = [
	"(function(){",
	"var head = document.getElementsByTagName('head')[0];",
	"var link = document.createElement('link');",
	"link.type = 'text/css';",
	"link.rel = 'stylesheet';",
	"link.href = '" + url + "';",
	"head.appendChild(link);",
	"})();"
].join("");

$.post({
	url: "/pfad/zur/site/subsite/_api/web/usercustomactions",
	data: JSON.stringify({
		"__metadata": { "type": "SP.UserCustomAction" },
		"Location":"ScriptLink",
		"Sequence":"100",
		"Title":"",
		"Description":"",
		"ScriptBlock" : block
	}),
	headers: { 
		"X-RequestDigest": $("#__REQUESTDIGEST").val(),
		"content-type": "application/json;odata=verbose",
	},
	success: successHandler,
	error: errorHandler
});