SERIE: IL CLIENT SIDE RENDERING DI SHAREPOINT 2013


In uno dei precedenti post abbiamo fatto un'introduzione all'argomento. Oggi faremo il primo passo: come ridefinire quello che è il rendering di default di uno dei campi di SharePoint 2013.
Per farlo prendiamo come esempio il campo "% complete" di una lista di task (internal name: "PercentComplete").
Useremo questo campo molto spesso da qui in avanti per vedere le varie funzionalità del CSR.
Per ridefinire uno o più campi di una lista SharePoint, non dobbiamo far altro che creare un array di oggetti (a definire ogni singolo campo da sovrascrivere) ed assegnare tale array alla proprietà "Fields" del template (fate riferimento al precedente post per la struttura di una template CSR).

(function () {
    var ctx = {};
    ctx.Templates = {};
    ctx.Templates.Fields = {
        'PercentComplete': {
            'View': function() { return 'Hello from <b>CSR</b>!'; },
            'DisplayForm': function() { return 'Hello from <b>CSR!</b>'; },
            'EditForm': function() { return 'Hello from <b>CSR!</b>'; },
            'NewForm': function() { return 'Hello from <b>CSR!</b>'; },
        }
    };
    SPClientTemplates.TemplateManager.RegisterTemplateOverrides(ctx);
})();

Nota: come potete notare, rispetto al template che abbiamo descritto nel primo post di questa serie, non abbiamo definito tutte le proprietà del nostro display template che non avevamo intenzione di ridefinire, ma abbiamo specificato solamente la proprietà "Fields". Così facendo il display template risulta sicuramente più leggero e leggibile.

Ogni elemento di questo array è a sua volta un nuovo oggetto che verrà poi utilizzato da SharePoint 2013 per visualizzare il campo nelle seguenti quattro condizioni:

  • View – All'interno delle viste della lista a cui viene legato il nostro template
  • DisplayForm – All'interno della pagina di visualizzazione di un singolo elemento di lista
  • EditForm – All'interno della form di modifica di un singolo elemento di lista
  • NewForm – All'interno della form di creazione di nu nuovo elemento di lista

La cosa importante, ma credo che l’abbiate già colta, è che il campo deve essere specificato tramite il suo internal name. Altrimenti questo template non verrà mai caricato dal CSR di SharePoint 2013. Ora che abbiamo ridefinito la visualizzazione del nostro campo in tutti i suoi aspetti (view, display, new, edit), dobbiamo eseguire queste azioni:

  • Salviamo lo script all'interno di un file .js
  • Facciamo l’upload di questo file .js all'interno di una qualsiasi document library (o sotto la _layouts se preferite)
  • Creiamo una nuova lista di task
  • Modifichiamo la pagina della lista di task appena creata, inserendo all’interno della proprietà ScriptLink la URL al nostro file .js
  • Salviamo la modifica

Se avete seguito tutti i passi, il risultato sarà questo:


Il client side rendering di SharePoint 2013

Abbiamo quindi ridefinito completamente la visualizzazione di un campo di una lista SharePoint 2013.
L’abbiamo fatto specificando all’interno di un oggetto Javascript quattro funzioni in-line che ritornano il codice HTML che viene poi preso dal CSR e messo in pagina.

Nota: l'utilizzo delle funzioni in-line è sicuramente immediato, ma vi consiglio di creare le vostre funzioni di rendering a parte e poi di assegnarle al template CSR. In questo modo evitate sprechi di memoria nel browser e riuscite a riutilizzare il codice che scrivete. Parleremo di questo in un post a sé stante. 

Ok. Probabilmente ora, dopo la gioia iniziale di aver visto funzionare il proprio lavoro, rimarrete delusi aprendo una qualsiasi tra le form di creazione, modifica o visualizzazione di un elemento e vedendo il rendering del campo rimanere quello di default.

Il client side rendering di SharePoint 2013

Questo accade perché (purtroppo) dobbiamo specificare il nostro file .js all'interno delle proprietà JSLink di tutte le web part che stanno dentro a tutte le form in cui vogliamo che il nostro script venga lanciato.
Eh sì.. una bella rottura di scatole.
Ovviamente abbiamo tutti gli strumenti per effettuare questa operazione in automatico, basta solo ingegnarsi un po’. Parleremo di questo argomento in uno dei prossimi post, dedicato proprio al provisioning di template per il Client Side Rendering.

[UPDATE - 28/01/2015]
Prima di andare avanti nella serie, volevo segnalarvi un ultimo tip.
La proprietà JS Link vi permette di utilizzare dei placeholder nella URL del display template utili a far riferimento alla URL del sito o della site collection. Questi placeholder sono:
  • ~site – per riferirsi al sito SharePoint corrente
  • ~sitecollection – per riferirsi alla site collection SharePoint corrente
Vi consiglio di preferirli all'utilizzo di URL con lo slash (/) iniziale in quanto ho notato che se si installa il display template all'interno della Style Library e lo si referenzia con lo slash iniziale, tale display template non viene applicato dal Client Side Rendering.