SP.Web
Utilisation basique de l'objet Web
23/02/2010
1955 lectures
0 commentaire
5/5 (1 vote)
A l'instar de l'objet SPWeb en .NET, il existe l'objet SP.Web qui permet de récupérer ou de modifier des propriétés liées aux sites Web. Dans ce cours, nous allons voir comment récupérer les principales propriétés d'un site Web et comment en modifier. L'objet SP.Web contient un grand nombre de propriétés et de méthodes, nous ne verrons bien évidemment pas toutes ces propriétés dans ce cours. Nous verrons les principales techniques de récupération et de modification de données. Une fois que vous avez compris ces différentes techniques, vous n'aurez plus aucun problème pour récupérer d'autres données de cet objet.
Créez donc un nouveau projet de type Empty SharePoint Project avec Visual Studio 2010 et nommez-le Areaprog.Ecma.Web :
Déployez cette solution au niveau de la ferme :
Cliquez maintenant avec le bouton droit de votre souris sur votre projet et choisissez Add > New Item. Ajoutez alors une Visual Web Part que vous nommerez EcmaWeb :
Cliquez ensuite sur l'élément Feature1 et modifiez sa propriété Folder Name sur EcmaWeb. Cliquez à nouveau avec le bouton droit de votre souris sur votre projet et choisissez Add > SharePoint "Layouts" Mapped Folder. Ce dossier va nous permettre de contenir notre fichier JavaScript contenant les principales fonctions que nous allons utiliser. Ajoutez donc un fichier JScript File nommé core.js dans ce dossier. Nous allons maintenant charger les deux fichiers js lors du chargement de notre Web Part. Ouvrez donc le fichier EcmaWebUserControl.ascx.cs et remplacez la fonction Page_Load par :
Ce code permet simplement de charger le fichier sp.js, qui contient les principales fonctions Ecma Script de SharePoint. Il charge également le fichier core.js de notre solution pour nous permettre d'utiliser nos fonctions personnalisées. Pour utiliser l'objet ScriptLink/I], vous devrez ajouter un [I]using :
Ouvrez maintenant votre fichier ASCX et insérez-y le code suivant :
Cette division nous permettra d'afficher les différentes informations sur le site. Nous voici maintenant prêt à utiliser l'objet SP.Web. Ouvrez donc votre fichier JavaScript et tapez ceci :
Cette fonction va permettre d'attendre que le fichier sp.js/I] soit totalement chargé avant d'exécuter la fonction passée en premier paramètre. Cette fonction est celle qui va nous afficher les différentes propriétés de l'objet [I]SP.Web. Tapez donc cette fonction :
La première chose que nous devons faire est de récupérer le contexte d'exécution actuel. Nous le récupérons donc et le plaçons dans la variable context. Nous utilisons ensuite la fonction get_web pour récupérer le site web relatif au contexte actuel. Nous créons également une variable div qui va contenir une référence à la division de notre contrôle.
Ce qu'il faut savoir, c'est que l'ECMA Script se base sur l'AJAX pour exécuter ces requêtes, nous avons donc la possibilité de choisir les objets que nous allons charger et également le moment du chargement. Il existe donc la méthode load qui va permettre d'indiquer les objets que nous voulons. Ici, nous allons charger l'objet web car nous allons en récupérer les propriétés et en modifier. Une fois que nous avons définit les objets que nous voulons charger, nous devons indiquer que nous voulons exécuter toutes les requêtes en attente. Cela nous permet d'exécuter toutes nos requêtes en une fois plutôt que de lancer autant d'exécution qu'il y a de requêtes.
La fonction executeQueryAsync nous permet donc de lancer cette exécution. La méthode que nous utilisons dans ce code attend 2 paramètres étant chacun des délégués contenant le nom de la fonction à exécuter en cas de succès (premier argument) ou en cas d'échec (deuxième argument) de l'exécution.
Nous allons maintenant bien évidemment devoir déclarer les deux fonctions passée à la méthode executeQueryAsync. Tapez donc cette fonction :
Cette fonction affiche simplement un message d'erreur suivi de la valeur renvoyée par la fonction get_message. Celle-ci renvoi simplement une description de l'erreur qui a été rencontrée lors de l'exécution des méthodes. Déclarez également cette fonction :
Nous allons utiliser cette méthode pour afficher les propriétés "basiques" de l'objet SP.Web. Commencez donc par taper ceci :
Ici, nous ne faisons qu'afficher les différentes propriétés de l'objet web. Il est très facile de voir les différentes propriétés présentées par l'EcmaScript de SharePoint. Effectivement, ouvrez le fichier 14\TEMPLATE\LAYOUTS\SP.debug.js. Ce fichier contient le code JavaScript de beaucoup de fonction permettant de piloter SharePoint. Faites une recherche sur SP.Web.pro. Visual Studio vous positionnera directement sur cette portion de code :
Il y a donc ici tout le code relatif à la manipulation de l'objet SP.Web, c'est donc là que vous pouvez voir les propriétés que vous pouvez récupérer ou modifier sur l'objet SP.Web. Revenons maintenant sur notre code. Nous affichons d'abord l'id, le titre, la description, la date de création et le langage du site actuel. Vous remarquerez que nous avons mis un lien Reverse à coté du titre du site. En fait, ce lien va appeler une fonction qui va nous permettre de modifier le titre par l'inverse du titre actuel. Nous verrons cela plus tard.
Pour l'instant, nous nous sommes contentés de récupérer de simples propriétés et de les afficher. Maintenant, nous allons afficher d'autres informations, mais plus complexes : l'ensemble des listes présentes sur le site, l'url du dossier racine et le login de l'utilisateur actuellement connecté. Vous allez voir que cette fois, ce n'est pas aussi simple. Tapez donc pour commencer :
Vous vous dites certainement que rien ne change et pourtant ce code ne fonctionnera pas. Effectivement, si vous essayé d'accéder à l'un de ces objets, une erreur javascript vous indiquant qu'ils n'ont pas été chargés s'affichera. En fait, la fonction get_lists va renvoyer une grande quantité de données (les informations de toutes les listes du site), il est donc important de pouvoir choisir quand nous voulons récupérer ces informations. Ici, cela pourrait être tout de suite mais ca ne serait pas logique. Effectivement, nous voulons également récupérer le dossier racine (un objet de type SP.Folder) et l'utilisateur courant (un objet SP.User). Nous allons donc charger ces 3 objets d'un coup, plutôt que de les charger 1 par 1.
Maintenant que nous avons initialisé les 3 variables qui vont contenir nos données, nous allons indiquer que nous voulons les charger en utilisant la fonction load :
Actuellement, la page va savoir qu'elle doit charger 3 objets, mais elle ne les chargera pas tant qu'on ne lui ordonnera pas. C'est ce que nous faisons avec la ligne suivante :
Comme précédemment, nous appelons la fonction executeQueryAsync pour lancer l'exécution de toutes les requêtes en attente. Si tous les objets sont chargés correctement, la fonction passera automatiquement dans la fonction onAdditionalDataLoaded :
Les deux premières lignes permettent simplement de récupérer des propriétés des objets que nous avons chargés (le nom du dossier racine et le login de l'utilisateur). La manière pour récupérer le login de l'utilisateur est un peu spéciale. Effectivement, si nous regardons la déclaration des objets SP.User dans le fichier sp.js, voilà ce que nous obtenons :
Vous voyez qu'il existe une fonction get_email et set_email mais rien pour récupérer le login. Cependant, si vous regardez la fonction $7, vous remarquerez qu'elle récupère 3 propriétés de l'utilisateur en utilisant get_objectData().get_properties(). Nous faisons donc la même chose et comme dans la fonction $7, nous faisons passer LoginName en indice du tableau pour récupérer le login du membre.
Nous voulons ensuite afficher le titre de toutes les listes du site. Vous vous doutez que this.lists est une collection (puisque c'est un objet qui contient toutes les listes du site), nous allons donc devoir la parcourir. Pour cela, l'Ecma Script de SharePoint met à disposition les énumérateurs. Effectivement, il est désormais possible de parcourir une collection comme en C# grâce aux énumérateurs.
Nous commençons donc par récupérer l'énumérateur de la collection lists. Ensuite, tant que l'énumérateur contient des valeurs, nous affichons la valeur de la propriété title de la liste courante. Une fois cela fait, nous affichons une notification pour indiquer que le chargement des données est terminé.
Nous devons également implémenter la fonction qui sera exécutée dans le cas où le chargement des données échouerait :
Cette fonction affiche simplement un message d'erreur.
Il ne nous reste à présent plus qu'une fonction à implémenter. Rappelez-vous, nous avions ajouté un lien Reverse à coté du titre du site. Ce lien permet de modifier le titre du site par l'inverse du titre actuel. Implémentez donc les deux fonctions suivantes :
La première fonction permet simplement d'ajouter la fonction reverse aux objets de type String. Ainsi, il sera possible d'appeler cette fonction sur tout objet de type String. reverse permet simplement de renvoyer la chaine de caractères sur laquelle la fonction est appliquée, mais renversée.
Nous avons ensuite la fonction reverseTitle qui va être exécutée quand nous cliquerons sur le lien. La première ligne appelle la fonction set_title pour modifier le titre du site courant. Nous lui passons la chaîne renversée du titre du site actuel. Nous devons ensuite appeler la fonction update sur le site web actuel pour indiquer que nous voulons sauver les modifications (comme en OM .NET). Enfin, nous appelons la fonction executeQueryAsync pour exécuter la requête. Ici, nous faisons directement passer la déclaration d'une fonction en paramètre. Ainsi, elle sera exécutée une fois que les requêtes auront bien été exécutées. Nous rechargeons simplement la page pour afficher le changement.
Déployez votre Web Part et placez-la sur une page de votre site :
Comme vous voyez, toutes les données sont bien chargés et une notification vous l'indique. Cliquez maintenant sur le lien Reverse :
Vous pouvez alors remarquer que la page est rechargée et que le titre du site est maintenant xobdnaS.
Télécharger les sources de l'exemple
Créez donc un nouveau projet de type Empty SharePoint Project avec Visual Studio 2010 et nommez-le Areaprog.Ecma.Web :
Déployez cette solution au niveau de la ferme :
Cliquez maintenant avec le bouton droit de votre souris sur votre projet et choisissez Add > New Item. Ajoutez alors une Visual Web Part que vous nommerez EcmaWeb :
Cliquez ensuite sur l'élément Feature1 et modifiez sa propriété Folder Name sur EcmaWeb. Cliquez à nouveau avec le bouton droit de votre souris sur votre projet et choisissez Add > SharePoint "Layouts" Mapped Folder. Ce dossier va nous permettre de contenir notre fichier JavaScript contenant les principales fonctions que nous allons utiliser. Ajoutez donc un fichier JScript File nommé core.js dans ce dossier. Nous allons maintenant charger les deux fichiers js lors du chargement de notre Web Part. Ouvrez donc le fichier EcmaWebUserControl.ascx.cs et remplacez la fonction Page_Load par :
Ce code permet simplement de charger le fichier sp.js, qui contient les principales fonctions Ecma Script de SharePoint. Il charge également le fichier core.js de notre solution pour nous permettre d'utiliser nos fonctions personnalisées. Pour utiliser l'objet ScriptLink/I], vous devrez ajouter un [I]using :
Ouvrez maintenant votre fichier ASCX et insérez-y le code suivant :
Cette division nous permettra d'afficher les différentes informations sur le site. Nous voici maintenant prêt à utiliser l'objet SP.Web. Ouvrez donc votre fichier JavaScript et tapez ceci :
Cette fonction va permettre d'attendre que le fichier sp.js/I] soit totalement chargé avant d'exécuter la fonction passée en premier paramètre. Cette fonction est celle qui va nous afficher les différentes propriétés de l'objet [I]SP.Web. Tapez donc cette fonction :
La première chose que nous devons faire est de récupérer le contexte d'exécution actuel. Nous le récupérons donc et le plaçons dans la variable context. Nous utilisons ensuite la fonction get_web pour récupérer le site web relatif au contexte actuel. Nous créons également une variable div qui va contenir une référence à la division de notre contrôle.
Ce qu'il faut savoir, c'est que l'ECMA Script se base sur l'AJAX pour exécuter ces requêtes, nous avons donc la possibilité de choisir les objets que nous allons charger et également le moment du chargement. Il existe donc la méthode load qui va permettre d'indiquer les objets que nous voulons. Ici, nous allons charger l'objet web car nous allons en récupérer les propriétés et en modifier. Une fois que nous avons définit les objets que nous voulons charger, nous devons indiquer que nous voulons exécuter toutes les requêtes en attente. Cela nous permet d'exécuter toutes nos requêtes en une fois plutôt que de lancer autant d'exécution qu'il y a de requêtes.
La fonction executeQueryAsync nous permet donc de lancer cette exécution. La méthode que nous utilisons dans ce code attend 2 paramètres étant chacun des délégués contenant le nom de la fonction à exécuter en cas de succès (premier argument) ou en cas d'échec (deuxième argument) de l'exécution.
Nous allons maintenant bien évidemment devoir déclarer les deux fonctions passée à la méthode executeQueryAsync. Tapez donc cette fonction :
Cette fonction affiche simplement un message d'erreur suivi de la valeur renvoyée par la fonction get_message. Celle-ci renvoi simplement une description de l'erreur qui a été rencontrée lors de l'exécution des méthodes. Déclarez également cette fonction :
Nous allons utiliser cette méthode pour afficher les propriétés "basiques" de l'objet SP.Web. Commencez donc par taper ceci :
Ici, nous ne faisons qu'afficher les différentes propriétés de l'objet web. Il est très facile de voir les différentes propriétés présentées par l'EcmaScript de SharePoint. Effectivement, ouvrez le fichier 14\TEMPLATE\LAYOUTS\SP.debug.js. Ce fichier contient le code JavaScript de beaucoup de fonction permettant de piloter SharePoint. Faites une recherche sur SP.Web.pro. Visual Studio vous positionnera directement sur cette portion de code :
Il y a donc ici tout le code relatif à la manipulation de l'objet SP.Web, c'est donc là que vous pouvez voir les propriétés que vous pouvez récupérer ou modifier sur l'objet SP.Web. Revenons maintenant sur notre code. Nous affichons d'abord l'id, le titre, la description, la date de création et le langage du site actuel. Vous remarquerez que nous avons mis un lien Reverse à coté du titre du site. En fait, ce lien va appeler une fonction qui va nous permettre de modifier le titre par l'inverse du titre actuel. Nous verrons cela plus tard.
Pour l'instant, nous nous sommes contentés de récupérer de simples propriétés et de les afficher. Maintenant, nous allons afficher d'autres informations, mais plus complexes : l'ensemble des listes présentes sur le site, l'url du dossier racine et le login de l'utilisateur actuellement connecté. Vous allez voir que cette fois, ce n'est pas aussi simple. Tapez donc pour commencer :
Vous vous dites certainement que rien ne change et pourtant ce code ne fonctionnera pas. Effectivement, si vous essayé d'accéder à l'un de ces objets, une erreur javascript vous indiquant qu'ils n'ont pas été chargés s'affichera. En fait, la fonction get_lists va renvoyer une grande quantité de données (les informations de toutes les listes du site), il est donc important de pouvoir choisir quand nous voulons récupérer ces informations. Ici, cela pourrait être tout de suite mais ca ne serait pas logique. Effectivement, nous voulons également récupérer le dossier racine (un objet de type SP.Folder) et l'utilisateur courant (un objet SP.User). Nous allons donc charger ces 3 objets d'un coup, plutôt que de les charger 1 par 1.
Maintenant que nous avons initialisé les 3 variables qui vont contenir nos données, nous allons indiquer que nous voulons les charger en utilisant la fonction load :
Actuellement, la page va savoir qu'elle doit charger 3 objets, mais elle ne les chargera pas tant qu'on ne lui ordonnera pas. C'est ce que nous faisons avec la ligne suivante :
Comme précédemment, nous appelons la fonction executeQueryAsync pour lancer l'exécution de toutes les requêtes en attente. Si tous les objets sont chargés correctement, la fonction passera automatiquement dans la fonction onAdditionalDataLoaded :
Les deux premières lignes permettent simplement de récupérer des propriétés des objets que nous avons chargés (le nom du dossier racine et le login de l'utilisateur). La manière pour récupérer le login de l'utilisateur est un peu spéciale. Effectivement, si nous regardons la déclaration des objets SP.User dans le fichier sp.js, voilà ce que nous obtenons :
Vous voyez qu'il existe une fonction get_email et set_email mais rien pour récupérer le login. Cependant, si vous regardez la fonction $7, vous remarquerez qu'elle récupère 3 propriétés de l'utilisateur en utilisant get_objectData().get_properties(). Nous faisons donc la même chose et comme dans la fonction $7, nous faisons passer LoginName en indice du tableau pour récupérer le login du membre.
Nous voulons ensuite afficher le titre de toutes les listes du site. Vous vous doutez que this.lists est une collection (puisque c'est un objet qui contient toutes les listes du site), nous allons donc devoir la parcourir. Pour cela, l'Ecma Script de SharePoint met à disposition les énumérateurs. Effectivement, il est désormais possible de parcourir une collection comme en C# grâce aux énumérateurs.
Nous commençons donc par récupérer l'énumérateur de la collection lists. Ensuite, tant que l'énumérateur contient des valeurs, nous affichons la valeur de la propriété title de la liste courante. Une fois cela fait, nous affichons une notification pour indiquer que le chargement des données est terminé.
Nous devons également implémenter la fonction qui sera exécutée dans le cas où le chargement des données échouerait :
Cette fonction affiche simplement un message d'erreur.
Il ne nous reste à présent plus qu'une fonction à implémenter. Rappelez-vous, nous avions ajouté un lien Reverse à coté du titre du site. Ce lien permet de modifier le titre du site par l'inverse du titre actuel. Implémentez donc les deux fonctions suivantes :
La première fonction permet simplement d'ajouter la fonction reverse aux objets de type String. Ainsi, il sera possible d'appeler cette fonction sur tout objet de type String. reverse permet simplement de renvoyer la chaine de caractères sur laquelle la fonction est appliquée, mais renversée.
Nous avons ensuite la fonction reverseTitle qui va être exécutée quand nous cliquerons sur le lien. La première ligne appelle la fonction set_title pour modifier le titre du site courant. Nous lui passons la chaîne renversée du titre du site actuel. Nous devons ensuite appeler la fonction update sur le site web actuel pour indiquer que nous voulons sauver les modifications (comme en OM .NET). Enfin, nous appelons la fonction executeQueryAsync pour exécuter la requête. Ici, nous faisons directement passer la déclaration d'une fonction en paramètre. Ainsi, elle sera exécutée une fois que les requêtes auront bien été exécutées. Nous rechargeons simplement la page pour afficher le changement.
Déployez votre Web Part et placez-la sur une page de votre site :
Comme vous voyez, toutes les données sont bien chargés et une notification vous l'indique. Cliquez maintenant sur le lien Reverse :
Vous pouvez alors remarquer que la page est rechargée et que le titre du site est maintenant xobdnaS.
Télécharger les sources de l'exemple
0 commentaires
Ajouter un commentaire