DevelopWidgets
User and group picker
Lets the user pick one or more users. The result comes back as the message select. The widget shows only after it has received post-widget-parameters.
The user-and-group-picker widget lets the user search for and pick one user or several, and sends the picked users back to your page.
URL and parameters
The widget is at <site>/widgets/user-and-group-picker. The parameters every widget takes are in Widgets.
| Parameter | Meaning | Required |
|---|---|---|
single_select | true allows one user. The default is false. | No |
The other values are in the payload of post-widget-parameters. See the next section.
Messages
| action | Direction | payload |
|---|---|---|
ready | widget to your page | None. The widget has loaded. |
post-widget-parameters | your page to the widget | { disabledUsers, disabledGroups }, arrays of the _id of users and groups that cannot be picked (the members of those groups do not appear either). Send it after ready. An empty array is fine, but you must send it. |
select | widget to your page | { items }, an array of the picked users. Each has _id, username, firstName, middleName, lastName, displayName, email, picture and role, plus fullName and pictureUrl, which the widget adds. It is an array even when one user is picked. |
cancel | widget to your page | None. The user closed it without picking. |
The widget stays empty until it gets post-widget-parameters. It never lists the signed-in user or a deleted user.
Example
embedParams is the common parameters from Widgets.
const params = new URLSearchParams({ ...embedParams, single_select: 'false' })
frame.src = `${site}/widgets/user-and-group-picker?${params}`
addEventListener('message', (e) => {
if (e.origin !== site || e.data.messageToken !== messageToken) return
if (e.data.action === 'ready') {
frame.contentWindow.postMessage(
{ messageToken, action: 'post-widget-parameters', payload: { disabledUsers: [], disabledGroups: [] } },
site
)
}
if (e.data.action === 'select') addMembers(e.data.payload.items)
})