Kolumne: SharePoint ganz praktisch

SharePoint: so funktioniert clientseitiges Rendering mit JavaScript
Kommentare

In früheren Ausgaben dieser Kolumne haben wir uns dem Thema der Datenausgabe durch serverseitige Ausgabevorlagen gewidmet. Die SharePoint Version 2013 stellt eine weitere Möglichkeit bereit, um auch clientseitig auf die Datenausgabe Einfluss zu nehmen: das clientseitige Rendering mithilfe von JavaScript.

In den vergangenen Ausgaben wurde gezeigt, wie mithilfe serverseitiger Ausgabevorlagen die Darstellung in Listen und Formularen an eigene Bedürfnisse angepasst werden kann. Die Erstellung solcher Vorlagen ist allerdings nicht einfach und benötigt immer serverseitigen Code. Da mittlerweile die Einbringung serverseitigen Codes in SharePoint in bestimmten Szenarien nicht mehr möglich ist, wurde ein weiteres Konzept eingeführt, um die Datendarstellung anpassen zu können. Dieser neue Mechanismus namens „Clientseitiges Rendering“ (engl. Client-Side Rendering, kurz: CSR) ermöglicht die Anpassung der Ausgabe direkt im Browser über JavaScript.

Um den Unterschied der beiden Möglichkeiten zu verdeutlichen, stellt Abbildung 1 die beiden Verfahren schematisch gegenüber. Im oberen Bereich ist die klassische serverseitige Generierung der Ausgabe dargestellt. Wie hieran erkennbar ist, fordert der Client Daten an (Request) und bekommt diese direkt im HTML zurück. Auf der Serverseite stehen für die Beeinflussung des erstellten HTML verschiedene Möglichkeiten wie XSLT oder eigener Code zur Verfügung. Von Nachteil in dieser Variante ist jedoch, dass die Rückgabe des Aufrufs eine Vermischung zwischen Präsentation und Daten darstellt. Wünschenswert wäre, dass die Anfrage nur reine Daten zurückliefert. Genau das leistet nun der clientseitige Rendering-Mechanismus, wie es die untere Darstellung in Abbildung 1 verdeutlicht. Bei einer Anfrage (Request) antwortet der Server lediglich mit einem Datenpaket in Form von JSON. Für die Aufbereitung und Darstellung der Daten ist dann der Client zuständig.

Abb. 1: Serverseitiges vs. clientseitige Ausgabe

Abb. 1: Serverseitiges vs. clientseitige Ausgabe

Möchten Sie noch tiefer in SharePoint einsteigen? Besuchen Sie den SharePoint Day auf der BASTA! Herbst!

Flexibler Einsatz der Vorlagen

Der clientseitige Mechanismus kann für verschiedene SharePoint-Elemente zum Einsatz kommen. So können Ausgabevorlagen bei Listen, Formularen und bei der Ausgabe von Suchresultaten verwendet werden. Abbildung 2 zeigt beispielhaft die verschiedenen Bereiche einer Listenansicht, die durch clientseitige Vorlagen angepasst werden können. Wie hier erkennbar ist, können alle Bereiche über Vorlagen beeinflusst werden. Um nun einen ersten Eindruck davon zu bekommen, wie eigene Ausgabevorlagen zu definieren sind, wird in einem ersten Beispiel die Ausgabe einer Listenspalte innerhalb einer Listenansicht verändert. Abbildung 3 zeigt den Endzustand der Anpassung. In Listing 1 ist das zugehörige JavaScript abgebildet. Zunächst wird hier ein JavaScript-Objekt namens templateCtx definiert. Dieses wird um die Objekteigenschaft Templates und Templates. Fields erweitert. Über die Eigenschaft Templates.Fields kann nun festgelegt werden, wie einzelne Spalten ausgegeben werden sollen. Das über die Eigenschaft Fields definierte Objekt erwartet als Schlüssel den Namen des Felds aus der Liste, das um eine spezielle Ausgabevorlage erweitert werden soll. Für die Felder kann zusätzlich für jede Ausgabemöglichkeit eine JavaScript-Funktion angegeben werden, die das spezielle HTML für die Darstellung generiert. In diesem Beispiel soll die Ausgabe für die Listendarstellung angepasst werden, daher wird hier für die Darstellungsart View eine JavaScript-Funktion angegeben. Die JavaScript-Funktion renderTitle ist für die Generierung des HTML zuständig. Diese Funktion erhält über einen Parameter Zugriff auf alle relevanten Informationen. Die wohl wichtigste Eigenschaft des übergebenen Objekts ist CurrentItem. Hierüber können alle Felder des aktuellen Listeneintrags abgerufen werden. Zudem können hierüber leicht die aktuellen Werte des Listeneintrags abgerufen werden. Das so vorbereitete JavaScript-Objekt templateCtx muss nun nur noch vom so genannten TemplateManager registriert werden, damit es bei der Listenausgabe auch berücksichtigt wird. Steht das JavaScript in Listing 1 bereit, stellt sich natürlich schnell die Frage, wie es mit der Liste verknüpft werden kann. Dieses wird im Folgenden beantwortet.

Abb. 2: Mögliche Bereiche für eine clientseitige Anpassung

Abb. 2: Mögliche Bereiche für eine clientseitige Anpassung

Abb. 3: Ergebnis der Layoutanpassung für das Feld „Titel“

Abb. 3: Ergebnis der Layoutanpassung für das Feld „Titel“

(function () {
  var templateCtx = {};
  templateCtx.Templates = {};
  templateCtx.Templates.Fields = {
    'Title': { 'View': renderTitle }
  };
  SPClientTemplates.TemplateManager.RegisterTemplateOverrides(templateCtx);
  function renderTitle(ctx) {
    return "<h1 style=\"color: red;\" >" + ctx.CurrentItem.Title + "</h1>";
  }
})();

CSR installieren und verwenden

Im ersten kleinen Einstiegsbeispiel aus Listing 1 wurde die Darstellung der Spalte „Titel“ angepasst. Um dieses Script in SharePoint testen zu können, gibt es mehrere Möglichkeiten. Die einfachste und für erste Entwicklungsschritte schnellste Variante besteht darin, die JavaScript-Datei innerhalb des SharePoint-LAYOUTS-Verzeichnisses innerhalb eines Unterordners abzulegen. Danach kann diese Datei über die JS-Link-Eigenschaft des Listenansichts-Web-Parts referenziert werden. Dazu ist wie folgt vorzugehen:

  1. Seite mit der gewünschten Liste im Browser aufrufen
  2. Seite in den Bearbeitungsmodus schalten
  3. Die WebPart-Eigenschaften der Liste öffnen
  4. Die URL zur JavaScript-Datei ist innerhalb der Eigenschaft JS-Link einzutragen.
  5. Eigenschaften speichern und Seite speichern

Schnell und überall: Datenzugriff mit Entity Framework Core 2.0

Dr. Holger Schwichtenberg (www.IT-Visions.de/5Minds IT-Solutions)

C# 7.0 – Neues im Detail

Christian Nagel (CN innovation)


Ist die URL korrekt eingetragen worden, sollte nun der Titel gemäß definiertem Layout dargestellt werden. Geschieht dies noch nicht, sollte zunächst geprüft werden, ob die Datei geladen wurde und keine JavaScript-Fehler auftraten. Diese Art der Einbindung eignet sich besonders gut für die Entwicklung eigener Ausgabevorlagen. Für die spätere Bereitstellung innerhalb einer produktiven Umgebung existieren weiterhin die folgenden Möglichkeiten:

  • Anlage einer eigenen deklarativen Felddefinition
  • Setzen der Feldeigenschaft JSLink per serverseitigem Code
  • Aktualisierung über PowerShell (Feld oder WebPart)
  • Anlage eines neuen Feldsteuerelements

Werden im Zuge einer SharePoint-Lösung eigene Felder deklarativ erstellt, kann bei der XML-Felddefinition direkt der Link zu einer CSR-JavaScript-Datei angegeben werden. Listing 2 zeigt dazu ein entsprechendes Beispiel. Sind alle Felder bereits installiert, kann auch die JSLink-Eigenschaft über das SharePoint-Objektmodell gesetzt werden. Listing 3 zeigt dazu ein entsprechendes Beispiel. Weiterhin kann diese Eigenschaft auch über PowerShell gesetzt werden (Listing 4). Sollen bestehende Web Parts auf Seiten um die JSLink-Eigenschaft aktualisiert werden, bietet sich auch hier der Weg über PowerShell an. Anstatt alle betroffenen Web Parts manuell zu aktualisieren, kann PowerShell aus Listing 5 zur Automatisierung herangezogen werden.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">  
  <Field ID="{...}" Name="Interne Prüfung"
       DisplayName="Geben Sie das Ergebnis der Überprüfung ein."
       Type="Text" Required="FALSE" Group="Legal"
       JSLink="/_layouts/15/[custom-solution]/csr-script.js">
  </Field>
</Elements>
using (SPSite site = new SPSite("[PORTAL URL]"))
{
    SPWeb web = site.RootWeb;
    SPField fldIComment = web.Fields["InternalComment"]; 
    fldIComment.JSLink = "/_layouts/15/[custom-solution]/csr-script.js ";
    fldIComment.Update(true);
}
$web = Get-SPWeb [PORTAL URL]
$field = $web.Fields["InternalComment"]
$field.JSLink = "/_layouts/15/[custom-solution]/csr-script.js";
$field.Update($true)
$web = Get-SPWeb [PORTAL URL]
$webPartPage = "/Lists/contacts/AllItems.aspx"
$file = $web.GetFile($webPartPage)
$file.CheckOut()
$webPartManager = $web.GetLimitedWebPartManager($webPartPage, 
  [System.Web.UI.WebControls.WebParts.PersonalizationScope]::Shared)
$webpart = $webPartManager.WebParts[0]
$webpart.JSLink = "/_layouts/15/[custom-solution]/csr-script.js"
$webPartManager.SaveChanges($webpart)
$file.CheckIn()

Details zum TemplateManager

Um die Struktur und die Möglichkeiten der Templateregistrierung beim TemplateManager besser verstehen zu können, zeigt Listing 6 die für die Ausgabeformatierung wichtigsten Eigenschaften des Templateobjekts. Im Vergleich dazu kann noch einmal Abbildung 2 herangezogen werden, in der die verschiedenen anpassbaren Bereiche dargestellt wurden. Zunächst existieren dort die beiden Ereignisse OnPreRender und OnPostRender. Wie die Ereignisnamen schon vermuten lassen, wird das Ereignis OnPreRender vor der Ausgabe und das zweite Ereignis nach der Ausgabegenerierung aufgerufen. Innerhalb dieser Ereignisse können dann eventuelle Vor- und Nachinitialisierungen durchgeführt werden. Zum Beispiel kann das OnPostRender-Ereignis dazu verwendet werden, um nach der Generierung des dynamischen DOM noch zusätzliche Ereignisbehandler (EventHandler) zu registrieren oder das DOM zu manipulieren.

Die Eigenschaft Templates stellt für jeden anpassbaren Bereich eine eigene Eigenschaft zur Verfügung. Über diese inneren Eigenschaften wie View, Body, Header usw. kann für jeden entsprechenden Bereich das Ausgabeformat festgelegt werden. Die Eigenschaft Fields ermöglicht die Festlegung des Ausgabeformats für jedes Feld bzw. jede Listenspalte. Hierbei muss zunächst als Schlüssel der Feldname angegeben werden. Anschließend können dann für die verschiedenen Darstellungsformen

  • Listenansicht (View),
  • Bearbeitungsformular (EditForm),
  • Ansichtsformular (DisplayForm) und
  • Neuformular (NewForm)

spezielle Ausgabeformate definiert werden. Somit ermöglicht dieses Objekt die flexible Anpassung der Ausgabe für alle Bereiche der Oberfläche.

var options = {
  OnPreRender: /* Funktion(en)  */,
  OnPostRender: /* Funktion(en) */
  Templates: {
    View: /* Funktion oder eine Zeichenkette */,
    Body: /* Funktion oder eine Zeichenkette */,
    Header: /* Funktion oder eine Zeichenkette */,
    Footer: /* Funktion oder eine Zeichenkette */,
    Group: /* Funktion oder eine Zeichenkette */,
    Item: /* Funktion oder eine Zeichenkette */,
    Fields: {
      'Field1 Internal Name': {
          View: /* Funktion oder eine Zeichenkette */,
          EditForm: /* Funktion oder eine Zeichenkette */,
          DisplayForm: /* Funktion oder eine Zeichenkette */,
          NewForm: /* Funktion oder eine Zeichenkette */
      },
      'Field2 Internal Name': {
          View: /* Funktion oder eine Zeichenkette */,
          EditForm: /* Funktion oder eine Zeichenkette */,
          DisplayForm: /* Funktion oder eine Zeichenkette */,
          NewForm: /* Funktion oder eine Zeichenkette */
      },
      ...
    }
  },
  ListTemplateType: [VALUE], ViewStyle: [VALUE], BaseViewID: [VALUE]  
  ...
};

CSR-Reichweite

Wird ein CSR-JavaScript eingebunden, wirkt es sich zunächst – ohne weitere Einschränkung – auf alle Listendarstellungen auf einer Seite aus. Das heißt: Befinden sich auf einer Seite mehrere unterschiedliche Listen, wirkt sich das eingebundene CSR-JavaScript auf alle diese Listen aus. Das ist in der Regel nicht gewünscht, vielmehr soll das Script auf eine bestimmte Liste oder einen bestimmten Listentyp eingeschränkt werden. Dazu dienen die in Listing 6 dargestellten Eigenschaften ListTemplateType, ViewStyle und BaseViewID. Über die Eigenschaft ListTemplateType kann die relevante Listenvorlage angegeben werden. Sollen zum Beispiel alle Aufgabenlisten (Task Lists) um ein spezielles clientseitiges Layout erweitert werden, muss die Eigenschaft auf die ID 171 eingestellt werden. Eine Übersicht über alle Listenvorlagen-IDs ist online abrufbar. Weiterhin kann über die Eigenschaft BaseViewID das eigene CSR auf eine bestimmte Ansicht eingegrenzt werden. Zusätzlich zu den beiden Eigenschaften ermöglicht ViewStyle die Begrenzung auf eine bestimmte Darstellungsform.

Zusammenfassung

Neben den serverseitigen Feldsteuerelementen bieten clientseitige Ausgabevorlagen eine weitere gute Möglichkeit, um auf die Darstellung von Daten Einfluss nehmen zu können. In manchen Szenarien, in denen der Einsatz von serverseitigem SharePoint-Code nicht möglich ist, stellt der CSR-Mechanismus die einzige Option dar, die Ausgabe anzupassen. In neueren Projekten, die auf SharePoint 2013 oder höher basieren, sollten, wenn möglich, keine neuen serverseitigen Feldsteuerelemente umgesetzt werden. Der Realisierung eigener flexibler CSR-Vorlagen ist – wenn möglich – immer Vorrang zu geben. Der CSR-Mechanismus entlastet den SharePoint-Server und verschiebt etwas Arbeit auf den Client. Das ist in Anbetracht der heutzutage sehr leistungsfähigen Endgeräte als wesentlicher Vorteil zu verstehen. Zudem können CSR-Definitionen sehr viel einfacher angepasst und erweitert werden, als dies bei serverseitigen Feldsteuerelementen möglich ist. Da das CSR-Feature auf JavaScript beruht, ist auch kein spezielles SharePoint-Server-API-Wissen notwendig, sodass im Prinzip jeder Webentwickler CSR-Lösungen realisieren kann. Allerdings ist derzeit die API-Dokumentation in diesem Bereich sehr überschaubar, sodass die Entwicklung nicht immer ganz einfach ist.

Möchten Sie noch tiefer in SharePoint einsteigen? Besuchen Sie den SharePoint Day auf der BASTA! Herbst!

Entwickler Magazin

Entwickler Magazin

Dieser Artikel ist im Entwickler Magazin erschienen – es bietet Softwareentwicklern Einblicke und Orientierung in einem Markt, der stets komplexer wird. Natürlich können Sie das Entwickler Magazin über den entwickler.kiosk auch digital im Browser oder auf Ihren Android- und iOS-Devices lesen.

 

Aufmacherbild: Online customer service satisfaction survey on a digital tablet via Shutterstock / Urheberrecht: mama_mia

Unsere Redaktion empfiehlt:

Relevante Beiträge

Meinungen zu diesem Beitrag

X
- Gib Deinen Standort ein -
- or -