Usar el widget experimental Selector de personas en complementos de SharePoint
Puede usar el widget Selector de personas en cualquier página web, aunque la página no esté hospedada en SharePoint. Use el widget Selector de personas en los complementos para ayudar a los usuarios a buscar y seleccionar personas y grupos.
Advertencia
The Office Web Widgets - Experimental are only provided for research and feedback purposes. Do not use in production scenarios. The Office Web Widgets behavior may change significantly in future releases. Read and review the Office Web Widgets - Experimental License Terms.
Puede usar el widget experimental Selector de personas en los complementos para ayudar a los usuarios a buscar y seleccionar personas y grupos en un inquilino. Los usuarios empiezan a escribir en el cuadro de texto y el widget recupera a las personas cuyo nombre o correo electrónico coincida con el texto.
Widget Selector de personas mientras soluciona una consulta
Su complemento puede obtener acceso a las personas seleccionadas leyendo la propiedad selectedItems del widget. La propiedad selectedItems es una matriz de objetos que representan personas o grupos. La tabla siguiente muestra las propiedades disponibles del objeto de usuario.
| Propiedad | Descripción |
|---|---|
| department | Departamento del usuario o grupo. |
| displayName | Nombre para mostrar del usuario o grupo. |
| Dirección de correo electrónico del usuario o grupo. | |
| isResolved | Indica si el widget resolvió correctamente el texto en el widget en relación con un usuario o grupo del espacio empresarial. |
| jobTitle | Puesto del usuario. |
| loginName | Nombre de inicio de sesión del usuario o grupo. |
| mobile | Número de teléfono móvil del usuario o grupo. |
| principalId | Identificador de la entidad de seguridad del usuario o grupo. |
| principalType | Indica si el elemento es un usuario o un grupo. Si es un usuario, el valor es 1; si es un grupo, 4. |
| sipAddress | Dirección SIP del usuario o grupo. |
| text | Título de texto del nombre de usuario o grupo. |
El widget Selector de personas tiene una memoria caché de las entradas utilizadas recientemente (MRU). La memoria caché almacena las cinco últimas entradas que el widget resolvió.
Requisitos previos para usar los ejemplos de este artículo
Para seguir los ejemplos de este artículo, necesita lo siguiente:
- Visual Studio 2013 o posterior.
- Administrador de paquetes NuGet. Para obtener más información, vea Instalación de NuGet.
- Un entorno de desarrollo de SharePoint (es necesario aislar la aplicación en los escenarios locales).
- Paquete NuGet Office Web Widgets: Experimental. Para obtener más información sobre cómo instalar un paquete NuGet, vea NuGet Package Manager UI (Interfaz de usuario del Administrador de paquetes NuGet). También puede examinar la Página Galería de NuGet.
Usar el widget Selector de personas en un complemento de SharePoint hospedado por el proveedor
En este ejemplo, se hospeda una página sencilla fuera de SharePoint que declara un widget Selector de personas mediante marcado. Para simplificar, en este ejemplo no se declara ninguna opción, pero puede verse un ejemplo con las opciones en la sección Pasos siguientes.
Para usar el widget Selector de personas, tiene que seguir este procedimiento:
Crear un Complemento de SharePoint y proyectos web.
Cree un módulo en la web de complemento. Este paso garantiza también que se cree una web de complemento cuando los usuarios implementen el complemento.
Nota
La biblioteca entre dominios requiere la existencia de una web de complemento. El widget Selector de personas se comunica con SharePoint mediante la biblioteca entre dominios.
Cree una página de complemento donde se declare una instancia del widget Selector de personas mediante marcado.
Para crear un complemento de SharePoint y proyectos web
Abra Visual Studio como administrador. (Para ello, seleccione el icono de Visual Studio del menú Inicio y elija Ejecutar como administrador).
Cree un proyecto con la plantilla de complemento de SharePoint. La plantilla Complemento de SharePoint está en Plantillas > Visual C#, Office/SharePoint > Complementos.
Especifique la dirección URL del sitio web de SharePoint que quiere usar para la depuración.
Seleccione Hospedado por el proveedor como la opción de hospedaje del complemento.
Nota
También puede usar el widget Selector de personas con otras opciones de hospedaje o incluso con complementos de Office o su propio sitio web.
Seleccione Aplicación de formularios Web Forms ASP.NET como tipo de proyecto de aplicación web.
Seleccione Servicio de control de acceso de Windows Azure como opción de autenticación.
Para crear un módulo en la web de complemento
Seleccione el proyecto de complemento de SharePoint en el Explorador de soluciones. Seleccione Agregar > Nuevo elemento.
Seleccione Elementos de Visual C# > Office/SharePoint > Módulo. Especifique un nombre para el módulo.
Nota
Si crea un complemento hospedado por SharePoint, no tiene que crear ningún módulo adicional.
Para agregar una nueva página que use el widget Selector de personas
Seleccione la carpeta Páginas del proyecto web en el Explorador de soluciones.
Copie el código siguiente y péguelo en un archivo ASPX del proyecto. El código realiza las tareas siguientes:
Agrega referencias a las bibliotecas y recursos de Office necesarios.
Inicializa el entorno de ejecución de los controles.
Ejecuta el método renderAll del tiempo de ejecución de los controles de Office.
Declara un marcador de posición para el widget Selector de personas.
<!DOCTYPE html> <html> <head> <!-- IE9 or superior --> <meta http-equiv="X-UA-Compatible" content="IE=9" > <title>People Picker HTML Markup</title> <!-- Widgets Specific CSS File --> <link rel="stylesheet" type="text/css" href="../Scripts/Office.Controls.css" /> <!-- Ajax, jQuery, and utils --> <script src=" https://ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js.js"> </script> <script src=" https://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.9.1.min.js"> </script> <script type="text/javascript"> // Function to retrieve a query string value. // For production purposes you may want to use // a library to handle the query string. function getQueryStringParameter(paramToRetrieve) { var params = document.URL.split("?")[1].split("&"); var strParams = ""; for (var i = 0; i < params.length; i = i + 1) { var singleParam = params[i].split("="); if (singleParam[0] == paramToRetrieve) return singleParam[1]; } } </script> <!-- Cross-Domain Library and Office controls runtime --> <script type="text/javascript"> //Register namespace and variables used through the sample Type.registerNamespace("Office.Samples.PeoplePickerBasic"); //Retrieve context tokens from the querystring Office.Samples.PeoplePickerBasic.appWebUrl = decodeURIComponent(getQueryStringParameter("SPAppWebUrl")); Office.Samples.PeoplePickerBasic.hostWebUrl = decodeURIComponent(getQueryStringParameter("SPHostUrl")); //Pattern to dynamically load JSOM and and the cross-domain library var scriptbase = Office.Samples.PeoplePickerBasic.hostWebUrl + "/_layouts/15/"; //Get the cross-domain library $.getScript(scriptbase + "SP.RequestExecutor.js", //Get the Office controls runtime and // continue to the createControl function function () { $.getScript("../Scripts/Office.Controls.js", createControl) } ); </script> <!--People Picker --> <script src="../Scripts/Office.Controls.PeoplePicker.js" type="text/javascript"> </script> </head> <body> Basic People Picker sample (HTML markup declaration): <div id="PeoplePickerDiv" data-office-control="Office.Controls.PeoplePicker"> </div> <script type="text/javascript"> function createControl() { //Initialize Controls Runtime Office.Controls.Runtime.initialize({ sharePointHostUrl: Office.Samples.PeoplePickerBasic.hostWebUrl, appWebUrl: Office.Samples.PeoplePickerBasic.appWebUrl }); //Render the widget, this must be executed after the //placeholder DOM is loaded Office.Controls.Runtime.renderAll(); } </script> </body> </html>
Nota
En el ejemplo anterior se especifica explícitamente la web de host y la web de complemento en las direcciones URL para inicializar el tiempo de ejecución de los controles de Office. Pero, si las direcciones URL de la web de complemento y la web de host se especifican respectivamente en los parámetros SPAppWebUrl y SPHostUrl de la cadena de consulta, se puede pasar un objeto vacío y el código intentará obtener los parámetros automáticamente. Los parámetros SPAppWebUrl y SPHostUrl se incluyen en la cadena de consulta al usar el token {StandardTokens}.
En el siguiente ejemplo se muestra cómo pasar un objeto vacío al método de inicialización:
// Initialize with an empty object and the code
// will attempt to get the tokens from the
// query string directly.
Office.Controls.Runtime.initialize({});
Para crear y ejecutar la solución
Seleccione la tecla F5.
Nota
Al seleccionar F5, Visual Studio compila la solución, implementa el complemento y abre la página de permisos del complemento.
Seleccione el botón Confiar.
Seleccione el icono del complemento en la página Contenidos del sitio.
Para descargar este ejemplo de la galería de código, vea el ejemplo de código Usar el widget experimental Selector de personas en un complemento.
Pasos siguientes
En este artículo le enseñamos a usar el widget Selector de personas en su complemento con HTML. También puede explorar los siguientes escenarios y detalles sobre el widget.
Usar JavaScript para declarar el widget Selector de personas
Según sus preferencias, tal le vez le convenga usar JavaScript en lugar de HTML para declarar el widget. Si este es el caso, puede usar el marcado siguiente como el marcador de posición para el widget.
<div id="PeoplePickerDiv"></div>
Use el siguiente código JavaScript para crear una instancia del Selector de personas.
new Office.Controls.PeoplePicker(
document.getElementById("PeoplePickerDiv"), {});
Si quiere ver un ejemplo de código de cómo hacer las tareas, vaya a la página JSSimple.html en el ejemplo de código Usar el widget experimental Selector de personas en un complemento.
Especificar las opciones del widget
Puede especificar opciones para el widget usando el atributo datos-office-opciones en la declaración del widget. El código HTML siguiente muestra cómo especificar las opciones del widget Selector de personas.
<div id="PeoplePickerDiv"
data-office-control="Office.Controls.PeoplePicker"
data-office-options='{
"allowMultipleSelections" : true,
"onChange" : handleChange,
"placeholder" : "Check the count message, it changes when you add names..."
}'>
</div>
En el código siguiente se muestra cómo especificar opciones al declarar el widget Selector de personas con JavaScript.
new Office.Controls.PeoplePicker(
document.getElementById("PeoplePickerDiv"), {
allowMultipleSelections: true,
placeholder: "Check the count message, it changes when you add names...",
onChange: function (ctrl) {
document.getElementById("count").textContent =
ctrl.selectedItems.length.toString();
}
});
También puede especificar controladores de eventos para los eventos onChange, onAdded y onRemoved. Observe en el código anterior que el controlador de eventos para el evento onChange recibe un solo parámetro ctrl, que es una referencia al widget.
Para consultar un ejemplo de cómo especificar opciones, vea las páginas MarkupOptions.html y JSOptions.html en el ejemplo de código Usar el widget experimental Selector de personas en un complemento.
Recuperar las personas o los grupos seleccionados en el widget
Para recuperar las personas del widget debe realizar las siguientes tareas:
Obtener una referencia al widget.
Obtener acceso a la propiedad selectedItems del widget.
Puede usar la sintaxis siguiente para obtener una referencia al widget.
var pplPicker = document.getElementById("PeoplePickerDiv")._officeControl;
También puede guardar una referencia al crear una instancia del widget.
var pplPicker = new Office.Controls.PeoplePicker(
document.getElementById("PeoplePickerDiv"), {});
La propiedad selectedItems es una matriz de objetos que representan personas o grupos. Las personas o los grupos de la matriz selectedItems pueden estar resueltos o no, lo que se puede comprobar en la propiedad isResolved. En el siguiente ejemplo se muestra cómo obtener acceso al elemento i de la matriz y usar el nombre de la persona o el grupo.
var principal = pplPicker.selectedItems[i];
$("#msg").text(principal.text + " is selected in the control.");
Si quiere un ejemplo de cómo recuperar del widget las personas o los grupos seleccionados, vea la página demo.html del ejemplo de código Demostración de Office Web Widgets: Experimental.
Personalizar el estilo del widget
Como desarrollador, tal vez quiera personalizar la apariencia del widget. La imagen siguiente muestra la jerarquía de HTML en el widget después de que se ha representado. El widget define muchas clases con el prefijo office-peoplepicker, que puede encontrar y personalizar en la hoja de estilos Office.Controls.css.
Jerarquía HTML en el widget Selector de personas
Puede usar el widget experimental Selector de personas para seleccionar personas y grupos en el espacio empresarial. El complemento puede luego usar las entidades de seguridad seleccionadas por los usuarios. Proporcione ideas y comentarios en el sitio de UserVoice de la plataforma para desarrolladores de Office.