You are here:
Grouped List Control
Organize items within a list by grouping and sorting them in a GroupedList element. For example, group products based on a product group or brand in an order.
Required Editions
| Available in Lightning Experience in Professional, Unlimited, and Enterprise Editions that have Consumer Goods Cloud enabled. |
The GroupedList element defines a UI control that lets
you sort and group elements. The list also lets you to search for one or multiple elements
in the list. The GroupedList element has a single item
child, which can be of any type that’s available for list items and use any list item
pattern.
Attributes
These attributes are available in the GroupedList
element:
| Attribute | Description | Values/Pattern | Required |
|---|---|---|---|
| name | Unique name of this list. | String | Yes |
| searchable | Determines whether the search bar is visible. Use the search bar to search for an item within a grouped list. Default is true, the search bar is visible. | Boolean | No, defaults to true |
| groupBy | Defines the attribute that all list entries must have, which is used for
grouping. Mandatory if you use the sortInsideGroupBy or DynamicallySortInsideGroupBy setting. |
Any attribute of the attached data | No |
| sortBy | Defines the attribute that is used to sort the items within a group. | Any attribute of the attached data | No |
| dataSource | Defines the data linked to the list. | Any data resource | Yes |
| master | Specifies the GroupedList as Master Control in a MasterDetailSectionPage layout. |
Boolean | No, defaults to false |
| direction | Defines the direction of the alphanumeric sorting order in ascending or descending order. | String (ASC or DESC) | No |
| flex | Enables the Flex List feature if the value is set to true. When you enable Flex List, pagination is disabled and the maximum configured value of list items are shown. | Boolean | No, defaults to false |
| indexBar | Defines whether the list contains an index bar. | Boolean | No, defaults to false |
| hasBorder | Defines whether the list has a border. Lists are shown without border by default. | Boolean | No, defaults to false |
| numberPadDefaultField | Specifies the stepper field name of the underlying list item within the Datasource contract. The stepper field value is used when a user taps the Next or Previous button in the number pad to place input cursor focus in the specified field. | Any attribute of the LI within the Datasource contract of type Stepper. | No |
| showPreviousNextEnter | Defines if the Previous, Next, and Enter buttons are displayed when the number pad is opened in the grouped list. Possible values are: true and false.
|
Boolean | No, defaults to false |
| sortInsideGroupBy | Defines the list item member name to sort the list items in a group. | Attributes of the bound list of the group | No |
| sortDirectionInGroup | Defines the direction of the alphanumerical sorting order. | String (ASC or DESC) | Mandatory, if sortInsideGroupBy or DynamicallySortInsideGroupBy is used. |
| itemAnimation | If the flex attribute is enabled in a GroupedList or BreadCrumbControl list, use this attribute to enable the slide in or slides out feature of the list items. This attribute uses these values:
The screen mentioned in the preceding list refers to the list-driven screens like the questionnaire screen or a survey screen. |
rightToLeft OR leftToRight OR none |
No |
| onItemDisclosure | needs info | Boolean | No |
| searchBarPlacement | Use this setting to position the search bar of a list . For example, in the header line. |
String |
If the property indexBar is set to true, an Index Bar
component is shown as an overlay on the right side of the list. It contains the symbol # for
numeric entries and the letters from A to Z. Tapping on or swiping over one of the entries
on the Index Bar takes the user to the first group in the GroupedList, which starts with the selected letter. If no group is found, the
list will scroll to the best matching previous entry. Depending on the sort order of the
groups, this can be the next one in alphabetical order or the previous one in alphabetical
order.
<GroupedList name="OverviewList" searchable="true" groupBy="grouping1" master="true" dataSource="ProcessContext::OverviewList.Items[]" indexBar="true">
<SearchAttributes>
<SearchAttribute name="SearchAttribute1" />
<SearchAttribute name="SearchAttribute2" />
<SearchAttribute name="SearchAttribute3" />
</SearchAttributes>
<Items name="Items" itemPattern="OverviewListPattern">
<ItemListLayout>
<Default>
<Col>
<Row layoutType="itemIdentifier" bindingId="Name" />
<Row layoutType="itemSecondary" bindingId="LastName" />
</Col>
</Default>
</ItemListLayout>
<Bindings>
<Binding target="Name" type="Text" binding=".name" bindingMode="ONE_WAY" />
<Binding target="LastName" type="Text" binding=".lastName" bindingMode="ONE_WAY" />
</Bindings>
</Items>
<Events>
<ItemSelectedEvent event="itemSelected" resetMultiAreas="true">
<Params>
<Param name="pKey" value=".pKey" />
</Params>
</ItemSelectedEvent>
</Events>
</GroupedList>Sub Elements
The GroupedList element can contain the following sub elements:
- Bindings
- Events
- Items
- SearchAttributes
- Textbar
Bindings
The Bindings element consists of the Resource and Binding
elements. The GroupedList control supports a DynamicallyGroupBy binding that allows you to change grouping
attribute of the grouped list dynamically during runtime in Consumer Goods Cloud offline
mobile app. A GroupedList can either contain the
groupBy attribute or the DynamicallyGroupBy binding. If both are present, then a validation error appears
when the contract is built.
Similarly, GroupedList control also supports the
DynamicallySortBy and DynamicallySortInsideGroupBy binding targets that allow you to dynamically
switch to the attribute that sorts the list items inside the group.
sortBy or sortInsideGroupBy. Only one of the two options is allowed.The order precedence of the sort attributes is listed here:
- sortBy (highest precedence)
- groupBy
- sortInsideGroupBy (lowest precedence)
The order specified in the preceding list ensures that the sortBy attribute first sorts the groups and then the attribute sortInsideGroupBy sorts the data within the groups. In
Consumer Goods Cloud Mobile App Framework, if a binding (DynamicallySortBy,DynamicallySortInsideGroupBy, or sortInsideGroupBy) value is null or can’t be found in the list item of the
group, then no sorting is performed and a warning message is logged.
Sample Code
Grouping
<Bindings>
Binding target="DynamicallyGroupBy" type="Text" binding="ProcessContext::MyBo.myGroupAttribute"/>
</Bindings>Sorting
<Bindings>
<Binding target="DynamicallySortBy" type="Text" binding="ProcessContext::MyBo.mySortAttribute"/>
<Binding target="DynamicallySortInsideGroupBy" type="Text" binding="ProcessContext::MyBo.mySortAttributeInsideTheGroups"/>
</Bindings>Events
The GroupedList control supports these events. For
more details about the Events element, see Events.
| Event Name | Event Trigger | Required |
|---|---|---|
| SwipeEvent | This event is triggered when an app user performs a swipe gesture to change tab pages or change week or day in a call calendar using the horizontal swipe gesture. | No |
| ItemSelectedEvent | This event is triggered when an app user taps a list item. | No |
| ContextOpeningEvent | This event is triggered when a context menu is pops up. | No |
| ContextSelectedEvent | This event is triggered when an item from a context menu is selected. | No |
| ListButtonPressedEvent | This event is triggered when an application user taps a button (short press) in a list item. | No |
| LongPressMenuOpeningEvent | This event is triggered before the context menu opens on long press of a button. This also allows business logic to customize the list contents of the data source. | No |
| LongPressMenuSelectedEvent | This event is triggered when an app user taps a context menu option of a button in a list. | No |
Search Attributes
Search attributes simply define which attributes of the underlying datastructure of your list are searchable or used in the quick filter. The SearchAttributes element is a container for all defined search attributes. The following list controls define SearchAttributes if they support searching for one or more elements in the list.
- GroupedList
- MultiSelectionGroupedList
- BreadCrumbControl
- MultiSelectionBreadCrumbControl
- CockpitList
- GroupedButtonList
You can define search attributes for a grouped list when searchable is set to true. Define the name attribute for each search attribute.
| Attribute | Description | Values/Pattern | Required |
|---|---|---|---|
| name | Unique name of the search attribute. If you set the searchable attribute of a list to true, ensure that at least one SearchAttribute is defined. | String | No |
<SearchAttributes>
<SearchAttribute name="Name" />
<SearchAttribute name="MainAddress" />
<SearchAttribute name="CustomerId" />
</SearchAttributes>
If a product list contains name and ean, then define these as searchable:
<SearchAttributes>
<SearchAttribute name="ean" />
<SearchAttribute name="name" />
</SearchAttributes>when you search through these list items
- ean=991, name=Cola
- ean=988, name=Fanta
- Quick search with “C” will return Cola
- Quick search with “9” will return Cola and Fanta because 9 is present in ean of both products
- Quick search with “8” will return Fanta
GroupedList Sample Code
<!-- left out details for brevity -->
<GroupedList name="CustomerList" groupBy="grouping1" sortBy="distance" indexBar="true" searchable="true" dataSource="ProcessContext::CustomerList.Items[]">
<Items name="Items" itemPattern="CustomerLookupItem">
<Bindings>
<Binding target="Name" type="Text" binding=".name" bindingMode="ONE_WAY" />
<Binding target="MainAddress" type="Text" binding=".mainAddress" bindingMode="ONE_WAY" />
<Binding target="Distance" type="Text" binding=".distanceText" bindingMode="ONE_WAY" />
</Bindings>
<ItemListLayout>
<Col>
<Row layoutType="itemIdentifier" bindingId="Name" />
<Row layoutType="itemSecondary" bindingId="MainAddress" />
</Col>
<Col width="2em">
<Row layoutType="itemValue" bindingId="Spacer" />
</Col>
<Col align="right">
<Row layoutType="itemIdentifier pull-right" bindingId="Distance" />
</Col>
</ItemListLayout>
</Items>
<Events>
<ItemSelectedEvent event="itemSelected">
<Params>
<Param name="pKey" value=".pKey" />
<Param name="name" value=".name" />
<Param name="substitutedUsrPKey" value=".substitutedUsrPKey" />
<Param name="subValidFrom" value=".subValidFrom" />
<Param name="subValidThru" value=".subValidThru" />
<Param name="isManagedCustomer" value=".managed" />
<Param name="managementRelationValidFrom" value=".managementRelationValidFrom" />
<Param name="managementRelationValidThru" value=".managementRelationValidThru" />
</Params>
</ItemSelectedEvent>
</Events>
<SearchAttributes>
<SearchAttribute name="Name" />
<SearchAttribute name="MainAddress" />
<SearchAttribute name="CustomerId" />
</SearchAttributes>
</GroupedList><GroupedList name="GroupedListCtrl" searchable="true" groupBy="groupBy" sortBy="sortBy" master="true" numberPadDefaultField = "quantity" showPreviousNextEnter = "true" dataSource="dataSource" direction="ASC" indexBar="true" hasBorder="true" onItemDisclosure="true">
<SearchAttributes>
<SearchAttribute name="SearchAttribute1" />
</SearchAttributes>
<Items name="Items" itemPattern="itemPattern">
<ItemListLayout>
<xml />
</ItemListLayout>
<Bindings>
<Binding target="ListAttribute1" type="Text" binding="binding" bindingMode="ONE_WAY" /> ... <Binding target="ListAttribute1" type="Dynamic" binding="binding" bindingMode="ONE_WAY" typeField="typeField" toggleId="DomAnaDeploymentStatus" />
</Bindings>
</Items>
</GroupedList>Sample Process Contract - Swipe Event
<Action name="Swipe_Decision" actionType="DECISION" parameter="Event.direction">
<Case value="left" action="MoveToNextDay" />
<Case value="right" action="MoveToPrevDay" />
<CaseElse action="ShowCalendarView_Decision" />
</Action>- TextBar Control
Use TextBar to define additional information, which acts as an aid for the app user to perform the necessary tasks related to the list. TextBar is rendered at the top of the GroupedList and above the SearchBar.
