Skip to content

List Specification

Tacho Zhelev edited this page Mar 26, 2019 · 9 revisions

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>
  • be able to set an active item.
  • be able to focus list items.
  • be able to change focused items via keyboard keys: Enter, Space, Home, End, Arrow keys.
  • be able to remove focus from an item via the Escape key.
  • be able to control whether keyboard navigation would continue when reaching the start/end of the list.
  • be able to specify a display density for the layout of the list and its items:
<igx-list [displayDensity]="'compact'">
    <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>

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.
  • be able to navigate through list items via the keyboard.

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.

Test Scenarios

  • Test defining a list:
    • with content items only;
    • with items and header;
    • with multiple headers.
  • Test defining an empty list and verify the default empty template is used.
  • Verify the specified list width is honored.
  • Verify items' maxLeft, maxRight and left property values are properly reflected.
  • Verify allowRightPanning properly controls whether panning items right is allowed.
  • Verify allowLeftPanning properly controls whether panning items left is allowed.
  • Verify custom empty template would be shown when specified instead of the default one.
  • Verify the loading template is always shown when IgxList's isLoading property is set to true.
  • Verify the loading template is hidden once IgxList's isLoading property is set to false.
  • Verify a custom loading template would be shown when specified instead of the default one.
  • Verify IgxList's ItemClicked event is emitted on clicking a list item.
  • Verify ItemClicked event is emitted with the correct direction when swiping items.
  • Verify items' roles are properly set.
  • Verify items can be hidden.
  • Test panning events.
  • Verify list items get activated on click and on key press.
  • Verify list items get focused on click and on key press.
  • Verify Escape key clears the focus from the focused item.
  • Verify Arrow keys navigate successfully through list items.
  • Verify Space and Enter keys activate & focus the first list item if there's no active item already.
  • Verify Home and End keys navigate to the first and last list item respectively.
Clone this wiki locally
You can’t perform that action at this time.