SharePoint 2013. Контрол ClientPeoplePicker

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

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

Свойства ClientPeoplePicker

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

  • AutoFillEnabled - флаг, указывающий на использование автокомплита. Если указать его равным false, то автокомплита не будет, а будет кучка исключений из-за отсутствия типа SPClientAutoFill. В SharePoint 2013 Preview этим свойством лучше не пользоваться;
  • InitialHelpText - текст, отображаемый в пустом поле. Если текст будет длинным, то будет не очень красиво:
    Текст-подсказка для ClientPeoplePicker
  • SetFocus - флаг, указывающий, должен ли элемент получить фокус при загрузке страницы;
  • MaximumEntitySuggestions - максимальное количество элементов в результате поиска;
  • VisibleSuggestions - максимальная высота подсказки для автокомплита, измеряется в строках (одна строка - один элемент + итоговая строка);
  • PrincipalSource - задание области выбора пользователей. Выбор из перечисления:
    1. public enum SPPrincipalSource
    2. {
    3.     All = 15,
    4.     MembershipProvider = 4,
    5.     None = 0,
    6.     RoleProvider = 8,
    7.     UserInfoList = 1,
    8.     Windows = 2
    9. }
    Также можно комбинировать, т.к. SPPrincipalSource имеет атрибут Flags. Т.е. для выбора пользователей из списка пользователей и windows-пользователей можно сделать примерно так:
    1. // Выбор из списка пользователей и windows-пользователей
    2. Picker.PrincipalSource = SPPrincipalSource.UserInfoList | SPPrincipalSource.Windows;
  • OnControlValidateClientScript, OnUserResolvedClientScript, OnValueChangedClientScript - задание скриптов для обработки событий на стороне клиента. Подробнее об этом чуть ниже.

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

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

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

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

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

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

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

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

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

  1. <SharePoint:ClientPeoplePicker ID="Picker" runat="server"
  2.     OnControlValidateClientScript="PickerControlValidate"
  3.     OnUserResolvedClientScript="PickerUserResolved"
  4.     OnValueChangedClientScript="PickerValueChanged">
  5. </SharePoint:ClientPeoplePicker>

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

  1. function PickerControlValidate(topElementId, users){
  2.     // Валидация
  3. }
  4.  
  5. function PickerUserResolved(topElementId, users){
  6.     // Разрешение записи
  7. }
  8.  
  9. function PickerValueChanged(topElementId, users){
  10.     // Изменение значения
  11. }

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

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

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

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

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

Кэш данных

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

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

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

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

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

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

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

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

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

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

  1. public List<PickerEntity> AllEntities { get; }

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

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

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

  1. public void AddEntities(List<PickerEntity> newEntities)

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

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


Поделиться

Коментарии