Personnaliser vos sites SharePoint 2013 avec le Client Side Rendering (CSR) et le JS Link

Introduction

Effectuer des personnalisations dans l’interface utilisateur de SharePoint a toujours été un défi pour bien des développeurs. Dans les versions 2007 et 2010, on utilisait majoritairement le XSLT pour faire des personnalisations bien que c’était relativement complexe à s’y familiariser. D’autres utilisaient des WebParts de type Éditeur de contenu pour effectuer des modifications JavaScript directement dans une page et dans ce cas la difficulté est de trouver une « poignée » pour appliquer les modifications sur un élément précis. La fonctionnalité JSLink est arrivé dans SharePoint 2013 pour simplifier la vie aux développeurs en leur permettant de faire des personnalisations avec des langages qu’ils connaissent déjà : HTML, JavaScript et CSS. Grâce à cette fonctionnalité, on peut contrôler via un fichier JavaScript le rendu visuelle des éléments suivant :

  • Champ
  • Élément
  • Formulaire de liste
  • Vue
  • WebPart

XSL/XSLT vs Client Side Rendering

Le tableau ici-bas résume bien les différences entre les deux fonctionnalités :

XSL/XSLT Client Side Rendering
Performance
  • Plus rapide lorsqu’il y a un grand nombre d’éléments à afficher.
  • Aucune charge additionnel dans le navigateur.
  • Plus lent lorsqu’il y a un grand nombre d’éléments à afficher.
  • La vitesse du navigateur client peut avoir un impact sur la performance.
  • Réduit la charge du serveur.
Complexité
  • Langage complexe à apprendre initialement.
  • Difficile à déboguer (Souvent par essaie-erreur).
  • Temps de développement plus grand.
  • Facile de déboguer du JavaScript, HTML et CSS avec les navigateurs modernes.
  • Temps de développement réduit.
Flexibilité
  • Limité aux fonctions XSLT 1.0 pour SharePoint 2010 et 2013.
  • Limité pour faire un rendu visuel complexe.
  • Très efficace pour faire des opérations coûteuse (ex : Count dans une vue).
  • Permet de cibler les personnalisations sur une vue, un champ, une WebPart, etc…
  • Possibilité d’utiliser des plugins (ex : JQuery).
  • Très adapté pour faire un rendu visuel complexe.
  • Inefficace pour faire des opérations coûteuses (ex : Count dans une vue).
Compatibilité
  • Indépendant du navigateur.
  • Supporté dans SP2010 et SP2013.
  • Fonctionne même si le JavaScript est désactivé dans le navigateur.
  • Génère du contenu statique qui est bien interprété par les robots d’indexation.
  • Adapté pour des sites publiques.
  • Dépendant du navigateur.
  • Supporté dans SP2010 et SP2013
  • Requiert que le JavaScript soir activé dans le navigateur.
  • Génère du contenu dynamique qui n’est pas bien interprété par les robots d’indexation.
  • Non-adapté pour des sites publiques.

Comment configurer le JSLink?

Pour référencer vos fichiers dans la propriété JSLink vous pouvez spécifier un jeton de remplacement (Token) ainsi qu’un séparateur (|) si vous avez plusieurs fichiers.

Les jetons disponibles sont les suivants :

  • ~site : correspond au URL du site Web courant.
  • ~sitecollection : correspond au URL de la collection de site parent du site Web courant.
  • ~layouts : correspond au dossier « _layouts/15 » de la web application.
  • ~sitelayouts – correspond au dossier layouts du site courant (ex : site/monsite/monsoussite/_layouts/15).
  • ~sitecollectionlayouts : correspond au dossier layouts de la collection de site courante (Ex:  /sites/monsite/_layouts/15).
  • ~sitelayouts – correspond au dossier layouts du site courant (Ex: /site/monsite/monsoussite/_layouts/15).

En utilisant ces jetons avec le séparateur on peut donc référencer plusieurs fichiers de scripts dans le JSLink.

Ex : ~site/style library/­monScript1.js|~sitecollection/style library/monScript2.js.

On peut spécifier la propriété JSLink en utilisant ces méthodes :

  • PowerShell
  • Code serveur C#/VB en utilisant l’API
  • Code serveur déclaratif XML
  • Interface utilisateur

Pour simplifier ce billet, je vous propose la méthode utilisant l’interface utilisateur :

jslink_link

Pour plus de détail sur les autres méthodes permettant de spécifier la propriété JSLink, je vous recommande le billet de Tobias Zimmergren.

Fonctionnement technique

À l’intérieur de ces fichiers, le JavaScript est utilisé pour « overrider » :

  • la manière dont les données sont affichés
  • le contenu à afficher

Voici un exemple de code permettant de modifier la valeur d’un champ dans une vue :

// Créer un namespace pour la fonction afin d'éviter des collisions avec les autres fonctions
var sharepointerie = sharepointerie || {};

(sharepointerie.CustomizeFieldRendering = function () {

// Initialise les variables pour overrider les objets
 var overrideCtx = {};
 overrideCtx.Templates = {};

 /*
 * Force la valeur "SharePointerie" dans le titre de tous les éléments.
 */
 overrideCtx.Templates.Fields = {
 'LinkTitle': { 'View' : 'SharePointerie' }
 };

 /*
 * Enregistre l'override du template.
 */
 SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrideCtx);
})();

Techniquement, on construit un objet qui sera ensuite utilisé afin d’enregistrer l’override du template. L’objet « overrideCtx » peut ensuite interagir avec ces propriétés :

  • View
  • Header
  • Body
  • Footer
  • Group
  • Item
  • Fields
  • OnPreRender
  • OnPostRender

Dans l’exemple on utilise la propriété Fields avec ce format :

overrideCtx.Templates.Fields = {NomDuChamp: {Porté : Override}}

  • NomDuChamp : Le nom interne du champ que l’on veut overrider.
  • Porté : Les choix possibles « View », »DisplayForm », »EditForm », et « NewForm » permettent de spécifier l’endroit ou l’on veut faire l’override.
  • Override : Contient une chaîne HTML ou une fonction à exécuter à l’intérieur de tags « <#= #> ».

Résultat (avant l’ajout du CSR) :

jslink_technique_avant

Résultat (après l’ajout du CSR) :

jslink_technique_apres

Des exemples concrets

1) Limiter la taille du texte dans le champ « Corps » d’une liste d’annonces

Cet exemple de code, réalisé par Muawiyah Shannak, permet d’afficher un résumé du corps d’une annonce et d’afficher la version intégrale dans une infobulle.

Pour déployer la solution :

  1. Télécharger le fichier CSR.
  2. Ajouter le fichier sous /Style Library/.
  3. Créer une liste de type Annonces
  4. Créer ou modifier une vue afin d’afficher le champ Corps.
  5. Modifier la page contenant la List View WebPart.
  6. Aller dans les propriétés de la WebPart et ajouter le fichier JSLink (~sitecollection/Style%20Library/SubstringLongText.js) dans la propriété Lien Js (JSLink) sous l’onglet Divers
  7. Cliquer sur Appliquer et quitter l’édition de la page.

Résultat (avant l’ajout du CSR) :

jslink_limite_texte_avant

Résultat (après l’ajout du CSR) :

jslink_limite_texte_apres

2) Ajouter des onglets dans un formulaire

Cet exemple de code, réalisé par Muawiyah Shannak, permet d’utiliser JQuery Tabs pour afficher des onglets dans un formulaire.

Pour déployer la solution :

  1. Télécharger le fichier CSR.
  2. Ajouter le fichier sous /Style Library/.
  3. Créer une liste personnalisé
  4. Ajouter des colonnes à la liste
  5. Modifier l’objet tabsObj selon vos besoin.
  6. Créer une nouvelle vue contenant le champ Lien
  7. Modifier les pages « newform » et « editform » de la liste
  8. Aller dans les propriétés de la WebPart et ajouter le fichier JSLink (~sitecollection/Style%20Library/Tabs.js) dans la propriété Lien Js (JSLink) sous l’onglet Divers
  9. Cliquer sur Appliquer et quitter l’édition de la page.

Résultat (avant l’ajout du CSR) :

jslink_tabs_avant

Résultat (après l’ajout du CSR) :

jslink_tabs_apres

Points à faire attention

  • Il peut y avoir des conflits avec le CSR si vous utilisez la fonctionnalité « Minimal download strategy ». Pour corriger ce problème consulter ce billet.
  • Le code de vos fonctions CSR ne devrait pas être défini dans le Namespace globale.
  • Le nom interne des colonnes est utilisé dans le code JavaScript des fonctions CSR alors favoriser des noms de colonnes sans espaces et sans caractères accentués.
  • Le CSR, contrairement au XSLT, dépend du navigateur alors assurez-vous de tester dans plusieurs navigateurs.

Conclusion

Pour conclure, le CSR comporte plusieurs avantages au niveau de la flexibilité et de la complexité comparativement au XSLT. Cependant, il vient aussi avec certaines lacunes en lien avec la performance et la compatibilité. Il y a donc énormément de potentiel à utiliser le CSR pour vos personnalisations (Validations, AJAX, etc…) mais comme il y a des limitations, je crois que le XSLT va continuer d’exister en parallèle. Je vous invite donc à l’essayer et à me donner vos commentaires!

Références

Voici quelques liens pour approfondir vos connaissance sur le CSR / JSLink.

Exemples de codes CSR réalisé par Muawiyah Shannak

Perfomance de l’utilisation du CSR via le JSLink

5 faits concernant l’utilisation du JSLink

Comment : personnaliser un type de champ à l’aide de rendu côté client

Comment : personnaliser le mode Liste dans les apps pour SharePoint à l’aide du rendu côté client

Introduction au CSR par Ross Bradbrook

Bon point de départ sur l’utilisation de l’API CSR

Advertisements

20 avis sur « Personnaliser vos sites SharePoint 2013 avec le Client Side Rendering (CSR) et le JS Link »

  1. dany

    Bonjour.
    Sympathique blog.
    J’ai une petite question.
    Sauriez vous , comment pourrait ont overrider le fichier clientrendered.js par example.
    Il y a une solution pour le core.js en , optant l’option defere au niveau de la master page a son appel.
    Comme vous devez le savoir c’est un peut different avec clientrendered.js ou search.clientcontrol.js.
    Bien evidement , ma question se pose pour l’unique raison de ne pas perdre le support microsoft au sein de l’organisation ou je travail.

    Desole pour les fautes et la ponctuation mais je traivail sur un clavier querty car je me situe a l’etrange depuis pas mal d’annees maintenant.

    Répondre
      1. dany

        Bonjour
        merci pour votre réponse.
        Au final, j’ai overrider un namespace spécifique à partir du fichier javascript sharepoint dans un fichier javascript externe personnalisé et ainsi je n’ai pas eu à toucher au fichier original de Microsoft. Par contre, a mon gout cela fait un peut lourd comme solution.
        Avez vous une autre suggestion ?

      2. dany

        Bonsoir samuel
        oui effectivement ,cependant
        le temps qu’il m’a pris d’overrider le name space complet a ete tres rapide
        d’autant plus qu’il n’etait pas si grand que cela et ne contenait que quelques functions ,trois ou quatre si je ne m’abuse ,functions qui etaient relativement courtes .
        Par contre quand nous arriverons a la version suivante de ce module de dev ,je ne manquerai certainement pas d’overrider juste les fonctions concernnees.
        L’idee etait en gros de pouvoir interragir avec le resultat des recherches de sharepoint a la racine sans avoir a developper du code security trimming interface , car ce code s’execute au niveau du server d’indexation et en plus c’est un code c# relativement long, sans oublier la parti system de notre organisation,qui nous aurait cause pas mal de problemes au niveau des supports de dev.
        Alors entre wcf , clientrendered .js et autre et avec un algorithme de gestions des permissions personnalisees sans avoir a breaker les permissions de default en special, nous avons pu arriver a nos fins.
        merci pour votre aide et espere avoir d’autre echanges.
        et encore une fois, desole pour les fautes mais j’ai un peut perdu mon francais a force de ne plus que parler anglais 😦

  2. Milna

    Je trouve votre billet très intéressant, merci pour tous ces éléments. Comme le dit le vielle adage « Le bien-être est la loi des corps, mais l’ordre est la loi des esprits ». Bonne continuation !

    Répondre
  3. PIERRAT

    Bonjour, merci pour cette excellent tutoriel qui m’ouvre pas mal de voies dans mon développement sous Sharepoint.
    Seul souci, j’essaye de mettre en place les onglets pour rendre plus sympathique mes listes, malheureusement je rencontre un souci.
    Les onglets se mettent en place, mais pas les champs. En fait seul les onglets apparaissent et tout les champs disparaissent. J’ai déjà changé le fichier js évidemment, en remplaçant les noms de colonne mais rien n’y fait ils ne veulent pas apparaître.
    Une solution à me proposer?

    Répondre
    1. Samuel Levesque Auteur de l’article

      Bonjour,

      Désolé de la réponse tardive!
      Dans quel formulaire est-ce que vous effectuez la modification : NewForm, EditForm, DisplayForm?
      Pour ma part, je viens de le tester dans mon environnement O365 sur le NewForm avec Chrome.
      Assurez vous que vous utilisez bien le nom Interne des colonnes et non pas le nom d’affichage de la colonne.
      Ex :

      var tabsObj = [
      [« General », [« Title », « Age »]],
      [« Work », [« Manager »]]
      ];

      Title est le nom interne alors que Titre est le nom d’affichage.

      Il y a un Add-in qui permet de faire le travail aussi : https://store.office.com/apptex-WA104379332.aspx?assetid=WA104379332

      Merci

      Répondre
      1. Alex Piki

        Merci beaucoup de ta réponse 😀 Effectivement je m’étais laissé abusé par le nom d’affichage. Je les avais changé sans pensé que le nom interne lui n’avait pas changé. Du coup après rectification cela marche très bien, encore merci !

        Du coup j’ai une autre question qui me vient en tête, le script est écrit pour fonctionner sur le formulaire de modifications et le formulaire d’ajout. Est-il possible en modifiant le script d’avoir le même design pour le formulaire d’affichage ? Si oui as-tu une piste ou un lien pouvant m’expliquer comment faire? (je ne maitrise pas javascript, je comprends le fonctionnement mais je connais pas ou peu les fonctions à utiliser du coup pour ré-écrire un script c’est encore compliqué ^^ )

        D’avance merci !

      2. Samuel Levesque Auteur de l’article

        Salut !

        Pour le Dispform, la dernière partie du code doit sélectionner un élément différent du DOM :


        function TabsOnPostRender(ctx) {

        var controlId = ctx.ListSchema.Field[0].Name;

        jQuery("a[name^='SPBookmark_" + controlId + "']").closest("tr").hide();

        }

        function showTabControls(index)

        {

        jQuery("a[name^='SPBookmark_']").closest("tr").hide();

        for (var i = 0; i < tabsObj[index][1].length; i++) {

        jQuery("a[name^='SPBookmark_" + tabsObj[index][1][i] + "']").closest("tr").show();

        }

        Je viens de l’essayer et ça fonctionne parfaitement 🙂

        Merci !

  4. Piki

    Vous êtes mon sauveur ! Cela marche parfaitement, je vous remercie encore une fois.Rapidité, simplicité, courtoisie franchement je vous tire mon chapeau 😀
    Bonne continuation à vous et encore un grand merci

    Répondre
  5. Nadia

    Bonjour
    merci pour ce article très intéressant. J’ai fait un essai en commençant de crée une liste personnalisé et en ajoutant tout les colonnes . Puis j’ai fait copier coller programme pour faire un test mais reste que je comprends pas ou je doit enregistrer mon programme ? car j’ai crée une bibliothèque et j’ai télécharger .js dans cette bibliothèque. Puis dans la webpart j’ai ajouter le lien LInkjs mais ca fonctionne pas? pourriez vous m’expliquer un peu ou je dois mettre mon fichier .js merci

    Répondre
    1. Samuel Levesque Auteur de l’article

      Bonjour, vous pouvez enregistrer vos fichiers dans la bibliothèque de votre choix et ensuite les référer dans votre WebPart via le lien JS. Pour faire un premier test, peut-être utiliser la bibliothèque existante « /style library/ » à la racine de votre collection de site et mettre ceci dans votre WebPart : ~sitecollection/Style%20Library/VotreScript.js
      Merci et bonne journée!

      Répondre
      1. nadia

        Bonjour
        Merci beaucoup pour la réponse mais toujours ne fonctionne pas . Donc ma question est ce que çà est relié a le faite que la fonctionnalité Publication SharePoint Server n’est pas activé car j’ai vu sur un article qu’il faut l’activé

Laisser un commentaire

Entrer les renseignements ci-dessous ou cliquer sur une icône pour ouvrir une session :

Logo WordPress.com

Vous commentez à l’aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l’aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l’aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l’aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s