Client Side People Picker with HTML5 Placeholder text

Lately I have been working with the OfficeDev Patterns & Practices samples a lot. The amount of quality examples provided in that project is amazing, and a huge thanks should go out to all that contributed. One of the components created in the Patterns & Practices is a client side people picker that can be used in Provider Hosted Apps. This component creates a people picker inputbox that closely resembles the one you get in OOTB SharePoint.

In this blog post I’ll guide you through the steps required to extend this component to be able to add a placeholder text that describes what the field’s value should contain, using the HTML5 placeholder attribute. This allows for a much nicer UX, and makes your client side people picker go from this:

peoplepicker4

To this:

peoplepicker2

Before we get down to business, it’s important to note that this post assumes you already have your client side people picker up and running, using the Core.PeoplePicker solution. You can find out how to do just that here.

The first step is to actually include the placeholder text in the input element. That part is relatively easy. The sample dictates a certain HTML structure, because the javascript file is dependent on that structure. You need a surrounding div, span element, input textbox, search area and a hidden field that ends up containing the actual selected people value. This structure is shown below:

In order to add the placeholder text, change the Width of the asp:Textbox to 155 (or a different value based on the length of your placeholder text), and add the attribute placeholder=”your placeholder text”. If you fire up the page, the initial result is exactly what you want. However, if you add a user, you want the placeholder text to disappear, and only adding the placeholder attribute doesn’t do that:

peoplepicker3

The reason it doesn’t hide the placeholder text is because the value for Test User 1 isn’t stored inside the input box, but rather inside the hidden field. And because the input box doesn’t have any value, the default behavior is to show the placeholder text.

In order to fix this, we’ll need to add a change event to the hidden field that stores the people picker value. In case the value is changed, we want to adjust the placeholder attribute on the input field accordingly. And secondly, we need to make sure the change event is fired when a user is added or deleted (default behavior for a hidden field is that value change events do not fire, because it’s not the user that executes the change, but rather the javascript).

To add a change event to the hidden field, you can include the following line of javascript in your $(document).ready function:
$(‘#hdnSiteOwner’).change(changeSiteOwnerPlaceholder);

The function that is executed on the value change is shown below:

It looks at the value for the hidden field. If the value does not equal ‘[]’ (which is the value set by the control in case a user is cleared out), a user has been selected and the placeholder text is emptied. If the value does equal ‘[]’, no user is selected and the placeholder text is restored.

The last step is to make sure the change() method gets executed when a user is selected or removed. To do that, we need to add several lines of code to the peoplepickercontrol.js file. The methods ‘RemoveResolvedUser’, ‘RecipientSelected’ and ‘DeleteProcessedUser’ need to have the following line included at the end:

this.PeoplePickerData.change();

Which makes the methods end up like this:

And that’s it! Now you have a fully functioning client side people picker with a placeholder text that is cleared after a user has been selected, and returns in case all users are cleared. Your end users will certainly appreciate the informative description that you have just added! Happy coding.