SP.UI.Status
Gestion des statuts
16/02/2010
1910 lectures
1 commentaire
5/5 (6 votes)
Pour ce premier cours sur l'ECMA Script, nous allons voir quelque chose d'assez simple et qui peut s'avérer bien utile. Nous allons voir comment gérer les statuts. Pour mieux comprendre ce que sont les statuts, regardez l'image ci-dessous :
Le message en noir sur fond rouge disant "The SharePoint Health Analyzer has detected some critical issues that require your attention. View these issues." est en fait un statut. Nous allons donc voir comment ajouter, modifier et supprimer ce genre de statuts.
Pour illustrer nos propos, nous allons créer une Visual Web Part qui va permettre d'effectuer des opérations sur des statuts personnalisés. Ouvrez donc Visual Studio 2010 et créez un nouveau projet de type Empty SharePoint Project que vous nommerez AreaProg.EcmaScript.Statut :
Étant donné que nous allons déployer un fichier javascript dans le dossier layouts de SharePoint, déployez votre solution en tant que solution de ferme ;
Cliquez maintenant avec le bouton droit de votre souris sur votre projet et choisissez Add > New Item et ajoutez une Visual Web Part nommée EcmaStatut :
Cliquez ensuite sur l'élément Feature1 de votre projet et dans la fenêtre de propriétés, modifiez la valeur de la propriété Folder Name sur EcmaStatut.
Nous allons maintenant passer au code ASPX du contrôle ASCX. Nous allons simplement disposer une zone de texte dans laquelle l'utilisateur inscrira le message à mettre dans le statut, une liste déroulante pour choisir la couleur du statut et deux boutons qui permettront respectivement d'ajouter un statut et de supprimer tous les statuts. Voici le code nécessaire à taper dans le fichier ASCX :
Vous voyez qu'ici, nous allons utiliser une fonction javascript personnelle, à savoir EcmaAddStatus. Nous allons donc devoir créer une fichier javascript qui va contenir cette fonction. Cliquez avec le bouton droit de votre souris sur votre projet et choisissez Shared "Layouts" Mapped Folder. Ceci va permettre d'ajouter un dossier dont le contenu sera automatiquement copié dans le dossier Layouts de SharePoint lors du déploiement de la solution. Cliquez ensuite avec le bouton droit sur le dossier AreaProg.EcmaScript.Statut du dossier Layouts et choisissez Add > New Item. Dans la fenêtre qui apparaît, choisissez JScript File et nommez le core.js.
Avant de passer au code, nous allons devoir faire une dernière chose; Charger le fichier sp.js (nous y reviendrons) et notre fichier core.js grâce au contrôle. Cliquez donc avec le bouton droit de votre souris sur le fichier ASCX et choisissez View Code. Surchargez ensuite la méthode OnPreRender de cette manière :
Ajoutez également la directive suivante pour pouvoir utiliser l'objet ScriptLink :
Il faut savoir que tout le code javascript (EcmaScript) permettant de piloter SharePoint se trouve dans différents fichiers Javascript de SharePoint. Un des principaux est sp.js et peut être trouvé dans le dossier 14\TEMPLATE\LAYOUTS. Cependant, si vous ouvrez ce fichier, vous verrez qu'il est compressé et totalement illisible. C'est pour cela qu'il existe également le fichier sp.debug.js. Ce fichier contient exactement la même chose que le fichier sp.js, sauf que cette fois, ce n'est pas compressé et c'est donc tout à fait lisible. Une fois que nous avons chargé ce fichier, il faut également inclure notre fichier core.js, ce que nous faisons avec la deuxième ligne de code.
Il ne nous reste à présent plus qu'à définir le code de notre fichier core.js. Il faut savoir que le fichier sp.js doit être totalement chargé pour pouvoir travailler avec. Il est donc impératif de s'assurer que celui-ci a bien été chargé avant de travailler. Pour faire cela, tapez ceci dans le fichier core.js de votre solution :
Ne vous préoccupez pas de la variable statusId pour l'instant, nous y reviendrons. La fonction ExecuteOrDelayUntilScriptLoaded permet d'exécuter une fonction une fois qu'un fichier a été totalement chargé, en l'occurrence, sp.js. La fonction à exécuter est Go et va simplement initialiser la variable loaded sur true pour indiquer que le fichier sp.js a bien été chargé.
Si vous revenez à l'événement onclick du bouton d'ajout, vous remarquerez que nous faisons appel à la fonction EcmaAddStatus. Nous devons donc la déclarer :
Penchons nous maintenant sur l'objet qui va nous permettre de modifier les statuts de la page. En fait, c'est très simple. Si vous ouvrez le fichier sp.debug.js du dossier Layouts de SharePoint et que vous faites une recherche sur Status, vous obtiendrez la portion de code suivante :
Nous avons donc les différentes fonctions relatives à l'objet SP.UI.Status. Même s'il n'y a pas de commentaire, le nom de ces fonctions parlent d'elle-même. Complétez donc votre fonction EcmaAddStatus de la manière suivante :
La première chose que nous faisons est de vérifier si la variable loaded vaut bien true, ainsi nous nous assurons que le fichier sp.js a bien été chargé. Chaque messages de statut aura un id spécifique qui permettra de le modifier ou de le supprimer. Pour ajouter un statut, il suffit de passer par la fonction addStatus de l'objet SP.UI.Status et de lui faire passer le titre et le message (pouvant contenir de l'HTML). Le dernier argument de la fonction permet d'ajouter le statut au sommet de la liste s'il est sur true, ou à la suite s'il est sur false.
Nous voulons ensuite ajouter un lien qui va permettre de supprimer le statut en utilisant la fonction removeStatus, cependant, il nous faut le sid (status id) du statut pour le faire. Ce sid est renvoyé par la fonction addStatus et sera récupéré dans la variable statusId. Nous devons donc utiliser la fonction updateStatus pour modifier le statut que nous venons de créer et ajouter le lien. Le premier paramètre de la fonction updateStatus permet de passer le sid du statut à modifier alors que le deuxième paramètre indique le nouveau message du statut. Ici, nous faisons passer le contenu de la zone de texte suivi d'un lien de suppression appelant la fonction removeStatus. Cette fonction n'attend que le sid du statut à supprimer.
Enfin, nous utilisons la fonction setStatusPriColor pour modifier la couleur de fond du statut. Nous vous conseillons de ne choisir qu'une seule couleur même s'il y a plusieurs statut à afficher. Effectivement, SharePoint a un comportement un peu bizarre lorsque nous voulons ajouter des statuts de couleurs différentes des précédents. La fonction setStatusPriColor attend bien évidemment le sid du statut à colorer mais également la couleur à lui attribuer (red, blue, green,...).
Si nous revenons à la fonction onclick du second bouton (celui qui permet d'effacer tous les statuts), il contenait un appel à la fonction removeAllStatus. Cette fonction permet simplement de supprimer d'un coup tous les statuts de la page. L'attribut de cette fonction permet de cacher la barre de statut s'il est défini sur true. Dans le cas contraire, il ne cachera pas cette zone.
Il existe une autre fonction que nous n'avons pas abordé : appendStatus. Cette fonction permet simplement d'insérer un statut à coté d'un autre. Elle n'est pas compliqué à utiliser, il suffit simplement de faire passer le sid du statut à coté duquel le nouveau statut devra se placer ainsi que le titre et le message de celui-ci.
Compilez et déployez maintenant votre solution. Une fois ceci fait, ajoutez notre Web Part sur une page contenant le Ribbon et testez la. Ajoutez un élément :
Ajoutez également un deuxième :
Essayez maintenant de supprimer le premier en cliquant sur Delete :
Enfin, cliquez sur le bouton Remove all pour tout supprimer :
Télécharger les sources de l'exemple
Le message en noir sur fond rouge disant "The SharePoint Health Analyzer has detected some critical issues that require your attention. View these issues." est en fait un statut. Nous allons donc voir comment ajouter, modifier et supprimer ce genre de statuts.
Pour illustrer nos propos, nous allons créer une Visual Web Part qui va permettre d'effectuer des opérations sur des statuts personnalisés. Ouvrez donc Visual Studio 2010 et créez un nouveau projet de type Empty SharePoint Project que vous nommerez AreaProg.EcmaScript.Statut :
Étant donné que nous allons déployer un fichier javascript dans le dossier layouts de SharePoint, déployez votre solution en tant que solution de ferme ;
Cliquez maintenant avec le bouton droit de votre souris sur votre projet et choisissez Add > New Item et ajoutez une Visual Web Part nommée EcmaStatut :
Cliquez ensuite sur l'élément Feature1 de votre projet et dans la fenêtre de propriétés, modifiez la valeur de la propriété Folder Name sur EcmaStatut.
Nous allons maintenant passer au code ASPX du contrôle ASCX. Nous allons simplement disposer une zone de texte dans laquelle l'utilisateur inscrira le message à mettre dans le statut, une liste déroulante pour choisir la couleur du statut et deux boutons qui permettront respectivement d'ajouter un statut et de supprimer tous les statuts. Voici le code nécessaire à taper dans le fichier ASCX :
Vous voyez qu'ici, nous allons utiliser une fonction javascript personnelle, à savoir EcmaAddStatus. Nous allons donc devoir créer une fichier javascript qui va contenir cette fonction. Cliquez avec le bouton droit de votre souris sur votre projet et choisissez Shared "Layouts" Mapped Folder. Ceci va permettre d'ajouter un dossier dont le contenu sera automatiquement copié dans le dossier Layouts de SharePoint lors du déploiement de la solution. Cliquez ensuite avec le bouton droit sur le dossier AreaProg.EcmaScript.Statut du dossier Layouts et choisissez Add > New Item. Dans la fenêtre qui apparaît, choisissez JScript File et nommez le core.js.
Avant de passer au code, nous allons devoir faire une dernière chose; Charger le fichier sp.js (nous y reviendrons) et notre fichier core.js grâce au contrôle. Cliquez donc avec le bouton droit de votre souris sur le fichier ASCX et choisissez View Code. Surchargez ensuite la méthode OnPreRender de cette manière :
Ajoutez également la directive suivante pour pouvoir utiliser l'objet ScriptLink :
Il faut savoir que tout le code javascript (EcmaScript) permettant de piloter SharePoint se trouve dans différents fichiers Javascript de SharePoint. Un des principaux est sp.js et peut être trouvé dans le dossier 14\TEMPLATE\LAYOUTS. Cependant, si vous ouvrez ce fichier, vous verrez qu'il est compressé et totalement illisible. C'est pour cela qu'il existe également le fichier sp.debug.js. Ce fichier contient exactement la même chose que le fichier sp.js, sauf que cette fois, ce n'est pas compressé et c'est donc tout à fait lisible. Une fois que nous avons chargé ce fichier, il faut également inclure notre fichier core.js, ce que nous faisons avec la deuxième ligne de code.
Il ne nous reste à présent plus qu'à définir le code de notre fichier core.js. Il faut savoir que le fichier sp.js doit être totalement chargé pour pouvoir travailler avec. Il est donc impératif de s'assurer que celui-ci a bien été chargé avant de travailler. Pour faire cela, tapez ceci dans le fichier core.js de votre solution :
Ne vous préoccupez pas de la variable statusId pour l'instant, nous y reviendrons. La fonction ExecuteOrDelayUntilScriptLoaded permet d'exécuter une fonction une fois qu'un fichier a été totalement chargé, en l'occurrence, sp.js. La fonction à exécuter est Go et va simplement initialiser la variable loaded sur true pour indiquer que le fichier sp.js a bien été chargé.
Si vous revenez à l'événement onclick du bouton d'ajout, vous remarquerez que nous faisons appel à la fonction EcmaAddStatus. Nous devons donc la déclarer :
Penchons nous maintenant sur l'objet qui va nous permettre de modifier les statuts de la page. En fait, c'est très simple. Si vous ouvrez le fichier sp.debug.js du dossier Layouts de SharePoint et que vous faites une recherche sur Status, vous obtiendrez la portion de code suivante :
Nous avons donc les différentes fonctions relatives à l'objet SP.UI.Status. Même s'il n'y a pas de commentaire, le nom de ces fonctions parlent d'elle-même. Complétez donc votre fonction EcmaAddStatus de la manière suivante :
La première chose que nous faisons est de vérifier si la variable loaded vaut bien true, ainsi nous nous assurons que le fichier sp.js a bien été chargé. Chaque messages de statut aura un id spécifique qui permettra de le modifier ou de le supprimer. Pour ajouter un statut, il suffit de passer par la fonction addStatus de l'objet SP.UI.Status et de lui faire passer le titre et le message (pouvant contenir de l'HTML). Le dernier argument de la fonction permet d'ajouter le statut au sommet de la liste s'il est sur true, ou à la suite s'il est sur false.
Nous voulons ensuite ajouter un lien qui va permettre de supprimer le statut en utilisant la fonction removeStatus, cependant, il nous faut le sid (status id) du statut pour le faire. Ce sid est renvoyé par la fonction addStatus et sera récupéré dans la variable statusId. Nous devons donc utiliser la fonction updateStatus pour modifier le statut que nous venons de créer et ajouter le lien. Le premier paramètre de la fonction updateStatus permet de passer le sid du statut à modifier alors que le deuxième paramètre indique le nouveau message du statut. Ici, nous faisons passer le contenu de la zone de texte suivi d'un lien de suppression appelant la fonction removeStatus. Cette fonction n'attend que le sid du statut à supprimer.
Enfin, nous utilisons la fonction setStatusPriColor pour modifier la couleur de fond du statut. Nous vous conseillons de ne choisir qu'une seule couleur même s'il y a plusieurs statut à afficher. Effectivement, SharePoint a un comportement un peu bizarre lorsque nous voulons ajouter des statuts de couleurs différentes des précédents. La fonction setStatusPriColor attend bien évidemment le sid du statut à colorer mais également la couleur à lui attribuer (red, blue, green,...).
Si nous revenons à la fonction onclick du second bouton (celui qui permet d'effacer tous les statuts), il contenait un appel à la fonction removeAllStatus. Cette fonction permet simplement de supprimer d'un coup tous les statuts de la page. L'attribut de cette fonction permet de cacher la barre de statut s'il est défini sur true. Dans le cas contraire, il ne cachera pas cette zone.
Il existe une autre fonction que nous n'avons pas abordé : appendStatus. Cette fonction permet simplement d'insérer un statut à coté d'un autre. Elle n'est pas compliqué à utiliser, il suffit simplement de faire passer le sid du statut à coté duquel le nouveau statut devra se placer ainsi que le titre et le message de celui-ci.
Compilez et déployez maintenant votre solution. Une fois ceci fait, ajoutez notre Web Part sur une page contenant le Ribbon et testez la. Ajoutez un élément :
Ajoutez également un deuxième :
Essayez maintenant de supprimer le premier en cliquant sur Delete :
Enfin, cliquez sur le bouton Remove all pour tout supprimer :
Télécharger les sources de l'exemple
1 commentaires
Marc13100 a dit:
super
Ajouter un commentaire