Role Selection

Introduction

This component is used to select a role from a given list of roles. If you don’t define the role list, all roles will be loaded. It includes one label, one autocomplete and one message element to display messages related to this autocomplete element.

How to Use

You can insert this component into any page. This component offers the following two styles to display its label.

1. Default Style

   

   Code example:

   <ic:com.axonivy.portal.components.RoleSelection
      componentId="role-from-defined-role-autocomplete"
      fromRoleNames="#{data.definedRoleNames}"
      selectedRole="#{data.selectedRoleForDefinedRoles}"
      isRequired="true"
      label="Roles from defined role names"/>
   

2. Floating Label

   

   Code example:

   <ic:com.axonivy.portal.components.RoleSelection
      componentId="floating-label-and-exclude-role-autocomplete" hightlight="false"
      selectedRole="#{data.selectedRole}"
      label="Loading with all roles (exclude CaseOwner, GeneralManager)"
      excludedRolenames="#{data.excludedRoleNames}"
      isRequired="true" floatingLabel="true" />
   

Tip

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

For example:

I want to display roles in dropdown list formatted as “<Display Name> (<Member Name>)”. When I select a role, a message shall be displayed.

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

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

This component offers the following attributes:

Name	Default	Type	Description
fromRoleNames	null	List<String>	List of parent role names. Only child roles of these roles are loaded. Leave empty to load all roles.
componentId	role-selection	String	Unique identifier of this component instance.
selectedRole	null	RoleDTO	Holds the selected role value.
excludedRolenames	null	List<String>	List of role names 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 roles from the suggestion list can be selected.
minQueryLength	1	Boolean	Minimum number of characters required to start searching.
completeMethod	completeRole	Method Expression	Custom method for loading roles. Must accept a String query and return List<RoleDTO>.
isDisabled	false	Boolean	Disables the role selection input.
isRequired	false	Boolean	Marks the role selection field as required.
isReadOnly	false	Boolean	Prevents changing the selected role when enabled.
isRenderedMessage	true	Boolean	Controls whether validation messages are rendered.
hightlight	true	Boolean	Automatically highlights the first suggested role.
floatingLabel	false	Boolean	Displays the label using floating style.
autocompleteStyleClass	null	String	CSS style class applied to the role autocomplete component.
autoCompletePanelStyleClass	null	String	CSS style class applied to the role autocomplete dropdown panel.
inputStyleClass	null	String	CSS style class applied to the role autocomplete input field.
labelStyleClass	null	String	CSS style class applied to the label.
appendOption	null	String	Additional information appended to the role display, such as parent role name or none. Value: NONE, PARENT_NAME.
label	null	String	Label text for the role selection component.
size	null	Integer	Number of characters used to define the input width.
messageStyleClass	null	String	CSS style class applied to the validation message.
itemLabel	displayName	String	Text displayed for roles in the dropdown and the selected value.
cache	true	Boolean	Caches autocomplete search results when enabled.
moreText	More…	String	Text displayed for the ‘More’ link when results exceed the limit.
queryDelay	300	Integer	Delay in milliseconds before sending the search query.
maxResults	100	Integer	Maximum number of results displayed in the dropdown.
scrollHeight	390	Integer	Maximum height of the autocomplete dropdown panel.
hasCustomizedSelectionList	false	Boolean	Displays a customized selection list when enabled.
isShowAvatarInSelectionList		Boolean	Displays role avatars in the selection list when enabled. 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 role display name in the selection list.
displayNameInSelectionListStyleClass	null	String	CSS style class for the role 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 RoleSelection 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 removed. If you used this attribute, please remove it from your code.

Migrate from Deprecated Role Selection

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

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

   Note

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