User Selection

Introduction

This component is used for selecting a single user from a list of users defined by a role name list. If you don’t define the role name list, all users will be loaded. It includes a label, an autocomplete and one message element to display a message related to that autocomplete element.

How to Use

You can insert this component into any page. This component supports two styles to display a label.

1. Default Style

   

   Code example:

   <ic:com.axonivy.portal.components.UserSelection
     componentId="default-user-autocomplete"
     selectedUser="#{data.selectedUser}"
     label="Default user selection"
     isRequired="true" />
   

2. Floating Label

   

   Code example:

   <ic:com.axonivy.portal.components.UserSelection
     componentId="all-user-autocomplete"
     hightlight="false"
     selectedUser="#{data.selectedUserForExcludingUsers}"
     label="Loading users (exclude supporter, tester)"
     excludedUsernames="#{data.excludedUsernames}"
     floatingLabel="true" />
   

Tip

The autocomplete element of the user selection component allows to insert children and ajax events (Refer to UserSelection.xhtml). Any child in the UserSelection component will be re-parented into this autocomplete at the location of the insertChildren tag. We introduce a facet named event for autocomplete so that the ajax event can be nested, as well.

An example:

I want to display users in a dropdown list formatted as “<Full name> (<username>)”. When I select a user, a message shall be displayed.

<ic:com.axonivy.portal.components.UserSelection
  id="item-select-event-component"
  componentId="item-select-event-for-user-selection"
  fromRoleNames="#{data.definedRoleNames}"
  selectedUser="#{data.selectedUserForInsertChildren}"
  label="Demonstrate facet and children"
  floatingLabel="true"
  hasCustomizedSelectionList="true">
  <p:column>
    <pc:securityMemberNameAndAvatar
      displayName="#{user.getDisplayName()} (#{user.getMemberName()})"
      securityMember="#{user}"
      isStandAlone="false" />
  </p:column>
  <f:facet name="event">
    <p:ajax event="itemSelect" listener="#{logic.showSelectedUser}"
      update="#{p:resolveFirstComponentWithId('item-select-event-for-user-selection-message', view).clientId}" />
  </f:facet>
</ic:com.axonivy.portal.components.UserSelection>

Please refer to UserSelectionExample.xhtml in project portal-components-examples for more details.

This component offers the following attributes:

Name	Default	Type	Description
fromRoleNames	null	List<String>	List of role names. Only users in these roles are loaded. Leave empty to load all users.
componentId	user-selection	String	Unique identifier of this component instance.
selectedUser	null	UserDTO	Holds the selected user value.
excludedUsernames	null	List<String>	List of usernames to exclude from selection. Only applies when using the default completeMethod.
requiredMessage	This field is required	String	Validation message displayed when the required field is empty.
forceSelection	true	Boolean	When enabled, only users from the suggestion list can be selected.
minQueryLength	1	Boolean	Minimum number of characters required to start searching.
completeMethod	completeUser	Method Expression	Custom method for loading users. Must accept a String query and return List<UserDTO>.
isDisabled	false	Boolean	Disables the user selection input.
isRequired	false	Boolean	Marks the user selection field as required.
isReadOnly	false	Boolean	Prevents changing the selected user when enabled.
isRenderedMessage	true	Boolean	Controls whether validation messages are rendered.
hightlight	true	Boolean	Automatically highlights the first suggested user.
floatingLabel	false	Boolean	Displays the label using floating style.
autocompleteStyleClass	null	String	CSS style class applied to the autocomplete component.
autoCompletePanelStyleClass	null	String	CSS style class applied to the autocomplete dropdown panel.
inputStyleClass	null	String	CSS style class applied to the autocomplete input field.
labelStyleClass	null	String	CSS style class applied to the label.
label	null	String	Label text for the user selection component.
size	null	Integer	Number of characters used to determine the width of the input element.
messageStyleClass	null	String	CSS style class applied to the validation message.
itemLabel	displayName	String	Displayed text of selected user item and users in dropdown list.
cache	true	Boolean	If true, autocomplete caches search result list.
moreText	More…	String	The text shown in panel when the suggested list is greater than maxResults.
queryDelay	300	Integer	Delay in milliseconds before sending a query to the server.
maxResults	100	Integer	Maximum number of results to be displayed.
scrollHeight	390	Integer	scrollHeight attribute of primefaces autocomplete.
hasCustomizedSelectionList	false	Boolean	Displays a customized selection list when enabled.
isShowAvatarInSelectionList		Boolean	Displays user avatars in the selection list when enabled. Set to true to show avatar. The setting will detect Portal setting Portal.ShowAvatar as its default value, refer to HowTo: Update HowTo: Update Portal Settings for more details. If the Portal setting is not available, defaults to true.
displayNameRenderedInSelectionList	true	Boolean	Controls visibility of the user display name in the selection list.
displayNameInSelectionListStyleClass	null	String	CSS style class for the user display name in the selection list.
selectionListContainerStyleClass	null	String	CSS style class for the selection list item container.
emptyMessage	No results	String	Message displayed when no results are available.

Migrate to 12.0.12

1. The UserSelection component has been restructured to improve layout consistency. If you have custom styles for this component, please review and adjust them accordingly.

2. The attribute labelPanelStyleClass has been also removed. If you used this attribute, please remove it from your code.

Migrate from Deprecated User Selection

1. Replace code in HTML files: replace ic:ch.ivy.addon.portalkit.component.UserSelection with ic:com.axonivy.portal.components.UserSelection.

2. Replace ch.ivy.addon.portalkit.dto.UserDTO with com.axonivy.portal.components.dto.UserDTO.

   Note

   If you stored class ch.ivy.addon.portalkit.dto.UserDTO in your database, you have to update the database manually.