Usar el control Selector de personas del lado cliente en complementos de SharePoint hospedados por SharePoint
Importante
En este tema se supone que sabe cómo crear un complemento de SharePoint hospedado por SharePoint. Para aprender a crear uno, vea Introducción a la creación de complementos de SharePoint hospedados por SharePoint.
¿Qué es el control Selector de personas del lado cliente de SharePoint?
El control Selector de personas del lado cliente permite a los usuarios buscar y seleccionar rápidamente cuentas de usuario válidas para contactos, grupos y notificaciones de su organización. El selector es un control HTML y JavaScript que ofrece compatibilidad entre exploradores.
Agregar el selector al complemento resulta sencillo:
En el marcado, agregue un elemento contenedor para el control y referencias para el control y sus dependencias.
En el script, llame a la función global SPClientPeoplePicker_InitStandaloneControlWrapper para representar e inicializar el selector.
El selector se representa con el objeto SPClientPeoplePicker, que proporciona métodos que otros controles del lado cliente pueden usar para obtener información del selector o realizar otras operaciones. Se pueden usar las propiedades SPClientPeoplePicker para configurar el selector con opciones de configuración específicas de control, tales como permitir varios usuarios o especificar opciones de almacenamiento en caché.
El selector usa también valores de configuración de aplicación web, tales como parámetros de Active Directory Domain Services o bosques dirigidos. Las opciones de configuración de aplicaciones web se seleccionan automáticamente (desde la propiedad SPWebApplication.PeoplePickerSettings).
El selector incluye los componentes siguientes:
- Un cuadro de entrada de texto donde escribir los nombres de los usuarios, los grupos o las notificaciones.
- Un control span que muestra los nombres de los usuarios, grupos y notificaciones resueltos.
- Un elemento div oculto que autorellena un cuadro desplegable con resultados de la consulta.
- Un control de Autorrellenar.
Nota:
El selector y sus funciones se definen en los archivos de script clientforms.js, clientpeoplepicker.js y autofill.js, que se encuentran en la carpeta %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\TEMPLATE\LAYOUTS en el servidor.
Requisitos previos para configurar un entorno de desarrollo para usar el control Selector de personas del lado cliente en un complemento de SharePoint
En este artículo se presupone que crea el complemento de SharePoint con Napa en un sitio para desarrolladores de Office 365. Si está usando este entorno de desarrollo, ya cumple los requisitos previos.
Nota:
Si desea saber cómo registrarse en un sitio para desarrolladores y empezar a usar Napa, vea Configurar un entorno de desarrollo para complementos de SharePoint en Office 365.
Si no usa Napa en un sitio para desarrolladores, necesitará lo siguiente:
- SharePoint con, al menos, un usuario de destino
- Visual Studio 2012 o Visual Studio 2013
- Office Developer Tools para Visual Studio 2013
Nota:
Para obtener directrices sobre cómo configurar un entorno de desarrollo que se adapte a sus necesidades, vea Complementos de SharePoint.
En las siguientes secciones se describen los pasos generales para agregar un selector al complemento y luego obtener la información de usuario de otro control del lado cliente. Para obtener el código correspondiente, vea Ejemplo de código: Usar el Selector de personas del lado cliente.
Puede usar el control Selector de personas del lado cliente en complementos de SharePoint hospedados por SharePoint.
Usar el control Selector de personas del lado cliente en un complemento hospedado por SharePoint
En el marcado de página
Agregue referencias a las dependencias de script del control Selector de personas del lado cliente.
Agregue las etiquetas HTML para la interfaz de usuario de la página. El complemento de este ejemplo define dos elementos div: uno para que el selector se represente y otro para la interfaz de usuario, un botón que invoca el script para que consulte al selector y a los elementos que muestran información del usuario.
En el script
Cree un diccionario JSON para usarlo como esquema que almacena propiedades específicas del selector, como AllowMultipleValues o MaximumEntitySuggestions.
Llame a la función global SPClientPeoplePicker_InitStandaloneControlWrapper.
Obtenga el objeto de selector de la página.
Consulte el selector. El complemento de este ejemplo llama al método GetAllUserInfo para obtener toda la información de usuario correspondiente a los usuarios resueltos y al método GetAllUserKeys solo para obtener las claves de los usuarios resueltos.
Obtenga el identificador de usuario mediante el modelo de objetos de JavaScript. El identificador de usuario no está incluido en la información que devuelve el selector, así que el complemento llama al método SP.Web.ensureUser y obtiene el identificador del objeto SP.User devuelto.
El servidor controla las funciones del Selector, como la representación o la inicialización, así como la búsqueda y la resolución de entradas de usuario con los proveedores de autenticación de SharePoint.
Ejemplo de código: Usar el Selector de personas del lado cliente en un complemento hospedado por SharePoint
Los siguientes ejemplos de código HTML y JavaScript agregan un control Selector de personas del lado cliente a un complemento hospedado por SharePoint.
En el primer ejemplo se muestra el marcado de página de las etiquetas PlaceHolderMain asp:Content de la página Default.aspx. Este código hace referencia a las dependencias de script del selector, otorga un identificador único al elemento DOM donde se representará el selector y define la interfaz de usuario del complemento.
<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>
Nota:
Según el entorno, puede que no sea necesario hacer referencia de forma explícita a todas estas dependencias.
En el siguiente ejemplo se muestra el script del archivo App.js. Este script inicializa y representa el selector, lo consulta para obtener información de usuario y luego obtiene el identificador de usuario mediante el modelo de objetos 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());
}