Utiliser le contrôle Sélecteur de personnes côté client dans les compléments SharePoint hébergés par SharePoint
Importante
Pour parcourir cette rubrique, il est préférable de savoir comment créer un complément SharePoint hébergé par SharePoint. Pour savoir comment en créer un, consultez l’article Commencer à créer des compléments SharePoint hébergés sur SharePoint.
Qu’est-ce que le Contrôle Sélecteur de personnes côté client dans SharePoint ?
Le contrôle Sélecteur de personnes côté client permet aux utilisateurs de rechercher et sélectionner rapidement les comptes d’utilisateurs valides pour trouver des personnes, des groupes et des revendications dans leur organisation. Le sélecteur est un contrôle HTML et JavaScript pris en charge par plusieurs navigateurs.
Vous pouvez facilement l’ajouter à votre complément :
Dans vos balises, ajoutez un élément conteneur pour le contrôle et des références pour le contrôle et ses dépendances.
Dans votre script, appelez la fonction globale SPClientPeoplePicker_InitStandaloneControlWrapper pour afficher et initialiser le sélecteur.
Le sélecteur est représenté par l’objet SPClientPeoplePicker qui fournit des méthodes que d’autres contrôles côté client peuvent utiliser pour obtenir des informations dans le sélecteur ou effectuer d’autres opérations. Vous pouvez utiliser les propriétés SPClientPeoplePicker pour configurer le sélecteur avec des paramètres propres au contrôle, comme l’autorisation de plusieurs utilisateurs ou la définition des options de mise en cache.
Le sélecteur utilise également les paramètres de configuration de l’application web, tels que les services de domaine Active Directory ou les forêts ciblées. Les paramètres de configuration de l’application web sont sélectionnés automatiquement (à partir de la propriété SPWebApplication.PeoplePickerSettings).
Le sélecteur comprend les composants suivants :
- une zone de texte pour entrer des noms d'utilisateurs, de groupes et de revendications,
- un contrôle d’étendue qui affiche les noms des utilisateurs, de groupes et de réclamations résolus,
- un élément div masqué qui remplit automatiquement une zone déroulante à l'aide des résultats de requête correspondants,
- un contrôle de la recopie incrémentée.
Remarque
Le sélecteur et ses fonctionnalités sont définis dans les fichiers scripts clientforms.js, clientpeoplepicker.js et autofill.js, qui se trouvent sur le serveur dans le dossier %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\TEMPLATE\LAYOUTS.
Conditions préalables pour configurer votre environnement de développement afin d’utiliser le Contrôle Sélecteur de personnes côté client dans un complément SharePoint
Dans cet article, nous partons du principe que vous créez le complément SharePoint en utilisant Napa sur un site de développeur Office 365. Si vous utilisez cet environnement de développement, vous remplissez déjà les conditions préalables.
Remarque
Pour savoir comment obtenir un site de développeur et utiliser Napa, consultez l’article Configurer un environnement de développement pour les compléments SharePoint sur Office 365.
Si vous n’utilisez pas Napa sur un site de développeur, vous avez besoin des éléments suivants :
- SharePoint avec au moins un utilisateur cible
- Visual Studio 2012 ou Visual Studio 2013
- Outils de développement Office pour Visual Studio 2013
Remarque
Pour obtenir des conseils pour configurer un environnement de développement adapté à vos besoins, consultez l’article Compléments SharePoint.
Les sections suivantes décrivent en quelques étapes comment ajouter le sélecteur à votre complément et obtenir ses informations utilisateur depuis un autre contrôle côté client. Pour connaître le code correspondant, consultez l’exemple de code : utiliser le Sélecteur de personnes côté client.
Vous pouvez utiliser le contrôle Sélecteur de personnes côté client dans les compléments SharePoint hébergés par SharePoint, mais pas dans les compléments hébergés par un fournisseur.
Utiliser le Contrôle Sélecteur de personnes côté client dans un complément hébergé par SharePoint
Dans le balisage de la page
Ajoutez des références à des dépendances de script du Contrôle Sélecteur de personnes côté client.
Ajoutez les balises HTML de l’interface utilisateur de la page. Dans cet exemple, le complément définit deux éléments div : un pour l’affichage du sélecteur et un autre pour l’interface utilisateur (un bouton qui appelle le script d’interrogation du sélecteur et les éléments qui affichent les informations utilisateur).
Dans votre script
Créez un dictionnaire JSON à utiliser en tant que schéma pour stocker les propriétés propres au sélecteur, comme AllowMultipleValues et MaximumEntitySuggestions.
Appelez la fonction globale SPClientPeoplePicker_InitStandaloneControlWrapper.
Obtenez l’objet de sélecteur à partir de la page.
Envoyez une requête au sélecteur. Dans cet exemple, le complément appelle la méthode GetAllUserInfo pour obtenir toutes les informations des utilisateurs résolus, et la méthode GetAllUserKeys pour obtenir uniquement les clés des utilisateurs résolus.
Obtenez l’ID utilisateur à l’aide du modèle objet JavaScript. L’ID de l’utilisateur n’est pas inclus dans les informations qui sont renvoyées par le sélecteur, le complément appelle donc la méthode SP.Web.ensureUser et obtient l’ID de l’objet SP.User renvoyé.
L'affichage, l'initialisation et d'autres fonctionnalités du sélecteur sont gérés par le serveur, notamment la recherche et la résolution des entrées utilisateur auprès des fournisseurs d'authentification SharePoint.
Exemple de code : utiliser le Sélecteur de personnes côté client dans un complément hébergé par SharePoint
Les exemples suivants de code HTML et JavaScript ajoutent un Contrôle Sélecteur de personnes côté client à un complément hébergé par SharePoint.
Le premier exemple montre les balises de page liées aux balises PlaceHolderMain asp:Content dans la page Default.aspx. Ce code référence les dépendances de script du sélecteur, attribue un ID unique à l’élément DOM dans lequel le sélecteur est affiché, et définit l’interface utilisateur du complément.
<asp:Content ContentPlaceHolderId="PlaceHolderMain" runat="server">
<SharePoint:ScriptLink name="clienttemplates.js" runat="server" LoadAfterUI="true" Localizable="false" />
<SharePoint:ScriptLink name="clientforms.js" runat="server" LoadAfterUI="true" Localizable="false" />
<SharePoint:ScriptLink name="clientpeoplepicker.js" runat="server" LoadAfterUI="true" Localizable="false" />
<SharePoint:ScriptLink name="autofill.js" runat="server" LoadAfterUI="true" Localizable="false" />
<SharePoint:ScriptLink name="sp.js" runat="server" LoadAfterUI="true" Localizable="false" />
<SharePoint:ScriptLink name="sp.runtime.js" runat="server" LoadAfterUI="true" Localizable="false" />
<SharePoint:ScriptLink name="sp.core.js" runat="server" LoadAfterUI="true" Localizable="false" />
<div id="peoplePickerDiv"></div>
<div>
<br/>
<input type="button" value="Get User Info" onclick="getUserInfo()"></input>
<br/>
<h1>User info:</h1>
<p id="resolvedUsers"></p>
<h1>User keys:</h1>
<p id="userKeys"></p>
<h1>User ID:</h1>
<p id="userId"></p>
</div>
</asp:Content>
Remarque
Selon votre environnement, il se peut que vous n’ayez pas besoin de référencer explicitement toutes ces dépendances.
L’exemple suivant montre le script du fichier App.js. Ce script initialise et affiche le sélecteur, lui envoie une requête pour obtenir des informations utilisateur et récupère l’ID de l’utilisateur à l’aide du modèle objet JavaScript.
// Run your custom code when the DOM is ready.
$(document).ready(function () {
// Specify the unique ID of the DOM element where the
// picker will render.
initializePeoplePicker('peoplePickerDiv');
});
// Render and initialize the client-side People Picker.
function initializePeoplePicker(peoplePickerElementId) {
// Create a schema to store picker properties, and set the properties.
var schema = {};
schema['PrincipalAccountType'] = 'User,DL,SecGroup,SPGroup';
schema['SearchPrincipalSource'] = 15;
schema['ResolvePrincipalSource'] = 15;
schema['AllowMultipleValues'] = true;
schema['MaximumEntitySuggestions'] = 50;
schema['Width'] = '280px';
// Render and initialize the picker.
// Pass the ID of the DOM element that contains the picker, an array of initial
// PickerEntity objects to set the picker value, and a schema that defines
// picker properties.
this.SPClientPeoplePicker_InitStandaloneControlWrapper(peoplePickerElementId, null, schema);
}
// Query the picker for user information.
function getUserInfo() {
// Get the people picker object from the page.
var peoplePicker = this.SPClientPeoplePicker.SPClientPeoplePickerDict.peoplePickerDiv_TopSpan;
// Get information about all users.
var users = peoplePicker.GetAllUserInfo();
var userInfo = '';
for (var i = 0; i < users.length; i++) {
var user = users[i];
for (var userProperty in user) {
userInfo += userProperty + ': ' + user[userProperty] + '<br>';
}
}
$('#resolvedUsers').html(userInfo);
// Get user keys.
var keys = peoplePicker.GetAllUserKeys();
$('#userKeys').html(keys);
// Get the first user's ID by using the login name.
getUserId(users[0].Key);
}
// Get the user ID.
function getUserId(loginName) {
var context = new SP.ClientContext.get_current();
this.user = context.get_web().ensureUser(loginName);
context.load(this.user);
context.executeQueryAsync(
Function.createDelegate(null, ensureUserSuccess),
Function.createDelegate(null, onFail)
);
}
function ensureUserSuccess() {
$('#userId').html(this.user.get_id());
}
function onFail(sender, args) {
alert('Query failed. Error: ' + args.get_message());
}