building a people picker field for Office365 based applications
If your building an application for Office 365, at some point you may need to incorporate a people picker field in your user interface. If your application is using React as the front end framework, you’ve got the Office UI Fabric People Picker available to use as shown below.
The Office UI Fabric People Picker has plenty of functionality and if you can use it, it will save a lot of development time. If however, your application does not use React, you may well find yourself having to build a people picker from scratch. As daunting as this may sound, it’s not that bad, if you follow some simple rules.
Build a people picker component
No matter what UI Framework your Office 365 application uses, start by building the people picker as a component. This is important for both re-use in other areas of the application and re-use for different application modes. Put the effort into building a solid component with a rich interface and it will become an excellent addition to your application toolbox.
A few examples of the interface options to consider are as follows:
- Allow multiple selections
- Allow users, groups or both to be selected
- Mode for editable or read only
- Model for storing the selected objects
- Callback methods for when selections are made or cleared
With the component framework created and the interface defined, it can be added to different areas of the application that need it.
Styling the people picker component
One of the major drawbacks of the Office UI Fabric evolution is that the style sheets are no longer available for the different components. The initial release of Office UI Fabric had a components.css that contained all the styles for all the components along with markup samples and you simple needed to build the markup in your UI Framework of choice. Our best option here is to put the style sheet together ourselves using the Office UI Fabric People Picker component page as a reference.
Start with a new Syntactically Awesome Style Sheet and as with most components, I use a flexbox layout. Using flex means the selected people or groups will flow nicely in the control along with the input box.
Creating the style for the person or group selection item is super simple. Each item is an html div wrapper styled as a flexbox with three columns. The div wrapper has a border radius to give the rounded edges. The first and last columns also have the border radius and a fixed height and width so they appear to be round.
The person icon and the remove button icon are provided by the Office UI Fabric core styles. I use the ms-Icon–Contact and the ms-Icon–Cancel icons. Some more flexbox magic will align the text and icons in each direction.
When a search is made, the results are displayed in a scroll pane for selection. If we were to design the control using an html select element, this functionality would be built in. However, the select control does not allow the options to be styled nicely so we need to use a different mechanism. I simply use an absolute positioned html div element. Inside the div element, are a few different areas.
Results pane header section
The header section for the results pane has a message area and a clear button. The messages in the message area have a few purposes, as follows:
- Prompt the user to continue typing in order to perform a search (there must be at least 2 characters to do a search)
- Show the Office UI Fabric loading spinner when a search is being made.
- Show a count of the number of results returned.
The clear button removes the search results and the search text that was typed into the control. This allows a completely new search to be performed.
Results body
The results body is simply a div element with a fixed maximum height and an auto overflow set on the y axis. When more than just a few results are returned, the scroll bar is displayed and the results can be scrolled.
Results pane interaction
The (sort of) tricky part is showing and hiding the results pane as required. I use the following logic to show and hide the pane:
- Show if the control has focus and there is at least one character has been entered.
- Hide if the control loses focus and the results pane also does not have focus (the scroll bar has been clicked).
That sounds pretty simple but there are a few oddities when using Internet Explorer that need to be catered for in a cross browser solution.
The navigation is nice and simple:
- The tab key moves to the next tab index on the page, e.g. the next form control.
- When the results pane is open, the arrow keys navigate up and down the results list, highlighting the next result.
- The enter key selects the highlighted result.
- Clicking on a result also selects it.
- When a result is selected, the search text is cleared and the results pane is hidden.
Calling the Microsoft Graph api
There are two api endpoints that can provide the functionality required for the people picker:
In order use these endpoints to ‘search’ for matching people or groups, you’ll need to make use of the OData $filter attribute. There are currently a number of limitations in the Graph api implementation of $filter so you’ll need to be patient/creative! There are two main areas to consider before digging in too deep.
Number 1:
Note: The following $filter operators are not supported for Azure AD resources: ne, gt, ge, lt, le, and not. The contains string operator is currently not supported on any Microsoft Graph resources.
Number 2:
Look at the properties section of the User object and the Group object and note which properties support the $filter attribute. Unfortunately, some important properties DO NOT support $filter…
The completed people picker control
Recent Comments