Masterpage Sharepoint Alternative aux webparts

par Stephane Eyskens (Blog)

Date de publication : 20/08/2007 Dernire mise jour :

En parcourant les forums Sharepoint, j'ai constat que certains visiteurs pensaient que la seule intgration possible de contrles dans un environnement Sharepoint devait forcment passer par les webparts. Interloqu par cette interrogation, j'ai dcid de faire un article sur le sujet en prenant un exemple qui consiste dvelopper un contrle serveur personnel (non webpart) que l'on va insrer dans la masterpage et qui affichera les N dernires annonces de la liste "Announcements". On pourrait tenter de faire quelque chose d'quivalent en utilisant Sharepoint Designer et en insrant notre liste "Announcements" dans la masterpage. Le seul problme avec cette technique est que les webparts de liste standards ne sont pas "partageables" entre plusieurs sites car ils pointent sur une liste d'un seul et mme site or la masterpage est partage et de ce fait, lorsque vous naviguez sur un autre site, le systme plantera en vous disant que cette liste n'existe pas d'o l'intrt d'ventuellement passer par la technique dcrite dans ce tutoriel.

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

I - Introduction II - Webpart dans une masterpage? III - Web custom control - Contrle serveur web personnel, qu'est-ce que c'est au juste? IV - Notre contrle personnel dans la masterpage V - Cration du projet dans Visual Studio VI - Rfrencement des namespaces ncessaires et hritage de la classe principale VI - Proprits de notre contrle VIII - Les deux mthodes principales rcrire IX - Vrifier que l'utilisateur courant ait bien un accs en lecture la liste d'annonces X - Interrogation de la liste d'annonces XII - Dploiement de notre contrle dans la GAC et dans Sharepoint X-A - Dploiement du contrle (la DLL) dans la GAC X-B - Marquer le contrle comme "Safe" dans Sharepoint X-C - Insertion du contrle dans la masterpage Sharepoint XIII - Tlchargement XIV - Conclusion

-2Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

I - Introduction
Le but de cet article est de montrer une autre manire d'intgrer des contrles personnels dans Sharepoint. La manire la plus frquente est le dveloppement de webparts que l' on intgre ensuite dans des pages. Pour toute information sur les webparts, vous pouvez consulter les tutoriaux suivants: Dploiement d'un webpart personnel dans Sharepoint Utilisation et connexion de WebParts Ecrire un webpart pour Sharepoint avec Smartpart Aller plus loin avec les webparts Sharepoint

Nous allons crer un contrle personnel qui affiche les dernires annonces disponibles pour une collection de sites directement sur la masterpage. Pour ce faire, nous utiliserons un "web custom control" ASP.NET.

-3Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

II - Webpart dans une masterpage?

C'est en parcourant les forums que je suis tomb sur l'une ou l'autre question qui voquait la mise en place d'un webpart dans une masterpage. Les utilisateurs ne voyaient aucune possibilit d'insrer un webpart dans une masterpage et pour cause, il n'y a gnralement pas de webpart zone dans une masterpage, ce qui rend impossible l'ajout d'un webpart. On peut cependant utiliser la barre d'outils "Webparts" de Sharepoint Designer pour accder aux diffrents webparts disponibles et les insrer en faisant un glisser/dplacer dans la masterpage. Ceci dit, comme expliqu dans le synopsis, on peut rencontrer certaines limitations inhrentes aux webparts de liste standard comme par exemple la liste d'annonces. On peut facilement contourner ce problme en dveloppant un contrle personnel ou mme un webpart personnel (je prfre la premire solution) que l'on dploie ensuite dans la masterpage.

-4Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

III - Web custom control - Contrle serveur web personnel, qu'est-ce que c'est au juste?
Une alternative (plus simple d'ailleurs) aux webparts et probablement plus adapte au contexte d'une masterpage est le dveloppement d'un simple contrle serveur. Sharepoint reposant sur ASP.NET, on peut facilement dvelopper des contrles tel qu'on le ferait en ASP.NET pour les utiliser dans Sharepoint par la suite. Un contrle personnel n'est autre qu'un contrle dans lequel on implmente "manuellement" le code behind qui sera ensuite utilis pour gnrer le code client interprt par le navigateur. Plutt que de crer une page ASPX avec le support de Visual Studio, on va crer une DLL que l'on rfrencera ensuite dans la masterpage utilise par notre collection de sites Sharepoint.

-5Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

IV - Notre contrle personnel dans la masterpage

Afin que vous ayez une ide plus prcise de ce que nous allons faire, voici une capture d'cran qui montre notre contrle insr dans une masterpage Sharepoint. Celui-ci affiche une liste de N annonces sous forme de liens cliquables qui redirigent le visiteur vers l'annonce complte o N correspond la valeur attribue la proprit ItemLimit.

-6Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

V - Cration du projet dans Visual Studio

Pour crer un web custom control en dehors du contexte d'un site web, crez simplement un projet de type class library comme illustr ci-dessous

-7Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

VI - Rfrencement des namespaces ncessaires et hritage de la classe principale

Notre contrle devant s'excuter dans un contexte web et devant interroger une liste Sharepoint, vous devez rfrencer ces deux DLL Microsoft.Sharepoint que vous pouvez trouver dans le rpertoire ISAPI de votre installation Sharepoint System.Web que vous trouvez directement lorsque vous ajoutez une rfrence votre projet comme illustr sur l'image ci-dessous

Lorsque vous avez ajout les DLL, veuillez rfrencer les espaces de noms suivants: Microsoft.Sharepoint System.Web System.Web.UI System.Web.UI.WebControls System.Web.UI.HtmlControls

Vous disposez prsent de tous les espaces de noms requis pour pouvoir raliser notre contrle. Vous n'avez plus qu'une chose faire, c'est de faire hriter notre classe principale de WebControl car notre contrle sera un nouveau WebControl.

-8Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

VI - Proprits de notre contrle

Afin de permettre plus de souplesse et notamment pour ne pas figer des informations telles que l'URL du site Sharepoint o se trouve la liste d'annonces, le nom de la liste d'annonces, nous allons passer par des proprits. Celles-ci permettront l'utilisateur du contrle de spcifier les valeurs requises. Voici deux captures d'cran qui montrent comment ces proprits peuvent tre paramtres par l'utilisateur Dans Sharepoint Designer

Dans un projet web classique (vous pouvez bien sr rutiliser ce contrle dans un projet web normal)

-9Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

Voici ce que a donne au niveau du code

bool _TruncateTitle = false; string _SiteURL = null; string _AnnouncementList = null; public bool TruncateTitle { get { return _TruncateTitle; } set { _TruncateTitle = value; } } public string SiteURL { get { return _SiteURL; } set { _SiteURL = value; } } - 10 Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

public string AnnouncementList { get { return _AnnouncementList; } set { _AnnouncementList = value; } } ///....autres proprits

- 11 Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

VIII - Les deux mthodes principales rcrire

Comme pour un webpart, il y a certaines mthodes rcrire pour pouvoir gnrer nos sous contrles et le rendu de ceux-ci. Mthode CreateChildControls Render Description Permet de crer ses sous-contrles (label, textbox, button etc...) Permet de "rendre" le HTML de ces contrles pour que le navigateur puisse les interprter

CreateChildControls

protected override void CreateChildControls() { ErrorMessage = new Label();//Holds the error message if any ErrorMessage.Style.Add(HtmlTextWriterStyle.Color, "red"); ContentTable = new HtmlTable();//Will contain all the announcements ContentTable.Width = "100%"; ContentTable.Height = "100%"; ContentTable.Style.Add(HtmlTextWriterStyle.Overflow, "auto"); HtmlTableRow HeaderRow = new HtmlTableRow(); HtmlTableCell HeaderCell = new HtmlTableCell(); HeaderCell.InnerText = Title; //Announcement Title HeaderRow.Cells.Add(HeaderCell); ContentTable.Rows.Add(HeaderRow); GetLatestAnnouncments();//Call to retrieve the announcements this.Controls.Add(ContentTable);//Adding our table to the page controls this.Controls.Add(ErrorMessage);//Adding our label to the page controls }

Nous crons un label qui affichera les messages d'erreurs en cas de problme Nous crons une table HTML qui contiendra toutes les annonces.

Render

protected override void Render(HtmlTextWriter writer) { EnsureChildControls();//Makes sure the controls are created before rendering them if (ErrorMessage.Text == "") //If no error, display the announcements { ContentTable.RenderControl(writer); } else //else display the error message { ErrorMessage.RenderControl(writer); } }

Nous appelons EnsureChildControls qui s'assure que les contrles enfants sont bien crs. Nous utilisons la mthode RenderControl des contrles pour gnrer le HTML.

- 12 Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

IX - Vrifier que l'utilisateur courant ait bien un accs en lecture la liste d'annonces
Une masterpage tant un objet utilis par plusieurs sites/sous-sites, il est tout fait possible qu'un utilisateur U ayant accs un site S voie cette masterpage malgr le fait qu'il n'ait pas accs aux annonces que l'on met disposition de tous. Nous devons donc vrifier au pralable si l'utilisateur courant a bien accs aux annonces ou pas et le cas chant, ne rien afficher. Une technique permettant de le faire est la suivante:

try { TargetWeb.Lists[AnnouncementList].CheckPermissions(SPBasePermissions.ViewListItems); } catch { CanReadItems = false; }

La mthode CheckPermissions lance une exception au cas o l'utilisateur courant n'a pas l'accs pass en paramtre. Ce n'est pas trs lgant car il eut t prfrable que cette mthode renvoie un true ou false. Donc, en cas de non accs, le code branchera le catch dans lequel vous pourrez mettre un boolen "false". Notez qu'il est possible d'empcher le systme de gnrer cette exception mais dans le cas qui nous occupe, ce n'est pas ncessaire.

- 13 Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

X - Interrogation de la liste d'annonces

Pour pouvoir rcuprer les annonces prsentes dans notre liste, nous devons bien sr interroger celle-ci.

try { SPQuery AnnouncementQuery = new SPQuery(); AnnouncementQuery.Query = "<OrderBy><FieldRef Name='Modified' Ascending='FALSE' /></OrderBy>"; AnnouncementQuery.ViewFields = "<FieldRef Name='LinkTitleNoMenu' /><FieldRef Name='" + TargetWeb.Lists[AnnouncementList].Fields["Encoded Absolute URL"].InternalName + "' />"; AnnouncementQuery.RowLimit = (uint)ItemLimit; foreach (SPListItem AnnItm in TargetWeb.Lists[AnnouncementList].GetItems(AnnouncementQuery)) { HtmlTableRow ItmRow = new HtmlTableRow(); HtmlTableCell ItmCell = new HtmlTableCell(); ItmCell.InnerHtml = "<a href='" + AnnItm["Encoded Absolute URL"].ToString().Substring(0, AnnItm["Encoded Absolute URL"].ToString().LastIndexOf("/") + 1) + "DispForm.aspx?ID=" + AnnItm.ID + "'>" + AnnItm["LinkTitleNoMenu"].ToString() + "</a>"; ItmRow.Cells.Add(ItmCell); ContentTable.Rows.Add(ItmRow); } } catch (Exception Ex) { ErrorMessage.Text = Ex.Message; }

On cre une CAML query via la classe SPQuery en slectionnant toutes les annonces tries ordre dcroissant de leur date de cration On dit que les champs inclure sont LinkTitleNoMenu et Encoded Absolute URL qui reprsente l'URL vers l'annonce On dit que la limite du nombre de lignes devant tre retournes correspond la proprit ItemLimit On parcourt le rsultat retourn par la SPQuery et on cre nos lignes/cellules de tableau permettant d'afficher l'information

- 14 Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

XII - Dploiement de notre contrle dans la GAC et dans Sharepoint X-A - Dploiement du contrle (la DLL) dans la GAC
Pour dployer la DLL dans la GAC, suivez les instructions dans ce tutoriel. La marche suivre est identique, il est donc inutile de rpter les instructions ici.

X-B - Marquer le contrle comme "Safe" dans Sharepoint

Afin que le contrle soit reconnu comme sr dans Sharepoint, rcuprez sa signature via Reflector (galement mentionn dans le lien vers le tuto ci-dessus) et ensuite ditez le web.config de votre application Sharepoint et placez-y le code suivant dans la section <SafeControls> <SafeControl Assembly="AnnoucementBanners, Version=1.0.0.0, Culture=neutral, PublicKeyToken=3bb84b5ba42087a0" Namespace="AnnoucementBanners" TypeName="*" Safe="True" />

X-C - Insertion du contrle dans la masterpage Sharepoint

Pour diter la masterpage, vous pouvez ouvrir Sharepoint designer, ouvrir le site de votre choix, naviguer dans "catalogs" et ensuite choisir la masterpage de votre choix. Vous pouvez galement utiliser la galerie de masterpage comme illustr ci-dessous.

Ensuite, lorsque vous tes en mode dition dans Sharepoint designer, passez en mode code et enregistrez le contrle via une directive Register.

- 15 Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

Exemple de proprit
> <%@ Register TagPrefix="Announcement" Namespace="AnnoucementBanners" Assembly="AnnoucementBanners, Version=1.0.0.0, Culture=neutral, PublicKeyToken=3bb84b5ba42087a0" %>

Ensuite, l'endroit o vous voulez afficher le contrle, crivez ces lignes de code

Comme vous le constatez, nous retrouvons nos proprits AnnoucementList etc.. exposes par notre contrle. Vous n'avez plus qu' enregistrer les modifications apportes la masterpage et publier celle-ci afin que tous les visiteurs puissent bnficier de ce contrle. Vous pouvez tester en vous authentifiant avec des utilisateurs dont certains ont accs la liste et pas d'autres et vous verrez que le contrle s'adaptera en fonction du contexte.

- 16 Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

XIII - Tlchargement
Vous pouvez tlcharger l'exemple complet dcrit dans cet article ici

- 17 Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

XIV - Conclusion
Les contrles web personnels sont une solution d'intgration non ngligeable pour Sharepoint car ils incluent bien sr du code behind et peuvent s'intgrer la manire des webparts dans des pages, masterpage.

- 18 Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/

Masterpage Sharepoint - Alternative aux webparts par Stephane Eyskens (Blog)

- 19 Ce document est issu de http://www.developpez.com et reste la proprit exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise l'obtention pralable de l'autorisation de l'auteur.
http://stephaneey.developpez.com/tutoriel/sharepoint/webcustomcontrol/