This is the first in a series of how-to posts on using SP standard controls in your own webpart or user controls.
I saw this post on MSDN forums, so I thought I would go ahead and answer.
Ask any developer that has been writing code for more than a year, and you will find that you should have reusable code. In .Net classes this mean either common classes, interfaces, or utility classes.
So pick one(or a couple), and use it.
My point being, instead of just showing how to use a PeopleEditor control, create a class that provides these methods, or a utility class.
Okay, enough banter, let’s get started.
You will eventually want to save the data into a SPList, or fill the control with data from a SPList into the control. Even if you just want the values, extend your methods. bleow are two methods I commonly use: (This method will also add the user to the Site Collection Users collection as SharePoint does OOB with people editor controls.)
/// <summary>
/// Gets the value (Either SPUser or empty string) from the Control, can be used to store this directly to a SPListItem field.
/// </summary>
/// <param name="peopleEditorControl">The people editor control.</param>
/// <returns>SPUser if found, or Empty String.</returns>
public object GetPeopleEditorValue(PeopleEditor peopleEditorControl)
{
if (peopleEditorControl.IsValid)
{
try
{
//Check to make sure that there is at least one user
if (peopleEditorControl.Accounts.Count > 0)
{
//For more than one user, this can be changed to a foreach.
PickerEntity entity = peopleEditorControl.Entities[0] as PickerEntity;
Hashtable peopleEditorData = entity.EntityData;
string strUserLogin = entity.Key;
string strUserEmail = peopleEditorData["Email"].ToString();
string strUserDisplayName = peopleEditorData["DisplayName"].ToString();
SPUser SelectedUser = null;
try
{
if (peopleEditorData.Contains("SPUserID") && (!String.IsNullOrEmpty(peopleEditorData["SPUserID"].ToString())))
{
SelectedUser = SPContext.Current.Web.SiteUsers.GetByID(Convert.ToInt16(Convert.ToString(peopleEditorData["SPUserID"])));
}
else
{
SelectedUser = SPContext.Current.Web.SiteUsers.GetByEmail(strUserEmail);
}
}
catch (Exception)
{
//To add the user to the site collection
SPSecurity.RunWithElevatedPrivileges(
delegate()
{
//Could not find the user, add them to the site users.
SPContext.Current.Web.SiteUsers.Add(strUserLogin, strUserEmail, strUserDisplayName, "");
SelectedUser = SPContext.Current.Web.SiteUsers.GetByEmail(strUserEmail);
});
}
return SelectedUser;
}
else
{
return String.Empty;
}
}
catch (Exception ex)
{
Debug.WriteLine("There was an error processing the PeopleEditor Control: " + ex.Message);
return String.Empty;
}
}
else
{
//control is not valid, entries are not valid.
//Throwing an exception is optional
throw new Exception("People Editor Control is not valid, please correct the selection, and try again.");
}
}
Now, to set the value of a PeopleEditor control from list data:
/// <summary>
/// Fills the control with the appropriate user, can be used to fill a control from a SPListItem field.
/// </summary>
/// <param name="strUserId">The user id. eg. id#;domain\login</param>
/// <param name="peopleEditorControl">The people editor control.</param>
public void FillPeopleEditorControl(string strUserId, PeopleEditor peopleEditorControl)
{
try
{
if (!String.IsNullOrEmpty(strUserId))
{
strUserId = strUserId.Substring(0, strUserId.IndexOf(";"));
SPUser SelectedUser = SPContext.Current.Web.AllUsers.GetByID(Convert.ToInt16(strUserId));
PickerEntity pe = new PickerEntity();
pe.Key = SelectedUser.LoginName;
pe = peopleEditorControl.ValidateEntity(pe);
peopleEditorControl.Entities.Add(pe);
}
}
catch (Exception ex)
{
Debug.WriteLine("There was an error loading the PeopleEditor control: " + ex.Message);
}
}
Generally in the CreateChildControls override, I use Setup methods similar to the following:
/// <summary>
/// Setup a people editor control.
/// This method should be called from CreateChildControls method, and the control should be a member variable of the class.
/// </summary>
/// <param name="control">The control.</param>
/// <param name="strControlId">The STR control id.</param>
private void SetupPeopleEditorControl(ref PeopleEditor control, string strControlId)
{
//Create an instance of the control.
control = new PeopleEditor();
//Setup the ID
control.ID = "pplEditor_" + strControlId;
//This can be changed, or overriden as needed.
control.Width = Unit.Pixel(200);
//Only want one row, if using multipe users, then raise this number
control.Rows = 1;
//Set this to false to require an etnry
control.AllowEmpty = true;
//Set this to true to allow more than one selection
control.MultiSelect = false;
//Set this to the appropriate number of users
control.MaximumEntities = 1;
//Now add the control to the Controls collection.
Controls.Add(control);
}
Now there are a ton of ways to modify and extend the above methods, but they are a good stating point.
Hope this helps to explain some things about the People Editor Control. Next post will be about the DateTimeControl!