Working with users in SharePoint Hosted Apps - Part II
In the previous article, we went over how to work with users and people picker control in SharePoint hosted apps. In this article, we will look at how we can use people picker control to specify only the type of users and/or groups we want. The following MSDN article just touches on the basic minimum you would need to setup people picker control. The topic of interest here is the schema that is used to initialize the control. The schema settings specified allows people picker control to resolve all users and groups. Let's look at the schema:
var schema = {
'PrincipalAccountType': 'User,DL,SecGroup,SPGroup',
'SearchPrincipalSource': 15,
'ResolvePrincipalSource': 15,
'AllowMultipleValues': false,
'Required': true,
'MaximumEntitySuggestions': 5,
'Width': '235px'
};
So what are these properties? Here is brief overview, starting from the most obvious:
Width: This value specifies the width of the div control
Required: This forces the control to have a valid value before form gets submitted
MaximumEntitySuggestions: This shortens the list of valid values for selection to the number specified. For instance, if the user name is "David" and there are 10 "David"s in the system, specifying 5 would return the top 5 values and you would need to type additional characters to narrow the search results. You can increase/decrease the value to fit your need
AllowMultipleValues: If set to "false", this forces the control to have only one valid value. Setting it to "true" would allow you to select multiple values. This is independent from the list column settings. For instance, if the column doesn't allow multiple values and vice versa, the column setting would not effect the selection
PrincipalAccountType: This allows to specify what valid values can be selected. For instance, do you want to allow group selection, user selection, everything, and/or none. This is also independent from the list column settings. For instance, if the column allows selection of only users, you can still select groups though you will run in to issues saving the information back to the column. In order to allow only user selection, you would set this property to "User". You can read more about the valid enumeration values here
SearchPrincipalSource: This value specifies where you would want to search for the valid values. This provides a list of valid values which is trimmed by MaximumEntitySuggestions. In this case, we are specifying 15 which means we want valid values from "All" sources. It is a bitwise combination of its member values so valid values are 0, 1, 2, 4, 8, and 15. You can read more about the valid enumerations here
ResolvePrincipalSource: This value specifies which store to use to resolve the selected values. This value should match the SearchPrincipalSource so you are only searching values that you would want to resolve
In our last article, we were comparing the valid values to the user information list. If you notice, we are using 15 as SearchPrincipalSource and ResolvePrincipalSource, but here is the issue. We might run in to a case where the user selected does not exist in the user information list and you will not get back an ID to store in the list column. To resolve this, we will specify 1, which is UserInfoList, as SearchPrincipalSource and ResolvePrincipalSource.
All good so far? Great. But we still have a small concern. We have a lot of users on SharePoint and all those users will appear in our selection list. Here is our scenario:
1- We want to select only users
2- We want to search and resolve against user information list so we can search for a valid ID to store in the list column
3- We want to limit the search further to only a specific SharePoint group
4- We want to allow multiple user selection
Oh! The settings discussed so far does not include any property that would allow us to specify a particular SharePoint group to search and resolve users from. I would like to stop here and take a moment to thanks Microsoft for making our life a bit easier (seriously).
JSOM API model provides most frequently used types and objects which are based on .NET server implementation (SSOM). In some cases, types are native to CSOM, and there is no equivalent .NET server type. In other cases, some but not all possible, CSOM implementations of a specific type exist.
So let's go find "People Picker" Server Side Model. What we found a close relative which is "People Editor" type. After looking at all the properties, there are two properties that might help us with our scenario:
1- SharePointGroup property
2- SharePointGroupID property
We will use the SharePointGroupID property in order to avoid ambiguity with SharePoint Group names. We will create a small console application to fetch all the groups and IDs within the site collection. Let's fetch the group ID:
using (SPSite site = new SPSite("http://www.mysite.com/mysitecollection"))
{
using (SPWeb aweb = site.OpenWeb())
{
SPGroupCollection getgroups = aweb.SiteGroups;
Dictionary<int, string> gggg = new Dictionary<int, string>();
foreach (SPGroup gg in getgroups)
{
gggg.Add(gg.ID, gg.Name);
}
var sgggg = gggg.OrderBy(ee => ee.Value);
foreach (KeyValuePair<int, string> thd in sgggg)
{
Console.WriteLine("{0},{1}", thd.Key, thd.Value);
}
}
}
Make sure to reference the necessary libraries. Now we will select the group ID that we want to use and modify the schema settings as per our scenario:
var schema = {
'PrincipalAccountType': 'User',
'SearchPrincipalSource': 1,
'ResolvePrincipalSource': 1,
'SharePointGroupID': 20,
'AllowMultipleValues': true,
'Required': true,
'MaximumEntitySuggestions': 5,
'Width': '235px'
};
Conclusion
There are several types and objects available in the Server Side Object Model which corresponds to equivalent types in Client Side Object Model, JavaScript Object Model and REST.
References
Working with users in SharePoint Hosted Apps
How to: Use the client-side People Picker control in SharePoint-hosted apps
PrincipalType enumeration
SPPrincipalSource enumeration
PeopleEditor class
SharePoint 2013 .NET Server, CSOM, JSOM, and REST API index