List Specification

Overview

igx-list should represent vertical container for contextual similar items. List is a building block of any complex UI used in almost every mobile application.

<igx-list>
    <igx-list-item isHeader="true">Header 1</igx-list-item>
    <igx-list-item>Item 1</igx-list-item>
    <igx-list-item>Item 2</igx-list-item>
    <igx-list-item>Item 3</igx-list-item>
    <igx-list-item isHeader="true">Header 2</igx-list-item>
    <igx-list-item>Item 4</igx-list-item>
    <igx-list-item>Item 5</igx-list-item>
    <igx-list-item>Item 6</igx-list-item>
</igx-list>

Objectives

Provides means for the developers to implement a simple common case, yet customizable list with minimal efforts. The list item component should be a container for text or some HTML content. A group of items into the list can be separated and labeled by header.

User Stories

Developer

As a developer I want to:

• add a list, so that I can create rows of similar list-items.
• have a vertically scrollable list, so that I can add as many list-items as I need.
• be able provide data items to the list using an ngFor directive:

<igx-list>
    <igx-list-item *ngFor=”#apple of apples”>
        {{apple.sweetLevel}}
    </igx-list-item>
</igx-list>

• be able display group headers by adding a special header item into the list:

<igx-list>
    <igx-list-item isHeader="true">Mildly Sweet</igx-list-item>
    <igx-list-item>Red Delicious</igx-list-item>
    <igx-list-item>Ambrosia</igx-list-item>
    <igx-list-item>Rome</igx-list-item>

    <igx-list-item isHeader="true">Sweet</igx-list-item>
    <igx-list-item>Golden Delicious</igx-list-item>
    <igx-list-item>Cosmic Crisp</igx-list-item>
    <igx-list-item>Pinova</igx-list-item>

    <igx-list-item isHeader="true">Super Sweet</igx-list-item>
    <igx-list-item>Gala</igx-list-item>
    <igx-list-item>Fuji</igx-list-item>
    <igx-list-item>Kiku</igx-list-item>
</igx-list>

• be able to implement custom logic and behavior to be executed when clicking a list item.
• be able to provide a custom template for templating the list when it is empty.

<igx-list>
  <ng-template igxEmptyList>
    <p>My custom empty list template</p>
  </ng-template>
</igx-list>

End user

As a end user, I want to:

• have a list of information, so that I can quickly review rows of data.
• be able to vertically scroll the list, so that I can review all of the available list items.
• be able to use on-swipe gestures.
• be able to click any item, so that a certain behavior gets triggered.

Acceptance criteria

1. The developer can add a list component to the application.
2. The developer can define list items as headers, so they label other items below them.
3. The end-users can view a list.
4. The end-users can vertically scroll the list items.
5. The end-users can interact the list items by swiping them left or right.

Functionality

A list consists of a single continuous column of tessellated sub-divisions of equal width called rows that function as containers for list-items.

End User Experience

• Swipe gesture - I want to slide list items through swipe (or pan) gesture.
• Layout - Lists should scroll only vertically and the scroll should appear only when the list items overflow the screen view.

API

igx-list

Inputs

Name	Description
allowLeftPanning	Determines whether the left panning of an item is allowed
allowRightPanning	Determines whether the right panning of an item is allowed
emptyListTemplate	The custom template to be used when the list is empty

Properties

Name	Description
children	Collection of all IListChild components: items and headers
items	Array of items in the list
headers	Array of headers in the list
innerStyle	Currently used inner style depending on whether the list is empty or not
role	Gets the role of the list

Outputs

Name	Description
Event emitters	Notify for a change
onPanStateChange	Triggered when pan gesture is executed on list item
onLeftPan	Triggered when left pan gesture is executed on list item
onRightPan	Triggered when right pan gesture is executed on list item
onItemClicked	Triggered when a list item has been clicked

igx-list-item

Inputs

Name	Description
hidden	Determines whether the item should be displayed
isHeader	Determines whether the item should be displayed as a header, default value is false

Properties

Name	Description
index	The index of item in children collection
panState	Gets the item's pan state
list	Gets the list that is associated with the item
role	Gets the role of the item within its respective list - separator if isHeader is true and listitem otherwise
element	Gets the native element that is associated with the item
width	Gets the width of the item
maxLeft	Gets the maximum left position of the item
maxRight	Gets the maximum right position of the item
touchAction	Determines in what way the item can be manipulated by the user via a touch action
headerStyle	Gets if the item is styled as header item
innerStyle	Gets if the item is styled as list item

ARIA support

• Roles:
  • List will need list role
  • List item will need separator role when it is a header and listitem role when it is not.