Use o controle People Picker do lado do cliente nos Suplementos do SharePoint hospedados no SharePoint

O que é o controle People Picker no lado do cliente no SharePoint?

O controle People Picker do lado do cliente permite aos usuários pesquisar e selecionar contas de usuários válidas para pessoas, grupos e reivindicações na organização deles. O seletor é um controle HTML e JavaScript que fornece suporte a vários navegadores.

É fácil adicionar o seletor ao seu suplemento:

1. Na marcação, adicione um elemento de contêiner ao controle e às referências do controle e às dependências dele.

2. Em seu script, chame a função global SPClientPeoplePicker_InitStandaloneControlWrapper para renderizar e inicializar o seletor.

O seletor é representado pelo objeto SPClientPeoplePicker, que fornece métodos que outros controles do lado do cliente podem usar para obter informações do seletor ou executar outras operações. Você pode usar as propriedades SPClientPeoplePicker para definir o seletor com configurações específicas do controle, como permitir vários usuários ou especificar opções de cache.

O seletor também usa as configurações de aplicativo da Web, como os parâmetros de Serviços de Domínio do Active Directory ou florestas de destino. As configurações do aplicativo Web são definidas automaticamente (da propriedade SPWebApplication.PeoplePickerSettings).

O seletor tem os seguintes componentes:

• Uma caixa de texto de entrada para inserir nomes de usuários, grupos e declarações.
• Um controle de expansão que mostra os nomes de usuários, grupos e declarações resolvidos.
• Um elemento div oculto que preenche automaticamente uma caixa suspensa com resultados de consulta correspondentes.
• Um controle de preenchimento automático.

Pré-requisitos para configurar seu ambiente de desenvolvimento para usar o controle Seletor de Pessoas no lado do cliente em um Suplemento do SharePoint

Este artigo pressupõe que você crie o Suplemento do SharePoint usando Napa em um site do desenvolvedor do Office 365. Se você estiver usando esse ambiente de desenvolvimento, já atendeu aos pré-requisitos.

Se não estiver usando Napa em um Site do Desenvolvedor, você precisará do seguinte:

• SharePoint com pelo menos um usuário de destino
• Visual Studio 2012 ou Visual Studio 2013
• Office Developer Tools para Visual Studio 2013

As seções a seguir descrevem as etapas avançadas para adicionar o seletor ao seu suplemento e depois obter suas informações de usuários de outro controle no lado do cliente. Para o código correspondente, confira Exemplo de código: usar o People Picker no lado do cliente.

Saiba como usar o controle People Picker do lado do cliente nos Suplementos do SharePoint hospedados no SharePoint, mas não em suplementos hospedados pelo provedor.

Usar o controle People Picker no lado do cliente em um suplemento hospedado pelo SharePoint

Na sua marcação de página

1. Adicione referências às dependências de script do controle People Picker no lado do cliente.

2. Adicione as marcas HTML à interface do usuário da página. O suplemento neste exemplo define dois elementos div, um para o seletor renderizar e outro para a interface do usuário: um botão que invoca o script para consultar o seletor e os elementos que exibem informações de usuários.

No seu script

1. Crie um dicionário JSON para uso como um esquema que armazena propriedades específicas do seletor, como AllowMultipleValues e MaximumEntitySuggestions.

2. Chame a função global SPClientPeoplePicker_InitStandaloneControlWrapper.

3. Obtenha o objeto de seletor na página.

4. Consulte o seletor. O suplemento neste exemplo chama o método GetAllUserInfo para obter todas as informações dos usuários resolvidos e o método GetAllUserKeys para obter as chaves desses usuários resolvidos.

5. Obtenha a ID de usuário usando o Modelo de Objeto do JavaScript. A ID de usuário não está incluída nas informações que são retornadas pelo seletor e, portanto, o suplemento chama o método SP.Web.ensureUser e obtém a ID do objeto SP.User retornado.

A renderização, a inicialização e outras funcionalidades do seletor são manipuladas pelo servidor, inclusive as pesquisas e a resolução de entradas de usuário com base nos provedores de autenticação do SharePoint.

Exemplo de código: usar o People Picker no lado do cliente em um suplemento hospedado pelo SharePoint

Os seguintes exemplos de código HTML e JavaScript adicionam um controle People Picker no lado do cliente a um suplemento hospedado pelo SharePoint.

O primeiro exemplo mostra a marcação de página para as marcas PlaceHolderMain asp:Content na página Default.aspx. Esse código faz referência as dependências de script do seletor, fornece uma ID exclusiva para o elemento DOM no qual o seletor é renderizado e define a interface do usuário do suplemento.

<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>

O exemplo a seguir mostra o script do arquivo App.js. Esse script inicia e renderiza o seletor, consulta-o para saber mais sobre o usuário e depois obtém a ID de usuário usando o modelo de objeto 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());
}

Confira também

• Criar componentes de experiência do usuário no SharePoint
• Visão geral do Seletor de Pessoas e de provedores de declarações (SharePoint)
• Configurar o Seletor de Pessoas no SharePoint