SharePoint 2013. Контрол ClientPeoplePicker

Продолжая тему предыдущего поста о контроле ImageCrop, сегодня о ещё одном новом контроле - ClientPeoplePicker. Предназначен он, как видно из названия, для выбора пользователей. В отличии от классического PeoplePicker'а новый контрол обладает автокомплитом!

Автокомплит в ClientPeoplePicker'е вытеснил диалоговое окно поиска пользователей, которое можно очень сильно кастомизировать:

ClientPeoplePicker

ClientPeoplePicker

Свойства ClientPeoplePicker

В основном свойства аналогичны свойствам контрола PeoplePicker. Вот некоторые из свойств ClientPeoplePicker:

  • AutoFillEnabled - флаг, указывающий на использование автокомплита. Если указать его равным false, то автокомплита не будет, а будет кучка исключений из-за отсутствия типа SPClientAutoFill. В SharePoint 2013 Preview этим свойством лучше не пользоваться;
  • InitialHelpText - текст, отображаемый в пустом поле. Если текст будет длинным, то будет не очень красиво:

Текст-подсказка для ClientPeoplePicker

Текст-подсказка для ClientPeoplePicker
  • SetFocus - флаг, указывающий, должен ли элемент получить фокус при загрузке страницы;
  • MaximumEntitySuggestions - максимальное количество элементов в результате поиска;
  • VisibleSuggestions - максимальная высота подсказки для автокомплита, измеряется в строках (одна строка - один элемент + итоговая строка);
  • PrincipalSource - задание области выбора пользователей. Выбор из перечисления:
public enum SPPrincipalSource
{
    All = 15,
    MembershipProvider = 4,
    None = 0,
    RoleProvider = 8,
    UserInfoList = 1,
    Windows = 2
}

Также можно комбинировать, т.к. SPPrincipalSource имеет атрибут Flags. Т.е. для выбора пользователей из списка пользователей и windows-пользователей можно сделать примерно так:

// Выбор из списка пользователей и windows-пользователей
Picker.PrincipalSource = SPPrincipalSource.UserInfoList | SPPrincipalSource.Windows;
  • OnControlValidateClientScript, OnUserResolvedClientScript, OnValueChangedClientScript - задание скриптов для обработки событий на стороне клиента. Подробнее об этом чуть ниже.

Работа с ClientPeoplePicker'ом на стороне клиента

Для работы ClientPeoplePicker использует файл clientpeoplepicker.js.

Получение экземпляра SPClientPeoplePicker

Все контролы выбора пользователя регистрируются в словаре SPClientPeoplePicker.SPClientPeoplePickerDict и ключ к кокретному контролу формируется путем конкатенации клиентского ID контрола и _TopSpan. Таким образом, чтобы получить объект SPClientPeoplePicker можно использовать следующий скрипт:

// Получение пикера
function GetPeoplePicker(clientId){
    var key = clientId + "_TopSpan";
    var picker = SPClientPeoplePicker.SPClientPeoplePickerDict[key];
    return picker;
}

Теперь, чтобы получить ключ, имея объект SPClientPeoplePicker, можно использовать его свойство TopLevelElementId:

// Ключ для пикера
var key = picker.TopLevelElementId;

События ClinetPeoplePicker'а на стороне клиента

Используя свойства OnControlValidateClientScript, OnUserResolvedClientScript, OnValueChangedClientScript контрола ClientPeoplePicker можно подписаться на события на стороне клиента. При вызове этих методов им в качестве аргументов будут переданы TopLevelElementId и массив, содержащий выбранных пользователей (как разрешенных, так и неразрешенных). Примерно вот так можно указать эти свойства декларативно:

<SharePoint:ClientPeoplePicker ID="Picker" runat="server"
    OnControlValidateClientScript="PickerControlValidate"
    OnUserResolvedClientScript="PickerUserResolved"
    OnValueChangedClientScript="PickerValueChanged">
</SharePoint:ClientPeoplePicker>

И javascript-код для обработки этих событий:

function PickerControlValidate(topElementId, users){
    // Валидация
}
 
function PickerUserResolved(topElementId, users){
    // Разрешение записи
}
 
function PickerValueChanged(topElementId, users){
    // Изменение значения
}

users является массивом, содержащем информацию о выбранных пользователях:

Пользователь в ClientPeoplePicker

Пользователь в ClientPeoplePicker

Кастомизация вывода подсказок

Для вывода подсказки, SharePoint используется два значения: текст и подтекст. В моем случае использовались свойства DisplayText и Title для текста и подтекста соответственно. Изменять эти свойства можно только для всех контролов на странице сразу:

// Задание свойства для текста
SPClientPeoplePicker.DisplayTextName = "DisplayText";
 
// Задание свойства для подтекста
SPClientPeoplePicker.SubDisplayTextName = "Department";

Кэш данных

По умолчанию ClientPeoplePicker кэширует полученные данные. Чтобы запретить кэширование на стороне клиента для конкретного экземпляра ClientPeoplePicker'а:

// Получение экземпляра пикера (см. выше)
var picker = GetPeoplePicker(clientId);
 
// Запрет использования локального кэша
picker.UseLocalSuggestionCache = false;

До кэшированных данных можно добраться через свойство PPMRU объекта ClientPeoplePicker'а:

Чтобы принудительно сбросить кэш, просто вызываем метод ResetCache:

// Получение экземпляра пикера (см. выше)
var picker = GetPeoplePicker(clientId);
 
// Кэш
var cache = picker.PPMRU;
// Сбрасываем кэш
cache.ResetCache();

Это лишь малая доля всего клиентского разнообразия нового контрола. Самая интересная на мой взгляд.

Работа с ClientPeoplePicker'ом на стороне сервера

Теперь пару примеров работы на стороне сервера.

Чтение данных

Все пользователи, выбранные с помощью контрола, доступны в свойстве AllEntities, которое возвращает список объектов EntityPicker:

public List<PickerEntity> AllEntities { get; }

Это тот самый Microsoft.SharePoint.WebControls.PickerEntity, который используется в стандартных пикерах SharePoint. В SharePoint 2013 класс EntityPicker дополнен двумя internal-свойствами: EntityLookupId и EntityLookupValue. Возвращают они Id и Title выбранного пользователя или группы. Если выбранная сущность не является ни пользователем ни группой, то EntityLookupId будет равен -1.

Задание значения

Задание значения происходит аналогично со стандартным пикером PeopleEditor. Значения можно только добавлять!

public void AddEntities(List<PickerEntity> newEntities)

Также можно указать список объектов PickerEntity, выводимые в подсказке при загрузке контрола, передав их в качестве аргумента методу SetInitialSuggestions.

Вот такой интересный контрол появился в SharePoint 2013.

Виталий Жуков

Виталий Жуков

SharePoint архитектор, разработчик, тренер, Microsoft MVP (Office Development). Более 15 лет опыта работы с SharePoint, Dynamics CRM, Office 365, и другими продуктами и сервисами Microsoft.

Смотрите также

EntityFramework. Оптимистические блокировки

EntityFramework. Оптимистические блокировки

Linq to Sharepoint. Особенности

Linq to Sharepoint. Особенности

SharePoint 2010. Настройка входящей почты для кастомного списка

SharePoint 2010. Настройка входящей почты для кастомного списка

SharePoint 2010. PeopleEditor. Установка значения

SharePoint 2010. PeopleEditor. Установка значения

Linq to SharePoint. Особенности. Часть 2

Linq to SharePoint. Особенности. Часть 2